# Nivro API: guia para agentes de código que integram com o Nivro

> Instruções para o agente de código (Claude Code, Codex, Cursor e afins) de um desenvolvedor que está integrando um sistema com a API pública do Nivro, o sistema de gestão para varejo: como autenticar, o modelo de vendas, pedidos e assinaturas, convenções, padrões de integração, receitas e erros. Leia tudo antes da primeira chamada.

- Base URL: `https://api.nivro.app/api`
- Autenticação: header `Authorization: Bearer <token>` em toda requisição.
- Corpo e respostas em JSON (`Content-Type: application/json`).
- Referência para humanos: https://www.nivro.app/desenvolvedores
- Este arquivo: https://www.nivro.app/agents.md (o mesmo conteúdo em https://www.nivro.app/llms.txt)

## Este arquivo é para integrar pela API. Só consultar num chat?

Este guia é para você construir ou manter uma integração entre o sistema de um desenvolvedor e o Nivro pela API REST. Se o pedido é só CONSULTAR dados (vendas, clientes, estoque, contas a receber, caixa) pelo chat do ChatGPT ou do Claude, sem escrever código, não é aqui: existe o conector do Nivro, `https://mcp.nivro.app/mcp` (servidor MCP, só leitura, com login do Nivro por OAuth), com o passo a passo em https://www.nivro.app/suporte/conectar-chatgpt-e-claude. O resto deste arquivo é para a API REST: use-o para CRIAR ou ALTERAR dados, sincronizar sistemas e ler em volume.

## 1. Antes de escrever código: chave, conta de teste e conexão

Você está trabalhando no repositório de um desenvolvedor, para construir ou manter a integração dele com o Nivro. Fale com ele de igual para igual e seja direto. Peça só o que não dá para descobrir sozinho: a chave de acesso (token) e as decisões de negócio. Código e comentários seguem o idioma e o estilo do projeto dele.

