# idCerberus API Docs

> Documentação da API idCerberus para onboarding digital, KYC, biometria, FaceMatch, Liveness, análise de risco, compliance, enriquecimento cadastral e consultas de pessoa física e pessoa jurídica.

Base URLs:

- Homologação: `https://backoffice-hml.idcerberus.com`
- Produção: `https://backoffice.idcerberus.com`
- Documentação publicada: `https://api-docs.idcerberus.com/`

## Regras para assistentes de IA

- Use a documentação como fonte principal e não invente endpoints, parâmetros ou services.
- Para consultas externas, use `POST /api/service-api` e selecione o produto pelo campo `service`.
- Use `Authorization: Bearer {jwt_token}` em chamadas protegidas.
- Use homologação para testes e produção somente quando o usuário pedir explicitamente.
- Nunca exponha tokens, secrets, CPFs, CNPJs ou imagens reais em exemplos.
- Para OCR, use base64 puro em `image1`/`image2` e não inclua prefixo `data:image/...;base64,`.
- Não use `fieldsOutput`, campos nulos ou metadados internos como contrato público; use `result`.
- Se um service não aparecer no catálogo, informe que ele precisa ser confirmado antes de documentar ou integrar.

## Como escolher o arquivo certo

| Necessidade | Use |
| --- | --- |
| Entender a estrutura da documentação | https://api-docs.idcerberus.com/llms.txt |
| Gerar integração, curl ou escolher service | https://api-docs.idcerberus.com/llms-small.txt |
| Consultar payloads e responses por service | https://api-docs.idcerberus.com/llms-api-reference.txt |
| Buscar service em um índice leve | https://api-docs.idcerberus.com/services-catalog.min.json |
| Fazer busca estruturada por automação | https://api-docs.idcerberus.com/services-catalog.json |
| Configurar MCP ou agente com recursos estruturados | https://api-docs.idcerberus.com/mcp-manifest.json |
| Responder com todo o contexto da documentação | https://api-docs.idcerberus.com/llms-full.txt |

## Uso como base para MCP e agentes

Estes arquivos podem ser usados como fonte de contexto para um MCP da documentação. O MCP deve consultar a documentação, não executar chamadas na API idCerberus.

### Ordem recomendada de leitura

1. Leia `llms.txt` como manifesto inicial da documentação.
2. Use `services-catalog.min.json` para busca rápida por service, nome, categoria, campo e tag.
3. Use `services-catalog.json` quando precisar do contrato completo do service.
4. Use `mcp-manifest.json` para listar recursos, ferramentas sugeridas, regras de segurança e ordem de leitura.
5. Use `llms-api-reference.txt` para payloads, responses resumidos e exemplos por service.
6. Use `examples/*.curl` quando a resposta precisar de um curl pronto.
7. Use `llms-full.txt` apenas quando a pergunta exigir contexto completo dos guias, API Reference e OpenAPI.

### Recursos que um MCP pode expor

| Recurso | Uso no MCP |
| --- | --- |
| https://api-docs.idcerberus.com/llms.txt | Manifesto, regras, URLs principais e atalhos. |
| https://api-docs.idcerberus.com/llms-small.txt | Contexto curto para gerar integração, curl e explicação. |
| https://api-docs.idcerberus.com/llms-api-reference.txt | Payloads, responses e exemplos por service. |
| https://api-docs.idcerberus.com/llms-full.txt | Contexto completo para perguntas amplas. |
| https://api-docs.idcerberus.com/services-catalog.min.json | Índice leve para busca rápida por service, categoria, tag e campos. |
| https://api-docs.idcerberus.com/services-catalog.json | Busca estruturada e filtros por service/categoria/campo. |
| https://api-docs.idcerberus.com/mcp-manifest.json | Manifesto com recursos, ferramentas sugeridas, regras e ordem de leitura. |
| https://api-docs.idcerberus.com/examples/*.curl | Exemplos prontos para copiar e testar. |

### Regras para o MCP

