Dossiê

Manual de Integração — API Direct Data

---

Produto: Dossiê — Consolidação de Dados em Relatório

Base URL: /api/Dossier

Autenticação: Header Token (Guid)

Versão: 2.0

1. Visão Geral

1.1 Descrição do Produto

O Dossiê é o produto Direct Data que consolida em um único relatório os retornos de múltiplas APIs configuradas em um Template, para um ou mais documentos (CPFs ou CNPJs). Cada dossiê passa por um ciclo assíncrono — é criado, processado pelas APIs do template e fica disponível para consulta detalhada e/ou geração de PDF.

Esta API permite ao cliente: processar novos dossiês a partir de um template, consultar templates disponíveis, status e detalhes (resumo ou completo), gerar PDF de um dossiê concluído, listar o histórico filtrado e habilitar/desabilitar o monitoramento de um dossiê.

1.2 Conceitos-Chave

Antes de usar a API, é importante entender as três entidades centrais do produto:

1.3 Autenticação

Todos os endpoints exigem autenticação via header Token contendo o GUID de API emitido pela Direct Data para a sua empresa. Esse token é único por empresa e deve ser tratado como credencial sensível.

1.4 Estrutura de Resposta Padrão

Todas as respostas (exceto GeneratePDF, que retorna o binário do PDF em caso de sucesso) estendem o envelope ResponseMetaDataDTO. Independente de sucesso ou falha, o cliente sempre receberá os campos abaixo no corpo da resposta:

{
  "success": true,
  "status": "OK",
  "elapsedTimeMs": 124,
  "dateTimeExecution": "08/05/2026 14:32:15",
  "error": null
}

1.5 Enumeradores

PersonType (tipo de pessoa)

Usado em GET /Templates (filtro) e em respostas de histórico:

Estrutura de Status do Dossiê

O ciclo de vida de um dossiê é descrito por três campos independentes, todos do tipo { id, description }. Os três aparecem juntos no envelope dossierStatus de GET /Status, GET /Details e GET /Full-Details, e também em POST /History (como situationType, resultType e status).

situation — Situação do dossiê

Representa em qual etapa do ciclo de processamento o dossiê está.

resultType — Tipo do resultado consolidado

Reflete o desfecho do processamento sob a ótica do dado retornado pelas APIs do template.

status — Apontamento agregado

Sintetiza o nível de atenção exigido pelo conjunto de APIs consultadas.

1.6 Fluxo de Integração Recomendado

O fluxo padrão de uso da API combina descoberta de templates, processamento, polling de status e consulta de detalhes:

2. Endpoints POST

2.1 Process

Inicia o processamento de um ou mais dossiês a partir de um template e uma lista de documentos (CPFs ou CNPJs). Retorna imediatamente os dossieIDs criados — o processamento das APIs do template ocorre de forma assíncrona. Acompanhe o progresso via GET /Status.

Body da Requisição

Exemplo de Requisição

POST /api/Dossier/Process HTTP/1.1
Host: {base-url-directdata}
Token: 00000000-0000-0000-0000-000000000000
Content-Type: application/json

{
  "templateID": "TPL-9c4b1e02",
  "documents": [
    "12345678000190",
    "98765432000110"
  ]
}

Exemplo de Resposta (200)

{
  "success": true,
  "status": "OK",
  "elapsedTimeMs": 245,
  "dateTimeExecution": "08/05/2026 14:32:15",
  "error": null,
  "dossierProcesses": [
    {
      "dossieID": "DOS-f1e2d3c4-...",
      "document": "12345678000190",
      "message": "Dossiê em processamento."
    },
    {
      "dossieID": "DOS-a5b6c7d8-...",
      "document": "98765432000110",
      "message": "Dossiê em processamento."
    }
  ]
}

Campos da Resposta

2.2 History

Retorna o histórico paginado de dossiês da empresa autenticada com filtros por data, tipo de pessoa, status, template, etc. Use a paginação via take para controlar o volume de resultados.

Body da Requisição

Exemplo de Requisição

POST /api/Dossier/History HTTP/1.1
Host: {base-url-directdata}
Token: 00000000-0000-0000-0000-000000000000
Content-Type: application/json

{
  "startDate": "2026-04-01",
  "endDate": "2026-05-08",
  "personType": 2,
  "take": 50
}

