Integração Opera Capital → Ulloo

Resumo rápido

Esta documentação descreve os endpoints que a Opera Capital deve chamar para enviar eventos da esteira de antecipação à Ulloo no ambiente de homologação.

Ambiente de homologação

Use estas configurações em todas as chamadas para o ambiente de stage da Ulloo.

Base URL

https://ulloo.guaraipo.tech

Headers obrigatórios em todas as chamadas

Authorization: Bearer {TOKEN_STAGE}
Accept: application/json
Content-Type: application/json

Token de homologação

O token de homologação será fornecido pela Ulloo por canal seguro.

O que a Opera deve implementar agora

Visão geral dos endpoints. Endpoints marcados como "Aguardando alinhamento de payload" não devem ser usados para homologação funcional até liberação da Ulloo.

Evento	Método	Endpoint	Status
Análise do cedente	POST	/api/integrations/opera/webhooks/analysis-pipeline	Disponível para teste
Decisão da antecipação	POST	/api/integrations/opera/webhooks/anticipation-decision	Aguardando alinhamento de payload
Motor da operação	POST	/api/integrations/opera/webhooks/operation-motor	Aguardando alinhamento de payload

Autenticação

Todas as chamadas da Opera Capital para a API devem enviar Bearer Token no header Authorization.

Header obrigatório

Authorization: Bearer {TOKEN_STAGE}

Requisições sem o header Authorization são rejeitadas automaticamente com 401.

Sobre o token

O token de homologação será fornecido pela Ulloo por canal seguro. O token identifica o ambiente e o workspace autorizado da integração.

Respostas possíveis

401 Unauthorized — token ausente ou inválido
403 Forbidden — token sem permissão para o endpoint
422 Unprocessable Entity — payload inválido
500 Internal Server Error — erro inesperado no processamento

Webhook: análise da operação

Disponível para teste

POST /api/integrations/opera/webhooks/analysis-pipeline

Este endpoint deve ser chamado pela Opera para informar o resultado da análise cadastral do cedente. O campo Documento (CNPJ) identifica o cedente localmente.

// Aprovação
{
  "Documento": "00000000000000",
  "status_analise": "APROVADO",
  "observacao": "Cedente aprovado na análise cadastral."
}

// Reprovação
{
  "Documento": "00000000000000",
  "status_analise": "REPROVADO",
  "observacao": "Documentação incompleta. Reenviar contrato social."
}

O campo observacao é opcional, mas recomendado nos casos de REPROVADO para identificar o motivo. Usar CNPJ fictício apenas em testes.

Campo	Tipo	Obrigatório	Descrição
Documento	string	sim	CNPJ do cedente (apenas dígitos ou formatado)
status_analise	string	sim	Resultado da análise: APROVADO ou REPROVADO
observacao	string	não	Motivo ou observação da análise (opcional)

Respostas possíveis

O endpoint retorna respostas distintas conforme o CNPJ do cedente seja localizado ou não na base da Ulloo.

HTTP 202 — Cedente encontrado e processado

202

{
  "success": true,
  "status": "processed",
  "message": "Webhook processado com sucesso.",
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "received_at": "2026-05-24T10:30:00+00:00"
}

O cedente foi localizado e o status de análise foi registrado. Esta resposta confirma que o evento foi recebido e processado com sucesso.

HTTP 422 — Cedente não localizado

422

{
  "success": false,
  "status": "not_found",
  "message": "Documento informado não foi encontrado na base.",
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "received_at": "2026-05-24T10:30:00+00:00"
}

O CNPJ informado no campo Documento não corresponde a nenhum cedente cadastrado na Ulloo. O evento ainda é registrado internamente com o event_id para rastreamento. Verificar o CNPJ enviado e alinhar com a equipe Ulloo se necessário.

event_id

Presente em todas as respostas (202 e 422). Identificador UUID único do evento, salvo internamente para rastreamento e auditoria. Pode ser informado em chamados de suporte ou validações de homologação.

Exemplo cURL

Exemplo completo para testar o webhook de análise em homologação.

curl -i -X POST "https://ulloo.guaraipo.tech/api/integrations/opera/webhooks/analysis-pipeline" \
  -H "Authorization: Bearer {TOKEN_STAGE}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"Documento": "00000000000000", "status_analise": "APROVADO", "observacao": "Cedente aprovado na análise cadastral."}'

Substituir {TOKEN_STAGE} pelo token fornecido pela Ulloo por canal seguro. Usar CNPJ fictício apenas em testes.

Endpoints ainda em alinhamento

Os endpoints abaixo estão reservados mas não devem ser usados para homologação funcional até liberação da Ulloo.

Decisão da antecipação

POST /api/integrations/opera/webhooks/anticipation-decision

Endpoint reservado. Payload e liberação funcional ainda serão confirmados pela Ulloo.

Motor da operação

POST /api/integrations/opera/webhooks/operation-motor

Endpoint reservado. Payload e liberação funcional ainda serão confirmados pela Ulloo.

Checklist para a Opera

Itens para validar antes e durante a homologação.

Receber token de homologação da Ulloo por canal seguro
Confirmar URL base de homologação: https://ulloo.guaraipo.tech
Implementar envio do webhook de análise com os campos Documento e status_analise
Confirmar resposta HTTP 202 (CNPJ localizado) com status "processed", event_id UUID e received_at
Tratar resposta HTTP 422 (CNPJ não localizado) com status "not_found" — guardar event_id para rastreamento
Enviar exemplos reais de payload para homologação
Alinhar payloads dos webhooks de decisão e motor antes de implementar

Dicas práticas

Nunca reutilizar token de stage em produção — cada ambiente tem seu próprio token.
Endpoints marcados como "Aguardando alinhamento de payload" não devem ser testados funcionalmente até liberação da Ulloo.
Em caso de dúvidas sobre tokens, payloads ou endpoints, contatar a equipe Ulloo por canal oficial.