Erros comuns de integração

Use esta página quando uma chamada falhar, retornar vazio ou parecer diferente do esperado. A regra mais importante: em POST /api/service-api, olhe o body da resposta, não só o HTTP status. Uma chamada pode retornar HTTP 200 e mesmo assim o processamento vir como REFUSED ou ERROR.

Token ou acesso

401, 403, token vencido ou produto sem permissão para o service.

Payload

Campo obrigatório ausente, alias errado, CPF/CNPJ inválido ou JSON malformado.

Imagem e OCR

Base64, image1, image2, documento ilegível ou OCR sem campo esperado.

Erro técnico

ERROR, 500, falha externa, timeout ou investigação por externalId.

Diagnóstico rápido

Sintoma	Causa comum	Como corrigir
`401` ou `403`	Token ausente, expirado, inválido ou de outro ambiente	Gere um novo token no mesmo ambiente da chamada
`Don't have access to the service`	Produto sem o service ativo ou sem API habilitada	Confira configuração do produto antes de mexer no payload
`Unable to convert http message`	JSON inválido, base64 quebrado ou body malformado	Valide o JSON e gere o base64 novamente
API retorna HTTP 200 com `REFUSED`	Chamada autenticou, mas a regra de negócio recusou	Leia `status.message` e trate como recusa válida
API retorna HTTP 200 com `ERROR`	Falha técnica aconteceu dentro do processamento	Guarde `externalId`, horário e service chamado
Resultado vazio `{}`	Massa sem dados, imagem não lida ou service sem retorno para aquele caso	Teste massa válida e confira `status.message`
Campo esperado não veio	Campo não existe na fonte ou não foi extraído com segurança	Não invente dado; trate campo ausente como opcional quando o contrato permitir
Base64 rejeitado	Prefixo, encoding, quebra de linha ou arquivo inválido	Envie base64 puro, sem `data:image/...;base64,`
CPF/CNPJ não encontrado	Documento mascarado, incompleto, massa ruim ou ambiente errado	Teste sem máscara e confira a base URL
Timeout	Fonte externa demorou ou ficou indisponível	Aplique retry controlado e registre o `externalId`, quando houver

Token ou acesso

Antes de investigar código, confirme:

A chamada está indo para o ambiente certo.
O token foi gerado no mesmo ambiente.
O header está como Authorization: Bearer {jwt_token}.
O produto ligado ao token tem o service ativo.
O service está habilitado para API.
O alias enviado em service é o alias de chamada configurado no produto.

Exemplo típico:

{
  "result": {},
  "status": {
    "code": 400,
    "message": "Don't have access to the service"
  },
  "onboardingStatus": "REFUSED",
  "externalId": "..."
}

Nesse caso, o primeiro ponto é configuração do produto. Não adianta trocar CPF, CNPJ ou imagem antes de confirmar acesso.

Payload

Campos que mais geram erro:

Campo	Cuidado
`service`	Deve bater com o alias liberado no produto
`cpf`	Envie sem máscara quando o service não documentar outro formato
`cnpj`	Envie CNPJ completo, preferencialmente sem máscara
`birthDate`	Use o formato documentado para o service
`documentType`	Para OCR React, use `CNH` ou `RG` conforme o documento
`image1`, `image2`, `selfie1`	Confirme se o service espera imagem, selfie, frente, verso ou comparação
`key`	Use apenas quando o fluxo suportar chave de arquivo já armazenado

Exemplo de JSON mínimo válido:

{
  "service": "SERVICE_REGISTRATION_DATA_CNPJ",
  "cnpj": "00000000000000"
}

Imagem e OCR

Para services de OCR:

Use imagem real, nítida e completa.
Envie base64 puro.
Não envie data:image/jpeg;base64,.
Para RG, envie frente e verso quando o service exigir.
Para face, use selfie real, não foto de documento.
Confira se o documento enviado combina com o service.

Exemplo de erro por imagem ausente:

{
  "result": {},
  "status": {
    "code": 400,
    "message": "Imagem do verso do documento não encontrada"
  },
  "onboardingStatus": "REFUSED",
  "externalId": "..."
}

Ação: revisar o payload. Para RG, envie image1 com a frente e image2 com o verso. Se o retorno for:

{
  "result": {},
  "status": {
    "code": 400,
    "message": "Não foi possível ler o documento"
  },
  "onboardingStatus": "REFUSED",
  "externalId": "..."
}

Ação: testar uma imagem mais nítida e confirmar se o tipo de documento bate com o service.

Erro técnico

Erro técnico normalmente aparece como ERROR ou mensagem de falha no body:

{
  "result": {},
  "status": {
    "code": 500,
    "message": "Falha ao realizar OCR"
  },
  "onboardingStatus": "ERROR",
  "externalId": "..."
}

Nessa situação, guarde:

ambiente;
endpoint;
service enviado;
horário aproximado;
externalId;
status.code;
status.message;
payload sem dados sensíveis.

Não envie token JWT, client, secret, CPF, CNPJ, imagem real ou base64 completo em canais abertos.

Checklist antes de chamar suporte

Confirmei o ambiente da chamada.
Gerei token novo no mesmo ambiente.
Conferi o alias do service no produto.
Validei que o service está ativo e com API habilitada.
Validei o JSON antes de enviar.
Removi máscara quando o contrato não exigia máscara.
Para OCR, conferi se o base64 é puro.
Para OCR, abri a imagem e confirmei que está legível.
Guardei externalId, horário e status.message.

Como solicitar suporte

Envie um resumo nesse formato:

Ambiente: HML ou PROD
Endpoint: POST /api/service-api
Service: SERVICE_EXEMPLO
Horário aproximado: 2026-01-01 10:30
ExternalId: ...
Status code: ...
Status message: ...
O que era esperado: ...
O que retornou: ...

Não inclua credenciais, token, documento real, imagem real ou base64 completo.

Primeiros passos

Suporte e referência

Fluxos principais

POST /api/service-api

Pessoas

Empresas

Catálogo técnico

Erros comuns de integração

Erros comuns de integração

Token ou acesso

Payload

Imagem e OCR

Erro técnico

Diagnóstico rápido

Token ou acesso

Payload

Imagem e OCR

Erro técnico

Checklist antes de chamar suporte

Como solicitar suporte

​Erros comuns de integração

Token ou acesso

Payload

Imagem e OCR

Erro técnico

​Diagnóstico rápido

​Token ou acesso

​Payload

​Imagem e OCR

​Erro técnico

​Checklist antes de chamar suporte

​Como solicitar suporte

Erros comuns de integração

Diagnóstico rápido

Token ou acesso

Payload

Imagem e OCR

Erro técnico

Checklist antes de chamar suporte

Como solicitar suporte