1. **Chave de acesso (token).** Procure `NIVRO_API_TOKEN` nas variáveis de ambiente e no `.env` do projeto (que deve estar no `.gitignore`). Se não houver, peça ao desenvolvedor. Quem cria é o proprietário da conta, em https://portal.nivro.app/settings?section=api-tokens (Ajustes, Usuários e acessos, aba "API e tokens"): "Gerar token", escolher o nome e a permissão. O valor começa com `nv_` e aparece uma única vez; perdeu, gera outro e revoga o antigo. Nunca grave a chave no código, em log, em teste versionado nem em mensagem de commit.
2. **Menor permissão que resolve.** Só ler: **Visualizador**. Lançar vendas, pedidos e clientes: **Operador**. Cadastrar produto, faturar pedido, ver relatórios, caixa e assinaturas (criar, cobrar, descontar, cancelar): **Gerente**. **Proprietário** só se o desenvolvedor pedir. Para webhooks é preciso Gerente. Diga qual papel você escolheu e por quê.
3. **Plano e conta de teste.** A API é do plano Profissional (o teste de 30 dias, sem cartão, já inclui). Não existe ambiente sandbox: toda chamada mexe numa loja de verdade, e uma venda entra no caixa, baixa estoque e pode emitir nota. Desenvolva e teste numa conta de teste, nunca na de produção do cliente. Se só houver produção, não crie dados de teste: leia e peça confirmação antes de escrever.
4. **Confira a conexão com `GET /v1/me`** (nome da empresa e papel do token) antes de escrever código. `401`: chave errada ou revogada, pare e peça outra. `403` com mensagem de plano: a conta não está no Profissional. `403` com `code: "billing_access_blocked"`: assinatura do Nivro com pendência (o desenvolvedor regulariza em Ajustes, Assinatura). Os cabeçalhos `x-tenant-billing-*` das respostas são informativos.
5. **A chave vive no servidor.** Chame a API do backend do desenvolvedor (job, worker, API dele), nunca do navegador nem de um app instalado: o token dá acesso à loja. Se o projeto é só front-end, proponha um pequeno backend que guarde a chave.
6. **Prefira o contrato a escrever à mão.** O OpenAPI (https://www.nivro.app/openapi/nivro-v1.json) é gerado do backend e traz todos os campos, tipos e exemplos. Em projeto tipado, gere o cliente ou os tipos a partir dele em vez de digitar interfaces; releia-o ao atualizar a integração, porque rotas novas entram nele.
7. **Comece pequeno.** Confirme o objetivo da integração em uma frase (o que sai do sistema dele, o que volta do Nivro, em que frequência), implemente o menor fluxo de ponta a ponta contra a conta de teste e só então amplie. Siga os padrões da seção 7 desde o primeiro commit: chave de idempotência, retry com espera, paginação e verificação de webhook são mais baratos de acertar agora do que de consertar depois.

## 2. Regras que você deve seguir

- **Ritmo:** no máximo 500 requisições por minuto por empresa, somando todos os tokens da conta. Leia `X-RateLimit-Remaining` em toda resposta e desacelere antes de zerar; `X-RateLimit-Reset` é o instante (Unix, em segundos) em que a cota volta. Em `429`, espere os segundos do header `Retry-After` e repita a mesma chamada. Nunca dispare em paralelo sem controle.
- **Token errado não se insiste:** `401` não melhora repetindo. Pare e peça outro token. Mais de 60 falhas de autenticação por minuto bloqueiam o seu IP por até um minuto, inclusive para o token certo.
- **Idempotência:** em todo `POST /v1/sales`, `POST /v1/memberships` e `POST /v1/memberships/:id/receive`, mande o header `Idempotency-Key` com um valor único por operação de negócio, derivado de um id ESTÁVEL do sistema de origem (o id do pedido, do contrato ou da parcela dele), e não um UUID novo a cada tentativa. Se a chamada der timeout ou erro de rede, repita com a MESMA chave e o MESMO corpo: a API devolve a venda já criada em vez de duplicar (também `201`, com o mesmo `id`; o corpo pode trazer campos em outra forma, então compare pelo `id`). Mesma chave com corpo diferente é `422 IDEMPOTENCY_KEY_REUSED`.
- **Tipos dos valores, que mudam por campo:** em vendas, `items[].unitPrice` é string (`"49.90"`) e `payments[].amount` é número (`49.90`). Em produtos, `price` e `cost` são string. Em pedidos, `items[].unitPrice` aceita número ou string. No que você ENVIA, valores sempre em reais com ponto decimal; nunca vírgula, nunca centavos inteiros (exceto `creditLimitCents` no cliente). Nas RESPOSTAS, todo campo terminado em `Cents` está em centavos (ex.: `totalFaturadoCents: 8480` é R$ 84,80).
- **Paginação:** `take` e `skip` (padrão 50, máximo 200); em pedidos, `page` (a partir de 1) e `limit`. Pedir mais de 200 é `400`, não um corte. Para ler tudo, pagine até a página voltar com menos itens que o pedido.
- **Datas:** formato `AAAA-MM-DD`. O par `startDate`/`endDate` cobre no máximo 366 dias; para mais, quebre em janelas.
- **Estoque:** venda não é barrada por falta de estoque (o saldo pode ficar negativo, de propósito, para o balcão não parar). Pedido é: `POST /v1/orders` sem saldo responde `400` com `code: "insufficient_stock"`. A API não ajusta estoque: a entrada da mercadoria é feita dentro do Nivro. Trate o `400` na integração (avise quem opera o sistema de origem) e só mande `allowInsufficientStock: true` se o desenvolvedor confirmar que o pedido deve nascer assim mesmo.
- **Ids:** todo id é UUID. Não invente id: busque o cliente, produto ou variação antes e use o `id` que a API devolveu.
- **Leia a mensagem do erro:** os `400` dizem qual campo está errado e como corrigir, quase sempre em português. Corrija o payload a partir dela; não tente variações às cegas. Se o erro é de estado da loja (sem estoque, cliente no limite), não há payload a corrigir: explique ao usuário.

## 3. O que confirmar com o desenvolvedor antes de rodar contra uma conta real

- O token mexe na loja de verdade: venda criada entra no caixa, baixa estoque e pode emitir nota fiscal. **Não crie dados de teste numa conta de produção** e não rode o seu código de integração contra produção sem o desenvolvedor mandar. Para testar, peça uma conta de teste.
- Peça confirmação explícita ao desenvolvedor antes de rodar, contra uma conta real: faturar pedido (`/convert`), cancelar venda, pedido ou assinatura, criar vendas ou assinaturas em lote, e alterar preço ou custo de produtos em lote. Mostre antes o que vai ser feito (quantos registros, qual total).
- Antes de faturar, chame `GET /v1/orders/:id/invoice-preview`. Ela não grava nada; use-a no fluxo, e mostre a prévia ao desenvolvedor quando estiver testando.
- Não use `acknowledgeCreditLimit: true` por conta própria. Passar do limite de venda a prazo de um cliente é decisão do lojista: faça disso uma opção explícita da integração, e não o padrão.
- A API só dá baixa em parcela de assinatura (`POST /v1/memberships/:id/receive`); em outras parcelas a prazo a baixa é feita dentro do Nivro. Ela também não emite nota avulsa, não ajusta estoque direto, não cadastra usuários e não cria planos de assinatura. Se a integração precisa disso, diga ao desenvolvedor que é feito dentro do Nivro.

## 4. Permissões (papel do token)

Cada token atua com o papel escolhido na criação, o mesmo sistema de papéis da equipe dentro do Nivro: o que o papel não faz na tela, o token também não faz. Um papel superior herda as permissões dos inferiores, e cada endpoint abaixo diz o papel mínimo.

| Papel | Pode |
| --- | --- |
| Visualizador (VIEWER) | Somente leitura |
| Operador (OPERATOR) | Leitura de clientes, produtos, pedidos, vendas e recebíveis, mais criar vendas, pedidos e clientes, separar e andar o pedido. Não lê relatórios nem despesas, não recebe o custo da venda nem do produto e não fatura pedido |
| Gerente (MANAGER) | Tudo do Operador, mais faturar e cancelar pedido, cancelar venda, cadastrar produtos, relatórios e resumo de caixa, e autorizar venda acima do limite a prazo |
| Proprietário (OWNER) | Acesso completo, incluindo a gestão de tokens |

## 5. Respostas e erros

As listas devolvem um array JSON puro (`[ {...}, {...} ]`), exceto `GET /v1/orders`, que devolve `{ "data": [...], "meta": { "total", "page", "limit", "totalPages" } }`. A lista de vendas traz o resumo de cada venda (total, situação, cliente), sem os itens; os itens vêm em `GET /v1/sales/:id`. Valores monetários nas respostas podem vir como string ou número, e sem zeros à direita (`"2.50"` enviado volta como `"2.5"`): converta para número antes de comparar ou somar. Criação bem-sucedida responde `201`.

Erros vêm em JSON: `{ "error": "BAD_REQUEST", "code": "BAD_REQUEST", "message": "...", "requestId": "..." }`. Trate pelo status HTTP e pelo `code`, que é estável (ex.: `RATE_LIMITED`, `IDEMPOTENCY_KEY_REUSED`, `PRODUCT_SKU_TAKEN`, `insufficient_stock`, `picked_qty_exceeds_ordered`, `nothing_to_invoice`, `ADVANCE_PENDING_RESOLUTION`). `message` é texto, ou uma lista de textos quando vários campos falham na validação. Ao relatar um erro ao usuário ou ao suporte, inclua o `requestId`.

| Status | O que fazer |
| --- | --- |
| 400 | Payload ou parâmetro inválido. Leia `message` (diz o campo e o formato), corrija e tente de novo uma vez. |
| 401 | Token ausente, inválido, revogado ou expirado. Não repita: peça outro token ao desenvolvedor. |
| 403 | Papel do token sem permissão, ou recurso fora do plano. Diga ao desenvolvedor qual papel ou plano falta; não tente outra rota para o mesmo efeito. |
| 404 | O id não existe nesta conta. Busque de novo pela lista; não reaproveite id de outra conta. |
| 409 | Conflito com o estado atual (pedido sem nada separado, adiantamento pendente, produto com estoque virando serviço). Não é falha de rede: repetir dá o mesmo resultado. Trate como regra de negócio: corrija o fluxo da integração ou avise o desenvolvedor, seguindo a instrução da mensagem. |
| 422 | `IDEMPOTENCY_KEY_REUSED`: você reusou uma `Idempotency-Key` com outro corpo. Se é uma venda nova, gere uma chave nova. |
| 429 | Espere os segundos de `Retry-After` e repita a mesma chamada. Se acontecer de novo, reduza o ritmo. |
| 5xx | Erro do servidor. Espere alguns segundos e repita no máximo 3 vezes, com espera crescente. Em `POST /v1/sales`, repita sempre com a mesma `Idempotency-Key`. Nos outros `POST` (cliente, produto, pedido) não há chave: antes de repetir, confira pela lista se o registro já foi criado, senão ele duplica. Persistindo, pare e avise o usuário. |

**Limites de taxa.** **500 requisições por minuto por empresa**. O limite é da conta, não do token: dois tokens da mesma empresa dividem a mesma cota. Toda resposta traz os headers abaixo. `X-RateLimit-Reset` é o instante em que a janela recomeça, em segundos desde 1970 (Unix). Ao exceder o limite, a API responde `429` com o header `Retry-After`, que diz quantos segundos esperar. Tentativas com token inválido também contam, por IP: depois de 60 falhas em um minuto, aquele IP recebe `429` até a janela fechar.

```
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 412
X-RateLimit-Reset: 1793332924
```

**Paginação e datas.** Listas aceitam `take` e `skip` (ou `page` e `limit`, nos pedidos): padrão 50 itens, máximo 200. Acima do máximo a resposta é `400`, não um corte silencioso. Datas vão no formato `AAAA-MM-DD`; o início não pode ser depois do fim, e o período vai até 366 dias.

## 6. Como as coisas funcionam

Leia antes dos fluxos: é o modelo por trás das rotas, para você não adivinhar.

### Vendas e pedidos

- **Venda é fato consumado.** `POST /v1/sales` registra uma venda que já aconteceu: entra no caixa conforme os `payments`, baixa estoque, pode gerar nota fiscal e comissão. Não há rascunho: errou, cancele com `POST /v1/sales/:id/cancel` (que estorna) e lance de novo.
- **À vista x a prazo.** Venda à vista leva `payments` que somam o total. Venda a prazo leva `receivables` (parcelas com `installmentNo`, `dueDate`, `amount`) e exige `customerId`. As parcelas viram contas a receber, que você lê em `GET /v1/receivables`.
- **Pedido x venda.** Pedido (`/v1/orders`) é a intenção: reserva, separa e só vira venda quando é faturado (`/convert`). Use pedido quando a mercadoria ainda vai ser separada ou entregue; use venda quando já foi entregue e paga.
- **Canal.** `channel` diz de onde veio: `ONLINE`, `WHATSAPP`, `PHONE`, `POS` ou `OTHER`. Serve para os relatórios do lojista, não muda a regra da venda.

### Assinaturas (cobrança recorrente)

- **O que é.** Assinatura é uma cobrança recorrente de um cliente num plano (mensalidade de academia, clube, serviço). Três coisas: o **plano** (`GET /v1/memberships/plans`: preço, periodicidade `WEEKLY`, `MONTHLY`, `QUARTERLY`, `SEMIANNUAL` ou `YEARLY`, dias de teste), a **assinatura** (o cliente neste plano, com preço, desconto e situação) e as **cobranças** (uma por ciclo). Planos são criados dentro do Nivro; pela API você só os lê e assina um cliente neles.
- **Exige o módulo Assinaturas.** Sem o módulo ligado na loja, as rotas de escrita respondem `403`. Se isso acontecer, o lojista precisa ligar em Ajustes, Módulos: diga ao desenvolvedor e trate o `403` na integração com uma mensagem clara.
- **Como uma cobrança nasce.** O Nivro gera sozinho, alguns dias antes do vencimento, uma venda a prazo com uma parcela para aquele ciclo. Você não cria a cobrança; você a lê (`GET /v1/memberships/charges` ou `charges` dentro de `GET /v1/memberships/:id`) e pega o `receivableId` para dar baixa. Um ciclo ainda não gerado não tem `receivableId`: não dá baixa antecipada.
- **Situações (`status`).** `TRIALING` (em teste), `ACTIVE`, `PAUSED` (combinado com o cliente, volta com `resume`), `PAST_DUE` (inadimplente: cobrança vencida além da carência; sai sozinha quando ele paga), `SUSPENDED` (decisão da loja; só volta com `reactivate`), `CANCELED` e `ENDED` (chegou ao `endDate`). `CANCELED` e `ENDED` não voltam: crie outra assinatura.
- **Dar baixa.** `POST /v1/memberships/:id/receive` com `receivableIds` (até 60, da mesma assinatura) e `method`. É sempre o valor integral da parcela. Mande `Idempotency-Key`: sem ela, repetir uma baixa já feita é `409`; com ela, devolve o mesmo resultado. Quitar a dívida de uma assinatura `PAST_DUE` a reativa na hora.
- **Preço e desconto.** O `price` é negociado e congelado na adesão (pode ser diferente do plano). Para dar um desconto use `POST /v1/memberships/:id/discount` (`PERCENT` até 100 ou `AMOUNT`, por `cycles` ciclos ou para sempre; 100% zera o ciclo sem cobrança). Para mudar o preço de vez, `POST /v1/memberships/:id/reprice`. Ambos valem do próximo ciclo a gerar em diante e nunca mexem num ciclo já cobrado. `price` e desconto não aparecem para token de Operador.
- **Um mês diferente.** `POST /v1/memberships/:id/exceptions` isenta (`SKIP`) ou troca o valor (`OVERRIDE`) de UM vencimento futuro; `DELETE .../exceptions/:periodStart` desfaz. Ciclo já cobrado não aceita exceção.
- **Trocar de plano.** `POST /v1/memberships/:id/change-plan` agenda para o próximo ciclo; mandar o plano atual desfaz o agendamento. O evento `membership.plan_changed` só sai quando a troca é aplicada.
- **Cancelar.** `POST /v1/memberships/:id/cancel`: por padrão cancela agora e não se desfaz; com `atPeriodEnd: true` só agenda o fim e `POST .../keep` desfaz. `cancelOpenCharges` decide se cobranças em aberto também são canceladas: pergunte ao usuário antes.
- **Fuso e datas.** Todas as datas são `AAAA-MM-DD` no dia da loja (America/Sao_Paulo por padrão), não UTC.

### Webhooks (eventos de assinatura e cobrança)

- **Prefira webhook a ficar consultando.** Para saber que uma assinatura mudou ou que uma cobrança foi paga, cadastre um endpoint em `POST /v1/webhooks` (token de Gerente) em vez de chamar `GET /v1/memberships` de tempos em tempos. O segredo (`whsec_...`) volta UMA vez, na criação: guarde-o como a chave da API.
- **Eventos:** `membership.created`, `.paused`, `.resumed`, `.suspended`, `.reactivated`, `.plan_changed`, `.canceled`, `.past_due`, `charge.created`, `charge.paid` e `ping` (só pelo teste). Sem `events` no cadastro, recebe todos.
- **Verifique a assinatura em todo POST recebido.** Header `Nivro-Signature: v1=<hex>` é o HMAC-SHA256 de `"<Nivro-Timestamp>.<corpo cru>"` com o segredo. Calcule sobre o corpo CRU, antes de qualquer `JSON.parse`, compare em tempo constante e recuse timestamp com mais de 5 minutos. Há código pronto em Node e Python na descrição do grupo Webhooks, na referência abaixo.
- **Responda `2xx` em até 10 segundos e processe depois.** Qualquer outra coisa é falha e a entrega se repete (1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h; depois fica `FAILED` e dá para reenviar). Depois de 50 falhas seguidas o webhook é desligado. A entrega é **pelo menos uma vez**: deduplique pelo `id` do corpo e não conte com a ordem.
- **A URL precisa ser pública e `https://` (porta 443 ou 8443).** Endereço interno, `localhost` ou com usuário e senha é recusado. Para testar em desenvolvimento, exponha a máquina com um túnel `https` e use `POST /v1/webhooks/:id/test`.

## 7. Padrões de integração (aplique no código do desenvolvedor)

- **Idempotência em toda escrita que cria.** Derive a `Idempotency-Key` de um id estável do sistema de origem (pedido, contrato, parcela), nunca de um UUID novo a cada tentativa: assim o retry depois de um timeout devolve o que já foi criado, em vez de duplicar. Vale para `POST /v1/sales`, `POST /v1/memberships` e `POST /v1/memberships/:id/receive`. Nos demais `POST` não há chave: antes de repetir, confira pela lista se o registro já existe.
- **Guarde o mapa de ids.** Persista no sistema do desenvolvedor o `id` do Nivro de cada cliente, produto, venda e assinatura que ele criar, ao lado do id dele. Não busque por nome a cada sincronização: nome muda e se repete. Para achar o que já existe, use `search` por CPF/CNPJ, SKU ou e-mail uma vez, e guarde o resultado.
- **Retry com espera crescente, e só onde vale.** Repita `429` (respeite `Retry-After`) e `5xx` (até 3 vezes, com espera crescente e algum sorteio). Não repita `400`, `401`, `403`, `404`, `409` nem `422`: o resultado não muda. Registre o `requestId` de cada erro nos logs da integração; é o que o suporte do Nivro pede.
- **Prefira webhook a polling.** Para saber de mudança de assinatura ou de pagamento de ciclo, use `POST /v1/webhooks` em vez de listar de tempos em tempos. Se precisa listar mesmo assim (carga inicial, conciliação), pagine inteiro, filtre por data e não passe de uma varredura por minuto. Faça uma conciliação periódica (por exemplo diária) além dos webhooks: a entrega é pelo menos uma vez, sem ordem garantida, e um endpoint seu fora do ar por horas perde a janela de tentativas.
- **Receptor de webhook robusto.** Verifique a assinatura sobre o corpo cru antes de qualquer parse, recuse timestamp velho, responda `2xx` rápido e processe numa fila, e deduplique pelo `id` do evento (grave os ids já tratados). Trate o evento como aviso e, se a ordem importar, releia o recurso (`GET /v1/memberships/:id`) em vez de confiar no estado do corpo.
- **Valores em dinheiro.** Envie reais com ponto, em string onde a referência pede string; nunca ponto flutuante binário para somar. Use decimal ou centavos inteiros no seu lado e converta na borda. Compare valores das respostas depois de convertê-los (podem voltar sem zeros à direita).
- **Tempo e fuso.** Datas de negócio são `AAAA-MM-DD` no dia da loja (America/Sao_Paulo por padrão), não UTC. Para "hoje" use o dia da loja, senão uma assinatura que vence "hoje" some entre 21h e meia-noite.
- **Carga inicial em lote, com controle.** Para importar muitos registros, faça uma fila com concorrência pequena e fixa (2 a 4), leia `X-RateLimit-Remaining` e desacelere, grave o progresso (para retomar de onde parou) e uma lista de falhas com a mensagem e o `requestId`. Nunca dispare tudo em paralelo.
- **Sem segredos no repositório.** `NIVRO_API_TOKEN` e o segredo do webhook (`whsec_...`) vão para variáveis de ambiente ou para o cofre do desenvolvedor. Rotacione o do webhook com `rotate-secret` se vazar; revogue o token na tela de chaves.
- **Teste contra uma conta de teste, e escreva testes.** Cubra com teste automatizado a parte que é sua: montagem do corpo, chave de idempotência estável, verificação de assinatura do webhook (com um corpo e segredo conhecidos) e tratamento de `429` e `409`. Não faça teste automatizado bater na API de produção.

## 8. Fluxos de ponta a ponta

### Conferir a conexão

1. `GET /v1/me` e confirme com o desenvolvedor o nome da empresa e o papel do token.

```bash
curl -s https://api.nivro.app/api/v1/me -H "Authorization: Bearer $NIVRO_API_TOKEN"
```

### Importar produtos de uma planilha (token de Gerente)

1. Leia a planilha e monte um produto por linha: `name` (até 200), `price` (string), `unit` (ex.: `UN`, `KG`, até 10 caracteres), e opcionais `sku`, `cost`, `type` (`PRODUCT` ou `SERVICE`).
2. Tire os SKUs repetidos da própria planilha antes de tudo (sem diferenciar maiúsculas): a segunda linha com o mesmo SKU é "pulada", não criada. Se as linhas repetidas têm nome, unidade ou preço diferentes, provavelmente são produtos distintos com SKU errado: liste-as ao usuário e pergunte o SKU certo em vez de descartar.
3. Para cada linha, busque o SKU com `GET /v1/products?search=<sku>` para não duplicar o que já existe na loja. SKU repetido é `400` com `code: "PRODUCT_SKU_TAKEN"` e `details.productId` do produto que já tem o código.
4. Mostre ao desenvolvedor quantos produtos vão ser criados e peça confirmação (em produção).
5. Crie um por vez com `POST /v1/products` (sucesso é `201`), respeitando o ritmo. Guarde o `id` de cada um e registre as linhas que falharam com a mensagem do erro.
6. Produto nasce com estoque zero. Se a loja vai vender ou fazer pedido dele, lembre o desenvolvedor de que a entrada da mercadoria é feita dentro do Nivro.
7. No fim, informe criados, pulados (SKU já existia na loja ou repetido na planilha) e falhas.

```bash
curl -s -X POST https://api.nivro.app/api/v1/products \
  -H "Authorization: Bearer $NIVRO_API_TOKEN" -H "Content-Type: application/json" \
  -d '{"name": "Camiseta básica P", "sku": "CAM-P", "price": "59.90", "cost": "22.00", "unit": "UN"}'
```

### Puxar as vendas de um mês

1. `GET /v1/sales?startDate=2026-10-01&endDate=2026-10-31&take=200&skip=0`, depois `skip=200`, `skip=400`... até voltar menos de 200.
2. A lista traz o resumo de cada venda. Para os itens, chame `GET /v1/sales/:id` (conte essas chamadas no ritmo).
3. Se só precisa dos totais (faturamento, número de vendas, ticket médio), não pagine: `GET /v1/reports/sales-comparison?startDate=...&endDate=...` (Gerente) devolve `current.revenue`, `current.salesCount` e `current.avgTicket` numa resposta pequena, já comparados ao período anterior. Sem `previousStartDate`/`previousEndDate`, o "anterior" é o intervalo de mesmo tamanho logo antes (31 dias antes de outubro pegam 31/08); para comparar mês com mês, mande o mês anterior explícito (`previousStartDate=2026-09-01&previousEndDate=2026-09-30`). Se o mês ainda não acabou, marque o número como parcial no que você mostrar. `percent` vem `null` quando o período anterior é zero: trate como "sem base de comparação" e não invente porcentagem. O `daily-summary` também tem os totais, mas traz junto todas as vendas do período e fica pesado em mês inteiro.

```bash
curl -s "https://api.nivro.app/api/v1/sales?startDate=2026-10-01&endDate=2026-10-31&take=200" \
  -H "Authorization: Bearer $NIVRO_API_TOKEN"
```

### Registrar uma venda vinda de outro sistema (loja virtual, planilha)

1. Ache o cliente com `GET /v1/customers?search=<nome, CPF/CNPJ, telefone ou e-mail>`; se não existir, crie com `POST /v1/customers` (basta `name`; `doc`, `email`, `phone` são validados quando enviados). Venda à vista pode ir sem cliente; venda a prazo exige `customerId`.
2. Ache o produto (`GET /v1/products?search=`) e, se ele tiver grade, a variação (`GET /v1/products/:id/variants`) para mandar `variantId`.
3. Monte `items` (`productId`, `qty`, `unitPrice` string) e `payments` (`method`, `amount` número). A soma dos pagamentos deve fechar o total.
4. Mande com `Idempotency-Key` igual ao id do pedido na origem. Se repetir, a venda não duplica.
5. `channel`: `ONLINE` para loja virtual, `WHATSAPP`, `PHONE`, `POS` ou `OTHER` (padrão).

```bash
curl -s -X POST https://api.nivro.app/api/v1/sales \
  -H "Authorization: Bearer $NIVRO_API_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: loja-virtual-pedido-10423" \
  -d '{
    "channel": "ONLINE",
    "customerId": "CUSTOMER_ID",
    "items": [{ "productId": "PRODUCT_ID", "qty": 2, "unitPrice": "59.90" }],
    "payments": [{ "method": "PIX", "amount": 119.80 }]
  }'
```

### Criar pedido, separar e faturar

1. `POST /v1/orders` com `customerId` (obrigatório) e `items` (`productId`, `qty` inteira, `unitPrice`). A resposta (`201`) já é o pedido completo, com o `id` de cada item. Sem saldo em estoque a resposta é `400 insufficient_stock` (ver "Estoque" nas regras).
2. Para registrar a separação, `POST /v1/orders/:id/picking` com `items: [{ itemId, pickedQty }]`, usando o `id` do item do pedido (não o do produto). `pickedQty` não passa da quantidade pedida.
3. `GET /v1/orders/:id/invoice-preview` e confira o que vai ser faturado e o que faltou.
4. Não precisa mudar o status para `SEPARATED` antes de faturar: a separação registrada basta. A prévia traz `totalFaturadoCents` (em centavos) e `faltas`; é esse valor, não o total original do pedido, que os `payments` devem somar.
5. Com a confirmação, `POST /v1/orders/:id/convert` com `paymentType` (`CASH` ou `INSTALLMENTS`) e, para o que já foi pago, `payments`. A venda nasce com as quantidades separadas. A resposta é `{ order, sale, faltas, totalOriginalCents, totalFaturadoCents }`; o pedido passa a ter `saleId`, e `GET /v1/sales/:id` traz o `orderId` de volta.
6. Faturar de novo o mesmo pedido é `400` ("already converted"): se a resposta do `/convert` se perdeu, confira `GET /v1/orders/:id` (status `CONVERTED` e `saleId`) antes de repetir.

```bash
curl -s -X POST https://api.nivro.app/api/v1/orders/ORDER_ID/convert \
  -H "Authorization: Bearer $NIVRO_API_TOKEN" -H "Content-Type: application/json" \
  -d '{"paymentType": "CASH", "payments": [{ "method": "PIX", "amount": 119.80 }]}'
```

### Ver quem deve (parcelas em aberto)

1. `GET /v1/receivables/summary` sem filtro dá o total em aberto de tudo (vencido e a vencer), o recebido, quantas estão em atraso (`overdueCount`) e o próximo vencimento. Ele aceita os mesmos `search`, `startDate` e `endDate` da lista, sempre pelo vencimento.
2. Para as vencidas: `startDate`/`endDate` filtram o vencimento, então use `endDate=<ontem>`, calculado a partir da data de hoje (se hoje é 2026-10-30, `endDate=2026-10-29`). Atraso é derivado do vencimento: não existe `status=LATE`, e `status` aceita um valor por chamada. Faça uma chamada com `status=PENDING` e outra com `status=PARTIALLY_PAID` (parcela paga em parte também está em atraso), paginando com `take`/`skip`.
3. O total em atraso é `GET /v1/receivables/summary?endDate=<ontem>` (`openTotal`).

```bash
curl -s "https://api.nivro.app/api/v1/receivables?status=PENDING&endDate=2026-10-29&take=200" \
  -H "Authorization: Bearer $NIVRO_API_TOKEN"
```

### Assinar um cliente e acompanhar o pagamento (assinaturas)

1. Ache o plano (`GET /v1/memberships/plans`) e o cliente (`GET /v1/customers?search=`, ou crie com `POST /v1/customers`). Se o cliente já tem assinatura viva nesse plano, confira em `GET /v1/memberships?customerId=...&status=ACTIVE` antes de assinar de novo.
2. Crie com `POST /v1/memberships` (`customerId`, `planId`, e opcionais `startDate`, `billingDay`, `price`, `trialDays`, `endDate`, `discountType`/`discountValue`/`discountCycles`). Mande `Idempotency-Key` com o id do cliente ou do contrato na origem: um retry não assina duas vezes.
3. Guarde o `id` da assinatura. Se `startDate` é hoje e não há teste, o primeiro ciclo já nasce cobrado: leia `GET /v1/memberships/:id` e pegue o `receivableId` do ciclo em `charges`.
4. Para saber do pagamento sem consultar, cadastre um webhook com `charge.paid` (fluxo de webhooks). Se o pagamento acontece fora do Nivro (Pix na conta da loja, por exemplo), registre com `POST /v1/memberships/:id/receive` e `Idempotency-Key`.
5. Mensalmente, `GET /v1/memberships/charges?status=overdue` lista o que está vencido, para cobrar ou suspender.

```bash
curl -s -X POST https://api.nivro.app/api/v1/memberships \
  -H "Authorization: Bearer $NIVRO_API_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: contrato-8841" \
  -d '{"customerId": "CUSTOMER_ID", "planId": "PLAN_ID", "startDate": "2026-11-15", "billingDay": 10}'
```

### Dar 100% de desconto (cortesia) numa assinatura existente

1. Defina por quantos ciclos vale e o motivo (a integração costuma receber isso do sistema de origem); sem `cycles` o desconto vale para sempre.
2. `POST /v1/memberships/:id/discount` com `type: "PERCENT"`, `value: 100`, `cycles` e `reason`. Aplicar outro desconto substitui este.
3. Um ciclo já cobrado não muda. Para tirar, `DELETE /v1/memberships/:id/discount` (`409` se não há desconto).

```bash
curl -s -X POST https://api.nivro.app/api/v1/memberships/MEMBERSHIP_ID/discount \
  -H "Authorization: Bearer $NIVRO_API_TOKEN" -H "Content-Type: application/json" \
  -d '{"type": "PERCENT", "value": 100, "cycles": 3, "reason": "Cortesia de boas-vindas"}'
```

### Receber eventos por webhook em vez de consultar

1. Tenha uma URL `https://` pública no seu serviço que aceite `POST` com corpo JSON.
2. `POST /v1/webhooks` com `url` e `events` (token de Gerente). Guarde o `secret` da resposta: não volta.
3. `POST /v1/webhooks/:id/test` envia um `ping`. Confira que seu serviço verificou a assinatura e respondeu `2xx`.
4. No serviço: verifique `Nivro-Signature` sobre o corpo cru, deduplique pelo `id` do evento, responda `2xx` já e processe depois.
5. Para diagnosticar, `GET /v1/webhooks/:id/deliveries` mostra o que foi enviado, o código e o motivo da última falha; `.../deliveries/:deliveryId/retry` reenvia uma que falhou. Se o webhook foi desligado por falhas (`active: false`, com `disabledReason`), corrija o endereço e reative com `PATCH /v1/webhooks/:id` e `active: true`.

```bash
curl -s -X POST https://api.nivro.app/api/v1/webhooks \
  -H "Authorization: Bearer $NIVRO_API_TOKEN" -H "Content-Type: application/json" \
  -d '{"url": "https://exemplo.com.br/nivro/eventos", "events": ["membership.created", "charge.paid"]}'
```

## 9. Referência dos endpoints

Caminhos relativos à base URL. "Papel" é o papel mínimo do token.

### Conta e token

Confirma que o token funciona, sem criar nada no sistema.

É o primeiro endpoint que qualquer integrador chama, porque é o único que responde "meu token funciona?" sem criar nada no sistema de ninguém.

#### `GET /v1/me`

Confirma que o token é válido e devolve a empresa conectada, o nome do token e o papel dele. Não exige nenhuma permissão de negócio específica.

- Papel: qualquer token

```bash
curl https://api.nivro.app/api/v1/me \
  -H "Authorization: Bearer nv_..."
```

### Clientes

Criar, listar e buscar clientes.

#### `POST /v1/customers`

Cria um cliente

- Papel: Operador ou acima
- Corpo (JSON):
  - `name` (texto)
  - `customerType` ("PF" | "PJ")
  - `firstName` (texto)
  - `lastName` (texto)
  - `nameOfficial` (texto)
  - `nameDisplay` (texto)
  - `stateRegistration` (texto)
  - `municipalRegistration` (texto)
  - `phone` (texto)
  - `doc` (texto)
  - `email` (texto)
  - `street` (texto)
  - `number` (texto)
  - `complement` (texto)
  - `district` (texto)
  - `city` (texto)
  - `state` (texto)
  - `postalCode` (texto)
  - `cityIbgeCode` (texto): Código IBGE do município, 7 dígitos.
  - `country` (texto)
  - `address` (texto)
  - `notes` (texto)
  - `birthDate` (texto)
  - `creditLimitCents` (número): Limite de crédito para venda a prazo, em centavos. Ausente/NULL = sem limite (comportamento de hoje). 0 = bloqueia qualquer venda a prazo.
  - `preferences` (objeto): Preferências estruturadas do cliente (tamanho, sabor, restrições etc.). Shape livre de propósito — ver comentário do campo no schema.

```bash
curl -X POST https://api.nivro.app/api/v1/customers \
  -H "Authorization: Bearer nv_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Cliente Exemplo", "doc": "12345678900", "email": "maria@example.com"}'
```

#### `GET /v1/customers`

Lista clientes

- Papel: qualquer papel
- Parâmetros:
  - `search` (query): Texto a buscar.
  - `take` (query): Padrão 50, máximo 200
  - `skip` (query): Quantos itens pular, para paginar com `take`.

```bash
curl "https://api.nivro.app/api/v1/customers?search=maria&take=20" \
  -H "Authorization: Bearer nv_..."
```

#### `GET /v1/customers/:id`

Busca um cliente por id

- Papel: qualquer papel
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).

