Emitir e cancelar nota fiscal pela API (linha FIS)

Atualizado em 22/10/2026

Sim, dá para emitir nota fiscal pela API do ERP. Esta fonte é a linha FIS do aplicativo API e responde o que a integração faz com nota fiscal, o que ela não resolve sozinha e o que costuma travar na prática.

COMO A EMISSÃO FUNCIONA
Criar a nota e emitir a nota são duas chamadas diferentes. Primeiro você cria a nota; o ERP devolve o ID e ela nasce Em aberto. Depois, numa segunda chamada, você manda emitir aquele ID. Não existe "criar e autorizar" de uma vez. A vantagem é poder conferir ou corrigir a nota antes de ela ir para a SEFAZ.
A emissão só aceita POST. Chamada com GET, PUT ou qualquer outro método devolve "Método não permitido. Use POST.". O cancelamento segue a mesma regra.

TRÊS FAMÍLIAS, TRÊS ENDEREÇOS
São três conjuntos separados, cada um com endereço próprio:
nota de produto, a NF-e modelo 55, em notas_fiscais_produtos;
nota ao consumidor, a NFC-e modelo 65, em notas_fiscais_consumidores;
nota de serviço, a NFS-e, em notas_fiscais_servicos.
Os três têm listar, ver, criar, editar e excluir. Em todos, emitir e cancelar são POST no endereço da família terminando com o ID da nota — por exemplo POST /api/notas_fiscais_consumidores/emitir/{id} e POST /api/notas_fiscais_consumidores/cancelar/{id}. A nota de serviço tem código de emissão e de cancelamento próprio, separado dos outros dois.
Não misture as famílias: é o endereço que decide o modelo procurado. Se você pedir a emissão de uma nota de consumidor pelo endereço de produto, a busca procura uma nota modelo 55 e não encontra a sua.

O QUE A API NÃO FAZ
A API usa a sua configuração fiscal; ela não cria nem substitui essa configuração. Certificado digital, série, numeração, natureza de operação, CFOP, tributação e ambiente (produção ou homologação) continuam sendo do ERP e do módulo fiscal. Se a nota não sai pela tela do ERP, também não vai sair pela API, e o erro devolvido é o mesmo. Configure primeiro no ERP, pelas fontes de configuração fiscal e de emissão de nota, e só depois automatize.
Vale o mesmo para os cadastros: a nota é montada a partir do cliente, do fornecedor e do produto do ERP. NCM, CFOP e unidade saem do cadastro do produto quando você não envia esses dados.

O TOKEN E O USUÁRIO POR TRÁS DELE
O acesso usa dois cabeçalhos, access-token e secret-access-token, obtidos no próprio aplicativo API dentro do ERP. Faltando um deles, a chamada para na autenticação. Nunca envie esses valores no chat nem por e-mail.
Toda chamada responde por um usuário e por uma loja do ERP, definidos no próprio token ou informados na requisição — e, quando o token já traz essa amarração, é ela que vale. É esse usuário que "assina" a nota. Daí vêm os chamados clássicos:
a permissão é conferida em dois lugares. Primeiro a da própria API: sem ela vem "Este usuário não possui permissão para acessar este método!". Depois a do módulo fiscal, já dentro da emissão: sem ela vem "Você não tem permissão para executar esta ação!";
o usuário pode ter restrição de IP e de horário e dias de acesso, então integração rodando de madrugada ou de outro servidor é barrada ("Este usuário não está habilitado ao acesso neste horário!" ou "...por este IP!");
na emissão, a nota é procurada apenas na empresa e na loja do token. Nota de outra loja não é encontrada, e a resposta é "Nota fiscal não encontrada.". Se você mandar loja_id na chamada e o token já estiver amarrado a uma loja, o valor do token prevalece.

