Templates

Gerencie templates de extração que definem os campos esperados para cada tipo de documento.

Endpoints

Método	Endpoint	Descrição
`POST`	`/api/v1/data-extraction/templates`	Criar template
`GET`	`/api/v1/data-extraction/templates`	Listar templates
`GET`	`/api/v1/data-extraction/templates/:id`	Obter template
`PATCH`	`/api/v1/data-extraction/templates/:id`	Atualizar template
`DELETE`	`/api/v1/data-extraction/templates/:id`	Excluir template

Criar Template

POST https://data-extraction.stg.catalisa.app/api/v1/data-extraction/templates
Authorization: Bearer {token}
Content-Type: application/json

Request Body

{
  "data": {
    "type": "extraction-template",
    "attributes": {
      "name": "RG - Registro Geral",
      "description": "Template para extração de dados do RG brasileiro",
      "documentType": "RG",
      "expectedFields": [
        {
          "name": "nome",
          "type": "string",
          "description": "Nome completo do titular",
          "required": true
        },
        {
          "name": "rg",
          "type": "string",
          "description": "Número do RG",
          "required": true
        },
        {
          "name": "cpf",
          "type": "string",
          "description": "CPF do titular",
          "required": false
        },
        {
          "name": "dataNascimento",
          "type": "date",
          "description": "Data de nascimento",
          "required": true,
          "format": "DD/MM/YYYY"
        },
        {
          "name": "filiacao",
          "type": "string",
          "description": "Nome dos pais",
          "required": false
        },
        {
          "name": "naturalidade",
          "type": "string",
          "description": "Cidade e estado de nascimento",
          "required": false
        }
      ],
      "customPrompt": "Extraia os dados do RG brasileiro. Retorne apenas os campos solicitados.",
      "isActive": true
    }
  }
}

Atributos

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome identificador do template
`description`	string	Não	Descrição do template
`documentType`	string	Sim	Tipo do documento (RG, CNH, COMPROVANTE, etc.)
`expectedFields`	array	Sim	Lista de campos esperados
`customPrompt`	string	Não	Prompt customizado para o LLM
`isActive`	boolean	Não	Se está ativo (default: true)

Estrutura de Campo (expectedFields)

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do campo (camelCase)
`type`	enum	Sim	Tipo: `string`, `number`, `date`, `boolean`, `array`, `object`
`description`	string	Não	Descrição do campo para o LLM
`required`	boolean	Não	Se é obrigatório (default: false)
`format`	string	Não	Formato esperado (ex: `DD/MM/YYYY`)

Response (201 Created)

