Visão geral da API
URL base
Seção intitulada “URL base”Em produção use https://api.nivesistemas.com.br. A loja é identificada pelo header X-Store-Slug (ou ?loja=), não por um domínio próprio. O catálogo cobre as rotas protegidas por chave de API e as públicas relevantes. Provisionamento da plataforma, chat de suporte Nive, migração de dados (/data-migration), assistente de implantação (/store-onboarding) e warmup interno (POST /health/warm) ficam fora do escopo de integração externa.
Autenticação
Seção intitulada “Autenticação”Gere uma chave em Sistema → Integração API no ERP e envie em cada requisição via Authorization: Bearer sl_live_... ou X-API-Key: sl_live_..., junto com X-Store-Slug: sua-loja (ou ?loja=). Chaves revogadas deixam de funcionar imediatamente. A gestão das próprias chaves (/api-keys) exige sessão de usuário (JWT), não API key. Veja o guia de autenticação.
Escopo da chave
Seção intitulada “Escopo da chave”Toda chave tem um escopo, e as permissões efetivas são a interseção do escopo com as permissões do usuário que a criou. integration (padrão — “Vendas, estoque e cadastros”): vendas, clientes, produtos, estoque, contas a receber, relatórios e catálogo online, com leitura e escrita. read (“Somente leitura”): todas as permissões de consulta (*.view) mais o uso do PDV, sem escrita e sem o cofre. inherit (“Igual ao meu usuário”, legado): as mesmas permissões do usuário. Rotas fora do escopo respondem 403.
O acesso à API (criação de chaves) está disponível nos planos Expansão e Rede.
Formato
Seção intitulada “Formato”Requisições e respostas usam JSON (Content-Type: application/json), salvo download de arquivos.
Limites
Seção intitulada “Limites”A API autenticada aplica rate limit padrão de cerca de 300 requisições por minuto por IP (configurável no servidor). Em 429, aguarde e tente novamente. Detalhes no guia de limites.
NFS-e e ordens de serviço
Seção intitulada “NFS-e e ordens de serviço”Para emitir nota de serviço de outro sistema: use POST /nfse/emit-direct (payload completo sem OS) ou POST /nfse/emit-with-order (cria cliente/OS e emite). Consulte GET /nfse/emit-prep?serviceOrderId= antes de emitir a partir de uma OS. Para faturar OS no PDV: POST /service-orders/:id/to-sale e depois finalize a venda (NFS-e via saleId / nfseIntent). Também é possível gerenciar OS, projetos, contratos, visitas de campo e assinaturas nas rotas /service-*. A chave precisa das permissões nfse.view / nfse.manage (e as de serviços, quando aplicável).
Documento fiscal de mercadoria (NFC-e / NF-e)
Seção intitulada “Documento fiscal de mercadoria (NFC-e / NF-e)”A Sale usa um único FiscalDocument (modelo 65 NFC-e ou 55 NF-e de venda). O caixa escolhe o modelo na finalização; o cadastro do cliente pode fixar NFC-e ou NF-e. Emita com POST /fiscal/documents/emit/:saleId. Cancelamento e DANFE usam /fiscal/documents/:id/*. CC-e e inutilização 55: POST /fiscal/documents/:id/cce e POST /fiscal/inutilize-nfe-sale. Contingência offline permanece só para NFC-e. Devoluções 55 continuam em /sale-returns e /purchase-returns.
Erros comuns
Seção intitulada “Erros comuns”400 — loja não informada (envie X-Store-Slug ou ?loja=). 401 — credencial ausente ou inválida. 403 — sem permissão ou plano sem API. 404 — recurso não encontrado. 422 — validação (corpo da resposta traz detalhes). 409 — conflito (ex.: GTIN duplicado). 429 — rate limit.
Catálogo de recursos
Seção intitulada “Catálogo de recursos”São 1238 endpoints em 103 grupos. Use a busca (Ctrl K) para achar por caminho, método ou descrição.
Acesso e conta
Seção intitulada “Acesso e conta”Autenticação, chaves, usuários, perfis e configurações da loja.
Catálogo
Seção intitulada “Catálogo”Produtos, categorias, marcas, grade, preços e etiquetas.
| Recurso | Endpoints |
|---|---|
| Produtos | 46 |
| Categorias | 11 |
| Marcas | 6 |
| Tags de produto | 7 |
| GTINs | 5 |
| Divisões de grade | 6 |
| Subdivisões de grade | 6 |
| Grade (eixos e sugestão) | 4 |
| Tabelas de preço | 9 |
| Fila de etiquetas | 10 |
| Agente de impressão | 15 |
| Avaliações | 3 |
| Embalagem para presente | 5 |
| Custos adicionais | 5 |
Vendas e PDV
Seção intitulada “Vendas e PDV”Pedidos, caixa, clientes, devoluções, pagamentos e canais.
Fidelidade e promoções
Seção intitulada “Fidelidade e promoções”Programa de fidelidade, cupons, campanhas e promoções.
| Recurso | Endpoints |
|---|---|
| Fidelidade | 14 |
| Campanhas promocionais | 15 |
| Cupons | 7 |
| Promoções com brinde | 6 |
Compras e estoque
Seção intitulada “Compras e estoque”Compras, fornecedores, transferências, conferência e locais.
| Recurso | Endpoints |
|---|---|
| Compras | 35 |
| Devoluções de compra | 23 |
| Fornecedores | 6 |
| Transportadoras | 5 |
| Conferência de estoque | 12 |
| Locais (filiais e depósitos) | 6 |
| Transferências de estoque | 9 |
Financeiro
Seção intitulada “Financeiro”Contas a receber e a pagar, cheques e cartões.
| Recurso | Endpoints |
|---|---|
| Contas a receber | 30 |
| Contas a pagar | 21 |
| Cheques | 7 |
| Cartões de crédito da empresa | 13 |
NFC-e, NF-e, NFS-e, regras tributárias, cadastros e webhooks fiscais.
Serviços e campo
Seção intitulada “Serviços e campo”Ordens de serviço, contratos, visitas, checklists e ativos.
Segmentos
Seção intitulada “Segmentos”Padaria, tintométrico e segurança química.
| Recurso | Endpoints |
|---|---|
| Produção (receitas e ordens) | 26 |
| Tintométrico (fábrica de tintas) | 21 |
| Segurança química (FISPQ) | 15 |
Integrações e IA
Seção intitulada “Integrações e IA”E-commerce, catálogo online, inteligência artificial e rotas públicas.
Relatórios
Seção intitulada “Relatórios”Relatórios gerenciais da loja.
| Recurso | Endpoints |
|---|---|
| Relatórios | 47 |