Autenticação

Como enviar

Toda chamada precisa de dois headers obrigatórios:

Authorization: Bearer SEU_TOKEN
Content-Type: application/json

Exemplo de chamada autenticada para consultar o saldo:

curl https://api.saq.processamento.com/v1/user/balance \
  -H "Authorization: Bearer $SAQ_TOKEN" \
  -H "Content-Type: application/json"

const res = await fetch('https://api.saq.processamento.com/v1/user/balance', {
  headers: {
    Authorization: `Bearer ${process.env.SAQ_TOKEN}`,
    'Content-Type': 'application/json',
  },
});
const balance = await res.json();

import os
import requests

res = requests.get(
    'https://api.saq.processamento.com/v1/user/balance',
    headers={
        'Authorization': f'Bearer {os.environ["SAQ_TOKEN"]}',
        'Content-Type': 'application/json',
    },
)
balance = res.json()

req, _ := http.NewRequest("GET", "https://api.saq.processamento.com/v1/user/balance", nil)
req.Header.Set("Authorization", "Bearer " + os.Getenv("SAQ_TOKEN"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

<?php
$ch = curl_init('https://api.saq.processamento.com/v1/user/balance');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('SAQ_TOKEN'),
    'Content-Type: application/json',
  ],
]);
$balance = json_decode(curl_exec($ch), true);

Onde guardar

Nunca expõe o token no front-end, em repositório público ou em logs. Trata como senha: armazena em vault e injeta por variável de ambiente.

Recomendações:

Google Secret Manager, ideal se você já usa GCP.
HashiCorp Vault, pra setups self-hosted.
AWS Secrets Manager, equivalente AWS.
Variável de ambiente em CI, nunca commita.

Formato de erro

Toda resposta de erro da Saq (4xx e 5xx) segue o mesmo formato. O campo mais importante é o requestId, ele identifica univocamente a chamada nos logs internos da Saq.

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Não foi possível processar esta solicitação",
  "requestId": "cmp70zh4008dx01s6bwjb5bez"
}

Campo	Para que serve
`statusCode`	Código HTTP da resposta (espelha o status).
`error`	Nome curto do erro (`Unauthorized`, `Bad Request`, `Internal Server Error`).
`message`	Descrição em PT do que aconteceu. Use no log, não para usuário final.
`requestId`	ID único da chamada na Saq. Envie esse ID ao abrir chamado de suporte, eles rastreiam direto.

Sempre logue o requestId nos seus erros. Ao abrir suporte com "deu erro em produção", o time pede esse ID primeiro. Quem tem o requestId tem investigação em minutos; quem não tem, leva horas.

try {
  const res = await fetch(url, { headers, body });
  if (!res.ok) {
    const err = await res.json();
    log.error('Saq erro', {
      requestId: err.requestId,
      statusCode: err.statusCode,
      message: err.message,
      endpoint: url,
    });
    throw new Error(`Saq ${err.statusCode}: ${err.message} (requestId=${err.requestId})`);
  }
} catch (e) {
  // ...
}

Abrir suporte com o requestId

Abrir ticket Base de conhecimento Portal de suporte

Resolvendo erros

401 Unauthorized

As causas mais comuns, em ordem:

Token ausente, header Authorization não foi enviado.
Token incorreto, typo, espaço em branco extra, encoding errado.
Token revogado, foi rotacionado e você está usando o antigo.
Permissão insuficiente, o token não tem o escopo do endpoint.

Exemplo de resposta:

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Missing or invalid Bearer token",
  "requestId": "cmou00000abcdef01s6ghij1k2lm"
}

O token é válido mas não tem permissão para a operação. Verifica se o endpoint exige escopo adicional ou se sua conta está habilitada para o recurso (por exemplo, transferência interna pode exigir aprovação prévia).

Rotação

Se o token vazar, contata o suporte da Saq imediatamente para emissão de novo token e revogação do anterior.