API
Importação de Documentos - Checklist
Guia de configuração e interpretação do checklist de validações aplicado aos documentos
POST
Importação de Documentos - Checklist
Visão Geral
O Checklist é um recurso opcional da API de Importação de Documentos que aplica um conjunto de validações específicas sobre os documentos de um lote, além da análise formalística padrão (OCR, autenticidade e biometria). Cada projeto/cliente pode ter um checklist próprio, configurado previamente pela equipe de integração com um conjunto de regras de validação (checklistCode, checklistVersion, checklistGroup) e o resultado dessas validações retorna no webhook, dentro do campo checklist.
Configurável por Atividade
O checklist é acionado através do objeto
batchActivitys no momento da importaçãoValidações Customizadas
Cada projeto possui seu próprio conjunto de códigos e regras de validação
Resultado no Webhook
As validações executadas retornam no array
checklist da respostaPrazo de Execução
Cada atividade de checklist possui um
activityLimit (prazo limite)1. Configurando o Checklist no Envio
Para aplicar um checklist ao lote, inclua o objetobatchActivitys no jsonData da requisição de importação.
Objeto batchActivitys
Define atividades vinculadas ao lote. Para acionar um checklist, utilize activityType: "3".
string
required
Tipo da atividade a ser executada sobre o lote.Valor para checklist:
"3"string
required
Data/hora limite para conclusão da atividade.Formato: ISO 8601Exemplo:
"2026-08-12T18:00:00Z"object
required
Configuração do checklist a ser aplicado ao lote. Ver estrutura abaixo.
Objeto checklist
string
required
Código do checklist a ser aplicado.
Este valor é definido pela equipe de integração no momento da homologação do projeto e é específico para cada cliente/fluxo.
integer
required
Versão do checklist a ser utilizada.
Também definido junto com a equipe de integração. Novas versões podem ser publicadas quando as regras de validação são atualizadas.
string
required
Grupo/agrupamento lógico do checklist.
Assim como os demais valores, é fornecido pela equipe de integração conforme o projeto.
Exemplo de batchActivitys
Exemplo de jsonData Completo com Checklist
2. Interpretando o Checklist no Webhook
Após o processamento, o resultado das validações do checklist retorna dentro do arraychecklist no corpo do webhook, junto aos demais campos da análise (result, penalidades, codigoRejeicao, docs).
Estrutura do Checklist (ChecklistDto)
array
required
Lista de validações realizadas. Vazio quando não há pendências identificadas pelo checklist.Estrutura:Campos:
code(string): Código da validaçãodesc(string): Descrição da validação/pendência identificada
Exemplo de Webhook com Checklist
3. Exemplos de Códigos de Validação
Os códigos abaixo são exemplos genéricos de validações comumente aplicadas por checklists de Documento de Identidade (DI) e Comprovante de Endereço (CE). Cada projeto possui seu próprio conjunto de códigos, definidos com a equipe de integração.
Documento de Identidade (DI)
Documento de Identidade (DI)
Comprovante de Endereço (CE)
Comprovante de Endereço (CE)
4. Fluxo de Interpretação
1
Verificar result
Confira o resultado geral da análise (aprovado, pendente ou rejeitado).
2
Consultar checklist
Verifique o array
checklist para identificar pendências específicas apontadas pelas regras configuradas para o projeto.3
Cruzar com penalidades e codigoRejeicao
Combine as informações do checklist com
penalidades (divergências formalísticas) e codigoRejeicao (problemas de qualidade) para uma visão completa do motivo do resultado.4
Tratar pendências
Caso o checklist aponte itens pendentes, oriente o reenvio do documento correspondente ou o tratamento manual, conforme o fluxo do seu projeto.
5. Boas Práticas
Configuração
Configuração
- Solicite à equipe de integração os valores corretos de
checklistCode,checklistVersionechecklistGrouppara o seu projeto - Sempre informe um
activityLimitcoerente com o SLA esperado do seu fluxo - Ao atualizar regras de validação, confirme com a equipe de integração se uma nova
checklistVersionfoi publicada
Tratamento do Resultado
Tratamento do Resultado
- Nunca assuma que
checklistvazio significa “sem checklist configurado” — verifique também sebatchActivitysfoi enviado - Trate cada
codedo checklist de forma programática (mapeamento código → ação), evitando depender apenas do texto emdesc - Mantenha um dicionário atualizado dos códigos específicos do seu projeto, pois eles podem divergir de um projeto para outro
Importação de Documentos - Checklist