> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sinnu.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Documentação oficial da sinnu, gateway de pagamento brasileiro: Pix e cartão de crédito. O índice de todas as páginas está em https://docs.sinnu.com.br/llms.txt.
> A API (https://api.sinnu.com.br) e o checkout (https://pay.sinnu.com.br) documentados são de produção. Não há ambiente público de testes: cada chamada cria ou altera dados reais.
> A chave secreta sk_live_ fica só no servidor. O navegador recebe apenas o slug do link ou a URL do checkout.
> Unidades: amountCents do link e os valores de /api/transactions/ estão em centavos (inteiro). data.amount do webhook e amount das transações de um link estão em reais. Compare na mesma unidade.
> Status: a API de transações usa approved; o corpo do webhook usa paid; o evento é transaction.approved.
> Libere o pedido só pelo webhook assinado (X-Sinnu-Signature, validado sobre o corpo cru com constructEvent({ payload, signature, secret })) e confirme com transactions.get. Nunca pelo evento completed do Sinnu Elements nem pelos parâmetros da URL de retorno.
> Estorno é sempre do valor total. Não invente métodos, campos ou eventos: confira na referência do SDK e da API.

# Autenticação

> Use uma chave secreta de API no servidor para operar os recursos de uma empresa.

Envie sua chave `sk_live_...` no header `Authorization` de cada requisição:

```http Header theme={null}
Authorization: Bearer SUA_CHAVE_SECRETA
```

Gere a chave em **Chave de API**, no [painel](https://app.sinnu.com.br), com a empresa correta selecionada. Cada chave está vinculada a uma empresa; a API usa esse vínculo para limitar o acesso aos dados.

## Onde guardar

Use variáveis de ambiente do servidor ou o gerenciador de segredos da sua infraestrutura. No Next.js, a variável não deve ter o prefixo `NEXT_PUBLIC_`.

```ts Servidor TypeScript theme={null}
const apiKey = process.env.SINNU_API_KEY;
if (!apiKey) throw new Error("Configure SINNU_API_KEY no servidor.");

const response = await fetch("https://api.sinnu.com.br/api/payment-links", {
  headers: { Authorization: `Bearer ${apiKey}` },
});
```

O navegador recebe somente os dados públicos necessários à interface, como a URL do checkout. Não recebe a chave.

## Escolha os escopos

Conceda à chave as operações que sua integração precisa executar. Uma chave de leitura não pode criar links.

| Operação | Escopo |
| - | - |
| Consultar links | `links:read` |
| Criar, editar e arquivar links | `links:write` |
| Consultar clientes | `customers:read` |
| Criar e editar clientes | `customers:write` |
| Consultar transações | `transactions:read` |
| Estornar transações (devolução total) | `transactions:refund` |

O escopo `read` cobre os escopos de leitura. Ele não concede escrita nem estorno. Uma chave criada sem `transactions:refund` não estorna; para estornar pela API, crie uma chave com esse escopo e revogue a anterior. Para o primeiro link deste guia, habilite `links:write`; adicione `links:read` para consultar o link depois e `customers:write` quando enviar dados do comprador (`customer`) na criação ou edição do link.

Um escopo não substitui outras verificações de acesso da operação. Se uma chamada retornar `403`, confira também o contexto da empresa e as permissões necessárias.

## Diagnostique uma falha

| Sintoma | Confira |
| - | - |
| A requisição não autentica | Header presente, prefixo `Bearer`, chave completa e ativa. |
| O recurso não aparece | A chave pertence à empresa que criou o recurso? |
| A operação é negada | A chave e seu contexto de acesso permitem essa ação? |

## Rotacione uma chave

Crie uma nova chave, atualize o segredo no servidor e verifique uma consulta de leitura. Depois, revogue a anterior. Se houver exposição da chave, revogue-a e revise seu uso.

A chave de API e o **segredo do webhook** têm funções diferentes. O segundo verifica eventos recebidos e não autentica chamadas à API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.