Documentação da API

Base URL

Todos os endpoints desta documentação são relativos à base URL abaixo. Use sempre HTTPS em produção para garantir a confidencialidade dos dados em trânsito.

https://api.immutablelog.com

Autenticação*

Toda requisição à API precisa de um token de acesso enviado no header `Authorization` com o esquema Bearer. Você obtém seu token na área do cliente, em Chave de API. Tokens têm o prefixo `iml_live_` para ambiente de produção. Guarde-o com segurança — ele autentica operações de escrita e leitura no seu tenant.

Authorization: Bearer iml_live_xxxxxxxxxxxxxxxx

Dica de segurança: Nunca exponha o token em código cliente (frontend) ou repositórios públicos. Use variáveis de ambiente no servidor.

Idempotency-Key*

Para ingestão de eventos, recomendamos enviar um header `Idempotency-Key` único por requisição. Se a mesma chave for reenviada (por exemplo, em um retry após timeout de rede), o servidor reconhece a duplicata e responde com o mesmo resultado sem criar um segundo evento no ledger.

Idempotency-Key: seed-42-550e8400-e29b-41d4-a716-446655440000
Request-Id: 8d0b5f06-6d1f-4d3c-9b4f-9f5a2d7b3c1a

Quando usar: Recomendado para retries automáticos, workers assíncronos e integrações event-driven onde a entrega at-least-once é garantida pelo broker.

Timezone do cliente (opcional)

Para evitar a “confusão de data” (UTC vs horário local), você pode enviar o horário local do cliente via headers. O servidor mantém o tempo canônico em UTC para ordenação/prova e persiste esses valores apenas como metadado não-confiável para exibição no dashboard.

X-Client-Time: 2026-02-05T21:13:22-03:00
X-Client-TZ: America/Sao_Paulo
X-Client-Offset-Minutes: -180

`X-Client-Time` (ISO8601) é o mais importante. `X-Client-TZ` e `X-Client-Offset-Minutes` são opcionais e ajudam a UI a exibir corretamente. `Request-Id` é recomendado para rastreabilidade (logs/suporte).

curl -X POST https://api.immutablelog.com/v1/events \
  -H "X-Client-Time: 2026-02-05T21:00:00-03:00" \
  -H "X-Client-TZ: America/Sao_Paulo" \
  -H "X-Client-Offset-Minutes: -180" \
  -H "Request-Id: req-123" \
  -d '{"payload":"..."}'

Estrutura do Payload

O corpo de cada requisição de ingestão contém dois campos: `payload` e `meta`. O campo `payload` é tratado como uma string opaca pelo servidor — seu conteúdo não é interpretado, apenas armazenado e hasheado. Isso garante que o hash seja calculado sobre exatamente o que você enviou, sem nenhuma transformação.

{
  "payload": "{\"id\":\"d6b6c2e5-0c1a-4b92-9a62-2f2c4c2e9a2a\",\"kind\":\"info\",\"message\":\"http.GET.user-me\",\"context\":{\"user_id\":123,\"email\":\"user@example.com\"},\"timestamp\":\"2026-02-05T12:00:00Z\"}",
  "meta": {
    "type": "info",
    "event_name": "http.GET.user-me",
    "service": "api",
    "env": "prod",
    "trace_id": "2c3f4f1e-7d2d-4d10-9c47-0f8d7a1b2c3d"
  }
}

Limite: Limite de tamanho: ~16KB por evento. Payloads maiores devem ser armazenados externamente (ex: S3, banco de dados) e o evento deve conter apenas o identificador e metadados relevantes.

Ingestão de eventos

Envie eventos via `POST /v1/events`. O servidor calcula o hash SHA-256 do payload, armazena o evento e o inclui no próximo bloco do ledger imutável. A resposta retorna o `tx_id` (identificador único da transação) e o `payload_hash`, que você pode usar para verificar integridade futuramente.

curl -X POST https://api.immutablelog.com/v1/events \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Idempotency-Key: seed-42-550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": "{\"id\":\"d6b6c2e5-0c1a-4b92-9a62-2f2c4c2e9a2a\",\"kind\":\"info\",\"message\":\"http.GET.user-me\"}",
    "meta": {
      "type": "info",
      "event_name": "http.GET.user-me",
      "service": "api",
      "env": "prod",
      "trace_id": "2c3f4f1e-7d2d-4d10-9c47-0f8d7a1b2c3d"
    }
  }'

Importante: Salve o `tx_id` retornado na resposta no seu sistema. Ele é necessário para consultar o evento individualmente e para gerar a prova de inclusão.

Consulta de eventos

