Acesso e ambientes

Token de acesso

Toda requisição à API leva o token de acesso que a LideraNota entrega ao seu sistema, no cabeçalho Authorization com o esquema Bearer. O esquema não diferencia maiúsculas (bearer também é aceito); qualquer outro formato é recusado.

• Um token por emitente. O token identifica o emitente (o prestador do serviço) da nota. O CNPJ do emitente nunca vai no corpo da requisição: o contrato nem tem esse campo.
• Mostrado uma única vez. A LideraNota guarda só uma impressão do token, sem o valor: token perdido não pode ser recuperado.
• Guarda segura. Guarde o token no cofre de segredos ou na configuração protegida do seu sistema, com acesso restrito. Nunca o escreva no código-fonte, em log, em mensagem de erro ou em tela.
• Só por HTTPS. Os dois endereços da API usam HTTPS; não siga redirecionamentos levando o token para outro endereço.
• Token recusado: token ausente, inválido, revogado ou de emitente inativo recebe 401 TOKEN_INVALIDO, sempre com a mesma mensagem, sem dizer o motivo.
• Token de acesso e token de webhook são diferentes. O token de acesso autentica as chamadas do seu sistema à API; o token de webhook, no cabeçalho X-Lwnfse-Token, autentica as chamadas da LideraNota ao seu sistema (webhook). Um nunca substitui o outro.

Perda ou vazamento do token

Se o token for perdido ou vazar, peça um novo token de acesso. O token novo não invalida o anterior: os dois valem até a revogação. A LideraNota executa este passo: pedir pelo WhatsApp.

Depois de trocar o token na configuração do seu sistema, peça a revogação do token anterior; em caso de vazamento, peça logo. A LideraNota executa este passo: pedir pelo WhatsApp.

Teste do token

Uma busca por um idOperacao que não existe confere o token sem efeito nenhum: 404 NOTA_NAO_ENCONTRADA quer dizer que o token foi aceito; 401 TOKEN_INVALIDO, que foi recusado.

GET /v1/notas?idOperacao=teste-de-credencial HTTP/1.1
Host: hml.nfse.lideraweb.com
Authorization: Bearer <seu-token>

curl -X GET "$BASE_URL/notas?idOperacao=teste-de-credencial" \
  -H "Authorization: Bearer $TOKEN"

Ambientes

• Cada ambiente tem token e cadastro próprios. O token de homologação não vale em produção, e o contrário também.
• Comece pela homologação. Teste o envio, o webhook, os downloads e o cancelamento em homologação; passe para a produção depois de a integração funcionar.
• Mesmo contrato. As rotas, os campos e os códigos de erro são os mesmos nos dois ambientes; muda só o endereço base e o token.

Para começar os testes, peça o acesso ao ambiente de homologação, com o cadastro do emitente e a entrega do token desse ambiente. A LideraNota executa este passo: pedir pelo WhatsApp.

Com a integração testada, peça o acesso ao ambiente de produção, com o token de produção. A LideraNota executa este passo: pedir pelo WhatsApp.

Dados do emitente

Os dados fiscais do emitente (CNPJ, regime tributário, município de prestação padrão e certificado digital) não vão na nota: a LideraNota os guarda junto com o emitente, e a API recusa a nota que tenta informá-los.

Para emitir por um emitente novo, peça o cadastro do emitente. A LideraNota executa este passo: pedir pelo WhatsApp.

Quando um dado fiscal do emitente mudar (por exemplo o regime tributário), peça a alteração do cadastro do emitente antes de enviar as notas. A LideraNota executa este passo: pedir pelo WhatsApp.

Variáveis dos exemplos

Os exemplos de curl deste guia leem o endereço base e o token de variáveis de ambiente, para o token não ficar no histórico do terminal. Em homologação:

export BASE_URL="https://hml.nfse.lideraweb.com/v1"
export TOKEN="<seu-token>"

Em produção, BASE_URL recebe https://nfse.lideraweb.com/v1 e TOKEN, o token de produção. Nos exemplos de requisição HTTP, <seu-token> marca o lugar do token; os demais dados são fictícios.