Ir para o conteúdo
LideraNota API v0.10.0

Envio do lote e consulta

Envio do lote

POST /v1/lotes com Content-Type: application/json e o corpo { "notas": [ ... ] }.

  • Tamanho: de 1 a 500 notas por envio. Acima disso, o lote inteiro é recusado com 400 LOTE_ACIMA_DO_LIMITE e nenhuma nota é recebida: divida o envio em lotes menores. O corpo aceita até 5 MB (413 CORPO_ACIMA_DO_LIMITE acima disso).
  • Envelope inválido (sem notas, notas vazio ou que não é lista, campo além de notas): 400 VALIDACAO_CAMPO, com o detalhe em campos.
  • Resposta 202 imediata, mesmo quando alguma nota é recusada: a emissão acontece depois, em segundo plano.
  • Campos da nota: idOperacao, competencia, tomador, servico e valores, entre outros. Os objetos são estritos: campo não previsto recusa a nota. A lista completa, com regras e tamanhos, está na referência do envio do lote.

Requisição:

POST /v1/lotes HTTP/1.1
Host: hml.nfse.lideraweb.com
Authorization: Bearer <seu-token>
Content-Type: application/json

{
  "notas": [
    {
      "idOperacao": "FAT-1001",
      "competencia": "2026-11-10",
      "tomador": {
        "documento": "11222333000181",
        "nome": "Cliente Exemplo Ltda",
        "email": "financeiro@cliente.example",
        "endereco": {
          "cep": "30130000",
          "logradouro": "Rua Exemplo",
          "numero": "100",
          "bairro": "Centro",
          "codigoMunicipio": "3106200"
        }
      },
      "servico": {
        "codigoTributacaoNacional": "010701",
        "descricao": "Desenvolvimento de sistema sob encomenda"
      },
      "valores": {
        "valorServico": 1500,
        "issRetido": false
      }
    }
  ]
}

Com curl:

curl -X POST "$BASE_URL/lotes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "notas": [
    {
      "idOperacao": "FAT-1001",
      "competencia": "2026-11-10",
      "tomador": {
        "documento": "11222333000181",
        "nome": "Cliente Exemplo Ltda",
        "email": "financeiro@cliente.example",
        "endereco": {
          "cep": "30130000",
          "logradouro": "Rua Exemplo",
          "numero": "100",
          "bairro": "Centro",
          "codigoMunicipio": "3106200"
        }
      },
      "servico": {
        "codigoTributacaoNacional": "010701",
        "descricao": "Desenvolvimento de sistema sob encomenda"
      },
      "valores": {
        "valorServico": 1500,
        "issRetido": false
      }
    }
  ]
}'

Sem o cabeçalho Content-Type, o curl envia o corpo como application/x-www-form-urlencoded, recusado com 415 CONTEUDO_NAO_SUPORTADO.

Resposta 202:

{
  "loteId": "7c1e9a4b-2f3d-4e8a-b5c6-1d2e3f4a5b6c",
  "notas": [
    {
      "idOperacao": "FAT-1001",
      "aceita": true,
      "id": "3f8b2c1a-6d4e-4b7f-9a21-0c5e8d7f6a10",
      "status": "recebida",
      "existente": false
    }
  ]
}
  • notas vem na mesma ordem em que as notas foram enviadas: relacione cada resultado à nota enviada pela posição.
  • aceita: true traz o id da nota e o status. Guarde o id: é a chave da consulta, do webhook e dos downloads. Guarde também o loteId, para a consulta do lote.
  • aceita: false traz erros, com campo e mensagem em português. A nota não foi gravada: corrija o campo indicado e reenvie com o mesmo idOperacao.

Valores e texto

  • valores.valorServico é número JSON (não texto), em reais, com no máximo 2 casas decimais e mínimo 0.01. A API não arredonda: mais de 2 casas recusam a nota. Converta o valor guardado como texto ou no formato brasileiro (150,25) antes de gerar o JSON.
  • Os valores dos grupos valores.totTrib e valores.tribFed são texto decimal com ponto e até 2 casas (por exemplo "6.50"); o detalhe está na referência do envio do lote.
  • O JSON precisa estar em UTF-8. Nos campos de endereço do tomador e em informacoesComplementares, só caracteres da faixa Latin-1, sem tabulação nem quebra de linha: travessão, aspas curvas e emoji recusam a nota, e a API não troca caracteres.

Idempotência por idOperacao

