Introdução

Base URL, autenticação, formato de resposta, códigos de status e limites da API.

Base URL

Todas as requisições usam o seguinte endereço:

https://nucleopay.com.br

Toda requisição deve incluir sua chave de API no header Authorization:

Authorization: Bearer SUA_CHAVE_API

Requisições sem chave ou com chave inválida retornam 401 Unauthorized. Consulte a página de autenticação para criar e gerenciar suas chaves.

Todos os endpoints retornam JSON com a mesma estrutura:

{
  "success": true,
  "data": { ... }
}

Em caso de erro:

{
  "success": false,
  "error": "Mensagem descritiva do erro"
}

Sempre verifique success antes de acessar data. Nunca assuma que a requisição funcionou apenas pelo status HTTP.

Código	Significado
`200`	Sucesso
`400`	Requisição inválida — verifique os campos enviados
`401`	Não autenticado — chave ausente, inválida ou revogada
`403`	Sem permissão para o recurso solicitado
`404`	Recurso não encontrado
`422`	Erro de validação — dados corretos mas semanticamente inválidos
`429`	Rate limit atingido
`5xx`	Erro interno — tente novamente com backoff exponencial

O endpoint GET /api/pix/charges aceita limit (1–200, padrão 50). Futuramente outros endpoints de listagem suportarão paginação via offset.

Explore tokens e webhooks simulados sem criar conta.

Nunca comite sua chave de API no código. Use .env ou um gerenciador de segredos.

Registre o ID do evento e descarte duplicatas.

Implemente retentativas com espera crescente para falhas temporárias.