Visão geral da API do System Facts

O System Facts é o registro compartilhado do que aconteceu nos seus fluxos de negócio. Cada serviço que participa de um fluxo, chamado de producer, envia um fato imutável quando um momento de negócio acontece. Um pedido é feito. Um pagamento é liquidado. O System Facts confere cada fato contra o contrato que o producer registrou, armazena o fato uma única vez e liga os fatos que compartilham uma referência em um único fluxo. Assim você pergunta o que aconteceu com o pedido ORD-2026-000123 e recebe todos os fatos desse fluxo, de todos os producers, em uma só resposta. Um fato armazenado nunca muda. O System Facts registra e correlaciona. Ele não edita o histórico.

Conceitos

Termo	Significado
Producer	Um serviço que envia fatos, como `checkout-api` ou `payments-api`.
Namespace	O nome separado por pontos sob o qual um producer envia seus fatos, como `acme.checkout`. O primeiro serviço que registra um contrato para um producer e um namespace passa a ser o dono deles.
Tipo de fato	O nome de um tipo de momento de negócio, como `checkout.order_placed`.
Contrato	Uma versão semântica de um tipo de fato, com o JSON Schema do payload e as referências que os fatos carregam.
Tipo de referência	Um tipo nomeado de identificador de negócio, como `acme.order_id`. Você o registra uma vez, com escopo, correlação, sensibilidade e a configuração searchable.
Referência	Um identificador que um fato carrega: um tipo de referência, um valor e um escopo. Por exemplo, `acme.order_id` `ORD-2026-000123` com escopo `storeId: store-sp-01`.
Subject	A entidade de negócio sobre a qual o fato fala, dada como um tipo e um id, como `checkout.order` `ORD-2026-000123`.
Fato	Um registro imutável de que um momento de negócio aconteceu. É enviado como um envelope com o subject, as referências e o payload (`data`).
Fluxo	O grupo de fatos ligados por suas referências. Um `flowAggregationId` o identifica.

Um tipo de referência com correlation: exact liga o seu fato a todo fato que carrega a mesma referência. Quando um fato liga dois fluxos, eles se unem em um só. O id do fluxo absorvido continua resolvendo para o fluxo que sobrevive. Um tipo de referência registrado com searchable: true pode listar todo fato que o carrega.

Integre em quatro passos

Registre os tipos de referência

Registre cada tipo de identificador que seus fatos carregam com PUT /v1/reference-types/{type}, como acme.order_id e acme.payment_id. Faça isso no pipeline de deploy, antes de qualquer contrato usar o tipo.

curl -X PUT "$SYSTEM_FACTS_URL/v1/reference-types/acme.order_id" \
  -H "Authorization: Bearer $SYSTEM_FACTS_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": ["storeId"],
    "sensitivity": "none",
    "correlation": "exact",
    "searchable": true,
    "description": "Order number assigned by the checkout service, unique within a store"
  }'

Registre uma versão de contrato

Registre uma versão de cada tipo de fato com PUT /v1/contracts/{producer}/{namespace}/{type}/{schemaVersion}. Faça isso no pipeline de deploy, antes do rollout do producer. O System Facts só aceita fatos depois que o registro tem sucesso.

Envie fatos

Envie um envelope por momento de negócio com POST /v1/facts. Use a credencial de serviço do producer para o tenant.

curl -X POST "$SYSTEM_FACTS_URL/v1/facts" \
  -H "Authorization: Bearer $SYSTEM_FACTS_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "envelopeVersion": 1,
    "factId": "01a15493-ba10-7b21-9d44-3c1f8e2a9b01",
    "producer": "checkout-api",
    "namespace": "acme.checkout",
    "type": "checkout.order_placed",
    "schemaVersion": "1.0.0",
    "occurredAt": "2026-10-19T14:32:10Z",
    "subject": { "type": "checkout.order", "id": "ORD-2026-000123" },
    "references": [
      {
        "type": "acme.order_id",
        "value": "ORD-2026-000123",
        "scope": { "storeId": "store-sp-01" }
      }
    ],
    "data": { "amount": "129.90", "currency": "BRL" }
  }'

Um primeiro envio responde 201.

{
  "factId": "01a15493-ba10-7b21-9d44-3c1f8e2a9b01",
  "producer": "checkout-api",
  "flowAggregationId": "01a15493-bdf8-7c55-b0e2-6f4a1d9e7c33",
  "duplicate": false,
  "ingestedAt": "2026-10-19T14:32:11Z"
}

Leia os fluxos

Leia um fluxo pelo id com GET /v1/flows/{flowAggregationId}. Encontre o único fluxo de uma referência com GET /v1/flows/by-reference. Liste todo fato que carrega uma referência searchable com GET /v1/flows.

curl -G "$SYSTEM_FACTS_URL/v1/flows/by-reference" \
  -H "Authorization: Bearer $SYSTEM_FACTS_BEARER_TOKEN" \
  --data-urlencode "referenceType=acme.order_id" \
  --data-urlencode "referenceValue=ORD-2026-000123" \
  --data-urlencode "storeId=store-sp-01"

