Introdução - Liquerapay

A API Liquerapay segue um conjunto pequeno de convenções que se repetem em todos os endpoints. Conhecê-las economiza tempo e evita surpresas.

Princípios

REST: cada recurso tem uma URL e usa verbos HTTP (GET, POST, PATCH, DELETE).
JSON: requisições e respostas são JSON com Content-Type: application/json.
Centavos: todos os valores monetários são inteiros em centavos. Nunca use float.
Cursor pagination: listas usam paginação bidirecional por cursor (after/before + limit).

Envelope de resposta

Toda resposta segue o padrão { data, error, success }.

{
  "data": {
    "id": "cust_018f3a2b7c4d7c40a1b2",
    "name": "João Silva"
  },
  "error": null,
  "success": true
}

{
  "data": [
    { "id": "chg_018f8e2d9a5f7b10c3d4", "amount": 5000, "status": "PAID" },
    { "id": "chg_018f8e2e0a1b7c20d3e4", "amount": 1500, "status": "PENDING" }
  ],
  "pagination": {
    "hasMore": true,
    "next": "eyJjcmVhdGVkQXQiOiIyMDI2LTA0LTE5In0",
    "before": null
  },
  "error": null,
  "success": true
}

{
  "error": "VALIDATION_ERROR",
  "message": "amount: deve ser um número inteiro positivo",
  "success": false
}

Códigos HTTP

Código	Quando acontece
`200`	Sucesso (`GET`, `PATCH`, `DELETE`)
`201`	Recurso criado com sucesso (`POST`)
`400`	Validação ou regra de negócio violada
`401`	Token inválido ou ausente
`403`	Operação não permitida (ex.: saques bloqueados)
`404`	Recurso não encontrado
`409`	Conflito (ex.: documento duplicado)
`429`	Rate limit excedido
`500`	Erro interno (tente novamente)

Códigos de erro mais comuns

`error`	Significado
`VALIDATION_ERROR`	Falha de validação no body / query params
`UNAUTHORIZED`	Token inválido, ausente ou revogado
`FORBIDDEN`	Operação não permitida para este merchant
`NOT_FOUND`	Recurso solicitado não existe
`CONFLICT`	Duplicidade detectada
`BAD_REQUEST`	Regra de negócio violada (ex.: saldo insuficiente)
`RATE_LIMITED`	Excedeu o limite de requisições
`INTERNAL_ERROR`	Erro inesperado no servidor

Paginação

Listas são paginadas por cursor bidirecional, não por offset. Para buscar a próxima página:

Faça GET /transparents/list?limit=20
Pegue o pagination.next da resposta
Faça GET /transparents/list?limit=20&after={next}
Repita até pagination.hasMore === false

curl "https://api.liquerapay.com/transparents/list?limit=50" \
  -H "Authorization: Bearer $LIQUERAPAY_API_KEY"

limit aceita valores entre 1 e 100 (padrão: 20). Use before (em vez de after) para navegar para a página anterior.

​Princípios

​Envelope de resposta

​Códigos HTTP

​Códigos de erro mais comuns

​Paginação

Princípios

Envelope de resposta

Códigos HTTP

Códigos de erro mais comuns

Paginação