Exemplo de Resposta (200)

{
  "success": true,
  "status": "OK",
  "elapsedTimeMs": 312,
  "dateTimeExecution": "08/05/2026 14:35:02",
  "error": null,
  "histories": [
    {
      "guid": "DOS-f1e2d3c4-...",
      "name": "EXEMPLO TECNOLOGIA LTDA",
      "date": "07/05/2026",
      "user": "joao.silva@cliente.com.br",
      "company": "Cliente Exemplo Ltda",
      "hasMonitor": true,
      "iCanView": true,
      "resultType":    { "id": 6, "description": "Finalizado" },
      "situationType": { "id": 3, "description": "Concluído" },
      "status":        { "id": 1, "description": "Regular" },
      "templateName": "Análise Tributária PJ",
      "personType": "Pessoa Jurídica",
      "version": "1.0"
    }
  ]
}

Campos da Resposta — histories[]

2.3 GeneratePDF

Retorna o PDF de um dossiê concluído. Em caso de sucesso, a resposta é um arquivo application/pdf binário (não JSON).

Query Parameters

Exemplo de Requisição

POST /api/Dossier/GeneratePDF?dossieID=DOS-f1e2d3c4-... HTTP/1.1
Host: {base-url-directdata}
Token: 00000000-0000-0000-0000-000000000000

Resposta de Sucesso

Em caso de sucesso, a resposta é o binário do PDF — Content-Type: application/pdf, com o nome do arquivo igual ao dossieID.

Resposta de Erro

Em caso de erro, a resposta segue o envelope padrão ResponseMetaDataDTO em JSON (com success: false e o detalhe em error).

3. Endpoints GET

3.1 Templates

Lista os templates disponíveis para a empresa autenticada, filtrados pelo tipo de pessoa.

Query Parameters

Exemplo de Requisição

GET /api/Dossier/Templates?personType=2 HTTP/1.1
Host: {base-url-directdata}
Token: 00000000-0000-0000-0000-000000000000

Exemplo de Resposta (200)

{
  "success": true,
  "status": "OK",
  "elapsedTimeMs": 88,
  "dateTimeExecution": "08/05/2026 14:30:01",
  "error": null,
  "templates": [
    {
      "id": "TPL-9c4b1e02",
      "name": "Análise Tributária PJ",
      "date": "12/01/2026",
      "personType": 2
    }
  ]
}

Campos da Resposta — templates[]

3.2 Status

Consulta o status atual de um dossiê. Use este endpoint como polling após POST /Process, até que situation indique conclusão.

Query Parameters

Exemplo de Requisição

GET /api/Dossier/Status?dossieID=DOS-f1e2d3c4-... HTTP/1.1
Host: {base-url-directdata}
Token: 00000000-0000-0000-0000-000000000000

Exemplo de Resposta (200)

{
  "success": true,
  "status": "OK",
  "elapsedTimeMs": 38,
  "dateTimeExecution": "08/05/2026 14:33:18",
  "error": null,
  "dossierStatus": {
    "situation":  { "id": 3, "description": "Concluído" },
    "resultType": { "id": 6, "description": "Finalizado" },
    "status":     { "id": 1, "description": "Regular" }
  }
}

Os três campos seguem o padrão { id, description } descrito em 1.5 Enumeradores.

3.3 Details

Retorna o resumo das APIs do dossiê e seus alertas, sem o payload completo. Use para listar todas as APIs com seu status individual e priorização. Para o conteúdo completo (payload object), use Full-Details.

Query Parameters

Exemplo de Requisição

GET /api/Dossier/Details?dossieID=DOS-f1e2d3c4-... HTTP/1.1
Host: {base-url-directdata}
Token: 00000000-0000-0000-0000-000000000000

Exemplo de Resposta (200)

{
  "success": true,
  "status": "OK",
  "elapsedTimeMs": 124,
  "dateTimeExecution": "08/05/2026 14:34:12",
  "error": null,
  "listDetails": [
    {
      "nameAPI": "Receita Federal CNPJ",
      "moduleName": "Cadastro",
      "apiID": "API-001",
      "hasPdf": false,
      "origin": "Template",
      "statusPriority": "Sucesso",
      "alertList": [
        {
          "resultType": { "id": 6, "description": "Finalizado" }
        }
      ]
    }
  ],
  "dossierStatus": {
    "situation":  { "id": 3, "description": "Concluído" },
    "resultType": { "id": 6, "description": "Finalizado" },
    "status":     { "id": 1, "description": "Regular" }
  }
}

