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

# Ferramentas do servidor MCP

> O que cada ferramenta faz, o escopo que exige, os parâmetros principais e os cuidados ao usar.

O [servidor MCP](https://docs.sinnu.com.br/servidor-mcp/visao-geral.md) tem 12 ferramentas: 8 de consulta e 4 de escrita. Cada conexão vê só as que a credencial cobre:

* **Pelo login**, o [nível de acesso](https://docs.sinnu.com.br/servidor-mcp/visao-geral.md#escolha-o-nível-de-acesso) escolhido na autorização. **Somente leitura** vê as 8 de consulta; **Leitura e escrita** vê as 12.
* **Pela chave de API**, os escopos da chave. Em modo somente leitura (`?readonly=true`), vê só as de consulta.

As 4 de escrita são `create_payment_link`, `update_payment_link`, `create_customer` e `update_customer`. Cada uma exige, pelo login, o nível **Leitura e escrita** e, pela chave, o escopo de escrita indicado nela.

O assistente recebe a descrição e o schema de entrada de cada ferramenta pelo próprio protocolo. Esta página resume o que importa para quem configura a conexão e revisa o que o assistente faz.

## Convenções

* **Dinheiro em centavos.** Todo valor entra e sai como inteiro em centavos de real: `9900` é R\$ 99,00. Vale também para as transações de um link, que a API devolve em reais: o servidor converte antes de responder.
* **Listas paginadas.** As listas devolvem `{ data, total, page, pageSize }`. `page` começa em 1 e `pageSize` vale 20 quando omitido. Compare `total` com o que já foi recebido para saber se há mais páginas.
* **Resultado com tamanho limitado.** O texto de um resultado tem até 24.000 caracteres. Acima disso ele chega cortado, com um aviso no fim, e o JSON fica incompleto: refine os filtros ou peça páginas menores.
* **Entrada conferida antes.** Valor fora do formato e, nas ferramentas que recebem parâmetros, parâmetro desconhecido são recusados antes de qualquer chamada à API.
* **Dois vocabulários de status.** `list_transactions` e `get_transaction` usam `approved`, `pending`, `refused`, `refunded` e `chargeback`. `list_payment_link_transactions` repassa o status como a API o devolve naquele endpoint, em que um pagamento aprovado é `paid`. Veja [valores e status](https://docs.sinnu.com.br/fundamentos/valores-e-status.md).

Cada lista tem o seu máximo de `pageSize`, para a página caber inteira no resultado:

| Ferramenta | `pageSize` máximo |
| - | - |
| `list_payment_links` | 30 |
| `list_payment_link_transactions` | 50 |
| `list_transactions` | 25 |
| `list_customers` | 50 |

Em `list_payment_links`, uma página além do fim devolve `data` vazio. Em `list_transactions` e `list_customers`, devolve erro `404` com a mensagem "Página inválida", que só indica o fim da lista.

As ferramentas levam as anotações do protocolo (`readOnlyHint`, `destructiveHint` e `idempotentHint`). As de consulta são marcadas como somente leitura; `update_payment_link` e `update_customer`, como destrutivas, porque sobrescrevem valores. Um cliente MCP pode usar essas anotações para pedir confirmação antes de uma escrita.

## Conta

### `get_account_context`

Escopo: qualquer credencial válida. Não recebe parâmetros.

Mostra em nome de qual empresa a conexão age e o que a credencial permite. Devolve `company` (`id`, `slug` e `displayName`), `scopes` e `readOnly`. Use para confirmar a conta antes de uma escrita ou para entender por que uma ferramenta não aparece.

Pelo login, `scopes` mostra o nível: **Somente leitura** traz `links:read`, `transactions:read` e `customers:read`; **Leitura e escrita** traz também `links:write` e `customers:write`. `readOnly` é `true` só no [modo somente leitura](https://docs.sinnu.com.br/servidor-mcp/visao-geral.md#modo-somente-leitura) do endereço, usado com a chave; pelo login, vem `false` nos dois níveis.

## Links de pagamento

O link é a oferta que se envia ao comprador, pelo `checkoutUrl`. A transação é cada pagamento feito nele. Criar um link não gera cobrança.

As ferramentas de link devolvem estes campos:

| Campo | Significado |
| - | - |
| `id`, `slug` | Identificadores do link. Não mudam. |
| `checkoutUrl` | Endereço público do checkout, o que se envia ao comprador. |
| `title`, `description` | Nome e descrição da oferta. |
| `status` | `active`, `paused` ou `archived`. |
| `priceMode` | Modo de preço. Só os links com `fixed` podem ser alterados. |
| `amountCents` | Valor em centavos. `null` quando o link não tem valor fixo. |
| `methods` | Métodos que o link aceita: `pix`, `credit_card`, `applepay` e `googlepay`. |
| `maxInstallments`, `interestMode` | Parcelas no cartão e quem paga os juros. |
| `acceptsOneTime` | `true` quando o comprador paga uma vez o valor do link; `false` em link de assinatura. |
| `maxPayments` | Limite de pagamentos aprovados. `null` quando não há limite. |
| `tags`, `redirectUrl`, `externalReference` | Etiquetas, endereço de retorno e código do produto no seu sistema. |
| `salesCount`, `views`, `conversionRate`, `activeSubscriptions` | Vendas pagas, visitas ao checkout, vendas pagas por visita (fração de 0 a 1) e assinaturas que continuam sendo cobradas. |
| `createdAt`, `updatedAt` | Datas em ISO 8601. |

`acceptsOneTime`, `maxPayments`, `salesCount`, `views`, `conversionRate` e `activeSubscriptions` podem não vir. Campo ausente não significa `false`, zero nem sem limite.

### `list_payment_links`

Escopo: `links:read`.

Lista os links da conta, uma página por vez, com busca e filtros.

| Parâmetro | Uso |
| - | - |
| `page`, `pageSize` | Paginação. `pageSize` vai de 1 a 30. |
| `search` | Texto a procurar no título, no slug e na descrição. |
| `status` | Lista dos status a incluir: `active`, `paused` e `archived`. Omitido, a API devolve todos menos os arquivados. |
| `createdFrom`, `createdTo` | Primeiro e último dia de criação, inclusive, em `YYYY-MM-DD`, no horário de Brasília. |
| `ordering` | `createdAt`, `updatedAt`, `title`, `amountCents`, `status` ou `priceMode`. O prefixo `-` inverte a ordem. Padrão: `-createdAt`. |

O resultado traz também `counts` (`active`, `paused`, `archived` e `total`), que conta todos os links da conta por status, sem considerar filtros nem página. `counts` pode não vir.

### `get_payment_link`

Escopo: `links:read`.

Busca um link pelo `id` (UUID): configuração, status, números e `checkoutUrl`. Link inexistente ou de outra conta responde `404`.

### `create_payment_link`

Escopo: `links:write`. Pelo login, exige o nível **Leitura e escrita**.

Cria um link de valor fixo e devolve o link criado, já com o `checkoutUrl`.

| Parâmetro | Uso |
| - | - |
| `title` | Obrigatório. Nome da oferta. |
| `amountCents` | Obrigatório. Valor em centavos inteiros: R\$ 150,00 é `15000`. A API valida o mínimo e o máximo. |
| `description` | Descrição da oferta. |
| `methods` | Lista com `pix`, `credit_card`, `applepay` e `googlepay`. Uma carteira digital (`applepay` ou `googlepay`) exige `credit_card` no mesmo link. Omitido, a API cria o link aceitando só `pix`. |
| `maxInstallments` | Máximo de parcelas no cartão. A API valida o limite. |
| `interestMode` | `absorb` para absorver os juros do parcelamento; `pass_to_customer` para repassá-los ao comprador. Omitido, a API usa `pass_to_customer`. |
| `redirectUrl` | Para onde o checkout leva o comprador depois do pagamento confirmado: um endereço `https://` ou o deep link do seu app. |
| `externalReference` | Código do produto no seu sistema. Volta como `externalRef` do item em cada venda. |
| `tags` | Etiquetas livres para organizar os links. |
| `maxPayments` | Limite de pagamentos aprovados. Ao atingi-lo, a API arquiva o link. Omitido, o link não tem limite. |

Cuidados:

* **A criação não é idempotente.** Cada chamada cria um link novo, inclusive quando repete uma chamada que terminou em erro de rede ou de prazo. Na dúvida, confira com `list_payment_links` antes de tentar de novo.
* **Para uma cobrança única, envie `maxPayments: 1`.** Sem `maxPayments`, o mesmo link pode ser pago várias vezes. Com `1`, a API arquiva o link depois do primeiro pagamento aprovado.
* **Só valor fixo e pagamento avulso.** A ferramenta não cria link de assinatura nem link em que o comprador escolhe o valor, não envia imagem e não vincula cliente ao link.
* **Carteira digital depende do cartão.** A API recusa `applepay` ou `googlepay` sem `credit_card`, e nada é criado. Incluir a carteira em `methods` [não garante que ela esteja disponível](https://docs.sinnu.com.br/guias/links-de-pagamento.md#defina-a-oferta) para toda empresa, navegador ou dispositivo.
* **O link nasce ativo.** Ele fica disponível no `checkoutUrl` e herda os pixels de rastreamento padrão da empresa. Criar o link não gera cobrança nem movimenta dinheiro.
* **`redirectUrl` não confirma pagamento.** O retorno é liberado por empresa, e os parâmetros que chegam no endereço podem ser alterados pelo comprador. Confirme o pagamento pela API.
* **A API só cria link para empresa aprovada.** Quando ela recusa, o erro diz o motivo.
* **O link sai sem Vendedor responsável.** Vale para a conexão do login e para a chave de API, mesmo que quem autorizou a conexão seja da equipe.

### `update_payment_link`

Escopo: `links:write`. Para mudar `status`, a credencial precisa também de `links:read`, porque a ferramenta lê o link antes de alterar. Pelo login, exige o nível **Leitura e escrita**, que já inclui `links:read`.

Altera um link existente. Envie o `id` e só os campos a mudar, ao menos um: o que for omitido fica como está. Aceita os campos da criação e mais `status`.

| Parâmetro | Como muda |
| - | - |
| `description` | Texto vazio apaga a descrição. |
| `methods`, `tags` | Substituem a lista inteira. `tags: []` remove todas as etiquetas. |
| `redirectUrl`, `externalReference` | `null` remove o valor. |
| `maxPayments` | `null` remove o limite. Num link ativo, a API recusa um limite que os pagamentos já aprovados alcançaram. |
| `status` | `paused` pausa o link; `active` reativa um link pausado. |

Cuidados:

* **Cada campo enviado sobrescreve o valor atual.** `id`, `slug` e `checkoutUrl` não mudam. Repetir a mesma chamada leva ao mesmo resultado e não cria nada.
* **`methods` troca a lista inteira.** Para manter uma carteira digital que o link já aceita, envie a lista completa, com `credit_card` e o código da carteira: uma lista sem ele remove a carteira do link. A API recusa carteira digital sem `credit_card`, e nada é alterado.
* **Não arquiva, não exclui nem desarquiva.** Isso vale também para o link que a API arquivou ao atingir `maxPayments`. Com `status` num link arquivado, a ferramenta recusa e nada é alterado; os outros campos de um link arquivado podem ser alterados numa chamada sem `status`.
* **Link sem valor fixo não pode ser alterado.** Quando `priceMode` é diferente de `fixed`, a API responde `400` apontando `priceMode`, mesmo que a chamada só pause o link.

### `list_payment_link_transactions`

Escopo: `links:read`.

Lista todas as tentativas de pagamento de um link, da mais recente para a mais antiga. Recebe o `id` do link, `page` e `pageSize` (de 1 a 50). Link inexistente ou de outra conta responde `404`.

Cada item traz `id` (da transação), `amount` em centavos, `status`, `paymentMethod`, `installments`, `customer` (`id`, `name` e `email` do comprador), `createdAt` e `paidAt`, que é `null` quando a transação não foi paga.

Cuidados:

* **Nem toda tentativa é venda.** Além das pagas, vêm o Pix gerado e abandonado, as pendentes e as recusadas. Só os itens com `status` `paid` são vendas, e `total` conta as tentativas.
* **A lista não tem agregado.** Não some `amount` entre páginas para chegar a um total.
* **O `status` vem como a API o devolve neste endpoint.** Valores já vistos, sem que a lista seja fechada: `paid`, `pending`, `refused`, `declined`, `expired`, `refunded` e `chargedback`. Não trate como pago um status desconhecido.

## Transações

As duas ferramentas só consultam. O servidor não faz estorno nem emite recibo.

### `list_transactions`

Escopo: `transactions:read`.

Lista as transações da empresa, da mais recente para a mais antiga.

| Parâmetro | Uso |
| - | - |
| `page`, `pageSize` | Paginação. `pageSize` vai de 1 a 25. |
| `search` | Texto a procurar no nome do comprador, no e-mail do comprador ou na descrição da venda. Não procura por id, valor nem documento. |
| `status` | `approved`, `pending`, `refused`, `refunded` ou `chargeback`. |
| `customerId` | UUID do cliente: o `customer.id` de uma transação ou o `id` de `list_customers`. |

O resultado traz `metrics`, o agregado de todas as transações do filtro, e não só da página: `total` (soma bruta), `net` (soma líquida, só das aprovadas), `count` (quantidade) e `ticket` (ticket médio bruto). `metrics` pode não vir.

Cuidados:

* **Não há filtro por data, método de pagamento, valor nem link, e a ordem é fixa.** Para um período, percorra as páginas e pare quando `createdAt` passar da data procurada.
* **Use `metrics` para totais, em vez de somar páginas.** Sem `status`, `metrics.total` e `metrics.count` incluem recusadas, pendentes e estornadas. Para o total vendido, filtre por `status: "approved"`.

### `get_transaction`

Escopo: `transactions:read`.

Consulta uma transação pelo `id` (UUID): status atual, valores, taxas e motivo de uma recusa.

As duas ferramentas devolvem os mesmos campos por transação:

| Campo | Significado |
| - | - |
| `id` | Identificador da transação (UUID). |
| `status` | `approved` (paga), `pending` (aguardando pagamento), `refused` (recusada, cancelada ou expirada), `refunded` (com estorno) ou `chargeback` (em contestação). |
| `method` | `pix` ou `credit_card`. A API pode devolver outros códigos para variações do cartão. |
| `amount` | Valor bruto cobrado do comprador, em centavos. |
| `net` | Valor líquido da empresa, em centavos: o preço do produto menos as taxas e, quando você absorve os juros, menos os juros. |
| `productAmount`, `interestAmount` | Preço do produto e juros do parcelamento, em centavos. |
| `mdrAmount`, `fixedFeeAmount`, `otherFeeAmount`, `totalFeeAmount` | Taxas, em centavos. |
| `interestMode` | `pass_to_customer`, `absorb` ou `null`. |
| `installments`, `description` | Parcelas e descrição da venda. |
| `reference` | O pedido do seu sistema para a venda (o `?ref=` com que o checkout foi aberto), ou `null`. |
| `customer` | O comprador: `id`, `name` e `email`. |
| `createdAt`, `paidAt` | Datas em ISO 8601. `paidAt` é `null` enquanto não há pagamento. |
| `disputedAt`, `link`, `refusal`, `items` | Data da contestação; link que originou a venda (`id` e `title`); explicação de uma recusa (`code`, `title`, `detail`, `action`, `retryable` e `irreversible`); itens vendidos (`title`, `quantity`, `unitPrice` e `externalRef`). Podem não vir. |

Com os juros repassados ao comprador, `net` não é `amount` menos `totalFeeAmount`. `net` é um valor calculado e vem também na transação `pending`: não é dinheiro recebido. `items[].unitPrice` pode incluir os juros do parcelamento; para o preço do produto, use `productAmount`.

## Clientes

### `list_customers`

Escopo: `customers:read`.

Lista os clientes cadastrados na empresa. Cada item traz só `id`, `name`, `email`, `phone`, `type` (`pf` ou `pj`), `createdAt` e `archivedAt`. Documento, endereço e observações não vêm na lista: use `get_customer`.

| Parâmetro | Uso |
| - | - |
| `page`, `pageSize` | Paginação. `pageSize` vai de 1 a 50. |
| `search` | Texto a procurar no nome, no e-mail, no telefone ou no documento (CPF ou CNPJ, só os dígitos). |
| `ordering` | `createdAt`, `name` ou `id`. O prefixo `-` inverte a ordem. Padrão: `-createdAt`. |

Não há filtro por tipo de pessoa nem por data de cadastro, e cliente arquivado não aparece na lista.

### `get_customer`

Escopo: `customers:read`.

Consulta o cadastro completo de um cliente pelo `id` (UUID): `id`, `name`, `email`, `phone`, `document` (CPF ou CNPJ só com dígitos, ou `null`), `type`, `address`, `notes`, `createdAt`, `archivedAt` e `anonymizedAt`.

Cliente arquivado continua consultável pelo `id`. No cliente anonimizado (`anonymizedAt` preenchido), os dados pessoais foram apagados em definitivo e `document` sai `null`.

### `create_customer`

Escopo: `customers:write`. Pelo login, exige o nível **Leitura e escrita**.

Cadastra um cliente e devolve o cadastro criado. Só grava o cadastro: não cria cobrança nem link.

| Parâmetro | Uso |
| - | - |
| `name` | Obrigatório. Nome completo ou razão social. |
| `email` | Obrigatório. |
| `phone` | Telefone, com DDD. |
| `document` | CPF ou CNPJ, com ou sem máscara: a API guarda só os dígitos. Não pode repetir o de outro cliente ativo da empresa. |
| `type` | `pf` (pessoa física) ou `pj` (pessoa jurídica). Padrão: `pf`. A API não deduz o tipo pelo documento: para CNPJ, envie `pj`. |
| `address` | Endereço, em uma linha de texto livre. |
| `notes` | Observações internas, com até 500 caracteres. |

Cuidados:

* **O cadastro não é idempotente.** Repetir a chamada sem `document` cria outro cliente igual. Com um `document` que já é de um cliente ativo da empresa, a API recusa com `400` e nada é criado.
* **Procure antes de cadastrar.** Use `list_customers` para conferir se o cliente já existe.

### `update_customer`

Escopo: `customers:write` e `customers:read`. A ferramenta sempre lê o cadastro atual antes de gravar. Pelo login, exige o nível **Leitura e escrita**, que já inclui `customers:read`.

Altera o cadastro de um cliente pelo `id`. Envie só os campos a mudar, ao menos um, entre `name`, `email`, `phone`, `document`, `type`, `address` e `notes`. Texto vazio remove o `document` e pede para limpar `address` e `notes`; o cadastro devolvido mostra o que ficou.

Cuidados:

* **Cada campo enviado substitui o valor atual, sem como desfazer pelo servidor.** Consulte o cadastro com `get_customer` antes de sobrescrever. Repetir a mesma chamada deixa o cadastro no mesmo estado.
* **Cliente anonimizado é recusado.** Nada é enviado à API: os dados pessoais dele foram apagados em definitivo.
* **Documento repetido é recusado.** Um `document` que já é de outro cliente ativo da empresa volta com erro `400`.
* **Não arquiva nem exclui cliente.**

## Erros

Uma falha na chamada de uma ferramenta volta como resultado da ferramenta, com `isError: true` e um texto que começa com `Erro:`.

**Entrada inválida.** A entrada é conferida antes de qualquer chamada à API. O erro lista cada campo com o problema, em português:

```text Entrada inválida theme={null}
Erro: entrada inválida para esta ferramenta. Corrija e chame de novo:
- pageSize: Muito grande: esperado que number fosse <=25
- status: Opção inválida: esperada uma das "approved"|"pending"|"refused"|"refunded"|"chargeback"
```

**Erro da API.** O texto traz o status HTTP e o que a API informou: mensagem, código, campo e [ID da requisição](https://docs.sinnu.com.br/fundamentos/erros-e-limites.md#identificador-da-requisição). Por exemplo, ao criar um link com valor fora da faixa aceita:

```text Erro da API theme={null}
Erro: a API do sinnu recusou os dados enviados (HTTP 400). Mensagem da API: O valor deve estar entre R$ 10,00 e R$ 200.000,00. Código: invalid. Campo: amountCents. ID da requisição: 6f1c0b9e-2d4a-4c8e-9a51-0d3b7e2f8a10.
```

| HTTP | Significado | Ação |
| - | - | - |
| `400` / `422` | A API recusou os dados enviados. | Corrija o campo indicado. |
| `401` | A API recusou a credencial. A chave pode ter sido revogada, ou a conexão autorizada pode ter sido revogada ou expirado. | Com a chave, confira a chave no painel; com login, conecte de novo. As chamadas seguintes com a mesma credencial são recusadas na conexão. |
| `403` | A API não autorizou a operação, por falta de escopo na credencial ou por outra regra da conta. | Leia a mensagem da API, que diz o motivo. Não adianta repetir a chamada. |
| `404` | Recurso não encontrado nesta conta. | Confira o `id`. Em `list_transactions` e `list_customers`, "Página inválida" indica o fim da lista. |
| `429` | Limite de requisições da API. | Aguarde o tempo indicado no erro. |
| `5xx` | API indisponível no momento. | Tente de novo em instantes. Antes de repetir uma escrita, confira se ela já foi aplicada. |

**Sem resposta da API.** Cada chamada à API tem prazo de 30 segundos. Um [timeout não determina o resultado](https://docs.sinnu.com.br/fundamentos/erros-e-limites.md#timeout-não-determina-o-resultado): depois de um erro de prazo ou de rede numa criação, confira com a ferramenta de listagem antes de tentar de novo.

**Escrita confirmada com resposta inesperada.** Se a API confirmar uma criação ou alteração e responder num formato que o servidor não reconhece, o resultado é `{ written: true, id, warning }` no lugar do link ou do cadastro. A escrita foi feita: não repita a chamada.

## Limites de uso

* **Duas chamadas de ferramenta em andamento por credencial**, ou seja, por chave ou por conexão autorizada. As seguintes esperam a vez, até 32. Acima disso, a chamada volta com erro pedindo para tentar de novo, sem ser enviada à API.
* **Uma mensagem JSON-RPC por requisição**, com corpo de até 64 KiB.
* **Resposta de até 90 segundos.** Passado esse tempo, o servidor encerra a resposta.
* **Limite da API por credencial.** Com a chave, as chamadas das ferramentas contam no [limite por chave](https://docs.sinnu.com.br/fundamentos/erros-e-limites.md#limite-por-chave). Uma conexão autorizada tem o mesmo limite, contado por conexão.


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