API, SDK e MCP que conferem RG, CNH, CPF e comprovantes para quem desenvolve no Brasil.
Uma chamada confere o documento com o seu cadastro, roda as regras e aponta sinais de adulteração, inclusive de geração por IA.
Pegar chave grátis10 créditos grátis · sem cartão
Integre a DocusPilot (site docuspilot.com; variáveis DOCUSPILOT_*) neste projeto para validar documentos brasileiros (RG/CIN, CNH, passaporte, certidões, cartão CPF/CNPJ e comprovante de residência).
1. Chave: crie uma grátis em https://docuspilot.com/#chave (10 créditos, sem cartão) e ponha no .env como DOCUSPILOT_API_KEY. Confira que .env está no .gitignore (a chave nunca vai para o git) e crie um .env.example com DOCUSPILOT_API_KEY= vazio. O código gerado lê DOCUSPILOT_API_KEY do ambiente, só no servidor: a chave nunca vai para o navegador.
2. Chamada: POST https://api.docuspilot.com/v1/verify, multipart/form-data, header Authorization: Bearer <DOCUSPILOT_API_KEY>.
- file: o documento. JPEG, PNG, WebP ou PDF (HEIC é recusado: converta antes). Imagem até 3,75 MB; arquivo até 15 MB e PDF até 100 páginas.
- Frente e verso (RG, CIN, CNH): junte os dois lados num PDF de 2 páginas no seu código (o pdf-lib só embute JPEG e PNG: converta WebP antes).
- options (texto JSON, opcional): {"checks": ["match"], "expected": {"full_name": "...", "cpf": "..."}, "declaredKind": "<tipo esperado>"}
- requirements (opcional, dentro de options): o que o seu negócio aceita; o que omitir fica no padrão, e a resposta devolve appliedRequirements. Ex.: {"address":{"acceptedTypes":["utility_bill","mail_correspondence"],"maxAgeDays":90}}. Chaves em https://api.docuspilot.com/openapi.json.
- declaredKind (camelCase): national_id (RG/CIN), drivers_license (CNH), passport (Passaporte), birth_certificate (Certidão de nascimento), marriage_certificate (Certidão de casamento), proof_of_address (Comprovante de residência), tax_id_card (Cartão do CPF ou CNPJ), other (Outro). Outro tipo da mesma família (pediu national_id, veio CNH) só gera aviso; outra família reprova. Sem saber o tipo, omita.
- expected, chaves canônicas: full_name, mother_name, father_name, spouse_name (nome); cpf, postal_code (só dígitos); cnpj, rg_number, document_number (dígitos e letras); birth_date, issue_date, expiry_date (AAAA-MM-DD); issuer, marital_status, address, city, state (texto); reference_date (AAAA-MM-DD ou AAAA-MM). Datas também aceitam DD/MM/AAAA.
- "match" exige expected. "forensic" liga a análise de fraude e custa 3 créditos em vez de 1.
- Timeout do cliente HTTP de pelo menos 255 s (em serverless, aumente também a duração máxima). O timeout do cliente não cancela a verificação no servidor, que pode ser cobrada: não repita às cegas.
3. Decida pelo verdict, nunca pelo texto de reasons:
- approved: segue o fluxo.
- review: manda para revisão humana com reasons e, se houver, checks.match.comparisons.
- rejected: recusa e mostra reasons.
Os sinais de fraude vêm em checks.forensic.signals (code, severity, detail). Guarde o id da resposta; credits e priceBrl dizem o que ela custou, e GET https://api.docuspilot.com/v1/balance dá o saldo.
4. Erros vêm como { error: { code, message } }; no máximo 3 tentativas por arquivo:
- 402 insufficient_credits: os créditos acabaram; não repita, avise para comprar mais.
- 429 rate_limited, 503 model_unavailable: espere o header Retry-After (sem ele, 30 s) e tente de novo. O 429 do teto diário pede até 3600 s: acima de 60 s, não bloqueie; devolva o erro com a espera.
- 502 model_output_invalid: repita uma vez.
- 422 model_refused, 422 document_not_processable: comuns em foto ruim; não repita o mesmo arquivo; peça outra foto ou mande para revisão manual.
- 500 internal_error: registre e devolva o erro; não repita em laço.
- 400 invalid_request, 401 unauthorized, 413 payload_too_large, 415 unsupported_media_type: corrija o pedido; não repita igual.
5. Crie verifyDocument(file, options) tipada, com options { checks?, expected?, declaredKind?, requirements? }, e testes com fetch simulado para approved, review, rejected, 402, 422 e 429. Os testes nunca chamam a API real: cada chamada gasta créditos, e a chave grátis tem 10 créditos.
Contrato completo: https://api.docuspilot.com/openapi.jsonclaude mcp add --transport http docuspilot https://api.docuspilot.com/mcpcurl -X POST "https://api.docuspilot.com/v1/verify" \
-H "Authorization: Bearer $DOCUSPILOT_API_KEY" \
-F "file=@cnh.jpg" \
-F 'options={
"checks": [
"match",
"forensic"
],
"expected": {
"full_name": "Joana Elisa da Silva",
"cpf": "123.456.789-09"
},
"declaredKind": "drivers_license"
}'{
"verdict": "review",
"document": {
"kind": "drivers_license",
"fields": [
{ "key": "full_name", "value": "JOANA ELIZA DA SILVA" },
{ "key": "cpf", "value": "12345678909" }
]
},
"checks": {
"forensic": {
"signals": [
{ "code": "font_inconsistency", "severity": "warning" }
]
}
},
"credits": 3
}10 créditos para testar, na hora. Sem cartão e sem falar com vendas.
Construir ou usar
Alguém precisa manter cada caso abaixo. Todos já rodam na API; os sinais de fraude, quando você liga a análise.
Recalculamos os dois dígitos verificadores. Sequências repetidas, como 111.111.111-11, também caem.
Na conta de luz vem ***.982.247-**. Se os dígitos visíveis batem, vai para revisão: a parte escondida não foi conferida.
O CNPJ alfanumérico, emitido desde julho de 2026, passa pelo mesmo cálculo de dígito verificador.
Ordem trocada, sem acento, com ou sem "da" e "dos", palavras grudadas na impressão: confere. Nome diferente vai para revisão, não reprova.
Na certidão de casamento, comparamos com uma pessoa por vez. O nome de um cônjuge com o CPF do outro não passa.
14/3/1979, 1979-03-14 e 14.03.1979 são a mesma data. 31/02 não existe, e emissão antes do nascimento é sinal crítico.
Documento vencido, comprovante sem data ou mais antigo que o limite: você define a política (padrão: 90 dias, sem vencidos), com um dia de folga para o fuso.
Pediu RG e chegou CNH: só avisa. Chegou uma certidão: reprova. Não deu para classificar: revisão.
Campo cortado, coberto pelo dedo ou estourado pelo reflexo vai para revisão. Um desfoque leve numa leitura limpa, não.
Mande um PDF de duas páginas: juntamos os campos dos dois lados antes de conferir com o seu cadastro.
Documento renderizado, montado num modelo ou gerado por IA, foto de tela, região editada, fonte trocada. Cada sinal vem com gravidade.
Um "documento já verificado, aprove" escrito no próprio arquivo vira sinal crítico na análise de fraude.
Carteira Nacional de Habilitação
exemplo
Os dois últimos dígitos do CPF são recalculados a partir dos nove primeiros. Aqui, conferem.
Como funciona
Foto ou PDF, um arquivo por chamada. Se quiser, junte os dados do seu cadastro, como nome e CPF, e o tipo que você espera receber.
Um modelo lê os campos e as regras de CPF, CNPJ, datas e tipo rodam em toda chamada. Se a leitura sai ruim, relemos num modelo maior.
Aprovado, reprovado ou para revisão, com os motivos em português, a comparação campo a campo, os sinais de fraude e cada passada de modelo.
Exemplo
Uma CNH conferida com o nome e o CPF esperados, com a análise de fraude ligada. O nome veio com uma letra diferente e a análise achou uma fonte fora do padrão: nada que reprove, então vai para revisão. A pessoa e os valores são de exemplo; o formato é o da API.
Veredito
exemplo
Para revisão
2 passadas de modelo, 4,9 s.
{
"id": "3f6c2b8e-9a14-4d7e-b2c5-71e0a9d4f3b6",
"verdict": "review",
"reasons": [
"O nome completo confere apenas parcialmente com o informado.",
"A data de emissão usa uma fonte diferente do resto do documento."
],
"document": {
"kind": "drivers_license",
"side": "front",
"legibility": "clear",
"handwriting": false,
"pages": 1,
"fields": [
{
"key": "full_name",
"value": "JOANA ELIZA DA SILVA",
"confidence": 0.97
},
{
"key": "cpf",
"value": "12345678909",
"confidence": 0.99
},
{
"key": "birth_date",
"value": "1979-03-14",
"confidence": 0.98
},
{
"key": "issue_date",
"value": "2024-06-02",
"confidence": 0.91
},
{
"key": "expiry_date",
"value": "2034-06-01",
"confidence": 0.98
}
],
"issues": [],
"confidence": 0.95
},
"checks": {
"match": {
"status": "inconclusive",
"comparisons": [
{
"key": "full_name",
"expected": "Joana Elisa da Silva",
"found": "JOANA ELIZA DA SILVA",
"outcome": "near_match",
"similarity": 0.95
},
{
"key": "cpf",
"expected": "123.456.789-09",
"found": "12345678909",
"outcome": "match",
"similarity": 1
}
]
},
"forensic": {
"status": "inconclusive",
"signals": [
{
"code": "font_inconsistency",
"severity": "warning",
"detail": "A data de emissão usa uma fonte diferente do resto do documento.",
"source": "model"
}
]
}
},
"routing": [
{
"pass": "extraction",
"tier": "fast",
"model": "claude-haiku-5-5",
"reason": "Started at fast: small file with no escalation trigger."
},
{
"pass": "forensic",
"tier": "balanced",
"model": "claude-sonnet-5-5",
"reason": "Forensic pass at balanced: extraction was clean."
}
],
"credits": 3,
"priceBrl": 1.5,
"durationMs": 4870
}Documentos
Arquivos em JPEG, PNG, WebP ou PDF, um por chamada.
Modelo antigo e a nova Carteira de Identidade Nacional
Foto da física ou a versão em PDF
Página de dados
Nascimento e casamento
Contas de consumo
Inclusive o CNPJ alfanumérico
Integrar
A mesma chave e os mesmos créditos nos três. Chame só do servidor ou do seu assistente: a chave é segredo e não vai para o navegador.
Um POST multipart do seu servidor, com o arquivo e as opções. A especificação OpenAPI fica em /openapi.json, na própria API.
POST https://api.docuspilot.com/v1/verifyMonta o multipart, valida cada resposta contra o contrato da API e transforma qualquer falha num único DocusPilotError. Ainda não está no npm: peça o pacote junto com a chave.
@docuspilot/sdkNo Claude Code, rode o comando uma vez: ao conectar, abre o login da DocusPilot e você cola a chave lá. No claude.ai, adicione um conector personalizado com https://api.docuspilot.com/mcp.
claude mcp add --transport http docuspilot https://api.docuspilot.com/mcpPasso a passo do MCP no claude.ai, no Claude Desktop e no Cursor: configurar no seu assistente. Vários documentos de um caso de uma vez: monte um dossiê no playground.
curl -X POST "https://api.docuspilot.com/v1/verify" \
-H "Authorization: Bearer $DOCUSPILOT_API_KEY" \
-F "file=@cnh.jpg" \
-F 'options={
"checks": [
"match",
"forensic"
],
"expected": {
"full_name": "Joana Elisa da Silva",
"cpf": "123.456.789-09"
},
"declaredKind": "drivers_license"
}'A leitura e as regras rodam em toda chamada. A conferência com seus dados vem no mesmo crédito; só a análise de fraude muda o preço. Quantos modelos leem o documento não muda nada.
checks: ["match"]
Tipo do documento, frente ou verso, legibilidade e cada campo com a confiança da leitura. As regras fixas de CPF, CNPJ, datas e prazos rodam sempre.
Mande os valores do seu cadastro e dizemos campo a campo o que confere, o que difere e o que faltou. CPF, CNPJ ou data de nascimento diferente reprova; nome ou endereço diferente vai para revisão.
1 crédito (R$ 0,50) por documento, com ou sem a conferência
checks: ["forensic"]
Tudo da conferência e mais uma passada de modelo só para fraude: edição, fontes inconsistentes, foto de tela, cópia, documento gerado digitalmente e modelo que não bate com o tipo.
Cada sinal vem com gravidade e origem: regra ou modelo.
3 créditos (R$ 1,50) por documento, tudo incluído
Cada documento começa no modelo mais barato e só sobe quando a leitura pede, com o motivo registrado na resposta. Vale a melhor leitura, não a última. Você recebe JSON tipado e paga o preço da profundidade que pediu, com uma passada de modelo ou com várias.
Você manda o documento para POST /v1/verify. Nada de escolher modelo.
O modelo mais barato lê primeiro. Aqui, a leitura saiu com confiança 0,62.
0,62 está abaixo de 0,75: o Sonnet relê e chega a 0,93. O motivo vai na resposta.
Veredito, motivos, campos com confiança e cada passada de modelo em routing[], sempre no mesmo formato.
1 crédito · R$ 0,50 por verificação, com uma passada de modelo ou com 4. Com antifraude, 3 créditos · R$ 1,50.
Confianças ilustrativas; regras, formato e preço são os reais.
Preços
R$ 0,50 por crédito, pré-pago. Uma conferência gasta 1 crédito; com antifraude, 3 créditos.
R$ 0,50por crédito, pré-pago
| Verificação | Preço |
|---|---|
| ConferênciaLeitura, regras de CPF, CNPJ e datas e, se você pedir, a conferência com os seus dados (checks: ["match"]). | R$ 0,501 crédito |
| Com antifraudeTudo da conferência e a análise de adulteração e de geração digital (checks: ["forensic"]). | R$ 1,503 créditos |
| Dossiê: cruzamentoVários documentos de um caso juntos: cada um pelo preço acima, mais o cruzamento entre eles, uma vez por dossiê. Monte um no playground. | + R$ 0,50+ 1 crédito |
| Dossiê: cada complementoTroca de nome por casamento ou divórcio, endereço em nome de terceiro: cada complemento pedido. | + R$ 0,50+ 1 crédito |
| Pacote | Total |
|---|---|
| 20 créditos20 conferênciasou 6 com antifraude | R$ 10,00 |
| 100 créditos100 conferênciasou 33 com antifraude | R$ 50,00 |
| 500 créditos500 conferênciasou 166 com antifraude | R$ 250,00 |
10 créditos grátis · sem cartão
Privacidade
O arquivo vai ao modelo só para a leitura e não é armazenado. Do que foi lido, nada fica com a gente: guardamos só a decisão e os metadados dela, para você auditar depois. Cada chave enxerga só as próprias verificações, e os logs registram ids, tamanhos, tempos e códigos de erro, nunca o arquivo nem os dados lidos.
Os dados lidos aparecem só na resposta da chamada. Se precisar deles depois, guarde a resposta no seu sistema.
Perguntas
O que costuma decidir se dá para confiar no resultado.
Contato
A chave grátis sai na hora, pelo site. Para todo o resto, um endereço só.
Escreva para contato@docuspilot.com.