O idOperacao identifica a operação no seu sistema (por exemplo a fatura), não o conteúdo da nota:

  • Reenvio do mesmo idOperacao de uma nota já gravada devolve a nota existente, com existente: true e o status atual, sem duplicar a emissão. O conteúdo reenviado é ignorado, mesmo que seja diferente do original. Cada operação nova precisa de um idOperacao novo.
  • Nota recusada na recepção (aceita: false) não foi gravada: corrija e reenvie com o mesmo idOperacao.
  • Nota rejeitada já foi gravada: o mesmo idOperacao só devolve a nota rejeitada. Para emitir de novo, corrija os dados e use um idOperacao novo (por exemplo FAT-1001-2).
  • Nota pendente_intervencao: nunca reenvie com outro idOperacao, porque a nota pode já estar registrada na Sefin Nacional e haveria duas NFS-e para a mesma operação. Aguarde e consulte. Se a nota continuar pendente e você precisar de retorno sobre ela, informe o id da nota. A LideraNota executa este passo: pedir pelo WhatsApp.
  • Falha de rede ou tempo esgotado no envio: reenvie o mesmo lote, com os mesmos idOperacao. As notas já gravadas voltam com existente: true e nada é emitido em dobro. O reenvio recebe outro loteId, mas as notas continuam ligadas ao lote original: acompanhe-as pelo idOperacao ou pelo id.

Consulta do lote e da nota

As consultas são a alternativa e o complemento do webhook. As três rotas só enxergam lotes e notas do emitente do token: lote ou nota de outro emitente recebe o mesmo 404 de um inexistente.

Quando consultar: depois de uma falha de rede no envio, para saber se a nota foi gravada; para notas enviadas há muito tempo sem webhook, em especial as pendente_intervencao, que não geram webhook; e enquanto o webhook do seu sistema estiver fora do ar. Use uma rotina periódica com intervalo de minutos, não um laço contínuo. Para uma nota que continua pendente_intervencao, a LideraNota executa este passo: pedir pelo WhatsApp, informando o id da nota.

Consulta do lote

GET /v1/lotes/{loteId} devolve loteId, recebidoEm, totalNotas, contagemPorStatus e notas, com as notas gravadas por aquele lote, sem paginação (referência). totalNotas conta todos os itens enviados, inclusive os recusados e os reenvios de idOperacao já recebido; contagemPorStatus traz só os status presentes. Erros: 400 VALIDACAO_CAMPO (loteId fora do formato UUID) e 404 LOTE_NAO_ENCONTRADO.

GET /v1/lotes/7c1e9a4b-2f3d-4e8a-b5c6-1d2e3f4a5b6c HTTP/1.1
Host: hml.nfse.lideraweb.com
Authorization: Bearer <seu-token>

curl -X GET "$BASE_URL/lotes/7c1e9a4b-2f3d-4e8a-b5c6-1d2e3f4a5b6c" \
  -H "Authorization: Bearer $TOKEN"

Consulta da nota

GET /v1/notas/{notaId} devolve a nota (referência). Erros: 400 VALIDACAO_CAMPO (notaId fora do formato UUID) e 404 NOTA_NAO_ENCONTRADA.

GET /v1/notas/3f8b2c1a-6d4e-4b7f-9a21-0c5e8d7f6a10 HTTP/1.1
Host: hml.nfse.lideraweb.com
Authorization: Bearer <seu-token>

curl -X GET "$BASE_URL/notas/3f8b2c1a-6d4e-4b7f-9a21-0c5e8d7f6a10" \
  -H "Authorization: Bearer $TOKEN"

Resposta 200 de uma nota autorizada:

{
  "id": "3f8b2c1a-6d4e-4b7f-9a21-0c5e8d7f6a10",
  "idOperacao": "FAT-1001",
  "loteId": "7c1e9a4b-2f3d-4e8a-b5c6-1d2e3f4a5b6c",
  "status": "autorizada",
  "ambiente": "homologacao",
  "numeroNfse": "123",
  "chaveAcesso": "31062002211222333000181000000000012326110000001234",
  "autorizadaEm": "2026-11-10T14:05:40.000Z",
  "links": {
    "xml": "https://hml.nfse.lideraweb.com/v1/notas/3f8b2c1a-6d4e-4b7f-9a21-0c5e8d7f6a10/xml",
    "danfse": "https://hml.nfse.lideraweb.com/v1/notas/3f8b2c1a-6d4e-4b7f-9a21-0c5e8d7f6a10/danfse"
  }
}

A nota rejeitada traz erro (codigo e mensagem); a nota com pedido de cancelamento traz cancelamento; a nota com pedido de análise fiscal traz analiseFiscal; a substituta traz substitui e a original substituída traz substituidaPor. É o mesmo objeto na consulta da nota, na busca por idOperacao, em cada nota da consulta do lote e no webhook.

Busca pelo idOperacao

GET /v1/notas?idOperacao={idOperacao} devolve a nota pelo identificador do seu sistema (referência). 404 NOTA_NAO_ENCONTRADA quer dizer que a nota não foi recebida: depois de uma falha de rede, reenvie com o mesmo idOperacao. 400 VALIDACAO_CAMPO quando o idOperacao falta, está vazio, se repete ou passa de 64 caracteres. Codifique o valor para URL quando ele tiver espaço ou caracteres especiais.

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

curl -X GET "$BASE_URL/notas?idOperacao=FAT-1001" \
  -H "Authorization: Bearer $TOKEN"