---
name: sinnu
description: Integração de pagamentos com a sinnu, gateway brasileiro de Pix e cartão de crédito. Use ao criar links de pagamento, abrir o checkout hospedado, embutir o Sinnu Elements, validar webhooks, conciliar transações, estornar ou cadastrar clientes pela API REST ou pelo SDK TypeScript @sinnu-dev/sdk.
metadata:
  author: sinnu
  version: "1.0"
---

# sinnu

A sinnu recebe pagamentos por Pix e cartão de crédito. A integração tem três partes: o seu servidor cria um link de pagamento, o comprador paga no checkout da sinnu (hospedado em `pay.sinnu.com.br` ou embutido no seu site com o Sinnu Elements) e o seu servidor libera o pedido quando recebe o webhook assinado.

- API: `https://api.sinnu.com.br`, autenticada com `Authorization: Bearer sk_live_...`
- SDK de servidor: `@sinnu-dev/sdk` (npm), para Node.js e TypeScript
- Checkout embutido: `@sinnu-dev/elements` (npm ou CDN)
- Índice da documentação: https://docs.sinnu.com.br/llms.txt; cada página existe em Markdown com `.md` no fim do endereço

## Regras que não mudam

1. **Produção.** A API e o checkout documentados são de produção. Não há ambiente público de testes nem chave `sk_test_`. Cada chamada cria ou altera dados reais; avise antes de rodar código que cria link, cliente ou estorno.
2. **Chave no servidor.** `sk_live_` fica em variável de ambiente do servidor (`SINNU_API_KEY`; no Next.js, sem o prefixo `NEXT_PUBLIC_`). O navegador recebe só o slug do link ou a URL do checkout.
3. **Preço no servidor.** O valor vem do link criado pelo servidor. Nunca aceite preço vindo do navegador.
4. **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 (`links.transactions`) estão em **reais**. Compare na mesma unidade; para o preço antes dos juros, use `productAmount` da transação.
5. **Status.** A API de transações usa `approved`; o corpo do webhook usa `paid`; o evento é `transaction.approved`.
6. **Quem libera o pedido é o webhook.** Valide `X-Sinnu-Signature` sobre o corpo cru, confira a transação com `transactions.get` e marque o pedido uma vez só. O evento `completed` do Elements e os parâmetros da URL de retorno servem só para a interface.
7. **Estorno total.** `transactions.refund` devolve sempre o valor inteiro.
8. **Sem invenção.** Se um método, campo, evento ou opção não aparece na referência, ele não existe. Confira antes de usar.

## Escolha o caminho

| Necessidade | Caminho | Página |
| --- | --- | --- |
| Cobrar sem programar | Link criado no painel `app.sinnu.com.br` | https://docs.sinnu.com.br/inicio/escolha-sua-integracao.md |
| Criar cobranças pelo sistema | `links.create` + checkout hospedado | https://docs.sinnu.com.br/guias/checkout.md |
| Pagar sem sair do site, com o formulário da sinnu | Elemento `checkout` | https://docs.sinnu.com.br/elements/checkout.md |
| Pagar sem sair do site, com o seu formulário e o seu botão | Elemento `payment` + `confirm({ customer })` | https://docs.sinnu.com.br/elements/pagamento.md |
| Componentes React | `SinnuCheckout` e `SinnuPayment` | https://docs.sinnu.com.br/elements/react.md |
| App mobile | Checkout hospedado no navegador do sistema, com `redirectUrl` para o app | https://docs.sinnu.com.br/guias/checkout.md |
| Atribuir vendas a campanhas | Pixels ligados no link, no checkout hospedado | https://docs.sinnu.com.br/guias/rastreamento.md |

Limites do Elements: só venda avulsa (link só de assinatura gera `error` com `unsupported_link`), só `pt-BR`, sem Apple Pay e Google Pay, e os pixels de rastreamento do link não rodam dentro do elemento. Ele precisa ser liberado pela sinnu para a empresa, e a origem exata da página precisa estar em **Configurações → Checkout embutido → Domínios permitidos** (`www` é outra origem).

## Receitas

### Cliente do SDK

```ts
import { Sinnu } from "@sinnu-dev/sdk";

const apiKey = process.env.SINNU_API_KEY;
if (!apiKey) throw new Error("Configure SINNU_API_KEY no servidor.");

export const sinnu = new Sinnu({ apiKey });
```

### Link e checkout hospedado

```ts
const link = await sinnu.links.create({
  priceMode: "fixed",
  title: "Consultoria inicial",
  amountCents: 9900, // R$ 99,00
  methods: ["pix", "credit_card"],
  maxInstallments: 3,
  interestMode: "pass_to_customer", // ou "absorb"
  externalReference: "produto-consultoria", // código do produto no seu sistema
});

// Um link pode ser vendido muitas vezes; o pedido de cada venda vai em reference.
const url = sinnu.checkout.url(link.slug, { reference: order.id });
```

