Referência da API

Pedidos

Pedido local que agrupa as cobranças e define o total.

Criar pedido

POST/v1/ordersImplementada

Chave de API (Authorization: Bearer ep_…)· escopo orders:write· createOrder

Cria o pedido local que agrupa as cobranças. O total (amountCents) é definido aqui e nunca pelo navegador. Mesma referência com o mesmo conteúdo devolve o pedido original (200); com outro conteúdo, 409.

Escopo da chave: orders:write.

Idempotência: exige o header Idempotency-Key.

Headers de createOrder
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 createOrder
Parâmetro	Onde	Tipo	Descrição
`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 createOrder
Campo	Tipo	Descrição
`customerId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`externalOrderReference` obrigatório	texto	1–100 caracteres
`amountCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`currency` obrigatório	Currency (texto)
`description`	texto	0–500 caracteres
`fulfillmentPolicy` obrigatório	"ON_FULLY_PAID" \| "ON_FIRST_PAID"
`items`	lista de objeto	Só exibição; o total é amountCents. 0–50 itens
`items[].name` obrigatório	texto	1–120 caracteres
`items[].quantity` obrigatório	inteiro	1 a 10000
`items[].unitAmountCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`metadata`	mapa

Exemplo

curl -X POST "$ECLIPTA_PAY_API/v1/orders" \
  -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 '{"customerId":"cus_01JDY8A1B2C3D4E5F6G7H8J9KA","externalOrderReference":"pedido-98765","amountCents":"14970","currency":"BRL","description":"Plano anual","fulfillmentPolicy":"ON_FULLY_PAID"}'

Resposta 201: Recurso criado.

Campos da resposta 201 de createOrder
Campo	Tipo	Descrição
`id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`customerId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`externalOrderReference` obrigatório	texto
`amountCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`confirmedCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`receivedCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`refundedCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`overpaidCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`status` obrigatório	"OPEN" \| "PARTIALLY_PAID" \| "PAYMENT_COMPLETED" \| "REFUND_PENDING" \| "PARTIALLY_REFUNDED" \| "REFUNDED" \| "DISPUTED" \| "CANCELLED"
`fulfillmentEligible` obrigatório	booleano
`mode` obrigatório	texto ou nulo
`version` obrigatório	inteiro	1 a 9007199254740991
`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)))$

Exemplo 201

{
  "id": "ord_01JDY8B1B2C3D4E5F6G7H8J9KB",
  "customerId": "cus_01JDY8A1B2C3D4E5F6G7H8J9KA",
  "externalOrderReference": "pedido-98765",
  "amountCents": "14970",
  "confirmedCents": "0",
  "receivedCents": "0",
  "refundedCents": "0",
  "overpaidCents": "0",
  "status": "OPEN",
  "fulfillmentEligible": false,
  "mode": null,
  "version": 1,
  "createdAt": "2026-11-13T13:00:00.000Z"
}

Erros

Erros de createOrder
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.
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.

Listar pedidos

GET/v1/ordersEspecificada

Chave de API (Authorization: Bearer ep_…)· escopo orders:read· listOrders

Listar pedidos.

Situação: especificada, ainda não implementada nesta versão.

Escopo da chave: orders:read.

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

Parâmetros de listOrders
Parâmetro	Onde	Tipo	Descrição
`cursor`	query	texto	0–200 caracteres
`limit`	query	inteiro	1 a 100 · padrão 20
`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/orders" \
  -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
  -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT"

Resposta 200: Sucesso.

Campos da resposta 200 de listOrders
Campo	Tipo	Descrição
`data` obrigatório	lista de Order
`data[].id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`data[].customerId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`data[].externalOrderReference` obrigatório	texto
`data[].amountCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`data[].confirmedCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`data[].receivedCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`data[].refundedCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`data[].overpaidCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`data[].status` obrigatório	"OPEN" \| "PARTIALLY_PAID" \| "PAYMENT_COMPLETED" \| "REFUND_PENDING" \| "PARTIALLY_REFUNDED" \| "REFUNDED" \| "DISPUTED" \| "CANCELLED"
`data[].fulfillmentEligible` obrigatório	booleano
`data[].mode` obrigatório	texto ou nulo
`data[].version` obrigatório	inteiro	1 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)))$
`nextCursor` obrigatório	texto ou nulo

Erros

Erros de listOrders
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 pedido

GET/v1/orders/{id}Implementada

Chave de API (Authorization: Bearer ep_…)· escopo orders:read· getOrder

Total, valores confirmados/recebidos/estornados e se o pedido já pode ser entregue (fulfillmentEligible).

Escopo da chave: orders:read.

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

Parâmetros de getOrder
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/orders/{id}" \
  -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
  -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT"

Resposta 200: Sucesso.

Campos da resposta 200 de getOrder
Campo	Tipo	Descrição
`id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`customerId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`externalOrderReference` obrigatório	texto
`amountCents` obrigatório	PositiveCents (texto)	formato ^[1-9][0-9]{0,14}$
`confirmedCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`receivedCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`refundedCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`overpaidCents` obrigatório	Cents (texto)	formato ^(0\|[1-9][0-9]{0,14})$
`status` obrigatório	"OPEN" \| "PARTIALLY_PAID" \| "PAYMENT_COMPLETED" \| "REFUND_PENDING" \| "PARTIALLY_REFUNDED" \| "REFUNDED" \| "DISPUTED" \| "CANCELLED"
`fulfillmentEligible` obrigatório	booleano
`mode` obrigatório	texto ou nulo
`version` obrigatório	inteiro	1 a 9007199254740991
`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)))$

Exemplo 200

{
  "id": "ord_01JDY8B1B2C3D4E5F6G7H8J9KB",
  "customerId": "cus_01JDY8A1B2C3D4E5F6G7H8J9KA",
  "externalOrderReference": "pedido-98765",
  "amountCents": "14970",
  "confirmedCents": "14970",
  "receivedCents": "0",
  "refundedCents": "0",
  "overpaidCents": "0",
  "status": "PAYMENT_COMPLETED",
  "fulfillmentEligible": true,
  "mode": "PIX",
  "version": 3,
  "createdAt": "2026-11-13T13:00:00.000Z"
}

Erros

Erros de getOrder
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.

Todas as rotas