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

# Clientes

> Cadastre, consulte, atualize e liste clientes da empresa com o SDK.

Os exemplos pressupõem um cliente `sinnu` [configurado no servidor](https://docs.sinnu.com.br/sdk/configuracao.md) a partir da versão `0.3.0` do `@sinnu-dev/sdk`.

> [!TIP]
>
> Se o seu objetivo é apenas criar um link de pagamento já com os dados do comprador preenchidos no checkout, envie o objeto `customer` diretamente em [`sinnu.links.create`](https://docs.sinnu.com.br/sdk/links#crie-um-link-com-comprador-e-limite-de-pagamentos) em uma única requisição. Use `sinnu.customers` quando o seu sistema mantiver um cadastro próprio de clientes ou reutilizar o mesmo `linkedCustomer` em várias cobranças.

## Cadastre um cliente

```ts TypeScript theme={null}
const customer = await sinnu.customers.create({
  name: "Maria Oliveira",
  email: "maria@exemplo.com.br",
  type: "pf",
  document: "12345678909",
  phone: "11999998888",
});
```

| Campo | Obrigatório | Uso |
| - | - | - |
| `name` | Sim | Nome completo (pessoa física) ou razão social (pessoa jurídica). |
| `email` | Sim | E-mail do cliente. |
| `type` | Não | `"pf"` (pessoa física) ou `"pj"` (pessoa jurídica). |
| `document` | Não | CPF (11 dígitos) ou CNPJ (14 dígitos), com ou sem pontuação. Único por empresa. |
| `phone` | Não | Telefone com DDD. Quando omitido no cadastro, o comprador informa o celular no checkout hospedado. |
| `address` | Não | Endereço textual livre (opcional). |
| `notes` | Não | Observações internas do cadastro (opcional). |

Se já existir um cliente na sua empresa com o mesmo `document`, a API retorna `400` (`SinnuValidationError`). Para criar ou reaproveitar automaticamente pelo documento ao gerar uma cobrança, use `customer` em `sinnu.links.create`.

## Consulte e atualize

```ts TypeScript theme={null}
const current = await sinnu.customers.get(customer.id);

const updated = await sinnu.customers.update(customer.id, {
  phone: "11988887777",
});
```

`update` envia apenas os campos informados via `PATCH`.

## Liste e percorra

```ts TypeScript theme={null}
const page = await sinnu.customers.list({
  search: "maria@exemplo.com.br",
  page: 1,
  pageSize: 20,
});

for await (const item of sinnu.customers.listAll({ search: "Maria", pageSize: 50 })) {
  console.log(item.id, item.name);
}
```

| Parâmetro | Uso |
| - | - |
| `search` | Buscar por nome, e-mail, telefone ou CPF/CNPJ. |
| `page` / `pageSize` | Controlar a página. |

## Vincule a um link de pagamento

Com o `id` salvo no seu banco, passe `linkedCustomer` ao criar ou atualizar um link:

```ts TypeScript theme={null}
const link = await sinnu.links.create({
  title: "Mensalidade plano anual",
  priceMode: "fixed",
  amountCents: 29900,
  methods: ["pix", "credit_card"],
  linkedCustomer: customer.id,
  maxPayments: 1,
});
```


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