```bash
curl https://api.nivro.app/api/v1/customers/CUSTOMER_ID \
  -H "Authorization: Bearer nv_..."
```

### Produtos

Produtos e serviços: criar, atualizar, listar e ver as variações da grade.

- **type** é o único enum real neste payload. Aceita apenas `PRODUCT` ou `SERVICE` (padrão `PRODUCT` se omitido). Serviços são tratados como um produto sem controle de estoque.
- **unit** não é um enum, é texto livre (ex.: `"UN"`, `"KG"`, `"L"`) de até 10 caracteres, não validado contra uma lista fixa.
- **sku** é único na conta sem diferenciar maiúsculas de minúsculas: `ref-2l` e `REF-2L` são o mesmo SKU, e repetir dá `400`.
- **categoryId** precisa ser uma categoria da conta (senão `400`). **photoUrl** precisa ser uma URL `https` pública. **name** vai até 200 caracteres.
- Trocar `type` de `PRODUCT` para `SERVICE` com saldo em estoque dá `409`: zere o estoque antes.
- Token de Operador recebe o produto sem `cost` e `avgCost`.
- **price** e **cost** são sempre string numérica decimal positiva (ex.: `"8.90"`), nunca negativa e nunca zero para `price`.

#### `POST /v1/products`

Cria um produto ou serviço

