> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Visão geral da API do System Facts

> O que o System Facts registra, os quatro passos para integrar um producer e as convenções que toda operação compartilha: tenant, idempotência, paginação, sensibilidade e erros.

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

***

**1. 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.

```bash theme={null}
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"
  }'
```

**2. 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.

**3. 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.

```bash theme={null}
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`.

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

**4. 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`.

```bash theme={null}
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.

```json theme={null}
{
  "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](/pt/reference/platform/system-facts/system-facts-error-list)**
>
> Consulte cada código, quando o serviço o responde e se vale tentar de novo.

> **[Registrar uma versão de contrato](/pt/reference/platform/system-facts/register-a-contract-version)**
>
> Comece pela operação que todo producer executa primeiro.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.