> ## Documentation Index
> Fetch the complete documentation index at: https://docs-platform.services-valid.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Importação de Documentos - Checklist

> Guia de configuração e interpretação do checklist de validações aplicado aos documentos

## 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`.

<CardGroup cols={2}>
  <Card title="Configurável por Atividade" icon="list-check">
    O checklist é acionado através do objeto `batchActivitys` no momento da importação
  </Card>

  <Card title="Validações Customizadas" icon="sliders">
    Cada projeto possui seu próprio conjunto de códigos e regras de validação
  </Card>

  <Card title="Resultado no Webhook" icon="webhook">
    As validações executadas retornam no array `checklist` da resposta
  </Card>

  <Card title="Prazo de Execução" icon="clock">
    Cada atividade de checklist possui um `activityLimit` (prazo limite)
  </Card>
</CardGroup>

***

## 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"`.

<ResponseField name="activityType" type="string" required>
  Tipo da atividade a ser executada sobre o lote.

  **Valor para checklist:** `"3"`
</ResponseField>

<ResponseField name="activityLimit" type="string" required>
  Data/hora limite para conclusão da atividade.

  **Formato:** ISO 8601

  **Exemplo:** `"2026-08-12T18:00:00Z"`
</ResponseField>

<ResponseField name="checklist" type="object" required>
  Configuração do checklist a ser aplicado ao lote. Ver estrutura abaixo.
</ResponseField>

### Objeto `checklist`

<ResponseField name="checklistCode" type="string" required>
  Código do checklist a ser aplicado.

  <Info>
    Este valor é definido pela equipe de integração no momento da homologação do projeto e é específico para cada cliente/fluxo.
  </Info>
</ResponseField>

<ResponseField name="checklistVersion" type="integer" required>
  Versão do checklist a ser utilizada.

  <Info>
    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.
  </Info>
</ResponseField>

<ResponseField name="checklistGroup" type="string" required>
  Grupo/agrupamento lógico do checklist.

  <Info>
    Assim como os demais valores, é fornecido pela equipe de integração conforme o projeto.
  </Info>
</ResponseField>

<Warning>
  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.
</Warning>

### Exemplo de `batchActivitys`

```json theme={"theme":"catppuccin-latte"}
"batchActivitys": [
  {
    "activityType": "3",
    "activityLimit": "2026-08-12T18:00:00Z",
    "checklist": {
      "checklistCode": "{codigo_do_projeto}",
      "checklistVersion": 1,
      "checklistGroup": "{grupo_do_projeto}"
    }
  }
]
```

### Exemplo de `jsonData` Completo com Checklist

```json theme={"theme":"catppuccin-latte"}
{
  "workflowAlias": "plataforma_id",
  "batchExternalId": "LOTE-2026-001",
  "batchOrigin": "1",
  "keys": [
    { "key": "webhook_uri", "value": "https://seu-sistema.com/webhook" },
    { "key": "cpf", "value": "12345678900" }
  ],
  "batchActivitys": [
    {
      "activityType": "3",
      "activityLimit": "2026-08-12T18:00:00Z",
      "checklist": {
        "checklistCode": "{codigo_do_projeto}",
        "checklistVersion": 1,
        "checklistGroup": "{grupo_do_projeto}"
      }
    }
  ],
  "docs": [
    {
      "fileName": "documento-identidade.pdf",
      "contentType": "pdf",
      "typeAlias": "doc_identidade"
    },
    {
      "fileName": "comprovante-endereco.pdf",
      "contentType": "pdf",
      "typeAlias": "comprovante_endereco"
    }
  ]
}
```

***

## 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)

<ResponseField name="checklist" type="array" required>
  Lista de validações realizadas. Vazio quando não há pendências identificadas pelo checklist.

  **Estrutura:**

  ```json theme={"theme":"catppuccin-latte"}
  {
    "code": "di001",
    "desc": "Documento de Identidade não encontrado"
  }
  ```

  **Campos:**

  * `code` (string): Código da validação
  * `desc` (string): Descrição da validação/pendência identificada
</ResponseField>

### Exemplo de Webhook com Checklist

```json theme={"theme":"catppuccin-latte"}
{
  "dataInicio": "07/01/2026 18:12:27",
  "dataFinal": null,
  "codigoControle": 145900,
  "result": 1,
  "inconclusivo": null,
  "indiceAvaliacaoAutenticidade": 100,
  "indiceFacematch": null,
  "tipoDocumento": "CNH",
  "cpf": "12345678900",
  "origin": "document-analysis",
  "originKey": "3116063c-a61f-467a-83e5-5e3b07b66e2d",
  "customerId": "cliente-exemplo",
  "externalId": "LOTE-2026-001",
  "penalidades": [],
  "codigoRejeicao": [],
  "checklist": [
    {
      "code": "di001",
      "desc": "Documento de Identidade não encontrado"
    }
  ],
  "docs": [
    {
      "docName": "Documento de Identidade",
      "docId": 215170,
      "docType": "doc_identidade",
      "type": "cnh",
      "keys": [
        { "keyAlias": "nome", "keyName": "Nome", "value": "JOÃO DA SILVA" },
        { "keyAlias": "cpf", "keyName": "CPF", "value": "12345678900" }
      ]
    }
  ]
}
```

***

## 3. Exemplos de Códigos de Validação

<Info>
  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.
</Info>

<AccordionGroup>
  <Accordion title="Documento de Identidade (DI)" icon="id-card">
    | Código  | Descrição                                  | Detalhes                                                                                |
    | ------- | ------------------------------------------ | --------------------------------------------------------------------------------------- |
    | `di001` | Documento de Identidade não encontrado     | —                                                                                       |
    | `di002` | Tipo de documento de identidade não aceito | Somente RG ou CNH são aceitos                                                           |
    | `di003` | Documento ilegível ou incompleto           | Verifica campos obrigatórios extraídos via OCR (nome, número do documento, datas, etc.) |
    | `di004` | Documento vencido                          | Verifica data de validade quando aplicável                                              |
  </Accordion>

  <Accordion title="Comprovante de Endereço (CE)" icon="file-invoice">
    | Código  | Descrição                                           |
    | ------- | --------------------------------------------------- |
    | `ce001` | Documento de comprovante de endereço não encontrado |
    | `ce002` | Primeiro nome do titular divergente do DI           |
    | `ce003` | Último nome do titular divergente do DI             |
    | `ce004` | CPF divergente do DI                                |
    | `ce005` | Documento ilegível ou incompleto                    |
  </Accordion>
</AccordionGroup>

***

## 4. Fluxo de Interpretação

<Steps>
  <Step title="Verificar result">
    Confira o resultado geral da análise (aprovado, pendente ou rejeitado).
  </Step>

  <Step title="Consultar checklist">
    Verifique o array `checklist` para identificar pendências específicas apontadas pelas regras configuradas para o projeto.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  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).
</Warning>

***

## 5. Boas Práticas

<AccordionGroup>
  <Accordion title="Configuração" icon="gear">
    * 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
  </Accordion>

  <Accordion title="Tratamento do Resultado" icon="clipboard-check">
    * 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
  </Accordion>
</AccordionGroup>