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

# Links de pagamento

> Crie uma oferta com valor definido e gerencie sua disponibilidade.

Um link reúne preço, métodos de pagamento e opções do checkout. Ele pode receber mais de um pagamento: **link e transação são recursos diferentes**.

## Defina a oferta

```json Corpo de criação theme={null}
{
  "title": "Consultoria inicial",
  "description": "Uma sessão de 60 minutos",
  "priceMode": "fixed",
  "amountCents": 9900,
  "methods": ["pix", "credit_card"],
  "maxInstallments": 1,
  "interestMode": "pass_to_customer"
}
```

Envie o corpo para [`POST /api/payment-links`](https://docs.sinnu.com.br/api/links/criar). Guarde o `id` e o `slug` retornados.

| Campo | Como escolher |
| - | - |
| `title` | Use um nome que o comprador reconheça. |
| `amountCents` | Defina o preço em centavos no seu servidor. |
| `methods` | Selecione métodos habilitados para a empresa. |
| `maxInstallments` | Limite o parcelamento conforme a oferta e a configuração da empresa. |
| `interestMode` | `absorb` para absorver juros; `pass_to_customer` para repassá-los. |
| `redirectUrl` | Para onde o comprador volta depois do pagamento confirmado: `https://` ou o deep link do app. Não substitui a confirmação pelo webhook. |
| `externalReference` | Código do produto no seu sistema; volta como `externalRef` do item em cada venda. |
| `customer` | Objeto inline (`name`, `email`, `document`, `phone`) para cadastrar ou reaproveitar o cliente na mesma chamada e abrir o checkout já preenchido. |
| `linkedCustomer` | ID de um cliente já cadastrado na empresa. Mutuamente exclusivo com `customer`. |
| `maxPayments` | Inteiro opcional (`>= 1`) que limita a quantidade de pagamentos aprovados antes de o link ser arquivado automaticamente. |

O SDK também tipa `applepay` e `googlepay`. A presença no contrato não garante disponibilidade para toda empresa, navegador ou dispositivo.

## Dados do comprador no checkout

Se o seu sistema já coleta nome, CPF/CNPJ e e-mail no cadastro do usuário, envie `customer` diretamente em [`POST /api/payment-links`](https://docs.sinnu.com.br/api/links/criar) ou [`PATCH /api/payment-links/{id}`](https://docs.sinnu.com.br/api/links/atualizar), sem precisar criar o cliente em uma chamada separada:

```json Link com comprador e uso único theme={null}
{
  "title": "Pedido #1042",
  "priceMode": "fixed",
  "amountCents": 14900,
  "methods": ["pix", "credit_card"],
  "maxInstallments": 3,
  "interestMode": "pass_to_customer",
  "maxPayments": 1,
  "customer": {
    "name": "Maria Oliveira",
    "email": "maria@exemplo.com.br",
    "document": "12345678909",
    "phone": "11999998888"
  }
}
```

Como o vínculo se comporta:

* **Deduplicação por empresa**: quando `customer.document` (CPF ou CNPJ válido, com ou sem pontuação) já pertence a um cliente da sua empresa, a sinnu reaproveita o cadastro existente e atualiza nome, e-mail e telefone informados. Caso contrário, cria o cliente e retorna o identificador em `linkedCustomerId`.
* **Privacidade do documento**: ao abrir `https://pay.sinnu.com.br/{slug}` ou o [elemento `checkout`](https://docs.sinnu.com.br/elements/checkout), nome, e-mail e telefone aparecem preenchidos e o CPF/CNPJ é exibido mascarado (`***.456.789-**` ou `**.345.678/0001-**`), com o botão **Alterar**. O documento completo nunca é exposto na consulta pública do link; a cobrança usa o documento vinculado no servidor, exceto se o comprador clicar em **Alterar** e informar outro.
* **Telefone opcional na API**: se você enviar apenas `name`, `email` e `document`, esses três campos já abrem preenchidos e o comprador informa somente o celular e o meio de pagamento no checkout. Se enviar `phone`, ele segue direto para Pix ou cartão.
* **Cliente já salvo**: quando você já mantém o `id` retornado por [`POST /api/customers/`](https://docs.sinnu.com.br/api/clientes/criar) ou [`sinnu.customers`](https://docs.sinnu.com.br/sdk/clientes), envie `linkedCustomer` no lugar de `customer`. Não envie os dois campos na mesma requisição.
* **Escopos da chave**: enviar `customer` inline exige `links:write` e `customers:write`; enviar `linkedCustomer` exige `links:write` e leitura de clientes (`read` ou `customers:read`).

## Limite de pagamentos por link

Escolha o modelo conforme a relação entre link e pedido no seu sistema:

| Cenário | Como configurar | O que acontece |
| - | - | - |
| **Cobrança única por pedido ou cliente** | Envie `maxPayments: 1` (ou `N`) na criação ou atualização do link | Ao atingir `maxPayments` pagamentos aprovados (Pix pago ou cartão aprovado), o link muda automaticamente para `status: "archived"` e bloqueia novas cobranças. |
| **Oferta de catálogo vendida várias vezes** | Mantenha `maxPayments` vazio (`null`) e abra o checkout com [`?ref=pedido-123`](https://docs.sinnu.com.br/guias/checkout#pedido-de-cada-venda) | O mesmo link permanece ativo para vários compradores e cada pagamento retorna o `reference` do pedido correspondente. |
| **Expiração ou cancelamento pelo seu servidor** | Chame [`DELETE /api/payment-links/{id}`](https://docs.sinnu.com.br/api/links/arquivar) (`sinnu.links.archive(id)`) ou `PATCH` com `status: "paused"` | Retira o link de circulação imediatamente quando um pedido expira ou é cancelado antes do pagamento. |

Para reativar via `PATCH` um link arquivado ao atingir `maxPayments`, aumente `maxPayments` acima do total já aprovado ou limpe o limite com `maxPayments: null` junto de `status: "active"`.

## Gerencie o ciclo de vida

| Status | Uso |
| - | - |
| `active` | Link disponível para receber pagamentos. |
| `paused` | Interromper a disponibilidade do link. |
| `archived` | Retirar a oferta de circulação. |

Use [atualização parcial](https://docs.sinnu.com.br/api/links/atualizar.md) para alterar campos e [arquivamento](https://docs.sinnu.com.br/api/links/arquivar.md) para retirar a oferta. Arquivar um link não estorna os pagamentos que já ocorreram.

## Acompanhe os pagamentos

Consulte as [transações do link](https://docs.sinnu.com.br/api/links/transacoes.md). Esse endpoint retorna valores em reais. Para padronizar sua conciliação em centavos, consulte cada pagamento na [API de transações](https://docs.sinnu.com.br/api/transacoes/consultar.md).

O [SDK de links](https://docs.sinnu.com.br/sdk/links.md) oferece métodos para essas operações.


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