Autenticação

Chaves de API

Cada empresa gera suas chaves de API no painel Sinnu, em Chave de API. Toda chave tem o prefixo sk_live_... e é exibida por completo uma única vez, no momento da criação. Copie-a e guarde-a com segurança.

Como autenticar

Envie a chave no header Authorization em todas as requisições, com o prefixo Bearer:

Authorization: Bearer <SUA_CHAVE_DE_API>

curl https://api.sinnu.com.br/api/payment-links \
  -H "Authorization: Bearer <SUA_CHAVE_DE_API>"

Com o SDK TypeScript, a autenticação é aplicada automaticamente a cada chamada:

import { Sinnu } from "@sinnu/sdk";

const sinnu = new Sinnu({
  apiKey: process.env.SINNU_API_KEY!,
});

Erros de autenticação (401)

Requisições sem chave, com chave inválida ou revogada retornam HTTP 401 Unauthorized. Verifique se a chave está correta e se você está usando a URL base adequada (https://api.sinnu.com.br em produção).

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "status": "error",
  "message": "API key inválida ou ausente"
}

Limite de requisições (rate limit)

A API da Sinnu aceita até 100 requisições por minuto por API key. Ao exceder esse limite, a API responde com HTTP 429 Too Many Requests e inclui o header Retry-After com o número de segundos que você deve aguardar antes de tentar de novo.

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{
  "status": "error",
  "message": "Limite de requisições excedido. Tente novamente em instantes."
}

Implemente backoff: ao receber 429, espere o tempo indicado em Retry-After e repita a requisição. No SDK, um 429 vira SinnuRateLimitError.

import { SinnuRateLimitError } from "@sinnu/sdk";

try {
  await sinnu.links.create({
    title: "Teste",
    priceMode: "fixed",
    amountCents: 1000,
    methods: ["pix"],
  });
} catch (err) {
  if (err instanceof SinnuRateLimitError) {
    const retryAfter = Number(err.response?.headers.get("Retry-After") ?? 1);
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
    // ... repita a requisição ...
  }
}

Boas práticas

• Guarde a chave em variáveis de ambiente, nunca no código-fonte.
• Use uma chave por integração, para revogar isoladamente quando precisar.
• Rotacione as chaves periodicamente e ao desligar integrações.
• Trate 401 (reautenticar) e 429 (aguardar Retry-After) de forma explícita no seu código.