Skip to main content
Seguranca de integracao

​
Autentique sua API sem ambiguidade

Para integracao publica, use x-client-id e x-client-secret. Em operacoes financeiras sensiveis como payouts, checkout P0 e download de comprovantes, adicione assinatura HMAC com timestamp para proteger transacoes sensiveis.

Ver endpoint de payoutsVer glossario da API

​
Chaves de API

Importante: suas credenciais identificam a conta e autorizam cada requisicao. Configure apenas no backend e nunca exponha o secret no frontend, app mobile ou logs.
Headers obrigatorios para toda API publica:
  • x-client-id
  • x-client-secret

​
Fluxo basico

POST /sellers/pix
x-client-id: <client-id>
x-client-secret: <client-secret>
Idempotency-Key: pedido-123

​
Assinatura HMAC para operacoes financeiras sensiveis

Rotas financeiras sensiveis podem exigir tambem:
  • x-turbofy-timestamp
  • x-turbofy-signature
No Checkout P0 (POST /v1/checkouts), a politica real atual do backend e:
  • em production: assinatura obrigatoria;
  • fora de production: assinatura pode ser opcional.

​
Como a assinatura e calculada

Assine com HMAC SHA-256 a string abaixo: 
{timestamp}.{method}.{path}.{body}
  • timestamp: mesmo valor enviado em x-turbofy-timestamp
  • method: GET, POST, etc. sempre em maiusculo
  • path: somente caminho da rota (sem dominio e sem query string)
  • body: JSON bruto exatamente como enviado (em GET, use vazio)
Diagrama da assinatura HMAC usando timestamp, metodo, path e body para gerar os headers x-turbofy-timestamp e x-turbofy-signature. O payload assinado deve reproduzir exatamente a requisicao enviada. Qualquer mudanca em metodo, path, body ou timestamp exige nova assinatura.

​
Regra critica

Recalcule a assinatura em toda requisicao. Se mudar metodo, path, body ou timestamp, a assinatura antiga deixa de ser valida.

​
Exemplo Bash (Linux/macOS/Git Bash)

CLIENT_SECRET="SEU_CLIENT_SECRET"
TIMESTAMP=$(date +%s%3N)
METHOD="POST"
PATH_ONLY="/v1/payouts/batches"
BODY='{"idempotencyKey":"folha-001","description":"Folha semanal","items":[]}'

PAYLOAD="$TIMESTAMP.$METHOD.$PATH_ONLY.$BODY"

SIGNATURE=$(printf "%s" "$PAYLOAD" \
  | openssl dgst -sha256 -hmac "$CLIENT_SECRET" -hex \
  | sed 's/^.* //')

echo "$TIMESTAMP"
echo "$SIGNATURE"

​
Exemplo PowerShell (Windows)

$clientSecret = "SEU_CLIENT_SECRET"
$timestamp = [DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds().ToString()
$method = "POST"
$pathOnly = "/v1/payouts/batches"
$body = '{"idempotencyKey":"folha-001","description":"Folha semanal","items":[]}'

$payload = "$timestamp.$method.$pathOnly.$body"

$hmac = [System.Security.Cryptography.HMACSHA256]::new(
  [System.Text.Encoding]::UTF8.GetBytes($clientSecret)
)
$signatureBytes = $hmac.ComputeHash([System.Text.Encoding]::UTF8.GetBytes($payload))
$signature = -join ($signatureBytes | ForEach-Object { $_.ToString("x2") })

Write-Output $timestamp
Write-Output $signature

​
Erros comuns de assinatura

  • 401 INVALID_SIGNATURE: assinatura ausente, invalida ou expirada.
  • Metodo assinado diferente do metodo enviado (GET vs POST).
  • Path assinado com dominio ou query string.
  • Body assinado diferente do body efetivamente enviado.
  • Timestamp fora da janela de validacao.

​
Boas praticas

  • Gere assinatura imediatamente antes do envio.
  • Nao reutilize assinatura entre requisicoes.
  • Mantenha relogio do servidor sincronizado (NTP).
  • Nunca registre x-client-secret em logs.
  • Use Idempotency-Key em operacoes de escrita.

​
Proximos passos

  1. Teste uma chamada real em Criar cobranca PIX.
  2. Em checkout P0, valide Criar checkout.
  3. Em payouts, valide assinatura em Criar lote de payouts.
  4. Em comprovantes, valide assinatura em Baixar comprovante de transacao.
Last modified on June 8, 2026