- Papel: Gerente ou acima
- Corpo (JSON):
  - `name` (texto, obrigatório)
  - `type` ("PRODUCT" | "SERVICE")
  - `sku` (texto)
  - `brand` (texto): Marca do produto. Texto livre, independente da categoria e do fornecedor.
  - `price` (texto): Preço de venda, como texto numérico sem sinal de menos ("49.90"). Obrigatório para o que se vende; item só de insumo (`hiddenFromSales: true`) pode vir sem preço.
  - `hiddenFromSales` (verdadeiro/falso): Item só de insumo: não aparece no PDV nem no catálogo.
  - `rentable` (verdadeiro/falso): Produto locável (módulo Locação), com preço por período. Exige `rentPrice` e `rentUnit`; serviço e produto controlado por série não podem ser locáveis.
  - `rentPrice` (texto)
  - `rentUnit` ("DAY" | "WEEK" | "MONTH" | "EVENT")
  - `rentMinPeriods` (número)
  - `replacementPrice` (texto)
  - `cost` (texto)
  - `promotionalPrice` (texto): Preço promocional ("de/por"), com início e fim opcionais. Vale para todas as variações da grade. Tem de ser menor que o preço normal, e o fim depois do início.
  - `promotionStartsAt` (texto)
  - `promotionEndsAt` (texto)
  - `unit` (texto, obrigatório)
  - `categoryId` (texto)
  - `photoUrl` (texto)
  - `photoKey` (texto)
  - `photoThumbUrl` (texto)
  - `photoThumbKey` (texto)
  - `minStock` (número)
  - `maxStock` (número): Estoque máximo: acima dele o estoque é considerado excesso (capital parado).
  - `reorderPoint` (número)
  - `allowsFractionalQty` (verdadeiro/falso): Aceita quantidade fracionada neste produto? `null` (padrão) decide pela unidade; `true` ou `false` forçam a regra.
  - `ncm` (texto)
  - `cest` (texto)
  - `cfopDefault` (texto)
  - `origem` (texto)
  - `tracksExpiry` (verdadeiro/falso): O produto tem validade? Campo ausente faz o produto herdar a regra da categoria; `false` é uma resposta ("este não tem").
  - `axes` (lista de objetos)
  - `initialStockByCell` (lista de objetos): Estoque inicial por combinação. Exige `axes`.

```bash
curl -X POST https://api.nivro.app/api/v1/products \
  -H "Authorization: Bearer nv_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Refrigerante 2L", "type": "PRODUCT", "sku": "REF-2L", "price": "8.90", "cost": "5.50", "unit": "UN"}'
```

#### `GET /v1/products`

Lista produtos. Use type=PRODUCT ou type=SERVICE para filtrar apenas um dos dois. O catálogo do Nivro trata serviços como um tipo de produto sem estoque.

- Papel: qualquer papel
- Parâmetros:
  - `search` (query): Texto a buscar.
  - `type` (query): Filtra pelo tipo do item do catálogo
  - `take` (query): Padrão 50, máximo 200
  - `skip` (query): Quantos itens pular, para paginar com `take`.

```bash
curl "https://api.nivro.app/api/v1/products?type=SERVICE&take=20" \
  -H "Authorization: Bearer nv_..."
```

#### `PUT /v1/products/:id`

Atualiza um produto ou serviço. Todos os campos são opcionais: envie apenas o que deseja alterar.

- Papel: Gerente ou acima
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).
- Corpo (JSON):
  - `name` (texto)
  - `type` ("PRODUCT" | "SERVICE")
  - `sku` (texto)
  - `trackingMode` (objeto): Controle por número de série (IMEI ou série por unidade). Só `NONE` e `SERIAL` são aceitos. Virar `SERIAL` com saldo em estoque é recusado (`serial_conversion_required`): o saldo precisa de uma série por unidade, e isso se faz pela conversão em `POST /stock-units/convert-to-serial`.
  - `brand` (texto): Marca do produto. Texto livre, independente da categoria e do fornecedor.
  - `price` (texto)
  - `cost` (texto)
  - `promotionalPrice` (texto): Preço promocional ("de/por"), com início e fim opcionais. Vale para todas as variações da grade. `null` encerra a promoção; campo ausente não muda.
  - `promotionStartsAt` (texto)
  - `promotionEndsAt` (texto)
  - `unit` (texto)
  - `categoryId` (texto)
  - `photoUrl` (texto)
  - `photoKey` (texto)
  - `photoThumbUrl` (texto)
  - `photoThumbKey` (texto)
  - `minStock` (número)
  - `maxStock` (número): Estoque máximo: acima dele o estoque é considerado excesso (capital parado).
  - `reorderPoint` (número)
  - `commissionPercentage` (número): Comissão deste produto. `null` limpa a taxa (volta a herdar da categoria); campo ausente não muda.
  - `hiddenFromSales` (verdadeiro/falso)
  - `rentable` (verdadeiro/falso): Produto locável (módulo Locação). `rentPrice`, `rentUnit` e `replacementPrice` aceitam `null` para limpar; campo ausente não muda. Locável exige preço e unidade; serviço e produto com série não podem ser locáveis.
  - `rentPrice` (número)
  - `rentUnit` ("DAY" | "WEEK" | "MONTH" | "EVENT")
  - `rentMinPeriods` (número)
  - `replacementPrice` (número)
  - `allowsFractionalQty` (verdadeiro/falso): Aceita quantidade fracionada neste produto? `null` decide pela unidade; `true` ou `false` forçam a regra.
  - `ncm` (texto)
  - `cest` (texto)
  - `cfopDefault` (texto)
  - `origem` (texto)
  - `cBenef` (texto): Código de benefício fiscal da UF do emitente (`prod.cBenef`, I05f).
  - `ibsCbsCst` (texto): Código de situação tributária do IBS/CBS do produto. O formato é conferido ao salvar.
  - `ibsCbsClassTrib` (texto)
  - `icmsCst` (texto): Sobrepõe o padrão do tenant. `null` volta a herdar.
  - `icmsAliquota` (objeto)
  - `pisCst` (texto)
  - `pisAliquota` (objeto)
  - `cofinsCst` (texto)
  - `cofinsAliquota` (objeto)
  - `cfopSufixoVenda` (texto)
  - `tracksExpiry` (verdadeiro/falso): O produto tem validade? Campo ausente faz o produto herdar a regra da categoria; `false` é uma resposta ("este não tem").

```bash
curl -X PUT https://api.nivro.app/api/v1/products/PRODUCT_ID \
  -H "Authorization: Bearer nv_..." \
  -H "Content-Type: application/json" \
  -d '{"price": "9.90", "minStock": 10}'
```

#### `GET /v1/products/:id`

Busca um produto por id

- Papel: qualquer papel
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).

```bash
curl https://api.nivro.app/api/v1/products/PRODUCT_ID \
  -H "Authorization: Bearer nv_..."
```

#### `GET /v1/products/:id/variants`

Variações do produto (grade de tamanho e cor), com o saldo de cada uma. Use o `id` da variação como `variantId` ao vender ou criar pedido.

- Papel: qualquer papel
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).
  - `includeInactive` (query): Use `true` para incluir também as variações inativas.

```bash
curl https://api.nivro.app/api/v1/products/PRODUCT_ID/variants \
  -H "Authorization: Bearer nv_..."
```

### Pedidos

Do rascunho ao faturamento: separar, mudar o status, ver a prévia, faturar e cancelar.

Os pedidos fazem parte do plano Profissional. O pedido passa por rascunho, confirmado, agendado, separado, despachado e entregue, e termina em faturado (`CONVERTED`) ou cancelado (`CANCELLED`). Faturar é o "dar baixa" do dia a dia: cria a venda a partir do pedido.

- **Faturar cobra só o que foi separado.** Se a separação foi registrada, a venda sai com as quantidades separadas; sem separação registrada, fatura tudo. A prévia mostra o resultado antes de gravar, e a resposta do faturar traz as faltas.
- **Faturar emite nota se a conta usa emissão automática**, igual à tela: a nota entra na fila depois da venda gravada.
- **Faturar acima do limite a prazo do cliente** só passa com `acknowledgeCreditLimit: true` e token de Gerente ou Proprietário. Em token de Operador o campo é ignorado e a API recusa com o aviso do limite.
- **Produto com IMEI ou série** precisa de `serials` (id da linha do pedido para o IMEI) quando a série não foi gravada na linha.
- **items[].unitPrice** aceita número ou string numérica. O `POST` devolve o pedido completo, com itens e totais.
- Na separação, `pickedQty` não pode passar da quantidade do item. No faturar, `channel` é `OTHER` se omitido.

#### `POST /v1/orders`

Cria um pedido