Campos da Resposta — listDetails[]

O bloco dossierStatus segue a mesma estrutura descrita em GET /Status.

3.4 Full-Details

Retorna o conteúdo completo do dossiê — incluindo o sumário com nome do documento processado, o retorno bruto de cada API (object), histórico de monitoramento e, quando disponível, a análise de IA (aiAnalysis).

Query Parameters

Exemplo de Requisição

GET /api/Dossier/Full-Details?dossieID=DOS-f1e2d3c4-... HTTP/1.1
Host: {base-url-directdata}
Token: 00000000-0000-0000-0000-000000000000

Exemplo de Resposta (200)

{
  "success": true,
  "status": "OK",
  "elapsedTimeMs": 412,
  "dateTimeExecution": "08/05/2026 14:36:45",
  "error": null,
  "summary": {
    "name": "EXEMPLO TECNOLOGIA LTDA",
    "document": "12.345.678/0001-90",
    "lastUpdate": "07/05/2026",
    "hasMonitored": true,
    "status": "Concluído",
    "frequency": "Mensal",
    "templateName": "Análise Tributária PJ",
    "personType": 2
  },
  "details": [
    {
      "nameAPI": "Receita Federal CNPJ",
      "apiID": "API-001",
      "hasPdf": false,
      "origin": "Template",
      "moduleName": "Cadastro",
      "alertList": [],
      "object": { "...": "payload completo da API" },
      "result": "Sucesso",
      "statusPriority": "Sucesso",
      "hasChanged": false,
      "lastUpdated": "07/05/2026",
      "monitoringHistory": [
        {
          "api": "Receita Federal CNPJ",
          "apiID": "API-001",
          "monitoringID": "MON-...",
          "events": [
            { "date": "07/05/2026", "event": "Sem alteração detectada", "guid": "..." }
          ]
        }
      ],
      "aiInsights": []
    }
  ],
  "dossierStatus": {
    "situation":  { "id": 3, "description": "Concluído" },
    "resultType": { "id": 6, "description": "Finalizado" },
    "status":     { "id": 1, "description": "Regular" }
  },
  "aiAnalysis": null
}

Campos da Resposta — summary

Campos da Resposta — details[]

Campos Restantes

4. Endpoints PATCH

4.1 Monitoring-Config

Habilita ou desabilita o monitoramento de um dossiê. Quando habilitado, o dossiê passa a ser reexecutado periodicamente e gera eventos a cada alteração detectada — visíveis em Full-Details.details[].monitoringHistory[].

Query Parameters

Body da Requisição

Exemplo de Requisição

PATCH /api/Dossier/Monitoring-Config?dossieID=DOS-f1e2d3c4-... HTTP/1.1
Host: {base-url-directdata}
Token: 00000000-0000-0000-0000-000000000000
Content-Type: application/json

{
  "monitoring": true
}

Exemplo de Resposta (200)

{
  "success": true,
  "status": "OK",
  "elapsedTimeMs": 76,
  "dateTimeExecution": "08/05/2026 14:38:02",
  "error": null
}

5. Mapeamento de Erros por Endpoint

5.1 Estrutura do Erro

Quando uma requisição falha, o envelope ResponseMetaDataDTO retorna o campo error preenchido com o nome do campo problemático e a mensagem correspondente. O campo success será false e o status HTTP refletirá o tipo de falha.

// Exemplo de resposta 401 Unauthorized (token inválido)
{
  "success": false,
  "status": "Unauthorized",
  "elapsedTimeMs": 12,
  "dateTimeExecution": "08/05/2026 14:40:01",
  "error": {
    "fieldName": "Token",
    "message": "Token de acesso inválido. Verifique suas credenciais."
  }
}

// Exemplo de resposta 404 Not Found (dossiê não pertence à empresa)
{
  "success": false,
  "status": "Not Found",
  "elapsedTimeMs": 28,
  "dateTimeExecution": "08/05/2026 14:40:14",
  "error": {
    "fieldName": "dossieID",
    "message": "Dossiê não encontrado."
  }
}

5.2 Tabela Consolidada

Mesma família de erros se aplica a todos os endpoints da controller.