Skip to main content
Seguranca de integracao

​
Autentique sua API sem ambiguidade

Para integracao publica, use x-client-id e x-client-secret. Em payouts, 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>
x-idempotency-key: pedido-123

​
Assinatura HMAC para payouts

Rotas de payouts exigem tambem:
  • x-turbofy-timestamp
  • x-turbofy-signature

​
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)

​
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 x-idempotency-key em operacoes de escrita.

​
Proximos passos

  1. Teste uma chamada real em Criar cobranca PIX.
  2. Em payouts, valide assinatura em Criar lote de payouts.
Last modified on April 13, 2026