- Papel: Operador ou acima
- Corpo (JSON):
  - `customerId` (texto, obrigatório)
  - `sellerId` (texto)
  - `items` (lista de objetos, obrigatório)
  - `discountTotal` (número)
  - `discountPercentage` (número): Desconto em percentual (0 a 100)
  - `taxRate` (número): Alíquota de imposto em percentual (0 a 100)
  - `notes` (texto)
  - `deliveryAt` (texto)
  - `cobranca` ("ANTECIPADA" | "NA_ENTREGA"): Quando o pedido é cobrado: `ANTECIPADA` (padrão) converte em venda sem depender de entrega; `NA_ENTREGA` quer dizer que o entregador recebe na porta e a venda nasce depois, com o valor que ele trouxe.
  - `validUntil` (texto): Validade do orçamento — depois dessa data sem resposta do cliente, o lojista é notificado.
  - `pedeAprovacao` (verdadeiro/falso): O cliente precisa aprovar este pedido? Omitido, vale o padrão da loja. `false` grava o pedido sem validade e sem aceite pelo link público; uma `validUntil` enviada junto é descartada.
  - `allowInsufficientStock` (verdadeiro/falso): Permite criar pedido mesmo com estoque insuficiente (exige confirmação explícita do usuário).
  - `schedule` (texto): Agenda a recorrência do pedido no mesmo ato da criação.

```bash
curl -X POST https://api.nivro.app/api/v1/orders \
  -H "Authorization: Bearer nv_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "CUSTOMER_ID",
    "items": [{ "productId": "PRODUCT_ID", "qty": 2, "unitPrice": "49.90", "costAtTime": "20.00" }]
  }'
```

#### `GET /v1/orders`

Lista pedidos

- Papel: qualquer papel
- Parâmetros:
  - `status` (query): Situação a filtrar.
  - `page` (query): Página, a partir de 1.
  - `limit` (query): Padrão 50, máximo 200
  - `startDate` (query): Data inicial, AAAA-MM-DD.
  - `endDate` (query): Data final, AAAA-MM-DD. O período vai até 366 dias.
  - `search` (query): Código, número do pedido ou nome do cliente
  - `customerId` (query): Id do cliente.

```bash
curl "https://api.nivro.app/api/v1/orders?status=CONFIRMED,SEPARATED&limit=20" \
  -H "Authorization: Bearer nv_..."
```

#### `GET /v1/orders/:id`

Busca um pedido por id

- Papel: qualquer papel
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).

```bash
curl https://api.nivro.app/api/v1/orders/ORDER_ID \
  -H "Authorization: Bearer nv_..."
```

#### `PATCH /v1/orders/:id/status`

Anda o pedido pelo funil de entrega. Aceita `CONFIRMED`, `SEPARATED`, `DISPATCHED` e `DELIVERED`, na ordem permitida. Nunca aceita `CONVERTED` nem `CANCELLED`: esses têm rota própria.

- Papel: Operador ou acima
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).
- Corpo (JSON):
  - `status` ("CONFIRMED" | "SEPARATED" | "DISPATCHED" | "DELIVERED", obrigatório)
  - `reason` (texto)
  - `allowInsufficientStock` (verdadeiro/falso): Só vale ao aceitar pedido do catálogo (rascunho para confirmado), que passa a reservar estoque: aceita mesmo sem saldo. Sem isto, a falta de estoque recusa com `insufficient_stock`.

```bash
curl -X PATCH https://api.nivro.app/api/v1/orders/ORDER_ID/status \
  -H "Authorization: Bearer nv_..." \
  -H "Content-Type: application/json" \
  -d '{"status": "DISPATCHED"}'
```

#### `POST /v1/orders/:id/picking`

Registra a conferência da separação por item. `pickedQty: null` desfaz a conferência do item; `0` quer dizer "conferi e não achei".

- Papel: Operador ou acima
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).
- Corpo (JSON):
  - `items` (lista de objetos, obrigatório)
  - `markSeparatedWhenComplete` (verdadeiro/falso): Com `true`, avança o pedido para `SEPARATED` na mesma chamada se todos os itens ficarem conferidos. Opcional, porque conferir agora e fechar depois é um fluxo válido.

```bash
curl -X POST https://api.nivro.app/api/v1/orders/ORDER_ID/picking \
  -H "Authorization: Bearer nv_..." \
  -H "Content-Type: application/json" \
  -d '{"items": [{ "itemId": "ORDER_ITEM_ID", "pickedQty": 20 }]}'
```

#### `POST /v1/orders/:id/cancel`

Cancela o pedido. Se houver adiantamento em aberto, mande `advanceResolution` (devolver ou virar crédito); sem ele a resposta é `409` com `ADVANCE_PENDING_RESOLUTION`.

- Papel: Gerente ou acima
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).
- Corpo (JSON):
  - `reason` (texto)
  - `advanceResolution` (objeto)

```bash
curl -X POST https://api.nivro.app/api/v1/orders/ORDER_ID/cancel \
  -H "Authorization: Bearer nv_..." \
  -H "Content-Type: application/json" \
  -d '{"reason": "Cliente desistiu"}'
```

#### `GET /v1/orders/:id/invoice-preview`

Prévia do faturamento: o que a venda vai ter (quantidades separadas), a falta em relação ao pedido e o efeito do adiantamento. Não grava nada.

- Papel: Gerente ou acima
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).

```bash
curl https://api.nivro.app/api/v1/orders/ORDER_ID/invoice-preview \
  -H "Authorization: Bearer nv_..."
```

#### `POST /v1/orders/:id/convert`

Fatura o pedido: cria a venda e marca o pedido como `CONVERTED`, numa chamada só. `paymentType` é `CASH` ou `INSTALLMENTS`; para o dinheiro que já entrou, mande `payments` e a venda nasce quitada. Responde `400` se o pedido já foi faturado ou cancelado, ou se o orçamento venceu (`quote_expired`), e `409` com `nothing_to_invoice` quando nenhum item foi separado.

- Papel: Gerente ou acima
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).
- Corpo (JSON):
  - `paymentType` ("CASH" | "INSTALLMENTS", obrigatório)
  - `installments` (número)
  - `payments` (lista de objetos): Pagamentos com que a venda já nasce. Para o dinheiro que já entrou, mande `payments` e a venda nasce quitada.
  - `acknowledgeCreditLimit` (verdadeiro/falso): Autoriza o faturamento a prazo que estoura o limite de crédito do cliente. Vale só se quem converte é dono ou gerente; ver `CreateSaleDto.acknowledgeCreditLimit`.
  - `acknowledgeBlockedImei` (verdadeiro/falso): Autoriza faturar pedido com aparelho cujo IMEI está bloqueado. Só vale para Gerente ou Proprietário; a API pública não repassa esta autorização.
  - `channel` ("POS" | "ONLINE" | "WHATSAPP" | "PHONE" | "OTHER"): Canal da venda gerada. Ausente: `POS` (balcão) quando o pedido é faturado sem entrega, e `OTHER` quando há entrega.
  - `serials` (objeto): Séries por linha do pedido (id da linha do pedido para o IMEI ou série), para produto controlado por número de série. Vence a série gravada na linha. Faturar produto com série sem série por nenhum dos dois caminhos é recusado com `serial_required`.

```bash
curl -X POST https://api.nivro.app/api/v1/orders/ORDER_ID/convert \
  -H "Authorization: Bearer nv_..." \
  -H "Content-Type: application/json" \
  -d '{"paymentType": "CASH", "payments": [{ "method": "PIX", "amount": 40 }]}'
```

### Vendas

Criar, listar, abrir e cancelar vendas.

Sem `sellerId`, a venda fica com quem criou o token. Para atribuir a outro vendedor, mande o `sellerId` dele: precisa ser um usuário ativo da conta, senão a resposta é `400`.

- **occurredAt** (data da venda) é opcional e não pode estar mais de 1 dia no futuro.
- **Grade e IMEI:** em produto com variação (tamanho, cor), mande `items[].variantId`, senão a baixa cai na variação padrão. Em produto com número de série, mande `items[].unitSerial`; sem `unitPrice`, vale o preço da unidade.
- **Idempotency-Key:** mande este header com uma chave sua em `POST /v1/sales` e repetir a chamada (timeout, retry) devolve a mesma venda em vez de criar outra. A chave vale por conta. Reusar a chave com um corpo diferente dá `422`.
- **Limite a prazo:** a venda a prazo que passa do limite do cliente é recusada. `acknowledgeCreditLimit: true` só vale com token de Gerente ou Proprietário.
- **Operador não vê o custo:** em `GET /v1/sales/:id`, token de Operador recebe a venda sem o custo da linha e sem a comissão de outros vendedores, como na tela.
- **channel** aceita: `POS`, `ONLINE`, `WHATSAPP`, `PHONE`, `OTHER` (padrão `OTHER` se omitido).
- **payments[].method** aceita: `PIX`, `CASH`, `CARD`, `CREDIT_CARD`, `DEBIT_CARD`, `BANK_TRANSFER`, `CHECK`, `FIADO`, `OTHER`. Um valor fora dessa lista é rejeitado no momento de salvar.
- **Atenção ao formato dos valores:** `items[].unitPrice` é sempre **string** (ex.: `"49.90"`), enquanto `payments[].amount` e `receivables[].amount` são **number** puro (ex.: `49.90`). Não é um erro, apenas um detalhe fácil de deixar passar ao montar o payload.
- **items[].product.type** em `GET /v1/sales/:id` indica se o item vendido é `PRODUCT` ou `SERVICE`, útil para não tentar repor estoque de um item de serviço, por exemplo.

#### `POST /v1/sales`

Cria uma venda

- Papel: Operador ou acima
- Parâmetros:
  - `Idempotency-Key` (header): Chave gerada pelo cliente. Repetir a requisição com a mesma chave devolve a venda já criada em vez de duplicá-la.
- Corpo (JSON):
  - `sellerId` (texto)
  - `commissionSellerId` (texto): Quem RECEBE a comissão, quando não é quem operou o caixa.
  - `customerId` (texto)
  - `occurredAt` (texto): Quando a venda aconteceu, DECLARADO PELO APARELHO. ISO 8601.
  - `orderId` (texto)
  - `serviceOrderId` (texto)
  - `discount` (texto)
  - `autorizacaoDesconto` (texto): Token da autorização do gestor (`POST /sales/autorizacoes`), para passar do teto de desconto do vendedor. Opcional; só é lido quando o desconto passa do teto, e vale uma vez, para a loja, o pedido e o desconto autorizados.
  - `deliveryFee` (texto): Taxa de entrega — receita da venda que não é receita de mercadoria.
  - `channel` ("POS" | "ONLINE" | "WHATSAPP" | "PHONE" | "OTHER")
  - `fiscalModeloEscolhido` ("NFE" | "NFCE"): Documento que o operador escolheu no balcão: `NFE` ou `NFCE`.
  - `fiscalEmailCupom` (texto): E-mail para onde mandar o cupom desta venda.
  - `acknowledgeCreditLimit` (verdadeiro/falso): Autoriza a venda a prazo que estoura o limite de crédito do cliente.
  - `acknowledgeBlockedImei` (verdadeiro/falso): Autoriza vender aparelho cujo IMEI está bloqueado (Anatel/Celular Legal). Só vale para Gerente ou Proprietário; a API pública não repassa esta autorização, e a venda segue recusada com `imei_blocked`.
  - `items` (lista de objetos, obrigatório)
  - `payments` (lista de objetos)
  - `receivables` (lista de objetos)
  - `advanceIds` (lista de texto): Adiantamentos do pedido (`order_advance`) que esta venda absorve como pagamento já recebido.

```bash
curl -X POST https://api.nivro.app/api/v1/sales \
  -H "Authorization: Bearer nv_..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "ONLINE",
    "customerId": "CUSTOMER_ID",
    "items": [{ "productId": "PRODUCT_ID", "qty": 1, "unitPrice": "49.90" }],
    "payments": [{ "method": "PIX", "amount": 49.90 }]
  }'
```

#### `GET /v1/sales`

Lista vendas

