Referência da API

Eventos

Catálogo versionado de eventos dos últimos 30 dias.

Eventos dos últimos 30 dias

GET/v1/eventsImplementada

Chave de API (Authorization: Bearer ep_…)· escopo events:read· listEvents

Eventos públicos dos últimos 30 dias, do mais recente para o mais antigo, para recuperar perdas. Filtros por tipo, agregado e janela de criação.

Escopo da chave: events:read.

Headers de listEvents
Header	Obrigatório	Descrição
`X-Account-Id`	sim	Conta permitida pelos grants do principal.

Parâmetros de listEvents
Parâmetro	Onde	Tipo	Descrição
`cursor`	query	texto	0–200 caracteres
`limit`	query	inteiro	1 a 100 · padrão 20
`type`	query	texto	0–80 caracteres
`aggregateId`	query	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`createdFrom`	query	data e hora (ISO 8601)	formato ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`createdTo`	query	data e hora (ISO 8601)	formato ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`Eclipta-Pay-Version`	header	"2026-11-13"	Versão de data do contrato. Opcional; a resposta sempre informa a versão usada. Valor desconhecido responde 400 UNSUPPORTED_API_VERSION.

Exemplo

curl -X GET "$ECLIPTA_PAY_API/v1/events" \
  -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
  -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT"

Resposta 200: Sucesso.

Campos da resposta 200 de listEvents
Campo	Tipo	Descrição
`data` obrigatório	lista de Event
`data[].eventId` obrigatório	Id (texto)	Identificador estável do evento; o mesmo em todas as tentativas e reenvios. Deduplique por ele. 8–160 caracteres · formato ^[A-Za-z0-9_]+$
`data[].type` obrigatório	texto	Tipo do catálogo (ex.: payment.confirmed).
`data[].apiVersion` obrigatório	"2026-11-13"	Versão de contrato do envelope.
`data[].occurredAt` obrigatório	data e hora (ISO 8601)	formato ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`data[].tenantId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`data[].accountId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`data[].environment` obrigatório	Environment
`data[].aggregateId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`data[].aggregateVersion` obrigatório	inteiro	Versão do agregado; descarte eventos com versão menor que a já aplicada. 1 a 9007199254740991
`data[].data` obrigatório	mapa
`nextCursor` obrigatório	texto ou nulo

Exemplo 200

{
  "data": [
    {
      "eventId": "evt_01JDY9C1B2C3D4E5F6G7H8J9KH",
      "type": "order.payment_completed",
      "apiVersion": "2026-11-13",
      "occurredAt": "2026-11-13T13:00:00.000Z",
      "tenantId": "org_01JDY7Q2M3N4P5R6S7T8V9W0XA",
      "accountId": "acc_01JDY7Q2M3N4P5R6S7T8V9W0XB",
      "environment": "sandbox",
      "aggregateId": "ord_01JDY8B1B2C3D4E5F6G7H8J9KB",
      "aggregateVersion": 1,
      "data": {
        "orderId": "ord_01JDY8B1B2C3D4E5F6G7H8J9KB",
        "confirmedCents": "14970",
        "currency": "BRL"
      }
    }
  ],
  "nextCursor": null
}

Erros

Erros de listEvents
HTTP	Exemplo de code	Quando
400	`INVALID_REQUEST`	Requisição inválida: fieldErrors aponta cada campo.
401	`INVALID_API_KEY`	Chave de API ausente, inválida, expirada ou revogada.
403	`SCOPE_MISSING`	Escopo ausente, conta não permitida em X-Account-Id, IP fora da lista ou conta suspensa.
429	`TOO_MANY_REQUESTS`	Limite de requisições da chave atingido (rajada de 100 e 6.000 por minuto). Toda resposta traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset; o 429 traz Retry-After em segundos. Aguarde e repita com a mesma Idempotency-Key.

Consultar evento

GET/v1/events/{id}Implementada

Chave de API (Authorization: Bearer ep_…)· escopo events:read· getEvent

Consulta um evento pelo eventId, no mesmo envelope entregue por webhook.

Escopo da chave: events:read.

Headers de getEvent
Header	Obrigatório	Descrição
`X-Account-Id`	sim	Conta permitida pelos grants do principal.

Parâmetros de getEvent
Parâmetro	Onde	Tipo	Descrição
`id` obrigatório	caminho	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`Eclipta-Pay-Version`	header	"2026-11-13"	Versão de data do contrato. Opcional; a resposta sempre informa a versão usada. Valor desconhecido responde 400 UNSUPPORTED_API_VERSION.

Exemplo

curl -X GET "$ECLIPTA_PAY_API/v1/events/{id}" \
  -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
  -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT"

Resposta 200: Sucesso.

Campos da resposta 200 de getEvent
Campo	Tipo	Descrição
`eventId` obrigatório	Id (texto)	Identificador estável do evento; o mesmo em todas as tentativas e reenvios. Deduplique por ele. 8–160 caracteres · formato ^[A-Za-z0-9_]+$
`type` obrigatório	texto	Tipo do catálogo (ex.: payment.confirmed).
`apiVersion` obrigatório	"2026-11-13"	Versão de contrato do envelope.
`occurredAt` obrigatório	data e hora (ISO 8601)	formato ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`tenantId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`accountId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`environment` obrigatório	Environment
`aggregateId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`aggregateVersion` obrigatório	inteiro	Versão do agregado; descarte eventos com versão menor que a já aplicada. 1 a 9007199254740991
`data` obrigatório	mapa