- Operar como fonte somente leitura da documentação.
- Não chamar HML, produção, banco ou endpoints idCerberus.
- Não solicitar nem armazenar `client`, `secret`, JWT, CPF, CNPJ ou imagem real.
- Usar homologação como ambiente padrão quando gerar exemplos.
- Se o service não existir no catálogo, responder que precisa ser confirmado antes de integrar.
- Preferir `result` como contrato público; não usar `fieldsOutput` ou metadados internos.

## Contrato base do POST /api/service-api

- Endpoint de homologação: `POST https://backoffice-hml.idcerberus.com/api/service-api`.
- Endpoint de produção: `POST https://backoffice.idcerberus.com/api/service-api`.
- Header obrigatório: `Authorization: Bearer {jwt_token}`.
- Header recomendado: `Content-Type: application/json`.
- Campo obrigatório no body: `service`.
- O alias enviado em `service` deve ser o alias configurado no produto do cliente.
- Leia dados públicos em `result`; não trate `fieldsOutput` ou metadados internos como contrato público.
- Preserve `status`, `onboardingStatus` e `externalId` ao explicar respostas.

## Atalhos de services mais usados

| Caso | Service | Campos principais | Guia/API |
| --- | --- | --- | --- |
| CPF na Receita Federal | `SERVICE_RFB_PF` | `cpf`, `dataDeNascimento` | https://api-docs.idcerberus.com/api-reference/services-pessoa-fisica#SERVICE_RFB_PF |
| CNPJ na Receita Federal | `SERVICE_RFB_PJ` | `cnpj` | https://api-docs.idcerberus.com/api-reference/services-pessoa-juridica#SERVICE_RFB_PJ |
| OCR React | `SERVICE_OCR` | `documentType`, `image1`, `image2` | https://api-docs.idcerberus.com/api-reference/services-pessoa-fisica#SERVICE_OCR |
| OCR cartão CNPJ | `SERVICE_OCR_CNPJ_CARD` | `image1` | https://api-docs.idcerberus.com/api-reference/services-pessoa-juridica#SERVICE_OCR_CNPJ_CARD |
| OCR comprovante de endereço | `SERVICE_OCR_PROOF_OF_ADDRESS` | `image1` | https://api-docs.idcerberus.com/api-reference/services-pessoa-fisica#SERVICE_OCR_PROOF_OF_ADDRESS |
| Face Index | `SERVICE_FACE_INDEX` | `image1` | https://api-docs.idcerberus.com/api-reference/services-pessoa-fisica#SERVICE_FACE_INDEX |
| Risco de crédito PJ | `SERVICE_CREDIT_RISK_COMPANY` | `cnpj` | https://api-docs.idcerberus.com/api-reference/services-pessoa-juridica#SERVICE_CREDIT_RISK_COMPANY |
| Score de crédito PF | `SERVICE_CREDIT_SCORE` | `cpf` | https://api-docs.idcerberus.com/api-reference/services-pessoa-fisica#SERVICE_CREDIT_SCORE |
| Processos jurídicos PJ | `SERVICE_JURIDICAL_PROCESSES_PJ` | `cnpj` | https://api-docs.idcerberus.com/api-reference/services-pessoa-juridica#SERVICE_JURIDICAL_PROCESSES_PJ |
| Benefícios sociais familiares | `SERVICE_FAMILY_SOCIAL_BENEFITS` | `cpf` | https://api-docs.idcerberus.com/api-reference/services-pessoa-fisica#SERVICE_FAMILY_SOCIAL_BENEFITS |

## Notas rápidas para OCR e imagem

- OCR usa imagem do documento, não selfie.
- Face, FaceMatch e Face Index usam selfie/rosto, não foto de RG ou CNH.
- `image1` deve receber base64 puro, sem prefixo `data:image/...;base64,`.
- RG normalmente usa frente e verso: `image1` e `image2`.
- CNH usa `SERVICE_OCR`, `documentType: CNH` e `image1`.
- Cartão CNPJ usa `SERVICE_OCR_CNPJ_CARD` e `image1`.
- Comprovante de endereço usa `SERVICE_OCR_PROOF_OF_ADDRESS` e `image1`.
- Emancipação usa `SERVICE_OCR_EMANCIPATION`; o documento varia e o sucesso depende de OCR com texto útil.
- Se a imagem estiver ausente, ilegível ou for do tipo errado, espere `REFUSED` com mensagem clara, não invente sucesso.