- Papel: qualquer papel
- Parâmetros:
  - `take` (query): Padrão 50, máximo 200
  - `skip` (query): Quantos itens pular, para paginar com `take`.
  - `customerId` (query): Id do cliente.
  - `startDate` (query): Data inicial, AAAA-MM-DD.
  - `endDate` (query): Data final, AAAA-MM-DD. O período vai até 366 dias.

```bash
curl "https://api.nivro.app/api/v1/sales?take=20" \
  -H "Authorization: Bearer nv_..."
```

#### `GET /v1/sales/:id`

Busca uma venda por id

- Papel: qualquer papel
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).

```bash
curl https://api.nivro.app/api/v1/sales/SALE_ID \
  -H "Authorization: Bearer nv_..."
```

#### `POST /v1/sales/:id/cancel`

Cancela uma venda: estorna pagamentos e recebíveis (valor negativo referenciando o original), repõe estoque dos itens e marca a venda como CANCELLED. Requer token com role Gerente.

- Papel: Gerente ou acima
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).
- Corpo (JSON):
  - `reason` (texto): Motivo do cancelamento

```bash
curl -X POST https://api.nivro.app/api/v1/sales/SALE_ID/cancel \
  -H "Authorization: Bearer nv_..." \
  -H "Content-Type: application/json" \
  -d '{"reason": "Estorno solicitado pelo cliente"}'
```

### Contas a receber

Parcelas a prazo, só leitura; a baixa é feita dentro do Nivro.

Parcelas a prazo, só leitura. A baixa de parcela é feita dentro do Nivro.

#### `GET /v1/receivables`

Lista contas a receber (parcelas a prazo), com o cliente e o vencimento

- Papel: qualquer papel
- Parâmetros:
  - `search` (query): Texto a buscar.
  - `status` (query): PENDING | PARTIALLY_PAID | PAID | CANCELLED
  - `take` (query): Padrão 50, máximo 200
  - `skip` (query): Quantos itens pular, para paginar com `take`.
  - `startDate` (query): AAAA-MM-DD, data de vencimento
  - `endDate` (query): AAAA-MM-DD, data de vencimento

```bash
curl "https://api.nivro.app/api/v1/receivables?status=PENDING&endDate=2026-10-31" \
  -H "Authorization: Bearer nv_..."
```

#### `GET /v1/receivables/summary`

Totais sobre os mesmos filtros da lista, sem teto de linhas: em aberto, recebido, quantidade em atraso e próximo vencimento.

- Papel: qualquer papel
- Parâmetros:
  - `search` (query): Texto a buscar.
  - `startDate` (query): Data inicial, AAAA-MM-DD.
  - `endDate` (query): Data final, AAAA-MM-DD. O período vai até 366 dias.

```bash
curl https://api.nivro.app/api/v1/receivables/summary \
  -H "Authorization: Bearer nv_..."
```

#### `GET /v1/receivables/:id`

Busca uma conta a receber por id

- Papel: qualquer papel
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).

```bash
curl https://api.nivro.app/api/v1/receivables/RECEIVABLE_ID \
  -H "Authorization: Bearer nv_..."
```

### Assinaturas

Mensalidades: planos, assinaturas, cobranças de cada ciclo; criar, pausar, retomar, suspender, reativar, trocar de plano, cancelar, manter, dar desconto, reajustar, editar, isentar ciclo e dar baixa.

Exige o módulo Assinaturas ligado; sem ele a rota fica só leitura. Operador lê a situação e não vê preço negociado, desconto nem histórico; criar, pausar, retomar, suspender, reativar, trocar de plano, cancelar, manter, dar desconto, reajustar, editar e isentar ciclo são de Gerente em diante, e a baixa segue a baixa de parcela (Operador em diante). Visualizador não lê. Os relatórios de MRR e churn ficam dentro do Nivro.

- **Dar baixa em um ciclo:** leia a assinatura (`GET /v1/memberships/:id`) ou as cobranças (`GET /v1/memberships/charges`), pegue o `receivableId` do ciclo e mande em `POST /v1/memberships/:id/receive`. A baixa é sempre pelo valor integral da parcela; o Nivro não aceita pagamento parcial por aqui.
- **Idempotency-Key:** mande este header com uma chave sua em `POST /v1/memberships` e em `POST /v1/memberships/:id/receive`. Repetir a chamada (timeout, retry) devolve o mesmo resultado, com o header `Idempotent-Replayed: true`, em vez de assinar duas vezes ou dar baixa duas vezes. A chave vale por conta. Reusar a chave com um corpo diferente dá `422`. Sem a chave, repetir uma baixa já feita devolve `409` (`receivable_not_open`), sem pagar de novo.
- **Baixa em lote:** `receivableIds` aceita até 60 parcelas da mesma assinatura. Cada baixa é gravada à parte: se uma falha, as outras ficam pagas e a resposta traz `ok: false` e a lista `failed`. Para tentar só as que falharam, mande uma chave nova com os ids que sobraram.
- **method** da baixa aceita: `CASH`, `PIX`, `CARD`, `CREDIT_CARD`, `DEBIT_CARD`, `BANK_TRANSFER`, `BOLETO`, `CHECK`, `OTHER`. `paidAt` (AAAA-MM-DD ou data e hora) é opcional e vale agora se omitido.
- **Pausar x suspender:** pausar é combinado com o cliente (`until` opcional, `resume` volta). Suspender é decisão de quem vende, por exemplo por atraso: a assinatura sai do MRR e só volta com `reactivate`, sem cobrar os vencimentos que passaram.
- **Trocar de plano** (`change-plan`) vale a partir do próximo ciclo: nada muda na cobrança que já foi gerada. Mandar o plano atual desfaz a troca agendada. `price` negocia um valor no plano novo; sem ele vale o preço do plano.
- **Desconto:** `POST /v1/memberships/:id/discount` aplica um desconto no estilo cupom, `PERCENT` (até 100) ou `AMOUNT`, por `cycles` ciclos ou para sempre se omitido; aplicar outro substitui o atual. 100% zera o ciclo: não há cobrança, mas o ciclo conta para `cycles`. O desconto não altera um ciclo que já foi cobrado e não vale sobre a taxa de adesão. `DELETE /v1/memberships/:id/discount` remove (`409` se não há desconto). Também dá para já criar a assinatura com desconto.
- **Reajustar e editar:** `POST /v1/memberships/:id/reprice` muda o preço negociado a partir do próximo ciclo a gerar (o mesmo preço atual é `400`). `PATCH /v1/memberships/:id` altera `endDate` (AAAA-MM-DD, depois do início; `null` tira o término) e `notes`; só o que for enviado muda. Nenhum dos dois altera um ciclo já cobrado.
- **Exceção de ciclo:** `POST /v1/memberships/:id/exceptions` com `periodStart` (um vencimento FUTURO da assinatura) e `type`: `SKIP` isenta o mês (não gera cobrança nem gasta desconto) ou `OVERRIDE` cobra `amountOverride` naquele mês, valor final. Ciclo já cobrado é `409` (`cycle_already_charged`); data que não é vencimento é `400` (`not_a_due_date`). `DELETE /v1/memberships/:id/exceptions/:periodStart` remove.
- **Cancelar e manter:** `cancel` com `atPeriodEnd: true` só agenda o fim; `keep` desfaz esse agendamento. O cancelamento imediato não se desfaz: crie outra assinatura.
- **Módulo Contas a receber:** a baixa exige o módulo ligado; sem ele a resposta é `403` com `code: module_disabled`.

#### `GET /v1/memberships/plans`

Lista os planos de assinatura

- Papel: Operador ou acima
- Parâmetros:
  - `active` (query): `true` só os planos ativos; `false` só os inativos. Sem o filtro, todos.

```bash
curl "https://api.nivro.app/api/v1/memberships/plans?active=true" \
  -H "Authorization: Bearer nv_..."
```

#### `GET /v1/memberships/plans/:id`

Busca um plano por id

- Papel: Operador ou acima
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).

```bash
curl https://api.nivro.app/api/v1/memberships/plans/PLAN_ID \
  -H "Authorization: Bearer nv_..."
```

#### `GET /v1/memberships/charges`

Cobranças de todas as assinaturas: a vencer, vencidas ou pagas. Para Operador, o valor de um ciclo que ainda não virou venda vem `null`.

- Papel: Operador ou acima
- Parâmetros:
  - `status` (query): `upcoming` (a vencer, inclui os próximos ciclos ainda não gerados), `overdue` (vencidas) ou `paid` (pagas).
  - `from` (query): Vencimento a partir de (AAAA-MM-DD).
  - `to` (query): Vencimento até (AAAA-MM-DD).
  - `planId` (query): Id do plano.
  - `membershipId` (query): Só as cobranças de uma assinatura (a ação "cobrar por WhatsApp" na lista e na ficha).
  - `q` (query): Busca pelo nome, e-mail ou telefone do cliente.
  - `page` (query): Página, a partir de 1.
  - `limit` (query): Itens por página (padrão 50, máximo 200).

```bash
curl "https://api.nivro.app/api/v1/memberships/charges?status=overdue" \
  -H "Authorization: Bearer nv_..."
```

#### `GET /v1/memberships`

Lista assinaturas, com o cliente, o plano, a situação e o próximo vencimento

- Papel: Operador ou acima
- Parâmetros:
  - `status` (query): Situação a filtrar.
  - `customerId` (query): Id do cliente.
  - `planId` (query): Id do plano.
  - `q` (query): Busca pelo nome, e-mail ou telefone do cliente.
  - `delinquent` (query): `true`: só as que têm parcela vencida além da carência (inadimplentes).
  - `dueFrom` (query): Próximo vencimento a partir de (AAAA-MM-DD).
  - `dueTo` (query): Próximo vencimento até (AAAA-MM-DD).
  - `page` (query): Página, a partir de 1.
  - `limit` (query): Itens por página (padrão 50, máximo 200).

```bash
curl "https://api.nivro.app/api/v1/memberships?status=ACTIVE&delinquent=true" \
  -H "Authorization: Bearer nv_..."
```

#### `POST /v1/memberships`

Assina um cliente a um plano. Aceita `Idempotency-Key`. `startDate` padrão é hoje; `price` negocia um valor diferente do plano; `trialDays`, `endDate` e o desconto (`discountType`, `discountValue`, `discountCycles`) são opcionais.

- Papel: Gerente ou acima
- Parâmetros:
  - `Idempotency-Key` (header): Chave gerada pelo cliente. Repetir a requisição com a mesma chave devolve a assinatura já criada em vez de criar outra.
- Corpo (JSON):
  - `customerId` (texto, obrigatório)
  - `planId` (texto, obrigatório)
  - `startDate` (texto): Início da assinatura (dia da loja). Padrão: hoje.
  - `billingDay` (número): Dia do vencimento (1 a 31; no plano semanal, 1 = segunda a 7 = domingo). Padrão: o dia da âncora.
  - `price` (número): Preço negociado. Padrão: o do plano. Fica congelado na adesão.
  - `trialDays` (número): Dias de teste. Padrão: os do plano; 0 pula o teste.
  - `endDate` (texto)
  - `notes` (texto)
  - `discountType` ("PERCENT" | "AMOUNT")
  - `discountValue` (número)
  - `discountCycles` (número): Por quantos ciclos o desconto vale; ausente = para sempre.

```bash
curl -X POST https://api.nivro.app/api/v1/memberships \
  -H "Authorization: Bearer nv_..." \
  -H "Content-Type: application/json" \
  -d '{"customerId": "CUSTOMER_ID", "planId": "PLAN_ID", "billingDay": 10}'
```

#### `GET /v1/memberships/:id`

Ficha da assinatura: a cobrança de cada ciclo, o histórico e as exceções. Operador não recebe preço, desconto, histórico nem exceções.

- Papel: Operador ou acima
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).

```bash
curl https://api.nivro.app/api/v1/memberships/MEMBERSHIP_ID \
  -H "Authorization: Bearer nv_..."
```

#### `PATCH /v1/memberships/:id`

