Skip to main content
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ção

Validaçõ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 resposta

Prazo 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 objeto batchActivitys 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.
Os valores de checklistCode, checklistVersion e checklistGroup não são genéricos — cada cliente recebe seus próprios valores durante a configuração do projeto. Consulte a equipe de integração para obter os valores corretos do seu fluxo.

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 array checklist 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ção
  • desc (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.

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.
Um array checklist vazio significa que não houve pendências identificadas pelas regras configuradas — não confundir com a ausência do recurso de checklist no lote (quando batchActivitys não foi enviado na requisição).

5. Boas Práticas

  • Solicite à equipe de integração os valores corretos de checklistCode, checklistVersion e checklistGroup para o seu projeto
  • Sempre informe um activityLimit coerente com o SLA esperado do seu fluxo
  • Ao atualizar regras de validação, confirme com a equipe de integração se uma nova checklistVersion foi publicada
  • Nunca assuma que checklist vazio significa “sem checklist configurado” — verifique também se batchActivitys foi enviado
  • Trate cada code do checklist de forma programática (mapeamento código → ação), evitando depender apenas do texto em desc
  • Mantenha um dicionário atualizado dos códigos específicos do seu projeto, pois eles podem divergir de um projeto para outro