{
  "data": {
    "type": "extraction-template",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "links": {
      "self": "/api/v1/data-extraction/templates/550e8400-e29b-41d4-a716-446655440000"
    },
    "attributes": {
      "name": "RG - Registro Geral",
      "description": "Template para extração de dados do RG brasileiro",
      "documentType": "RG",
      "expectedFields": [...],
      "customPrompt": "Extraia os dados do RG brasileiro...",
      "isActive": true,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  }
}

Templates Comuns

CNH - Carteira Nacional de Habilitação

{
  "name": "CNH - Carteira Nacional de Habilitação",
  "documentType": "CNH",
  "expectedFields": [
    { "name": "nome", "type": "string", "required": true },
    { "name": "cpf", "type": "string", "required": true },
    { "name": "dataNascimento", "type": "date", "required": true },
    { "name": "rg", "type": "string", "required": false },
    { "name": "categoria", "type": "string", "required": true, "description": "Categoria da CNH (A, B, AB, etc.)" },
    { "name": "validade", "type": "date", "required": true },
    { "name": "primeiraHabilitacao", "type": "date", "required": false },
    { "name": "registro", "type": "string", "required": true, "description": "Número do registro da CNH" }
  ]
}

Comprovante de Residência

{
  "name": "Comprovante de Residência",
  "documentType": "COMPROVANTE_RESIDENCIA",
  "expectedFields": [
    { "name": "nome", "type": "string", "required": true, "description": "Nome do titular da conta" },
    { "name": "endereco", "type": "string", "required": true, "description": "Endereço completo" },
    { "name": "cep", "type": "string", "required": true },
    { "name": "cidade", "type": "string", "required": true },
    { "name": "estado", "type": "string", "required": true },
    { "name": "dataEmissao", "type": "date", "required": true },
    { "name": "tipoServico", "type": "string", "required": false, "description": "Tipo do serviço (água, luz, telefone, etc.)" }
  ]
}

Contracheque / Holerite

{
  "name": "Contracheque",
  "documentType": "CONTRACHEQUE",
  "expectedFields": [
    { "name": "nome", "type": "string", "required": true },
    { "name": "cpf", "type": "string", "required": true },
    { "name": "empresa", "type": "string", "required": true },
    { "name": "cnpj", "type": "string", "required": false },
    { "name": "cargo", "type": "string", "required": false },
    { "name": "competencia", "type": "string", "required": true, "description": "Mês/ano de referência" },
    { "name": "salarioBruto", "type": "number", "required": true },
    { "name": "salarioLiquido", "type": "number", "required": true },
    { "name": "descontos", "type": "number", "required": false },
    { "name": "dataAdmissao", "type": "date", "required": false }
  ]
}

Extrato Bancário

{
  "name": "Extrato Bancário",
  "documentType": "EXTRATO_BANCARIO",
  "expectedFields": [
    { "name": "banco", "type": "string", "required": true },
    { "name": "agencia", "type": "string", "required": true },
    { "name": "conta", "type": "string", "required": true },
    { "name": "titular", "type": "string", "required": true },
    { "name": "periodo", "type": "string", "required": true, "description": "Período do extrato" },
    { "name": "saldoInicial", "type": "number", "required": false },
    { "name": "saldoFinal", "type": "number", "required": true },
    {
      "name": "transacoes",
      "type": "array",
      "required": false,
      "description": "Lista de transações com data, descrição e valor"
    }
  ]
}

Listar Templates

GET https://data-extraction.stg.catalisa.app/api/v1/data-extraction/templates
Authorization: Bearer {token}

Query Parameters

Parâmetro	Tipo	Descrição
`page[number]`	integer	Número da página
`page[size]`	integer	Itens por página
`filter[documentType]`	string	Filtrar por tipo de documento
`filter[isActive]`	boolean	Filtrar por status

Response (200 OK)

{
  "links": {
    "self": "/api/v1/data-extraction/templates?page[number]=1&page[size]=20"
  },
  "meta": {
    "totalItems": 5,
    "totalPages": 1,
    "currentPage": 1,
    "pageSize": 20
  },
  "data": [
    {
      "type": "extraction-template",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "attributes": {
        "name": "RG - Registro Geral",
        "documentType": "RG",
        "isActive": true,
        "createdAt": "2024-01-15T10:30:00Z"
      }
    }
  ]
}

Custom Prompts

O campo customPrompt permite personalizar as instruções enviadas ao LLM:

{
  "customPrompt": "Você é um especialista em extração de dados de documentos brasileiros. Analise a imagem do RG e extraia os dados solicitados. Retorne os valores exatamente como aparecem no documento. Para datas, use o formato DD/MM/YYYY. Se um campo não estiver visível ou legível, retorne null."
}

Boas Práticas para Prompts

Seja específico: Mencione o tipo de documento e país
Defina formatos: Especifique formatos de data, moeda, etc.
Trate ausências: Instrua o que fazer com campos ilegíveis
Mantenha consistência: Use os mesmos nomes de campos

Erros Comuns

Código	Erro	Descrição
400	`VALIDATION_ERROR`	Campos obrigatórios ausentes ou inválidos
404	`NOT_FOUND`	Template não encontrado
409	`CONFLICT`	Já existe um template com este nome

Endpoints​

Criar Template​

Request Body​

Atributos​

Estrutura de Campo (expectedFields)​

Response (201 Created)​

Templates Comuns​

CNH - Carteira Nacional de Habilitação​

Comprovante de Residência​

Contracheque / Holerite​

Extrato Bancário​

Listar Templates​

Query Parameters​

Response (200 OK)​

Custom Prompts​

Boas Práticas para Prompts​

Erros Comuns​

Endpoints

Criar Template

Request Body

Atributos

Estrutura de Campo (expectedFields)

Response (201 Created)

Templates Comuns

CNH - Carteira Nacional de Habilitação

Comprovante de Residência

Contracheque / Holerite

Extrato Bancário

Listar Templates

Query Parameters

Response (200 OK)

Custom Prompts

Boas Práticas para Prompts

Erros Comuns