Para desenvolvedores

API Pública do Nivro

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

Antes de começar

A API pública é um recurso plano-dependente. Para usá-la, o proprietário (OWNER) da conta Nivro precisa gerar um token em Configurações → API e Integrações — veja o passo a passo no artigo de ajuda.

Um token não é uma sessão de usuário: ele é um cliente independente, com seu próprio nível de permissão.

Autenticação

Envie o token no header Authorization, no formato Bearer:

Authorization: Bearer nv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

O token é exibido apenas uma vez, no momento da criação — não fica recuperável depois. Se for perdido, revogue-o e gere um novo.

Base URL

https://app.nivro.app/api

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

Permissões

Cada token atua com o papel escolhido na criação — o mesmo sistema de papéis usado pela equipe dentro do Nivro. Um papel superior herda as permissões dos inferiores.

Visualizador (VIEWER)
Somente leitura
Operador (OPERATOR)
Leitura + criação de vendas, pedidos e clientes
Gerente (MANAGER)
Acesso mais amplo às operações do negócio
Proprietário (OWNER)
Acesso completo, incluindo gestão de tokens

Limites de taxa

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

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

Ao exceder o limite, a API responde 429 com o header Retry-After indicando quantos segundos aguardar.

Erros comuns

401
Token ausente, inválido, revogado ou expirado
403
Papel do token sem permissão para a ação, ou API não habilitada no plano do tenant
404
Recurso não encontrado (ou não pertence ao tenant do token)
429
Limite de requisições excedido — respeite o header Retry-After

Referência de endpoints

Clientes

POST
/v1/customers
Operador+

Cria um cliente

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

Lista clientes

Parâmetros: search, take, skip

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

Busca um cliente por id

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

Produtos

Somente leitura nesta versão da API.

GET
/v1/products
Visualizador+

Lista produtos

Parâmetros: search, take, skip

curl "https://app.nivro.app/api/v1/products?take=20" \
  -H "Authorization: Bearer nv_..."
GET
/v1/products/:id
Visualizador+

Busca um produto por id

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

Pedidos

POST
/v1/orders
Operador+

Cria um pedido

curl -X POST https://app.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
Visualizador+

Lista pedidos

Parâmetros: status, page, limit, startDate, endDate

curl "https://app.nivro.app/api/v1/orders?status=PENDING&limit=20" \
  -H "Authorization: Bearer nv_..."
GET
/v1/orders/:id
Visualizador+

Busca um pedido por id

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

Vendas

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

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 — é só 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
Operador+

Cria uma venda

curl -X POST https://app.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
Visualizador+

Lista vendas

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

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

Busca uma venda por id

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

# items[] inclui "product": { "name", "sku", "type", "photoUrl" }
POST
/v1/sales/:id/cancel
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://app.nivro.app/api/v1/sales/SALE_ID/cancel \
  -H "Authorization: Bearer nv_..." \
  -H "Content-Type: application/json" \
  -d '{"reason": "Estorno solicitado pelo cliente"}'

Financeiro

GET
/v1/cashflow/transactions
Visualizador+

Lista lançamentos de fluxo de caixa (despesas)

Parâmetros: startDate, endDate, status, category

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

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

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

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

Relatórios

GET
/v1/reports/daily-summary
Visualizador+

Resumo diário de vendas e caixa

Parâmetros: date, startDate, endDate

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

Verificar conexão

Endpoint simples para confirmar que um token é válido, sem exigir nenhuma permissão de negócio específica — ideal para testar a integração antes de ir aos endpoints de dados.

GET
/v1/me
Visualizador+

Retorna o tenant conectado e a identidade do token (nome, papel)

curl https://app.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" }
# }

Versionamento

A API está na versão

v1
. Mudanças que quebrem compatibilidade serão lançadas como uma nova versão (/v2), mantendo /v1 funcionando.