Autenticação, escopos e idempotência

Envie a API key#Link direto para a seção Envie a API key

Todas as rotas públicas usam a base URL abaixo. Crie a chave no painel, em Integrações › Chaves API: ela aparece inteira uma única vez, no momento da criação, e cada workspace pode ter até 5 chaves ativas. Substitua o valor de exemplo pela sua chave.

Authorization: Bearer sk_live_sua_chave
Content-Type: application/json

Conceda o menor acesso necessário#Link direto para a seção Conceda o menor acesso necessário

Cada chave pertence a um workspace e só acessa os recursos autorizados pelos seus escopos. Por exemplo, manual-pix é selecionável e não é incluído automaticamente em chaves novas ou existentes.

• manual-pixGera código, QR Code ou link de PIX manual.
• pix-singleCria cobranças PIX únicas.
• customersLê, cria e atualiza os clientes do CRM em /api/v1/crm/customers. Só o proprietário do workspace pode conceder este escopo, e os dados seguem as permissões de quem criou a chave.

Não envie workspaceId nem headers internos como x-api-user-id, x-api-key-id ou x-api-workspace-id. O gateway valida a chave e injeta esse contexto internamente.

Respeite o limite de chamadas#Link direto para a seção Respeite o limite de chamadas

Cada API key aceita, por padrão, 60 requisições por minuto. Passou disso, a API responde 429 e diz quanto esperar. Use os cabeçalhos abaixo para acompanhar o consumo e para localizar uma chamada com o suporte.

const response = await fetch(url, options);

if (response.status === 429) {
  const seconds = Number(response.headers.get("Retry-After") ?? 1);
  await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
  // Tente de novo. Com Idempotency-Key, reutilize a mesma chave.
}

Evite cobranças duplicadas#Link direto para a seção Evite cobranças duplicadas

Em POST /api/v1/payments, Idempotency-Key é opcional. Sem o header, cada chamada cria uma nova cobrança com identificadores gerados pelo CasePay, mesmo com o mesmo body. Para proteger retentativas após timeout ou falha de rede, envie uma chave desde a primeira chamada e reutilize-a com o mesmo body.

const idempotencyKey = crypto.randomUUID();
// Persista antes do POST e envie no header Idempotency-Key.
// Reutilize a chave salva nas retentativas da mesma cobrança.

• Formato: de 8 a 120 caracteres ASCII visíveis, sem espaços (um UUID serve).
• A chave vale para a API key e o endpoint que a receberam. Se você trocar a API key, a nova não reconhece a chave da antiga: conclua as retentativas pendentes com a mesma API key.
• Nova cobrança em /api/v1/payments: omita o header ou envie uma nova chave, mesmo com valor e pagador iguais. As chaves fixas dos exemplos são ilustrativas. As demais rotas mantêm os requisitos indicados em suas referências.
• Mesma chave e mesmo payload: a API devolve a resposta original com Idempotency-Replayed: true, inclusive quando o PIX já foi cancelado, expirou ou foi pago. O status dessa resposta é o da criação; consulte o pagamento para obter o status atual. O corpo é o mesmo da primeira resposta, com os horários também no horário de Brasília (-03:00).
• Payload diferente com a mesma chave: a API responde 409.
• Operação ainda em processamento: respeite Retry-After antes de consultar novamente.

Interprete erros de acesso#Link direto para a seção Interprete erros de acesso