AS SITUAÇÕES DA NOTA
A lista é fechada, são estas sete: Em aberto, Aprovada, Reprovada, Denegada, Cancelada, Enviando e Corrigida. Não existe outra.
Emitir só faz sentido em Em aberto, Reprovada e Enviando. Com a nota Aprovada, Cancelada, Denegada ou Corrigida, a API recusa com "Não é possível emitir uma nota que já se encontra Aprovada, Cancelada, Denegada ou Corrigida.".
Quando a emissão falha, a nota fica Reprovada com o motivo gravado, uma notificação é criada no ERP e, se a nota veio de um pedido, o motivo também entra como observação no pedido. Você corrige o que o motivo aponta e chama emitir de novo na mesma nota.

CANCELAMENTO
Cancelar também é POST e exige o campo motivo no corpo. Sem ele vem "O motivo do cancelamento é obrigatório.".
Nota Em aberto não cancela: "Não é possível cancelar uma nota fiscal em aberto." (na nota de serviço, "...uma nota fiscal de serviço em aberto."). Em aberto ela nem existe na SEFAZ; o que se faz nesse caso é excluir a nota.
Em NF-e e NFC-e o cancelamento só anda com a nota Aprovada ou Corrigida. Fora disso a resposta é "Esta nota fiscal não foi aprovada, por isso não pode ser cancelada!".
O cancelamento não usa o mesmo recorte de loja da emissão: ele vale para a empresa e para as lojas às quais o usuário está vinculado. Nota de uma loja fora dessas passa pela primeira checagem e é recusada mais adiante com "Você não tem permissão para acessar este registro.".
Prazo e regras de cancelamento são da SEFAZ e do seu estado. A API só encaminha o pedido e devolve a resposta que recebeu.

O QUE COSTUMA DAR ERRADO
"Método não permitido. Use POST." — a emissão ou o cancelamento foi chamado com outro método.
"Nota fiscal não encontrada." na emissão — o ID não existe, ou é de uma loja diferente da loja do token.
Mensagem de certificado — na emissão de NF-e e NFC-e vem "O certificado digital não é válido ou a senha está incorreta. Atualize o mesmo no ERP!". A causa quase sempre é certificado vencido ou senha alterada. No cancelamento e na nota de serviço a mesma falha volta sem esse complemento, no texto original do módulo fiscal; é o mesmo problema.
Resposta "Cron realizada com sucesso." — parece sucesso, mas nada foi emitido. Acontece quando a nota não bate com o endereço usado (modelo diferente), não é da loja do token, ou está com data de emissão fora da janela que a emissão varre, que é o mês anterior, o mês atual e o mês seguinte. Nota antiga não emite por aí.
"Esta nota já está sendo enviada, por favor, tente mais tarde!" — a nota está em Enviando e o envio começou há menos de um minuto. Espere e consulte a situação antes de tentar de novo.
"Configuração da empresa não encontrada." na nota de serviço — a loja daquela nota está sem configuração fiscal salva.
Envio automático na criação — o campo envio_automatico não emite na hora: ele joga a nota no caminho de emissão em massa do módulo fiscal, que recusa certificado A3. Esse resultado não aparece na resposta, que é a da criação; se o envio foi recusado, você só descobre pela situação da nota. Para emitir na hora, use a chamada de emissão.
Emitir pela API mexe no envio automático: a nota emitida sai do envio automático e o agendamento de envio automático daquela loja é apagado — inclusive quando a chamada não emite nada. Se o cliente usa as duas coisas, é isso que explica "o automático parou depois que integrei".

LIMITE DE REQUISIÇÕES
Os endereços de nota fiscal chamam um contador de requisições por usuário, mas o resultado dessa checagem é descartado: ele conta e registra, e não interrompe a emissão. Não conte com ele para segurar sua integração — controle o ritmo do seu lado. O que existe de bloqueio de verdade é o do próprio token: com o token bloqueado, a resposta é HTTP 429 citando os limites por segundo e por dia, com recado para procurar o suporte. Se a dúvida for sobre um limite específico da conta, verifique com o suporte em vez de supor um número.

TEMPO DE RESPOSTA
A emissão é síncrona. A mesma chamada monta o XML, assina, valida, envia e consulta o retorno antes de responder, então ela demora mais que as outras chamadas da API. Demora não é falha: em vez de reenviar na hora, consulte a situação da nota e decida pelo que ela mostra.