- `maxPayments: 1` faz um link de uso único, que arquiva ao ser pago.
- `customer` (nome, e-mail, documento) preenche o comprador no checkout e exige o escopo `customers:write`.
- `redirectUrl` devolve o comprador ao seu site ou app depois do pagamento confirmado. O retorno é liberado por empresa: confirme com a sinnu antes de depender dele.
- `reference` tem até 255 caracteres. Use o `id` do pedido, nunca e-mail, CPF ou telefone.

### Elemento checkout

```html
<div id="pagamento"></div>
<script src="https://cdn.jsdelivr.net/npm/@sinnu-dev/elements@0.1/dist/sinnu-elements.global.js"></script>
<script>
  const elements = SinnuElements.createElements({ link: "abc12345", reference: "pedido-123" });
  const checkout = elements.create("checkout");
  checkout.on("completed", ({ transactionId }) => showConfirming(transactionId)); // só interface
  checkout.on("error", ({ message }) => showError(message));
  checkout.mount("#pagamento");
</script>
```

Com `Content-Security-Policy`, libere `frame-src https://pay.sinnu.com.br` e, se usar a CDN, `script-src https://cdn.jsdelivr.net`.

### Webhook

```ts
import { constructEvent, SinnuWebhookSignatureError } from "@sinnu-dev/sdk";

export async function POST(request: Request): Promise<Response> {
  let event;
  try {
    event = constructEvent({
      payload: await request.text(), // corpo cru: não use request.json() antes
      signature: request.headers.get("X-Sinnu-Signature") ?? undefined,
      secret: process.env.SINNU_WEBHOOK_SECRET!,
    });
  } catch (error) {
    return new Response(error instanceof SinnuWebhookSignatureError ? "Assinatura inválida" : "Evento ilegível", { status: 400 });
  }
  if (event.test === true) return new Response(null, { status: 204 });

  await saveDurably(event); // banco ou fila; se falhar, responda 5xx para a sinnu reenviar
  return new Response(null, { status: 204 });
}
```

No Next.js, declare `export const runtime = "nodejs"` na rota. Eventos de transação: `transaction.approved`, `transaction.declined`, `transaction.refunded`, `transaction.chargeback` e `transaction.changed`.

### Confira antes de liberar

```ts
const order = await orders.get(event.data.reference);
if (!order || event.data.link?.id !== order.linkId) return; // não é um pedido seu

const tx = await sinnu.transactions.get(event.data.id);
if (tx.status === "pending") throw new Error("ainda pending"); // responda 5xx: a sinnu reenvia
if (tx.status !== "approved" || tx.reference !== order.id) return;
if (tx.productAmount !== order.amountCents) return; // centavos com centavos

// Idempotente: UPDATE ... WHERE id = ? AND status = 'pending', conferindo as linhas afetadas.
await orders.markPaidIfPending(order.id, tx.id);
```

A mesma entrega pode chegar mais de uma vez e fora de ordem.

## Escopos da chave

| 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 (valor total) | `transactions:refund` |

O escopo `read` cobre todas as leituras, sem escrita nem estorno.

## Falhas e limites

- **100 requisições por minuto, por chave.** Em `429`, respeite `Retry-After`. Prefira webhooks a consultas repetidas.
- **Timeout não determina o resultado.** Antes de repetir uma criação ou um estorno, consulte o recurso. O SDK não tem retentativa automática nem idempotência para criar links; não invente cabeçalho de idempotência.
- **Erros tipados no SDK:** `SinnuAuthError`, `SinnuNotFoundError`, `SinnuRateLimitError`, `SinnuValidationError`, todos derivados de `SinnuError`. Falha de rede pode chegar como o erro original do `fetch`.
- Registre método, caminho, status e o `X-Request-Id` da resposta. Nunca registre `Authorization`, segredo do webhook ou dados pessoais.

## Onde conferir

- Valores e status: https://docs.sinnu.com.br/fundamentos/valores-e-status.md
- Autenticação e escopos: https://docs.sinnu.com.br/fundamentos/autenticacao.md
- Erros e limites: https://docs.sinnu.com.br/fundamentos/erros-e-limites.md
- Webhooks: https://docs.sinnu.com.br/guias/webhooks.md
- Conciliação: https://docs.sinnu.com.br/guias/conciliacao.md
- SDK: https://docs.sinnu.com.br/sdk/visao-geral.md
- Sinnu Elements: https://docs.sinnu.com.br/elements/visao-geral.md
- Eventos e erros do Elements: https://docs.sinnu.com.br/elements/eventos.md
- Exemplo completo com Elements e webhook: https://docs.sinnu.com.br/elements/exemplo-propostas.md
- Referência da API: https://docs.sinnu.com.br/api/introducao.md e https://docs.sinnu.com.br/api/openapi.yaml