A API oferece dois modos de consulta: listagem com filtros e paginação, ou busca direta por ID de transação. Use a listagem para varreduras e auditorias de período; use a busca por ID quando precisar verificar um evento específico.

curl "https://api.immutablelog.com/v1/events?from_ts=1704067200&to_ts=1704153600&limit=100&type=info" \
  -H "Authorization: Bearer YOUR_TOKEN"

curl "https://api.immutablelog.com/v1/events/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": 1704067200,
  "payload": "{\"id\":\"d6b6c2e5\",\"kind\":\"info\",\"message\":\"Event received\"}",
  "payload_parsed": { "id": "d6b6c2e5", "kind": "info", "message": "Event received" },
  "payload_hash": "4f2b8e9a3c5d7f1e2a4b6c8d0e1f3a5b7c9d1e3f5a7b9c1d3e5f7a9b1c3d5e7",
  "meta": {
    "tenant_id": "...",
    "type": "info",
    "event_name": "Event received"
  }
}

Estatísticas

O endpoint de estatísticas retorna o volume de eventos agrupado por dia, com breakdown por tipo (`success`, `info`, `warning`, `error`). Útil para dashboards operacionais, relatórios de auditoria e monitoramento de anomalias de volume.

curl "https://api.immutablelog.com/v1/events/stats?days=7&tz_offset_minutes=-180" \
  -H "Authorization: Bearer YOUR_TOKEN"

curl "https://api.immutablelog.com/v1/events/stats?from_ts=1769904000&to_ts=1770422399&tz_offset_minutes=-180" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "stats": [
    {
      "date": "2026-02-01",
      "count": 8186,
      "timestamp": 1769904000,
      "by_type": {
        "success": 4523,
        "info": 2103,
        "error": 1203,
        "warning": 357
      }
    },
    {
      "date": "2026-02-02",
      "count": 7892,
      "timestamp": 1769990400,
      "by_type": { "success": 4201, "info": 2145, "error": 1198, "warning": 348 }
    }
  ],
  "total": 54600,
  "total_by_type": {
    "success": 30003,
    "info": 15087,
    "error": 6657,
    "warning": 2853
  }
}

`GET /v1/events/:tx_id/proof` retorna a prova Merkle que demonstra criptograficamente que um evento específico foi incluído no ledger exatamente como enviado, sem modificação. Essa prova é independente e pode ser verificada por qualquer terceiro sem precisar confiar no ImmutableLog.

A prova é verificável criptograficamente e independe de confiar no operador do sistema. Ideal para auditorias externas, disputas contratuais e compliance regulatório.

curl "https://api.immutablelog.com/v1/events/a1b2c3d4-e5f6-7890-abcd-ef1234567890/proof" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "tx_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tx_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "payload_hash": "4f2b8e9a3c5d7f1e2a4b6c8d0e1f3a5b7c9d1e3f5a7b9c1d3e5f7a9b1c3d5e7",
  "block_index": 48291,
  "block_hash": "0x9a2e8f7c4b1d3a5e7f9b1c3d5e7f9a1b3c5d7e9f1a3b5c7d9e1f3a5b7c9d1e",
  "prev_hash": "0x8f1c2a4b6d8e0f2a4c6e8f0a2c4e6f8a0c2e4f6a8c0e2f4a6c8e0f2a4c6e8",
  "merkle_root": "0x7d9e1f3a5b7c9d1e3f5a7b9c1d3e5f7a9b1c3d5e7f9a1b3c5d7e9f1a3b5c",
  "merkle_path": [
    { "hash": "0xabc123...", "position": "left" },
    { "hash": "0xdef456...", "position": "right" },
    { "hash": "0x789abc...", "position": "left" }
  ]
}

Como verificar: Como verificar: recalcule a raiz Merkle combinando o `tx_hash` do evento com os hashes do `merkle_path` (respeitando as posições `left`/`right`). Se o resultado corresponder ao `merkle_root` do bloco, a inclusão está provada.

Respostas da API

A API segue convenções REST padrão. Todos os corpos de resposta são JSON. Abaixo estão os principais status HTTP que você pode encontrar e o que fazer em cada caso.

{
  "ok": true,
  "tx_id": "3f227a2d-ae7b-4fde-95a5-313197cc6b3a",
  "payload_hash": "00cf048489f716479f124654cdb7c3551a05b46a1245eaaac34bd2fe933f2fd3",
  "status": "accepted",
  "duplicate": false,
  "request_id": "f7ba7cfe-bb18-454c-af2f-19404719b421"
}

{
  "ok": false,
  "reason": "unauthorized"
}

{
  "ok": false,
  "reason": "forbidden"
}

{
  "ok": false,
  "reason": "monthly_limit_exceeded: 50000/50000 events used this billing cycle"
}