Exemplo 200

{
  "eventId": "evt_01JDY9C1B2C3D4E5F6G7H8J9KH",
  "type": "order.payment_completed",
  "apiVersion": "2026-11-13",
  "occurredAt": "2026-11-13T13:00:00.000Z",
  "tenantId": "org_01JDY7Q2M3N4P5R6S7T8V9W0XA",
  "accountId": "acc_01JDY7Q2M3N4P5R6S7T8V9W0XB",
  "environment": "sandbox",
  "aggregateId": "ord_01JDY8B1B2C3D4E5F6G7H8J9KB",
  "aggregateVersion": 1,
  "data": {
    "orderId": "ord_01JDY8B1B2C3D4E5F6G7H8J9KB",
    "confirmedCents": "14970",
    "currency": "BRL"
  }
}

Erros

Erros de getEvent
HTTP	Exemplo de code	Quando
400	`INVALID_REQUEST`	Requisição inválida: fieldErrors aponta cada campo.
401	`INVALID_API_KEY`	Chave de API ausente, inválida, expirada ou revogada.
403	`SCOPE_MISSING`	Escopo ausente, conta não permitida em X-Account-Id, IP fora da lista ou conta suspensa.
404	`RESOURCE_NOT_FOUND`	Recurso inexistente nesta conta (inclusive recurso de outra conta ou de outro tenant).
429	`TOO_MANY_REQUESTS`	Limite de requisições da chave atingido (rajada de 100 e 6.000 por minuto). Toda resposta traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset; o 429 traz Retry-After em segundos. Aguarde e repita com a mesma Idempotency-Key.

Reenviar evento aos endpoints

POST/v1/events/{id}/resendImplementada

Chave de API (Authorization: Bearer ep_…)· escopo webhooks:write· resendEvent

Reenvia o evento para um endpoint específico (mesmo que ele não estivesse inscrito quando o evento ocorreu) ou para os endpoints ativos inscritos no tipo. Mantém uma entrega por evento × endpoint.

Escopo da chave: webhooks:write.

Idempotência: exige o header Idempotency-Key.

Headers de resendEvent
Header	Obrigatório	Descrição
`X-Account-Id`	sim	Conta permitida pelos grants do principal.
`Idempotency-Key`	sim	Chave única por intenção (16 a 128 caracteres visíveis). Ao refazer a mesma chamada, repita a mesma chave: o resultado gravado é devolvido. Mesma chave com outro conteúdo responde 409 IDEMPOTENCY_CONFLICT.

Parâmetros de resendEvent
Parâmetro	Onde	Tipo	Descrição
`id` obrigatório	caminho	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`Eclipta-Pay-Version`	header	"2026-11-13"	Versão de data do contrato. Opcional; a resposta sempre informa a versão usada. Valor desconhecido responde 400 UNSUPPORTED_API_VERSION.

Corpo da requisição

Campos do corpo de resendEvent
Campo	Tipo	Descrição
`endpointId`	Id (texto)	Reenviar só para este endpoint (mesmo que não estivesse inscrito quando o evento ocorreu). Sem ele, reenvia para os endpoints ativos inscritos no tipo. 8–160 caracteres · formato ^[A-Za-z0-9_]+$

Exemplo

curl -X POST "$ECLIPTA_PAY_API/v1/events/{id}/resend" \
  -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
  -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT" \
  -H "Idempotency-Key: <uma chave por intenção>" \
  -H "Content-Type: application/json" \
  -d '{"endpointId":"whk_01JDY9A1B2C3D4E5F6G7H8J9KF"}'

