Uma integração pensada
para confiança mútua.

Entrada na rede

O desenho abaixo é uma proposta para discussão técnica. Os critérios finais de participação, contratos, ambientes e procedimentos serão definidos antes de qualquer operação.

1. Identificação e alinhamento

   Validar a instituição e seus responsáveis, discutir finalidade de uso e formalizar responsabilidades. O formulário de interesse não realiza essa validação.

2. Configuração de segurança

   Trocar certificados públicos e cadeias por canal autenticado, cadastrar IPs fixos de saída e provisionar credenciais com permissões limitadas.

3. Homologação antes da produção

   Validar autenticação, autorização, contrato de eventos e procedimentos de atualização com dados sintéticos em ambiente separado.

Segurança em camadas

mTLS obrigatório

Cliente e servidor validam seus certificados. A troca envolve apenas certificados públicos e cadeias de confiança. Chaves privadas permanecem sob controle de seu titular e nunca devem ser enviadas pelo formulário ou compartilhadas com o Bastião.

IPs autorizados

O acesso depende de uma lista de IPs fixos de saída da instituição. Faixas amplas não devem ser liberadas. Mudanças de endereço precisam de validação e atualização prévia.

OAuth2 Client Credentials

Um token Bearer identifica a integração e limita suas operações. Os escopos propostos são events:write para registro e events:read para consulta. OAuth2 complementa mTLS e a lista de IPs.

A proposta deve incluir expiração, rotação e revogação de certificados e credenciais, além de trilhas de auditoria e resposta a incidentes.

Registrar um evento

Exemplo ilustrativo de um registro com status under_review. O evento informa um indício em análise; não estabelece fraude confirmada.

curl --request POST 'https://api.bastiao.example/v1/events' \
  --cert "$CLIENT_CERT_PATH" \
  --key "$CLIENT_KEY_PATH" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "subject": {"cnpj": "00000000000000"},
    "category": "suspected_identity_fraud",
    "status": "under_review",
    "occurred_at": "2026-01-15T12:00:00Z",
    "reference": "synthetic-event-001"
  }'

Todos os dados são sintéticos. O CNPJ é um placeholder e não deve ser usado como cadastro válido. O domínio .example não é um endpoint operacional. As variáveis apontam para credenciais e arquivos locais; nunca inclua chaves privadas em payloads.

{
  "id": "evt_synthetic_001",
  "status": "under_review",
  "created_at": "2026-01-15T12:01:00Z"
}

Consultar eventos

A consulta proposta retorna sinais acessíveis à instituição autenticada, conforme finalidade e autorização. A identidade do responsável pelo relato não integra a resposta pública proposta.

curl 'https://api.bastiao.example/v1/events?cnpj=00000000000000' \
  --cert "$CLIENT_CERT_PATH" \
  --key "$CLIENT_KEY_PATH" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

{
  "events": [{
    "id": "evt_synthetic_001",
    "category": "suspected_identity_fraud",
    "status": "under_review",
    "occurred_at": "2026-01-15T12:00:00Z"
  }]
}

Exemplos não incluem dados reais, tokens ou identificação de relatores. Paginação, limites de uso e tratamento de erros serão definidos na versão final do contrato.

Registros precisam de contexto

O modelo proposto distingue eventos em análise (under_review), confirmados após avaliação (confirmed) e descartados (dismissed). Critérios, permissões de transição, correções e prazos de retenção ainda dependem da definição de governança.

As informações devem apoiar a análise da instituição, com controles de qualidade e mecanismos de contestação. A participação e cada tratamento de dados dependem da avaliação das obrigações regulatórias e das bases legais aplicáveis.