Altera o término (`endDate`, AAAA-MM-DD, `null` tira o término) e as observações (`notes`). Só o que for enviado muda.

- Papel: Gerente ou acima
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).
- Corpo (JSON):
  - `endDate` (texto)
  - `notes` (texto)

```bash
curl -X PATCH https://api.nivro.app/api/v1/memberships/MEMBERSHIP_ID \
  -H "Authorization: Bearer nv_..." \
  -H "Content-Type: application/json" \
  -d '{"endDate": "2027-12-31", "notes": "Contrato anual"}'
```

#### `POST /v1/memberships/:id/receive`

Dá baixa, pelo valor integral, nas mensalidades em aberto da assinatura (`receivableIds`, de 1 a 60) e devolve o que entrou (`paid`), o que não (`failed`), o total e a situação da assinatura. Aceita `Idempotency-Key`. Parcela de outra assinatura é `400`; parcela já paga ou cancelada é `409`.

- Papel: Operador ou acima
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).
  - `Idempotency-Key` (header): Chave gerada pelo cliente. Repetir a requisição com a mesma chave devolve o mesmo resultado, sem dar baixa de novo.
- Corpo (JSON):
  - `receivableIds` (lista de texto, obrigatório)
  - `method` ("CASH" | "PIX" | "CARD" | "CREDIT_CARD" | "DEBIT_CARD" | "BANK_TRANSFER" | "BOLETO" | "CHECK" | "OTHER", obrigatório)
  - `paidAt` (texto): Data (AAAA-MM-DD) ou instante; vazio = agora. Mesma regra de `POST /receivable-payments`.

```bash
curl -X POST https://api.nivro.app/api/v1/memberships/MEMBERSHIP_ID/receive \
  -H "Authorization: Bearer nv_..." \
  -H "Idempotency-Key: baixa-2026-11-ciclo-1" \
  -H "Content-Type: application/json" \
  -d '{"receivableIds": ["RECEIVABLE_ID"], "method": "PIX", "paidAt": "2026-11-12"}'
```

#### `POST /v1/memberships/:id/pause`

Pausa a assinatura, sem cobrar, até `until` (AAAA-MM-DD) ou até alguém retomar.

- Papel: Gerente ou acima
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).
- Corpo (JSON):
  - `until` (texto): Volta sozinha nesta data. Ausente = pausada até alguém retomar.
  - `reason` (texto)

```bash
curl -X POST https://api.nivro.app/api/v1/memberships/MEMBERSHIP_ID/pause \
  -H "Authorization: Bearer nv_..." \
  -H "Content-Type: application/json" \
  -d '{"until": "2026-12-15", "reason": "Viagem"}'
```

#### `POST /v1/memberships/:id/resume`

Retoma uma assinatura pausada

- Papel: Gerente ou acima
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).

```bash
curl -X POST https://api.nivro.app/api/v1/memberships/MEMBERSHIP_ID/resume \
  -H "Authorization: Bearer nv_..."
```

#### `POST /v1/memberships/:id/cancel`

Cancela agora ou, com `atPeriodEnd: true`, no fim do período já cobrado. `cancelOpenCharges: true` cancela também as parcelas em aberto, sem nenhum pagamento.

- Papel: Gerente ou acima
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).
- Corpo (JSON):
  - `atPeriodEnd` (verdadeiro/falso): `true`: segue valendo até o fim do período já cobrado e cancela no próximo vencimento. Padrão: cancela agora.
  - `reason` (texto)
  - `cancelOpenCharges` (verdadeiro/falso): Cancela também as parcelas ainda em aberto (sem nenhum pagamento) dos ciclos já gerados. Padrão: mantém.

```bash
curl -X POST https://api.nivro.app/api/v1/memberships/MEMBERSHIP_ID/cancel \
  -H "Authorization: Bearer nv_..." \
  -H "Content-Type: application/json" \
  -d '{"atPeriodEnd": true, "reason": "Mudou de cidade"}'
```

#### `POST /v1/memberships/:id/suspend`

Suspende a assinatura: sai do MRR e não gera mensalidade até alguém reativar. `reason` fica no histórico.

- Papel: Gerente ou acima
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).
- Corpo (JSON):
  - `reason` (texto): Por que o lojista suspende (fica no histórico).

```bash
curl -X POST https://api.nivro.app/api/v1/memberships/MEMBERSHIP_ID/suspend \
  -H "Authorization: Bearer nv_..." \
  -H "Content-Type: application/json" \
  -d '{"reason": "Mensalidade em atraso"}'
```

#### `POST /v1/memberships/:id/reactivate`

Reativa uma assinatura suspensa, sem cobrar os vencimentos que passaram

- Papel: Gerente ou acima
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).
- Corpo (JSON):
  - `reason` (texto): Por que o lojista suspende (fica no histórico).

```bash
curl -X POST https://api.nivro.app/api/v1/memberships/MEMBERSHIP_ID/reactivate \
  -H "Authorization: Bearer nv_..." \
  -H "Content-Type: application/json" \
  -d '{"reason": "Regularizou o pagamento"}'
```

#### `POST /v1/memberships/:id/change-plan`

Agenda a troca para outro plano a partir do próximo ciclo. Mandar o plano atual desfaz a troca agendada. Plano inexistente ou desativado é `400`.

- Papel: Gerente ou acima
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).
- Corpo (JSON):
  - `planId` (texto, obrigatório)
  - `price` (número): Preço negociado no plano novo. Padrão: o preço do plano.
  - `reason` (texto)

```bash
curl -X POST https://api.nivro.app/api/v1/memberships/MEMBERSHIP_ID/change-plan \
  -H "Authorization: Bearer nv_..." \
  -H "Content-Type: application/json" \
  -d '{"planId": "PLAN_ID", "price": 90}'
```

#### `POST /v1/memberships/:id/keep`

Desfaz o cancelamento agendado para o fim do período. Sem cancelamento agendado é `409`.

- Papel: Gerente ou acima
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).

```bash
curl -X POST https://api.nivro.app/api/v1/memberships/MEMBERSHIP_ID/keep \
  -H "Authorization: Bearer nv_..."
```

#### `POST /v1/memberships/:id/discount`

Aplica desconto na assinatura, no estilo cupom: `PERCENT` (até 100) ou `AMOUNT`. `cycles` limita a quantos ciclos vale; sem ele vale para sempre. Substitui o desconto atual.

- Papel: Gerente ou acima
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).
- Corpo (JSON):
  - `type` ("PERCENT" | "AMOUNT", obrigatório)
  - `value` (número, obrigatório)
  - `cycles` (número): Por quantos ciclos vale; `null` ou ausente = para sempre.
  - `reason` (texto)

```bash
curl -X POST https://api.nivro.app/api/v1/memberships/MEMBERSHIP_ID/discount \
  -H "Authorization: Bearer nv_..." \
  -H "Content-Type: application/json" \
  -d '{"type": "PERCENT", "value": 100, "cycles": 3, "reason": "Cortesia de boas-vindas"}'
```

#### `DELETE /v1/memberships/:id/discount`

Remove o desconto da assinatura. Sem desconto aplicado é `409` (`no_discount`).

- Papel: Gerente ou acima
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).

```bash
curl -X DELETE https://api.nivro.app/api/v1/memberships/MEMBERSHIP_ID/discount \
  -H "Authorization: Bearer nv_..."
```

#### `POST /v1/memberships/:id/reprice`

Reajusta o preço negociado da assinatura a partir do próximo ciclo a gerar. O preço igual ao atual é `400`. `reason` fica no histórico.

- Papel: Gerente ou acima
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).
- Corpo (JSON):
  - `price` (número, obrigatório)
  - `reason` (texto)

```bash
curl -X POST https://api.nivro.app/api/v1/memberships/MEMBERSHIP_ID/reprice \
  -H "Authorization: Bearer nv_..." \
  -H "Content-Type: application/json" \
  -d '{"price": 110, "reason": "Reajuste anual"}'
```

#### `POST /v1/memberships/:id/exceptions`

Isenta um ciclo futuro (`SKIP`) ou troca o valor dele (`OVERRIDE`, com `amountOverride`). `periodStart` precisa ser um vencimento futuro da assinatura.

- Papel: Gerente ou acima
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).
- Corpo (JSON):
  - `periodStart` (texto, obrigatório): Vencimento do ciclo afetado (precisa ser um vencimento futuro da assinatura).
  - `type` ("SKIP" | "OVERRIDE", obrigatório): SKIP isenta o ciclo; OVERRIDE troca o valor dele.
  - `amountOverride` (número)
  - `reason` (texto)

```bash
curl -X POST https://api.nivro.app/api/v1/memberships/MEMBERSHIP_ID/exceptions \
  -H "Authorization: Bearer nv_..." \
  -H "Content-Type: application/json" \
  -d '{"periodStart": "2026-12-10", "type": "OVERRIDE", "amountOverride": 80, "reason": "Mês promocional"}'
```

#### `DELETE /v1/memberships/:id/exceptions/:periodStart`

Remove a exceção de um ciclo. Sem exceção naquele vencimento é `404`.

- Papel: Gerente ou acima
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).
  - `periodStart` (no caminho, obrigatório): Vencimento do ciclo, AAAA-MM-DD.

```bash
curl -X DELETE https://api.nivro.app/api/v1/memberships/MEMBERSHIP_ID/exceptions/2026-12-10 \
  -H "Authorization: Bearer nv_..."
```

### Webhooks

Receba por POST assinado os eventos das assinaturas, sem consultar a API: cadastrar, testar, girar o segredo e acompanhar as entregas.

Em vez de consultar a API de tempos em tempos, cadastre uma URL e o Nivro envia um `POST` assinado a cada evento de assinatura. Exige o papel Gerente ou Proprietário no token. A URL precisa ser `https://`, pública e na porta 443 ou 8443; endereços internos (rede privada, `localhost`, metadado da nuvem) e URLs com usuário e senha são recusados, no cadastro e a cada entrega.

**Como verificar a assinatura.** Cada entrega traz `Nivro-Timestamp` (segundos Unix) e `Nivro-Signature: v1=<hex>`, o HMAC-SHA256 de `"<timestamp>.<corpo>"` com o seu segredo (`whsec_...`, devolvido uma única vez ao cadastrar). Confira sobre o corpo CRU, antes de qualquer `JSON.parse`, e recuse entregas com `Nivro-Timestamp` de mais de 5 minutos atrás.

Node.js:

```js
const crypto = require('crypto')

function confere(segredo, headers, corpoCru) {
  const esperado = 'v1=' + crypto.createHmac('sha256', segredo).update(headers['nivro-timestamp'] + '.' + corpoCru).digest('hex')
  const a = Buffer.from(esperado)
  const b = Buffer.from(headers['nivro-signature'] || '')
  const recente = Math.abs(Date.now() / 1000 - Number(headers['nivro-timestamp'])) < 300
  return recente && a.length === b.length && crypto.timingSafeEqual(a, b)
}
```

Python:

```python
import hmac, hashlib, time

def confere(segredo, headers, corpo_cru):
    msg = headers['Nivro-Timestamp'].encode() + b'.' + corpo_cru
    esperado = 'v1=' + hmac.new(segredo.encode(), msg, hashlib.sha256).hexdigest()
    recente = abs(time.time() - int(headers['Nivro-Timestamp'])) < 300
    return recente and hmac.compare_digest(esperado, headers['Nivro-Signature'])
```

Responda com qualquer `2xx` em até 10 segundos. Qualquer outra resposta (inclusive redirecionamento, que o Nivro não segue) conta como falha e a entrega é repetida.