Resposta 202: Aceito: a intenção foi registrada; acompanhe o resultado (não é transação concluída).

Campos da resposta 202 de resendEvent
Campo	Tipo	Descrição
`data` obrigatório	lista de Delivery
`data[].id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`data[].eventId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`data[].eventType` obrigatório	texto
`data[].endpointId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`data[].state` obrigatório	"PENDING" \| "SENDING" \| "SUCCEEDED" \| "FAILED" \| "CANCELLED"
`data[].attempts` obrigatório	inteiro	0 a 9007199254740991
`data[].maxAttempts` obrigatório	inteiro	1 a 9007199254740991
`data[].nextAttemptAt` obrigatório	data e hora (ISO 8601) ou nulo
`data[].lastAttemptAt` obrigatório	data e hora (ISO 8601) ou nulo
`data[].lastHttpStatus` obrigatório	inteiro ou nulo
`data[].lastErrorCode` obrigatório	texto ou nulo
`data[].replayCount` obrigatório	inteiro	0 a 9007199254740991
`data[].createdAt` obrigatório	data e hora (ISO 8601)	formato ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`data[].attemptLog`	lista de DeliveryAttempt	Tentativas registradas (só na consulta individual).
`data[].attemptLog[].sequence` obrigatório	inteiro	1 a 9007199254740991
`data[].attemptLog[].trigger` obrigatório	"AUTOMATIC" \| "REPLAY" \| "TEST"
`data[].attemptLog[].startedAt` obrigatório	data e hora (ISO 8601)	formato ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`data[].attemptLog[].durationMs` obrigatório	inteiro ou nulo
`data[].attemptLog[].outcome` obrigatório	"SUCCEEDED" \| "HTTP_ERROR" \| "REDIRECT_NOT_FOLLOWED" \| "TIMEOUT" \| "NETWORK_ERROR" \| "DESTINATION_BLOCKED" \| "RESPONSE_TOO_LARGE" \| "INTERRUPTED"
`data[].attemptLog[].httpStatus` obrigatório	inteiro ou nulo
`data[].attemptLog[].errorCode` obrigatório	texto ou nulo
`data[].attemptLog[].responseExcerpt` obrigatório	texto ou nulo	Até 1 KB do início da resposta, com sequências que parecem documentos, cartões, e-mails ou credenciais mascaradas.
`nextCursor` obrigatório	texto ou nulo

Exemplo 202

{
  "data": [
    {
      "id": "whd_01JDY9B1B2C3D4E5F6G7H8J9KG",
      "eventId": "evt_01JDY9C1B2C3D4E5F6G7H8J9KH",
      "eventType": "order.payment_completed",
      "endpointId": "whk_01JDY9A1B2C3D4E5F6G7H8J9KF",
      "state": "PENDING",
      "attempts": 1,
      "maxAttempts": 9,
      "nextAttemptAt": "2026-11-13T13:00:00.000Z",
      "lastAttemptAt": "2026-11-13T13:00:00.000Z",
      "lastHttpStatus": 200,
      "lastErrorCode": null,
      "replayCount": 1,
      "createdAt": "2026-11-13T13:00:00.000Z"
    }
  ],
  "nextCursor": null
}

Erros

Erros de resendEvent
HTTP	Exemplo de code	Quando
400	`INVALID_REQUEST`	Requisição inválida: fieldErrors aponta cada campo.
401	`INVALID_API_KEY`	Chave de API ausente, inválida, expirada ou revogada.
403	`SCOPE_MISSING`	Escopo ausente, conta não permitida em X-Account-Id, IP fora da lista ou conta suspensa.
404	`RESOURCE_NOT_FOUND`	Recurso inexistente nesta conta (inclusive recurso de outra conta ou de outro tenant).
409	`IDEMPOTENCY_CONFLICT`	Conflito de idempotência (IDEMPOTENCY_CONFLICT), requisição em andamento com a mesma chave (REQUEST_IN_PROGRESS) ou estado do recurso.
422	`CAPABILITY_UNAVAILABLE`	Regra de negócio ou capacidade indisponível para a conta.
429	`TOO_MANY_REQUESTS`	Limite de requisições da chave atingido (rajada de 100 e 6.000 por minuto). Toda resposta traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset; o 429 traz Retry-After em segundos. Aguarde e repita com a mesma Idempotency-Key.

Todas as rotas