Autenticação

Visão geral

Integrações externas autenticam com chave de API, não com login de usuário no navegador.

Cada chamada precisa de dois dados:

1. Autenticação — a chave sl_live_...
2. Loja — o slug via X-Store-Slug (ou ?loja=)

Mecanismo	Uso
Authorization: Bearer sl_live_...	Recomendado
X-API-Key: sl_live_...	Alternativa equivalente
X-Store-Slug: sua-loja	Obrigatório em toda chamada (identifica a loja)
Cookies / JWT de sessão	Apenas UI do ERP — não use em integrações

URL canônica

https://api.nivesistemas.com.br

Host de produção da API: https://api.nivesistemas.com.br.

Como obter a chave

1. Faça login no Sistema Loja em https://erp.nivesistemas.com.br
2. Vá em Sistema → Integração API
3. Crie a chave (exige plano com acesso à API)
4. Copie o valor sl_live_... imediatamente — ele não é exibido de novo

Chaves revogadas deixam de funcionar na hora.

Identificar a loja

O token não escolhe a loja sozinho. Em toda requisição envie:

• Header X-Store-Slug: loja-demo, ou
• Query ?loja=loja-demo

Sem isso a API responde 400 (STORE_NOT_SPECIFIED).

Escopos

Toda chave é criada com um escopo. O que a chave pode fazer é a interseção do escopo com as permissões do usuário que a criou: se o usuário não pode emitir NFS-e, a chave também não pode, qualquer que seja o escopo.

Escopo (valor na API)	Nome no ERP	O que libera
integration (padrão)	Vendas, estoque e cadastros	Vendas, clientes, produtos, estoque, contas a receber, relatórios e catálogo online — leitura e escrita
read	Somente leitura	Todas as consultas (*.view) e o uso do PDV, sem escrita e sem o cofre de senhas
inherit	Igual ao meu usuário (legado)	As mesmas permissões do usuário

Pela API de gestão (POST /api-keys, com sessão do ERP) também é possível enviar permissions com uma lista personalizada de códigos de permissão. Uma rota fora do escopo responde 403.

O escopo Vendas, estoque e cadastros não inclui o módulo fiscal. Para emitir, cancelar ou inutilizar notas por API, e para cadastrar webhooks, crie a chave com permissions personalizadas incluindo fiscal.view e fiscal.manage.

Chaves criadas antes dos escopos continuam como Igual ao meu usuário. Para reduzir o acesso, crie uma nova chave com escopo menor e revogue a antiga.

A gestão das próprias chaves (/api-keys) exige sessão JWT no ERP — não funciona só com API key.

O que não fazer

• Não use POST /auth/login para integrar outro sistema
• Não compartilhe a chave em repositórios públicos ou front-ends de clientes
• Não reutilize a conta de um caixa do dia a dia para a integração
• Não omita X-Store-Slug / ?loja=

Exemplo completo (dados fictícios)

curl -X GET "https://api.nivesistemas.com.br/customers" \
  -H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
  -H "X-Store-Slug: loja-demo" \
  -H "Accept: application/json"

Equivalente com X-API-Key:

curl -X GET "https://api.nivesistemas.com.br/customers" \
  -H "X-API-Key: sl_live_exemplo_abc123xyz789" \
  -H "X-Store-Slug: loja-demo" \
  -H "Accept: application/json"

Substitua sl_live_exemplo_abc123xyz789 pela chave real e loja-demo pelo slug da sua loja.