## Conteúdo principal

### Guias / Primeiros passos

- [Mapa da documentação](https://api-docs.idcerberus.com/guides/mapa-da-documentacao): Encontre rapidamente o melhor caminho dentro da documentação idCerberus
- [Busca rápida](https://api-docs.idcerberus.com/guides/busca-rapida): Encontre services, payloads, guias e exemplos usando termos comuns, aliases e casos de uso
- [Quickstart](https://api-docs.idcerberus.com/guides/quickstart): Faça sua primeira chamada na API idCerberus com Postman, Windows, macOS ou Linux
- [Roteiro de integração](https://api-docs.idcerberus.com/guides/roteiro-de-integracao): Um passo a passo prático para sair do primeiro teste até uma integração pronta para produção
- [Visão geral](https://api-docs.idcerberus.com/guides/visao-geral): Entenda a arquitetura da integração, ambientes, endpoints e padrão de resposta da API idCerberus
- [Ambientes](https://api-docs.idcerberus.com/guides/ambientes): Entenda a diferença entre homologação e produção na API idCerberus
- [Arquivos para LLMs](https://api-docs.idcerberus.com/guides/llms): Use arquivos de contexto para apoiar integrações, automações e assistentes de IA
- [Como usar esta documentação](https://api-docs.idcerberus.com/guides/como-usar-a-documentacao): Entenda quando usar guias, catálogo técnico e API Reference
- [Postman do zero](https://api-docs.idcerberus.com/guides/postman-do-zero): Configure o Postman para testar token, service-api e OCR sem escrever código
### Guias / Suporte e referência

- [Status e erros](https://api-docs.idcerberus.com/guides/status-e-erros): Entenda como interpretar respostas, falhas e casos sem body JSON
- [Erros comuns de integração](https://api-docs.idcerberus.com/guides/erros-comuns-integracao): Diagnóstico prático para token, acesso, payload, base64, OCR, retorno vazio e falhas externas
- [Troubleshooting](https://api-docs.idcerberus.com/guides/troubleshooting): Resolva problemas comuns ao integrar com a API idCerberus
- [Boas práticas de integração](https://api-docs.idcerberus.com/guides/boas-praticas-integracao): Recomendações para integrar a API idCerberus com segurança e estabilidade
- [Glossário](https://api-docs.idcerberus.com/guides/glossario): Termos comuns usados na documentação da API idCerberus
### Guias / Fluxos principais

- [Autenticação](https://api-docs.idcerberus.com/guides/autenticacao): Gere tokens JWT e autentique chamadas protegidas da API idCerberus
- [Primeira consulta CPF](https://api-docs.idcerberus.com/guides/primeira-consulta-cpf): Execute uma consulta simples de pessoa física do início ao fim
- [Primeira consulta CNPJ](https://api-docs.idcerberus.com/guides/primeira-consulta-cnpj): Execute uma consulta simples de pessoa jurídica do início ao fim
- [Onboarding via SDK](https://api-docs.idcerberus.com/guides/onboarding-sdk): Gere TokenOnboarding, acompanhe o status do cadastro e baixe o relatório final
- [Escolha o serviço certo](https://api-docs.idcerberus.com/guides/escolha-o-servico-certo): Encontre os services idCerberus mais indicados para cada caso de uso
- [Receitas prontas](https://api-docs.idcerberus.com/guides/receitas-prontas): Fluxos práticos para testar CPF, CNPJ, OCR, Face Index, risco e score pela Service API
- [Exemplos por ambiente](https://api-docs.idcerberus.com/guides/exemplos-por-ambiente): Copie chamadas equivalentes para homologação e produção sem trocar parâmetros por engano
- [Exemplos por linguagem](https://api-docs.idcerberus.com/guides/exemplos-por-linguagem): Exemplos de integração com curl, Node.js, Python e C#
### Guias / POST /api/service-api

- [Matriz de serviços](https://api-docs.idcerberus.com/guides/matriz-de-servicos): Visão resumida dos principais serviços por tipo de documento, entrada e momento de uso
- [Índice de services](https://api-docs.idcerberus.com/guides/indice-de-services): Lista operacional dos services já documentados no API Reference
- [[object Object]](https://api-docs.idcerberus.com/[object Object])
- [Famílias de serviços](https://api-docs.idcerberus.com/guides/service-api/familias-de-servicos): Navegue pelos principais grupos de produtos executados via POST /api/service-api
### Guias / Pessoas

- [Enriquecimento cadastral](https://api-docs.idcerberus.com/guides/pessoas/enriquecimento-cadastral): Consulte, valide e complemente dados cadastrais de pessoas físicas
- [Biometria e documentos](https://api-docs.idcerberus.com/guides/pessoas/biometria-e-documentos): Valide documentos, selfies, biometria facial e evidências de identidade
- [Risco e compliance](https://api-docs.idcerberus.com/guides/pessoas/risco-e-compliance): Avalie exposição, restrições, certidões, débitos e sinais de risco de pessoas físicas
- [Dados eleitorais](https://api-docs.idcerberus.com/guides/pessoas/dados-eleitorais): Consulte candidaturas, doações, vínculos políticos e exposição eleitoral de pessoas físicas
### Guias / Empresas

- [Dados cadastrais de empresas](https://api-docs.idcerberus.com/guides/empresas/dados-cadastrais): Consulte situação cadastral, dados oficiais, atividades econômicas e obrigações de empresas
- [Sócios e relacionamentos](https://api-docs.idcerberus.com/guides/empresas/socios-e-relacionamentos): Analise quadro societário, vínculos empresariais, círculos de relacionamento e riscos associados a sócios
- [Compliance de empresas](https://api-docs.idcerberus.com/guides/empresas/compliance): Consulte débitos, protestos, restrições e exposições regulatórias de empresas
### Guias / Catálogo técnico

- [Serviços de Pessoa Física](https://api-docs.idcerberus.com/guides/servicos-pessoa-fisica): Serviços externos disponíveis para consultas de CPF
- [Serviços de Pessoa Jurídica](https://api-docs.idcerberus.com/guides/servicos-pessoa-juridica): Serviços externos disponíveis para consultas de CNPJ
### API Reference / Catálogo de services

- [Boas-vindas](https://api-docs.idcerberus.com/api-reference/boas-vindas): Comece a implementar os endpoints da API idCerberus
- [Como executar um service](https://api-docs.idcerberus.com/api-reference/como-executar-service): Passo a passo para autenticar, escolher ambiente, montar o body e chamar um service da API idCerberus.
- [Services por caso de uso](https://api-docs.idcerberus.com/api-reference/services-por-caso-de-uso): Mapa rápido para encontrar o service certo a partir do objetivo da integração.
- [Services de pessoa física](https://api-docs.idcerberus.com/api-reference/services-pessoa-fisica): Catálogo explícito dos services de pessoa física disponíveis via API, com campos esperados e exemplos de request.
- [Services de pessoa jurídica](https://api-docs.idcerberus.com/api-reference/services-pessoa-juridica): Catálogo explícito dos services de pessoa jurídica disponíveis via API, com campos esperados e exemplos de request.

## API Reference

- [OpenAPI reference](https://api-docs.idcerberus.com/api-reference/boas-vindas): endpoints, exemplos de request/response e schemas.
- Endpoint principal de consultas: `POST /api/service-api`.
- Autenticação: `POST /api/token-generate` retorna `access_token`; use `Authorization: Bearer {jwt_token}` nas chamadas protegidas.

## Arquivo completo para LLM

- [llms-small.txt](https://api-docs.idcerberus.com/llms-small.txt): resumo operacional com fluxos, autenticação, service-api e services documentados.
- [llms-full.txt](https://api-docs.idcerberus.com/llms-full.txt): versão consolidada dos guias e da API Reference.
- [llms-api-reference.txt](https://api-docs.idcerberus.com/llms-api-reference.txt): referência operacional dos services com exemplos de curl.
- [services-catalog.min.json](https://api-docs.idcerberus.com/services-catalog.min.json): índice leve para busca rápida por service, categoria, tag e campos.
- [services-catalog.json](https://api-docs.idcerberus.com/services-catalog.json): catálogo estruturado para ferramentas e automações.
- [mcp-manifest.json](https://api-docs.idcerberus.com/mcp-manifest.json): manifesto para MCPs e agentes com recursos, regras e ferramentas sugeridas.

## Exemplos curl

- [auth.hml.curl](https://api-docs.idcerberus.com/examples/auth.hml.curl): Gerar token em homologação. Use antes de chamar endpoints protegidos em HML.
- [auth.prod.curl](https://api-docs.idcerberus.com/examples/auth.prod.curl): Gerar token em produção. Use somente quando o cliente já estiver liberado em produção.
- [service-api-cpf.hml.curl](https://api-docs.idcerberus.com/examples/service-api-cpf.hml.curl): Consulta simples de CPF em HML. Exemplo base para validar token, produto e resposta de pessoa física.
- [service-api-cpf.prod.curl](https://api-docs.idcerberus.com/examples/service-api-cpf.prod.curl): Consulta simples de CPF em produção. Mesmo payload da consulta de CPF, apontando para produção.
- [service-api-cnpj.hml.curl](https://api-docs.idcerberus.com/examples/service-api-cnpj.hml.curl): Consulta simples de CNPJ em HML. Exemplo base para validar token, produto e resposta de pessoa jurídica.
- [service-api-cnpj.prod.curl](https://api-docs.idcerberus.com/examples/service-api-cnpj.prod.curl): Consulta simples de CNPJ em produção. Mesmo payload da consulta de CNPJ, apontando para produção.
- [service-api-ocr-cnh.hml.curl](https://api-docs.idcerberus.com/examples/service-api-ocr-cnh.hml.curl): OCR de CNH em HML. Use base64 puro da imagem da CNH em image1.
- [service-api-ocr-rg.hml.curl](https://api-docs.idcerberus.com/examples/service-api-ocr-rg.hml.curl): OCR de RG em HML. Use frente em image1 e verso em image2.
- [service-api-ocr-cnpj-card.hml.curl](https://api-docs.idcerberus.com/examples/service-api-ocr-cnpj-card.hml.curl): OCR de cartão CNPJ em HML. Use imagem legível do cartão CNPJ em image1.
- [service-api-ocr-proof-of-address.hml.curl](https://api-docs.idcerberus.com/examples/service-api-ocr-proof-of-address.hml.curl): OCR de comprovante de endereço em HML. Use conta, fatura ou comprovante aceito em image1.
- [service-api-face-index.hml.curl](https://api-docs.idcerberus.com/examples/service-api-face-index.hml.curl): Face Index em HML. Use selfie real em image1. Não use foto de documento.
- [service-api-credit-risk-company.hml.curl](https://api-docs.idcerberus.com/examples/service-api-credit-risk-company.hml.curl): Risco de crédito PJ em HML. Exemplo para consultar risco de crédito de empresa.
- [service-api-credit-score.hml.curl](https://api-docs.idcerberus.com/examples/service-api-credit-score.hml.curl): Score de crédito PF em HML. Exemplo para consultar score de crédito de pessoa física.
- [facematch.hml.curl](https://api-docs.idcerberus.com/examples/facematch.hml.curl): FaceMatch em HML. Compara duas imagens faciais. Use selfie/rosto, não OCR de documento.
- [documentoscopia.hml.curl](https://api-docs.idcerberus.com/examples/documentoscopia.hml.curl): Documentoscopia em HML. Fluxo com documento e selfie para análise documental.