API do DATTA — Visão Geral

Tudo o que você faz na interface do DATTA também pode ser feito por API: buscar, enviar documentos, disparar triagens, consultar o catálogo, ler painéis. É o caminho para integrar o DATTA aos seus sistemas — um portal interno, um robô de ingestão, um pipeline de dados ou um cliente de BI externo.

Esta seção concentra toda a referência de API da plataforma. Os guias de uso das demais seções descrevem as funcionalidades pela interface; quando uma capacidade também existe via API, ela aponta para cá.

Base e formato

• Base URL: o mesmo endereço da plataforma (ex.: https://datta.suaorg.gov.br). Todos os caminhos começam com /api/.
• Formato: JSON (UTF-8) em requisições e respostas.
• Erros: respostas de erro trazem um corpo JSON com o campo error contendo mensagem descritiva em português. Trate sempre error (com fallback para message).

Autenticação

A API usa o mesmo mecanismo de sessão da interface: um token JWT obtido no login.

1. Autentique-se com suas credenciais DATTA:

curl -X POST "$BASE/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username": "seu.usuario", "password": "sua-senha"}'

1. A resposta traz o token. Envie-o em toda chamada seguinte no header Authorization:

curl "$BASE/api/catalog/datasets" \
  -H "Authorization: Bearer $TOKEN"

• Tokens expiram; renove refazendo o login. Erros 401 com mensagem de sessão expirada indicam token vencido.
• As permissões do usuário valem também na API: um usuário sem acesso a uma funcionalidade na interface recebe 403 na chamada equivalente.

Proteção contra CSRF em mutações

Chamadas que alteram estado (criação, edição, exclusão) exigem o header X-Requested-With:

curl -X DELETE "$BASE/api/exemplo/recurso/123" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Requested-With: XMLHttpRequest"

Sem esse header, a plataforma bloqueia a mutação por segurança.

Onde encontrar cada API

• Referência de endpoints por área — busca, chat, documentos, triagem, catálogo, painéis, conexões e mais, com exemplos.
• Exportação de conhecimento — exporte ativos de conhecimento curados para sistemas externos.

Boas práticas

• Um token por integração: crie um usuário dedicado para cada sistema integrado (em Sistema›Usuários), com o papel de menor privilégio que atenda o caso.
• Trate limites: operações custosas (exportações, execuções em lote) têm limites de frequência; respeite respostas 429 aguardando antes de repetir.
• Acompanhe pela interface: execuções disparadas por API aparecem em Execuções como qualquer outra — mesma trilha de auditoria, mesmos status CONCLUIDA e FALHOU.