​
Dúvidas e Soluções

Esta página reúne, num só lugar, as perguntas que mais aparecem durante uma integração com a idCerberus. A ideia é simples: antes de abrir um chamado de suporte, procure sua dúvida aqui. Boa parte dos “bugs” reportados são comportamentos esperados que só não estavam claros na documentação técnica.
Use Ctrl + F (ou Cmd + F no Mac) para pesquisar uma palavra-chave nesta página antes de percorrer as seções manualmente.

​
Autenticação e token

Não. Gere um access_token em POST /api/token-generate e reutilize até ele expirar, conforme o campo expires_in do retorno. Gerar um novo a cada chamada funciona, mas desperdiça uma chamada extra por request.
Você recebe HTTP 401. Gere um token novo com client e secret e repita a chamada original. Isso é um HTTP de verdade, diferente das falhas de permissão de service que também aparecem como “401 no corpo” (veja a seção de status abaixo).
Não. São credenciais diferentes por ambiente. Um client/secret de HML não gera token válido para chamar produção, e vice-versa. Os bancos de dados e o realm de autenticação são separados fisicamente entre os dois ambientes.
Esse par é liberado pela React IT junto com o produto contratado, não é algo que você gera sozinho. Solicite pelo e-mail [email protected].

​
Consulta avulsa (POST /api/service-api)

Sim, e é o motivo número um de confusão nesta API. POST /api/service-api quase sempre retorna HTTP 200, mesmo quando a consulta falhou por completo. O motivo real fica dentro do corpo, em status.code e status.message. Nunca decida sucesso ou falha só pelo HTTP status.
HTTP 401/403 de verdade só acontece por problema de autenticação (token ausente, expirado ou de outro ambiente), e a chamada nem chega a processar o service. “Produto não liberado para o service” e “produto inativo” não geram HTTP 401/403 nesse endpoint: a chamada retorna HTTP 200 com o problema descrito em status.code (400 para payload/permissão de service, 401 para produto inativo ou não encontrado) dentro do corpo.
Existem pelo menos três causas distintas: a fonte de dados não encontrou nada para aquele documento (comportamento válido, nem todo retorno vazio é erro), a imagem não foi lida com sucesso em OCR, ou, se o seu produto for pré-pago, o saldo da organização está insuficiente. Esse último caso é traiçoeiro porque também vem com HTTP 200 e status.code 200, com status.message dizendo algo como “Not enough balance”. Sempre leia status.message quando result vier vazio, mesmo com 200/200.
Não. O alias de cada service (o valor que você envia em service) é único no sistema: não existe um alias customizado por produto. Se um service não funciona, o problema é ele não estar habilitado para o seu produto, não o nome do alias estar errado (a menos que você tenha digitado errado).
Só num caso específico: SEVICE_ONLINE_BETTING_PROPENSITY está documentado sem a letra R em SERVICE de propósito. Essa é a grafia implementada no backend. Corrigir esse alias ao copiar quebra a chamada. Fora esse caso, copie os aliases exatamente como aparecem no catálogo de services.

​
Onboarding via SDK ou Cliente Web

Não, e confundir os dois é uma fonte comum de erro. access_token autentica a sua aplicação e expira em minutos. tokenOnboarding identifica um cadastro específico e continua válido durante todo o processo, mesmo depois do access_token expirar. Se o access_token expirar no meio do fluxo, gere um novo: o tokenOnboarding não muda.
Não há um tempo fixo garantido. O processamento automático é verificado a cada poucos segundos internamente, mas o tempo total depende de quantos services estão na esteira e se algum deles depende de fontes externas lentas. Trate como comportamento observado, não como SLA contratual, e sempre implemente um limite máximo de espera na sua aplicação.
Não. REFUSED é um resultado de negócio: a chamada em si teve sucesso (HTTP 200), e o cadastro é que não foi aprovado pelas regras do produto. Não trate REFUSED como algo para repetir a chamada; trate como decisão que a sua aplicação precisa refletir para o usuário.

