> ## 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.

# Exemplo completo: propostas pagas pelo WhatsApp

> Um app Next.js de propostas que cria um link por proposta, cobra no elemento payment e libera o pedido só pelo webhook.

O **Propostiva** é o app de exemplo do Sinnu Elements: o sistema de propostas de uma agência fictícia. A agência monta a proposta, envia o link pelo WhatsApp, e o cliente paga com Pix ou cartão na própria página da proposta, pelo [elemento `payment`](https://docs.sinnu.com.br/elements/pagamento). Serve de modelo para qualquer negócio que vende produto, serviço ou software e quer receber dentro do próprio site.

O endereço do ambiente de demonstração (sandbox) é `https://propostiva.sinnu.cloud`: um domínio fora da sinnu, como o site de um cliente. Nenhum pagamento feito lá é real.

## Como funciona

**1. A agência cria a proposta**

O servidor do app cria um link de pagamento para a proposta, com o total, o máximo de parcelas e quem paga os juros. Junto nasce um pedido no banco do app; o `id` dele é a `reference`.

**2. A agência envia pelo WhatsApp**

A mensagem leva o endereço da página da proposta. O endereço tem um token aleatório e nenhum dado pessoal.

**3. O cliente paga na página da proposta**

A página coleta nome, e-mail, celular e CPF ou CNPJ e chama `confirm({ customer })`. O QR Code do Pix, os campos do cartão e o desafio do banco ficam dentro do elemento.

**4. O webhook libera o pedido**

O evento assinado `transaction.approved` marca o pedido como pago. A página, que consultava o servidor do app desde o `completed`, mostra a confirmação. O link é arquivado para ninguém pagar de novo por ele.

## Onde está cada parte

O que é integração com a sinnu fica separado do produto fictício. Copie a integração e troque o resto pelo seu sistema.

| Parte | No exemplo | O que faz |
| - | - | - |
| Cliente da API | `src/sinnu/client.ts` | O SDK com a chave secreta. Só roda no servidor. |
| Link por proposta | `src/sinnu/payment-link.ts` | O corpo de `links.create`, em centavos. |
| Pedido | `src/sinnu/orders.ts` | Os estados do pedido: aguardando, pago, estornado, contestado. |
| Webhook | `src/sinnu/webhook.ts` e `src/app/api/webhooks/sinnu/route.ts` | Assinatura, conferências e idempotência. |
| Status para a página | `src/app/api/propostas/[token]/status/route.ts` | Diz à página se o pedido já está pago. |
| Tela de pagamento | `src/components/public/pay-panel.tsx`, `src/sinnu/payment-flow.ts` e `src/sinnu/use-payment-flow.ts` | O elemento `payment`, o `confirm()` e o que a tela mostra em cada evento. |
| Content Security Policy | `next.config.ts` | Libera o elemento do checkout em `frame-src`. |

## Um link por proposta

O valor de cada proposta é diferente, e o elemento cobra pelo link. Por isso o app cria um link para cada proposta:

```ts TypeScript theme={null}
const link = await sinnu.links.create({
  title: proposal.title,
  amountCents: proposalTotalCents(proposal.items), // centavos
  methods: ["pix", "credit_card"],
  maxInstallments: proposal.maxInstallments,
  interestMode: proposal.interestPaidBy === "client" ? "pass_to_customer" : "absorb",
  externalReference: proposal.id,
});
```

A chave precisa dos escopos `links:write`, para criar e arquivar o link, e `transactions:read`, para conferir a venda no webhook. Veja [escopos](https://docs.sinnu.com.br/fundamentos/autenticacao.md).

## Libere só pelo webhook

O `completed` e o resultado do `confirm()` rodam no navegador do cliente. No exemplo, eles só mudam a tela para "confirmando". Quem marca o pedido como pago é o webhook, depois de quatro conferências:

```ts TypeScript theme={null}
// 1. A assinatura, sobre o corpo cru da requisição.
const event = sinnu.webhooks.constructEvent({ payload: rawBody, signature, secret });

// 2. A referência é um pedido seu, e a venda é do link desse pedido.
const order = await orders.get(event.data.reference);
if (!order || event.data.link?.id !== order.linkId) return ok();

// 3. O valor, na mesma unidade: a transação na API vem em centavos.
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 ok();
if (tx.productAmount !== order.amountCents) return ok();

// 4. Idempotente: o pedido só sai de "aguardando" uma vez.
await orders.markPaidIfPending(order.id, tx.id);
```

* **`data.amount` vem em reais** e inclui os juros quando o cliente paga o parcelamento. Por isso o exemplo compara `productAmount`, o preço antes dos juros, em centavos. Veja [valores e status](https://docs.sinnu.com.br/fundamentos/valores-e-status.md).
* **A mesma entrega pode chegar mais de uma vez**, e fora de ordem. No banco, a marcação é um `UPDATE ... WHERE id = ? AND status = 'pending'`, conferindo as linhas afetadas.
* **Transação ainda `pending` na API**: responda 5xx. Com 200, a sinnu daria o evento por entregue.
* **Arquive o link depois de pago** (`sinnu.links.archive`). O exemplo faz isso depois de responder ao webhook, para a resposta sair rápido.

## A tela de pagamento

* **Confirmando até o servidor dizer que está pago.** Depois do `completed`, a página consulta o servidor do app até ele responder que o pedido está pago.
* **Volta do app do banco.** Quem paga Pix pelo celular sai para o app do banco e volta. Quando a aba fica visível de novo, a página consulta na hora.
* **Recarregar não cobra de novo.** Entre o `completed` e o webhook, o pedido ainda está "aguardando". O exemplo guarda o `transactionId` na aba e, se o cliente recarregar, a tela volta para "confirmando" em vez de mostrar o formulário outra vez.
* **Falhas.** A tela decide pelo `retryable` de cada `failed`. Um `unknown` com `retryable: false` pede para conferir antes de cobrar de novo. Veja [eventos e erros](https://docs.sinnu.com.br/elements/eventos.md).

## O que configurar

1. **Sinnu Elements liberado para a empresa.** [Fale com o suporte de integração](https://docs.sinnu.com.br/comunidade/ajuda.md).
2. **A origem exata do site em Domínios permitidos**, em **Configurações → Checkout embutido**. `https://www.loja.exemplo.com.br` é outra origem que `https://loja.exemplo.com.br`. Veja [domínios permitidos](https://docs.sinnu.com.br/elements/seguranca.md#domínios-permitidos).
3. **Um webhook** assinando `transaction.*`, apontando para a rota do app. Veja [webhooks](https://docs.sinnu.com.br/guias/webhooks.md).
4. **A Content Security Policy do site** com o checkout em `frame-src`. O exemplo usa a variante simples, com `'unsafe-inline'` em `script-src`. Em produção, prefira a variante com nonce.
5. **`reference` e endereços sem dado pessoal.** Use o `id` do pedido e um token aleatório, nunca e-mail, CPF ou telefone.

> [card] [Elemento payment](https://docs.sinnu.com.br/elements/pagamento.md)
>
> O `confirm()` com o comprador do seu formulário.

> [card] [Segurança](https://docs.sinnu.com.br/elements/seguranca.md)
>
> Domínios permitidos, 3DS e liberação do pedido.


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