Para desenvolvedores

API pública do Nivro

Referência técnica para integrar sistemas de terceiros: ERPs, planilhas, automações (Zapier e n8n) e ferramentas próprias, com os dados de vendas, pedidos, clientes e financeiro do Nivro.

Ver a referência Como gerar o token, passo a passo

Antes de começar

Em três passos, a primeira chamada

A API faz parte do plano Profissional, inclusive nos 30 dias de teste. Um token não é uma sessão de usuário: é um cliente independente, com o seu próprio papel.

Gere um token
O proprietário (OWNER) da conta cria o token em Ajustes, Usuários e acessos, API e tokens. Ele aparece uma vez só: se for perdido, revogue e gere outro.
Envie no header
Use o header Authorization, no formato Bearer, em toda requisição.
Chame o /v1/me
Ele responde se o token funciona, sem criar nada no sistema de ninguém. É a primeira chamada de qualquer integração.

Autenticação

Authorization: Bearer nv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Base URL

https://api.nivro.app/api

Todos os endpoints abaixo são relativos a essa URL.

Regras da API

Permissões, limites e erros

Permissões

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 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 de fiado
Proprietário (OWNER): Acesso completo, incluindo a gestão de tokens

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.

Limites de taxa

Por padrão, 60 requisições por minuto por token. Toda resposta traz os headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42

Ao exceder o limite, a API responde 429 com o header Retry-After, que diz quantos segundos esperar.

Erros comuns

401: Token ausente, inválido, revogado ou expirado
403: Papel do token sem permissão para a ação, ou recurso (API, pedidos) fora do plano da conta
404: Recurso não encontrado (ou não pertence à conta do token)
429: Limite de requisições excedido. Respeite o header Retry-After

Referência

Endpoints

Conferir o token

É 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/mePapel mínimo: Visualizador

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.

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

# {
#   "ok": true,
#   "tenant": { "id": "...", "name": "Loja da Maria" },
#   "token": { "id": "...", "name": "Integração ERP", "role": "OPERATOR" }
# }

Clientes

POST/v1/customersPapel mínimo: Operador

Cria um cliente

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/customersPapel mínimo: Visualizador

Lista clientes

Parâmetros: search, take, skip

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

GET/v1/customers/:idPapel mínimo: Visualizador

Busca um cliente por id

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

Produtos

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"). Qualquer string é aceita, não é validada contra uma lista fixa.
price e cost são sempre string numérica decimal positiva (ex.: "8.90"), nunca negativa e nunca zero para price.

POST/v1/productsPapel mínimo: Gerente

Cria um produto ou serviço

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"}'

PUT/v1/products/:idPapel mínimo: Gerente

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

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/productsPapel mínimo: Visualizador

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.

Parâmetros: search, type (PRODUCT | SERVICE), take, skip

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

GET/v1/products/:id/variantsPapel mínimo: Visualizador

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.

Parâmetros: includeInactive (true inclui as desativadas)

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

GET/v1/products/:idPapel mínimo: Visualizador

Busca um produto por id

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

Pedidos

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 de fiado 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.

POST/v1/ordersPapel mínimo: Operador

Cria um pedido

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/ordersPapel mínimo: Visualizador

Lista pedidos

Parâmetros: status (um ou vários separados por vírgula: DRAFT, CONFIRMED, SCHEDULED, SEPARATED, DISPATCHED, DELIVERED, CONVERTED, CANCELLED), search, customerId, page, limit, startDate, endDate

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

GET/v1/orders/:idPapel mínimo: Visualizador

Busca um pedido por id

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

PATCH/v1/orders/:id/statusPapel mínimo: Operador

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.

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/pickingPapel mínimo: Operador

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

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 }]}'

GET/v1/orders/:id/invoice-previewPapel mínimo: Gerente

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.

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

POST/v1/orders/:id/convertPapel mínimo: Gerente

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.

Parâmetros: paymentType (obrigatório), installments, payments[], channel, serials, acknowledgeCreditLimit

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 }]}'

# { "sale": { "id": "...", "total": "40.00" }, "order": { "status": "CONVERTED" }, "faltas": [] }

POST/v1/orders/:id/cancelPapel mínimo: Gerente

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

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"}'

Vendas

O vendedor (sellerId) é resolvido automaticamente a partir do token, portanto não é preciso (nem possível) informá-lo no corpo da requisição.

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.
Limite de fiado: 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/salesPapel mínimo: Operador

Cria uma venda

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/salesPapel mínimo: Visualizador

Lista vendas

Parâmetros: take, skip, customerId, startDate, endDate

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

GET/v1/sales/:idPapel mínimo: Visualizador

Busca uma venda por id

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

# items[] inclui "product": { "name", "sku", "type", "photoUrl" }

POST/v1/sales/:id/cancelPapel mínimo: Gerente

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.

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

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

GET/v1/receivablesPapel mínimo: Visualizador

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

Parâmetros: search, status (PENDING, PARTIALLY_PAID, PAID, CANCELLED), take, skip, startDate, endDate (vencimento)

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

GET/v1/receivables/summaryPapel mínimo: Visualizador

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

Parâmetros: search, startDate, endDate

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

GET/v1/receivables/:idPapel mínimo: Visualizador

Busca uma conta a receber por id

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

Financeiro

GET/v1/cashflow/transactionsPapel mínimo: Visualizador

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.

Parâmetros: startDate, endDate, status, category

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

GET/v1/cashflow/summaryPapel mínimo: Gerente

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

Parâmetros: startDate (obrigatório), endDate (obrigatório)

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

Relatórios

GET/v1/reports/daily-summaryPapel mínimo: Gerente

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

Parâmetros: date, startDate, endDate, periodPreset, sellerId, channel, receivableStatus, categoryId

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

GET/v1/reports/sales-comparisonPapel mínimo: Gerente

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.

Parâmetros: startDate e endDate (obrigatórios), previousStartDate, previousEndDate, sellerId, channel

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

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

Continue pelo resto do sistema

Gere um token no teste e chame a API hoje

Os 30 dias de teste são do plano Profissional, que inclui a API. Crie a conta, gere o token e faça a primeira chamada ao /v1/me.

Começar o teste Ver planos

30 dias de teste, vendas ilimitadas. Sem cartão.
API e webhooks a partir do plano Profissional, R$ 449 por mês