Skip to main content

​
Visao geral

Os endpoints de /v1/customers permitem registrar e consultar clientes vinculados a sua conta Payle. Os registros sao utilizados em fluxos de cobranca, pagamentos recorrentes e faturamento.

​
Autenticacao

Todos os endpoints exigem o header x-api-key: <sua-chave> gerado no dashboard Payle. Para metodos de escrita a conta proprietaria da chave deve estar aprovada. Envie sempre o header x-correlation-id quando quiser rastrear chamadas em nossos logs. Respostas de erro incluem o mesmo identificador.

​
Rate limit

As rotas sao protegidas pelo guard V1RateLimitGuard, que aplica limites por chave de API ou usuario. Exceder o limite resulta em respostas 429 Too Many Requests.

​
Endpoints disponiveis

MetodoCaminhoDescricao
POST/v1/customersCria um novo cliente
GET/v1/customersLista clientes com filtros e paginacao

​
Estrutura de cliente

{
  "id": "cus_01hr8m2aym6rd0sx2xv5hek0nv",
  "object": "customer",
  "createdAt": "2025-10-21T13:55:21.000Z",
  "updatedAt": "2025-10-21T13:55:21.000Z",
  "name": "Maria Souza",
  "email": "[email protected]",
  "phone": "+55 11 99999-0000",
  "document": "12345678901"
}
A resposta sempre inclui object: "customer", datas em formato ISO 8601 (UTC) e campos opcionais phone e document podem vir null quando nao informados.