🔌 API de Ingestão

Como começar

O token

Autenticação por Bearer token no cabeçalho:

Authorization: Bearer ing_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Escopo

Cada token grava apenas nas entidades marcadas pelo administrador. Um token do SIEM que tenta gravar em emissao recebe 403 — e a mensagem diz explicitamente que a entidade existe, mas está fora do escopo, para você não perder tempo procurando erro de digitação no nome.

Descobrir os campos

# O que este token pode gravar, e com quais campos
curl "https://SEU-DOMINIO/api/ingestao-pub/entidades" \
  -H "Authorization: Bearer $TOKEN"

Resposta (recortada):

{
  "sucesso": true,
  "dados": {
    "token": { "nome": "SIEM Produção", "prefixo": "ing_AbCdEfGh", "modo": "UPSERT" },
    "maxLinhasPorRequisicao": 500,
    "entidades": [{
      "entidade": "incidente_seguranca",
      "nome": "Incidentes de segurança (ISO 27001)",
      "endpoint": "POST /api/ingestao-pub/incidente_seguranca",
      "campos": [
        { "campo": "codigo", "rotulo": "Código *", "obrigatorio": true,
          "tipo": "texto", "exemplo": "INC-2026-0007" },
        { "campo": "tipo", "rotulo": "Tipo (CIA) *", "obrigatorio": true,
          "descricao": "Confidencialidade, Integridade ou Disponibilidade...",
          "exemplo": "Disponibilidade" }
      ]
    }]
  }
}

Enviar dados

Formato do corpo

{
  "linhas": [
    { "campo1": "valor", "campo2": "valor" },
    { "campo1": "valor", "campo2": "valor" }
  ]
}

Regras que valem para todas as entidades:

Resposta

{
  "sucesso": true,
  "mensagem": "2 linha(s) gravada(s), 1 recusada(s).",
  "dados": {
    "entidade": "incidente_seguranca",
    "modo": "UPSERT",
    "preview": false,
    "loteId": "8f3c...",
    "totalLinhas": 3,
    "gravadas": 2,
    "recusadas": 1,
    "resultados": [
      { "linha": 1, "status": "OK", "id": "a1b2..." },
      { "linha": 2, "status": "OK", "id": "c3d4...", "aviso": "Ativo \"AT-9\" não está no inventário — incidente gravado sem vínculo com ativo." },
      { "linha": 3, "status": "ERRO", "erros": ["Data de detecção: \"32/13/2026\" não é uma data válida (use DD/MM/AAAA)."] }
    ]
  }
}

Exemplos por entidade

SIEM → incidente de segurança

Atenção ao campo tipo: ele classifica a propriedade violada (a tríade Confidencialidade / Integridade / Disponibilidade), não o vetor de ataque. Ransomware que derrubou o serviço é "Disponibilidade" — "Ransomware" e "Vazamento de dados" não são valores válidos.

curl -X POST "https://SEU-DOMINIO/api/ingestao-pub/incidente_seguranca" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "linhas": [{
      "codigo": "INC-2026-0007",
      "titulo": "Indisponibilidade do portal de protocolo",
      "descricao": "Falha no cluster de banco deixou o portal fora por 4h10",
      "tipo": "Disponibilidade",
      "severidade": "Alta",
      "dataDeteccao": "12/03/2026",
      "status": "Encerrado",
      "ativoAfetado": "AT-2026-0001",
      "dadosPessoaisEnvolvidos": "Não",
      "rootCause": "Disco cheio no nó primário sem alerta configurado"
    }]
  }'

Scanner de vulnerabilidade → inventário de ativos

curl -X POST "https://SEU-DOMINIO/api/ingestao-pub/ativo_informacao/preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"linhas":[{"codigo":"AT-SRV-0042","nome":"Servidor de aplicação — nó 2"}]}'

Repare no /preview: rode assim até a saída ficar limpa. Só então tire o sufixo.

GRC → risco corporativo

curl -X POST "https://SEU-DOMINIO/api/ingestao-pub/risco_corporativo" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"linhas":[{"codigo":"R-2026-014","titulo":"Dependência de fornecedor único de nuvem"}]}'

Medidor / ERP → ESG

curl -X POST "https://SEU-DOMINIO/api/ingestao-pub/consumo_energia" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"linhas":[{"competencia":"03/2026"}]}'

Códigos de erro

Erro sempre traz sucesso: false, um codigo estável (bom para tratar no seu código) e um erro em texto (bom para o log).

Perguntas