Ir para o conteúdo
Sharkpay

Documentação da API

Integre pagamentos, saques e webhooks ao seu sistema com uma API HTTP/JSON aberta e documentada.

API 2026-10-14

Autenticação e autorização

A API usa dois passos: (1) trocar a chave pública + secreta por um token Bearer; (2) enviar o token em todas as demais chamadas.

1. Obter o token

POST /api/auth com HTTP Basic: usuário = chave pública, senha = chave secreta.

POST /api/auth
#!/usr/bin/env bash
# Obter token de acesso (chave pública + chave secreta em HTTP Basic)
set -euo pipefail
: "${SHARKPAY_BASE_URL:?}" "${SHARKPAY_PUBLIC_KEY:?}" "${SHARKPAY_SECRET_KEY:?}"
curl -sS --fail-with-body -X POST "$SHARKPAY_BASE_URL/api/auth" \
  -u "$SHARKPAY_PUBLIC_KEY:$SHARKPAY_SECRET_KEY"
echo
CampoTipoDescrição
success.token string Token de acesso (JWT). Trate como segredo.
success.token_type string Sempre Bearer.
success.expires_in integer Validade em segundos (padrão 30 dias; configurável pelo operador do SharkPay).
StatusQuando
400 Cabeçalho ausente, malformado ou chave vazia.
401 Chaves incorretas.
429 Mais de 10 tentativas por minuto por IP. Respeite Retry-After.

2. Usar o token

Cabeçalho em todas as chamadas
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOi...
Content-Type: application/json

Faça cache do token em memória e renove antes de expires_in (ou ao receber 401, uma única vez, e repita a chamada). Não peça um token novo a cada requisição: o limite de 10/min por IP existe para isso.

Autorização: o que o token permite

  • O token representa a sua conta. Todas as consultas são isoladas por conta: pedir a cobrança, o cliente ou o saque de outra conta devolve 404.
  • Hoje o token tem acesso total às operações da API da sua conta (não há escopos granulares nem chaves somente-leitura — veja Limitações).
  • Cada meio de pagamento precisa estar habilitado na conta (Pix, boleto, cartão). Se não estiver, a criação responde 400.
  • Saques Pix movem dinheiro: exigem Idempotency-Key e respeitam o saldo disponível.

Erros de autenticação nas chamadas

401 — token ausente, inválido ou expirado
{ "message": "Unauthenticated." }

Ao receber 401, obtenha um novo token e repita uma vez. Se persistir, verifique se as chaves foram rotacionadas.