Toda escrita é idempotente, então um producer pode reenviar depois de um timeout.

Autenticação e permissões

Toda requisição, exceto os health probes públicos, envia Authorization: Bearer <token>. Fatos e fluxos pertencem ao tenant do token. Os catálogos de tipos de referência e de contratos são compartilhados por todos os tenants do deploy.

Operação	Permissão
`GET /v1/reference-types`, `GET /v1/reference-types/{type}`, `GET /v1/contracts`, `GET /v1/contracts/{producer}/{namespace}/{type}`, `GET /v1/contracts/{producer}/{namespace}/{type}/{schemaVersion}`	`contracts:read`
`PUT /v1/reference-types/{type}`, `PUT /v1/contracts/{producer}/{namespace}/{type}/{schemaVersion}`	`contracts:read`, `contracts:write` e `catalog:reserved`. Todo nome de catálogo fica sob um prefixo reservado.
`POST /v1/contracts/{producer}/{namespace}/{type}/{schemaVersion}/deprecate`	`contracts:read` e `contracts:write`, mais `catalog:deprecate` para uma versão cujo namespace você não possui
`POST /v1/facts`	`facts:read` e `facts:write`
`GET /v1/flows/{flowAggregationId}`, `GET /v1/flows/by-reference`, `GET /v1/flows`	`facts:read`. Com `facts:reveal`, os valores encrypted voltam em texto claro.

Uma permissão ausente responde 403 SF-0014. Um token ausente ou inválido responde 401 SF-0013.

Convenções

Tenant. O serviço sempre toma o tenant do token. Ele nunca lê um tenant de um caminho, de um parâmetro de consulta ou de um corpo.
Escritas idempotentes. Um primeiro registro ou envio responde 201. A mesma requisição de novo responde 200 e não muda nada. O envio de um fato acrescenta duplicate: true.
Imutabilidade. Uma versão de contrato, um tipo de referência e um fato nunca mudam. Conteúdo diferente sob a mesma identidade responde 409. Um tipo de referência pode ganhar um mask de exibição uma vez.
Paginação. Uma lista responde uma página e um nextCursor. Envie-o de volta como o parâmetro de cursor da página que você quer. Trate-o como opaco. Pare quando ele for omitido.
Timestamps. RFC 3339 em UTC, como 2026-10-19T14:32:10Z.
Tamanho. Um envelope de fato tem no máximo 256 KiB por padrão. Um envelope maior responde 413 SF-0012.
Nomes. O primeiro segmento separado por ponto de todo nome de namespace e de tipo de referência deve ser um dos prefixos reservados do deploy. O padrão é lerian. Estas páginas usam acme.

Sensibilidade e valores protegidos

A sensitivity de um tipo de referência decide como as leituras mostram seus valores. Um contrato pode marcar campos do payload da mesma forma com x-sensitivity.

Sensibilidade	O que uma leitura retorna
`none`	O valor como foi enviado.
`masked`	`**` mais os últimos 4 caracteres de um valor de 12 ou mais caracteres, e apenas `**` nos outros casos. Nunca o valor em texto claro.
`hashed`	O digest com chave `hmac-sha256:v1:<hex>`. Nunca o valor em texto claro.
`encrypted`	Armazenado selado com AES-256-GCM. Retorna mascarado, ou em texto claro para um chamador que tem `facts:reveal`.

Com mask: document, um valor masked mostra ***.456.789-** para 11 dígitos e **.345.678/0001-** para 14 dígitos. O System Facts recusa qualquer outra quantidade de dígitos no envio. Toda classe correlaciona exatamente como none, porque a comparação parte do valor em texto claro. Todo digest armazenado tem chave. Ele nunca é um hash simples. Um valor protegido volta com protected: true, e os campos protegidos do payload aparecem em protectedFields. Para encontrar um fluxo por uma referência protegida, envie sempre o valor em texto claro. O System Facts calcula o digest dele e compara com o digest armazenado.

Erros

Todo erro é application/problem+json (RFC 9457) com um code estável.

{
  "code": "SF-0009",
  "detail": "Verify the identifier: an identifier absorbed by a merge still resolves, an unknown one does not.",
  "instance": "0199c1f07a3e7b219d443c1f8e2a9b01",
  "status": 404,
  "title": "Not Found",
  "type": "https://errors.lerian.studio/v1/SF-0009"
}

Lista de erros

Consulte cada código, quando o serviço o responde e se vale tentar de novo.

Registrar uma versão de contrato

Comece pela operação que todo producer executa primeiro.

Visão geral

Tipos de referência

Contratos

Fatos

Fluxos

Tratamento de erros

Visão geral da API do System Facts

Conceitos

Integre em quatro passos

Autenticação e permissões

Convenções

Sensibilidade e valores protegidos

Erros

Lista de erros

Registrar uma versão de contrato

​Conceitos

​Integre em quatro passos

​Autenticação e permissões

​Convenções

​Sensibilidade e valores protegidos

​Erros

Lista de erros

Registrar uma versão de contrato

Conceitos

Integre em quatro passos

Autenticação e permissões

Convenções

Sensibilidade e valores protegidos

Erros