​
Webhooks

Primeiro, confirme que o evento que você espera realmente dispara webhook: mudança de status de onboarding, decisão de revisão manual, e consulta avulsa em POST /api/service-api (quando o produto tem webhook configurado). Segundo, lembre que consulta avulsa dispara o webhook cerca de 10 segundos depois da resposta HTTP, não instantaneamente. Terceiro, valide se a sua URL está acessível publicamente (a idCerberus não consegue entregar num endpoint atrás de firewall sem liberação).
Não. Não existe um processo automático que fica reenviando entregas que falharam. Um novo envio só acontece se o mesmo onboarding mudar de conteúdo de novo mais tarde (o que dispara como uma entrega nova, não como retry), ou se alguém com acesso ao Backoffice forçar o reenvio manualmente na tela. Por isso, nunca dependa só do webhook. Mantenha o polling (GET /api/onboarding/report/{tokenOnboarding}) como rede de segurança de verdade.
Sim. Webhook originado de onboarding usa o formato de relatório completo (tokenOnboarding, status, fields, services). Webhook originado de consulta avulsa usa o mesmo JSON que já veio na resposta HTTP síncrona da chamada (result, status, onboardingStatus, externalId). São formatos diferentes, então não assuma uma estrutura única.

​
OCR e imagem

Não. O sistema aceita base64 com ou sem esse prefixo e remove automaticamente quando presente. Se a sua ferramenta gera o base64 com prefixo (comum em navegador, por exemplo), não perca tempo removendo.
Confirme três coisas na ordem: se o documentType bate com o documento real enviado, se a imagem está completa e legível (sem corte nas bordas), e se o base64 não foi truncado no meio do envio. Esse último é comum quando o payload é montado manualmente e o corte acontece sem erro visível até chegar na API.
Pode variar. SERVICE_OCR é processado por parceiros diferentes conforme a configuração do seu produto, e isso pode mudar um campo pontual do result (o mais comum é o nome do campo que indica o tipo do documento reconhecido). Trate o contrato desta página como “os campos costumam vir assim”, não como uma garantia rígida campo a campo, e sempre valide pelo result retornado no seu ambiente real.

​
Backoffice

Não. São dois mecanismos de autenticação diferentes para o mesmo sistema. O login do backoffice é usuário e senha, pessoal. client e secret autenticam a sua aplicação e geram access_token via POST /api/token-generate. Veja Autenticação para o lado API.
A configuração de webhook (URL e chave) hoje é feita pela React IT sob pedido, não é uma tela de autoatendimento ainda. Veja Webhooks para como pedir a ativação.
backoffice-hml.idcerberus.com e backoffice.idcerberus.com são as mesmas URLs usadas pelo painel administrativo. Quando você chama /api/... nelas, está falando com a API, não com a interface visual. Não existe uma URL separada só para API: é o mesmo domínio, endpoints diferentes.

​
Ambientes

Não recomendado. Homologação e produção usam bancos de dados e credenciais completamente separados. Teste sempre em HML primeiro; use produção só depois de validar o fluxo, com dados reais e consciência de que consultas em produção normalmente têm custo.
Confirme, nesta ordem: se o token usado é de produção (não HML), se o produto de produção tem os mesmos services habilitados que o de HML, e se a massa de dados testada em produção é real (HML costuma ter dados fake que não existem nas fontes de produção). Divergência de configuração entre ambientes é a causa mais comum aqui.

​
Antes de abrir chamado

Se sua dúvida não está aqui, reúna estas informações antes de acionar o suporte. Isso evita idas e vindas e acelera a resposta. Veja o formato completo de chamado em Erros comuns de integração.

Erros comuns de integração

Diagnóstico por categoria: token, payload, imagem e erro técnico.

Troubleshooting

Sintomas técnicos específicos, como PowerShell quebrando o curl.

Webhooks

Como funciona, payload por origem e por que não há retry automático.

Glossário

Termos técnicos usados nesta página e no resto da documentação.