- **Cabeçalhos de cada entrega:** `Content-Type: application/json`, `User-Agent: Nivro-Webhooks/1`, `Nivro-Event` (o tipo), `Nivro-Delivery` (id desta entrega), `Nivro-Timestamp` e `Nivro-Signature`.
- **Corpo:** `{ "id": "<id do evento>", "type": "membership.paused", "createdAt": "2026-11-12T13:00:00.000Z", "data": { "membership": { ... } } }`. Os eventos de cobrança trazem também `data.charge` (`id`, `cycleNo`, `dueDate`, `amount`, `situation`, `receivableId`). `data.membership` traz `id`, `customerId`, `planId`, `status`, `price`, `billingInterval`, `startDate`, `nextChargeDate`, `trialEndsAt`, `pausedUntil`, `endDate`, `cancelAtPeriodEnd` e `createdAt`. Não leva dado interno do Nivro.
- **Entrega pelo menos uma vez.** Uma entrega pode chegar mais de uma vez (a sua resposta se perdeu, o servidor reiniciou) e a ordem entre eventos não é garantida. Deduplique pelo campo `id` do corpo, que é o mesmo em toda repetição, e ordene por `createdAt`.
- **Tentativas.** Se a resposta não for `2xx`, o Nivro tenta de novo depois de 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas, 12 horas e 24 horas. A 8ª falha encerra a entrega (`FAILED`); reenvie à mão em `POST /v1/webhooks/:id/deliveries/:deliveryId/retry`.
- **Desligamento automático.** Depois de 50 falhas seguidas o webhook é desativado (`active: false`, com o motivo em `disabledReason`) e para de receber eventos novos. Corrija o endereço e reative com `PATCH /v1/webhooks/:id` e `active: true`. Uma entrega com sucesso zera a contagem.
- **Eventos.** `membership.created`, `membership.paused`, `membership.resumed`, `membership.suspended`, `membership.reactivated`, `membership.plan_changed`, `membership.canceled`, `membership.past_due`, `charge.created`, `charge.paid` e `ping`. Sem `events` no cadastro, o webhook recebe todos.
- **Quando cada evento sai.** `membership.plan_changed` sai quando a troca é APLICADA (no primeiro ciclo do plano novo), não quando é agendada. `membership.canceled` sai no cancelamento imediato, no fim do período agendado e quando o contrato chega à data de término (neste caso com `status: ENDED`). `membership.reactivated` sai ao reativar uma assinatura suspensa e quando quitar a dívida tira a assinatura de inadimplente. `charge.created` sai quando o ciclo vira cobrança a prazo; `charge.paid` sai uma vez por parcela, quando ela fica quitada (e de novo se a baixa for estornada e a parcela paga outra vez). Se o Nivro cair no meio da baixa, o evento é recuperado em até alguns minutos, sem duplicar. `ping` só sai por `POST /v1/webhooks/:id/test`.
- **Segredo.** `secret` aparece só ao cadastrar e ao girar (`rotate-secret`); nas leituras vem só `secretPrefix`. Ao girar, o segredo antigo deixa de valer na hora, inclusive para entregas já na fila.
- **Limites.** Até 10 webhooks por empresa. O log de entregas guarda 30 dias e não traz o corpo enviado, só situação, tentativas, código de resposta e o motivo da última falha.

#### `POST /v1/webhooks`

Cadastra um webhook. Devolve o `secret` (`whsec_...`) UMA vez: guarde-o, ele não aparece de novo. `events` vazio ou omitido recebe todos os tipos; um tipo fora da lista dá `400` com a lista válida. A URL precisa ser `https://` e pública (`400` com `code` explicando o motivo se não for). Limite de 10 webhooks por empresa (`409` com `webhook_limit_reached`).

- Papel: Gerente ou acima
- Corpo (JSON):
  - `url` (texto, obrigatório): Endereço que recebe os eventos. Precisa ser `https://`, público, na porta 443 ou 8443, sem usuário e senha.
  - `events` (lista de texto): Tipos de evento a receber (veja a lista no grupo Webhooks). Vazio ou omitido: todos.
  - `description` (texto): Texto livre para você reconhecer o webhook (até 300 caracteres).

```bash
curl -X POST https://api.nivro.app/api/v1/webhooks \
  -H "Authorization: Bearer nv_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://exemplo.com.br/nivro/eventos", "events": ["membership.created", "charge.paid"], "description": "ERP da academia"}'
```

#### `GET /v1/webhooks`

Lista os webhooks da empresa. O segredo nunca aparece; só o `secretPrefix`.

- Papel: Gerente ou acima

```bash
curl -X GET https://api.nivro.app/api/v1/webhooks \
  -H "Authorization: Bearer nv_..."
```

#### `GET /v1/webhooks/:id`

Busca um webhook por id, com a situação (`active`), as falhas seguidas e, se foi desligado, o motivo.

- Papel: Gerente ou acima
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).

```bash
curl -X GET https://api.nivro.app/api/v1/webhooks/WEBHOOK_ID \
  -H "Authorization: Bearer nv_..."
```

#### `PATCH /v1/webhooks/:id`

Altera a URL, os tipos de evento, a descrição ou liga e desliga o webhook. Mandar `active: true` em um webhook desligado o reativa e zera a contagem de falhas seguidas. A URL nova passa pela mesma conferência do cadastro.

- Papel: Gerente ou acima
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).
- Corpo (JSON):
  - `url` (texto): Novo endereço. Precisa passar pela mesma conferência do cadastro.
  - `events` (lista de texto): Nova lista de tipos de evento. Lista vazia: todos.
  - `description` (texto): Novo texto de descrição. Texto vazio apaga a descrição.
  - `active` (verdadeiro/falso): `true` reativa um webhook desligado e zera as falhas seguidas; `false` o desliga.

```bash
curl -X PATCH https://api.nivro.app/api/v1/webhooks/WEBHOOK_ID \
  -H "Authorization: Bearer nv_..." \
  -H "Content-Type: application/json" \
  -d '{"events": ["membership.canceled", "membership.past_due"], "active": true}'
```

#### `DELETE /v1/webhooks/:id`

Apaga o webhook e o histórico de entregas dele. As entregas ainda na fila deixam de sair.

- Papel: Gerente ou acima
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).

```bash
curl -X DELETE https://api.nivro.app/api/v1/webhooks/WEBHOOK_ID \
  -H "Authorization: Bearer nv_..."
```

#### `POST /v1/webhooks/:id/rotate-secret`

Gira o segredo de assinatura e devolve o novo, uma única vez. O segredo antigo deixa de valer na hora: atualize o receptor antes, ou aceite os dois por um tempo.

- Papel: Gerente ou acima
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).

```bash
curl -X POST https://api.nivro.app/api/v1/webhooks/WEBHOOK_ID/rotate-secret \
  -H "Authorization: Bearer nv_..."
```

#### `POST /v1/webhooks/:id/test`

Coloca um evento `ping` na fila para este webhook (mesmo que ele não esteja inscrito em `ping`) e devolve o id da entrega, para acompanhar em `GET /v1/webhooks/:id/deliveries`. Webhook desligado dá `409`.

- Papel: Gerente ou acima
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).

```bash
curl -X POST https://api.nivro.app/api/v1/webhooks/WEBHOOK_ID/test \
  -H "Authorization: Bearer nv_..."
```

#### `GET /v1/webhooks/:id/deliveries`

Log recente de entregas do webhook, da mais nova para a mais antiga: tipo do evento, situação (`PENDING`, `DELIVERED` ou `FAILED`), tentativas, código da última resposta e o motivo da última falha. Não traz o corpo enviado. `status` filtra por situação e `limit` vai de 1 a 100 (padrão 50).

- Papel: Gerente ou acima
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).
  - `status` (query): Só as entregas nesta situação.
  - `limit` (query): Quantas entregas devolver (padrão 50, máximo 100).

```bash
curl "https://api.nivro.app/api/v1/webhooks/WEBHOOK_ID/deliveries?status=FAILED&limit=20" \
  -H "Authorization: Bearer nv_..."
```

#### `POST /v1/webhooks/:id/deliveries/:deliveryId/retry`

Recoloca na fila uma entrega que falhou (`FAILED`), com a contagem de tentativas zerada. Entrega que não falhou, ou webhook desligado, dá `409`.

- Papel: Gerente ou acima
- Parâmetros:
  - `id` (no caminho, obrigatório): Id do recurso (UUID).
  - `deliveryId` (no caminho, obrigatório)

```bash
curl -X POST https://api.nivro.app/api/v1/webhooks/WEBHOOK_ID/deliveries/DELIVERY_ID/retry \
  -H "Authorization: Bearer nv_..."
```

### Financeiro

Lançamentos e resumo do fluxo de caixa.

#### `GET /v1/cashflow/transactions`

Lista lançamentos de fluxo de caixa (despesas). Token de Operador não lê despesas, como na tela. A folha de pagamento sai somada, nunca itemizada.

- Papel: Proprietário, Gerente, Visualizador
- Parâmetros:
  - `startDate` (query): Data inicial, AAAA-MM-DD.
  - `endDate` (query): Data final, AAAA-MM-DD. O período vai até 366 dias.
  - `status` (query): Situação a filtrar.
  - `category` (query): Categoria do lançamento.

```bash
curl "https://api.nivro.app/api/v1/cashflow/transactions?startDate=2026-01-01&endDate=2026-01-31" \
  -H "Authorization: Bearer nv_..."
```

#### `GET /v1/cashflow/summary`

Resumo de entradas e saídas confirmadas no período

- Papel: Gerente ou acima
- Parâmetros:
  - `startDate` (query, obrigatório): Data inicial, AAAA-MM-DD.
  - `endDate` (query, obrigatório): Data final, AAAA-MM-DD. O período vai até 366 dias.

```bash
curl "https://api.nivro.app/api/v1/cashflow/summary?startDate=2026-01-01&endDate=2026-01-31" \
  -H "Authorization: Bearer nv_..."
```

### Relatórios

Resumo diário e comparação de vendas, de Gerente em diante.

#### `GET /v1/reports/daily-summary`

Resumo de vendas e caixa de um dia ou de um período. Relatórios são de Gerente em diante.

- Papel: Gerente ou acima
- Parâmetros:
  - `date` (query): Dia do resumo, AAAA-MM-DD. Padrão: hoje.
  - `startDate` (query): Data inicial, AAAA-MM-DD.
  - `endDate` (query): Data final, AAAA-MM-DD. O período vai até 366 dias.
  - `periodPreset` (query): Período pronto: `today`, `this-week`, `this-month`, `last-30-days` ou `custom` (com `startDate` e `endDate`).
  - `sellerId` (query): Id do vendedor.
  - `channel` (query): Canal da venda (o mesmo da tela).
  - `receivableStatus` (query): Situação das parcelas a considerar no resumo.
  - `categoryId` (query): Id da categoria.
  - `includeSales` (query): Use false para omitir a lista de vendas (`sales`): num mês ela passa de 200 KB e os KPIs já vêm prontos.

```bash
curl "https://api.nivro.app/api/v1/reports/daily-summary?date=2026-01-15" \
  -H "Authorization: Bearer nv_..."
```

#### `GET /v1/reports/sales-comparison`

Compara dois períodos de venda: receita, número de vendas e ticket médio. Sem o período anterior, compara com o intervalo imediatamente anterior ao informado.

- Papel: Gerente ou acima
- Parâmetros:
  - `startDate` (query, obrigatório): Data inicial, AAAA-MM-DD.
  - `endDate` (query, obrigatório): Data final, AAAA-MM-DD. O período vai até 366 dias.
  - `previousStartDate` (query): Início do período de comparação, AAAA-MM-DD. Sem ele (e sem `previousEndDate`), compara com o intervalo imediatamente anterior.
  - `previousEndDate` (query): Fim do período de comparação, AAAA-MM-DD.
  - `sellerId` (query): Id do vendedor.
  - `channel` (query): Canal da venda (o mesmo da tela).

```bash
curl "https://api.nivro.app/api/v1/reports/sales-comparison?startDate=2026-10-01&endDate=2026-10-31" \
  -H "Authorization: Bearer nv_..."
```

O contrato completo, com o corpo de resposta de cada rota, está em https://www.nivro.app/openapi/nivro-v1.json (OpenAPI 3).

## 10. Versão

A API está na versão `v1`. Mudanças que quebrem compatibilidade serão lançadas como nova versão (`/v2`), e a `/v1` continua funcionando.
