API para envio de NFe

Egon Hilgenstieler

Utilize a nossa API para integrar as operações de autorização, consulta e cancelamento de NFe à sua aplicação.

Conteúdo

Para integrar as operações de autorização, consulta e cancelamento de NFe à sua aplicação você pode utilizar nossa API web.

Caso você esteja desenvolvendo uma aplicação desktop em ambiente Windows, o comunicador por arquivo pode ser uma solução mais natural. Em outros casos a API descrita neste post poderá ser utilizada.

Para testar todas as operações envolvendo a NFe, não é necessário implementar nenhuma linha de código, todos os testes podem ser efetuados com o programa cURL que pode ser baixado em plataformas Linux, Windows ou MacOS. O comando cURL serve para efetuar chamadas HTTP GET ou POST, necessários para esta API. Neste post demonstraremos o uso da API com este comando.

Autenticação

A autenticação para os comandos da API será feita através de um token, que será fornecido pelo nosso suporte. Esse token deverá ser enviado em todas as solicitações da API. Será utilizado um token diferente para o ambiente de homologação e de produção.

Referência

Para identificar uma NFe no sistema, deverá ser fornecida uma referência única que irá representar a NFe no seu sistema. Esta referência pode ser qualquer cadeia de caracteres, como por exemplo o identificador da chave primária de seu banco de dados. Não recomendamos que você utilize a numeração da NFe, pois isto nosso sistema irá controlar automaticamente.

Operação Envio de NFe

Para enviar uma NFe, você deverá utilizar as seguintes URLs, para os ambientes de homologação e produção, respectivamente:

POST http://homologacao.acrasnfe.acras.com.br/nfe2/autorizar?token=TOKEN&ref=REFERENCIA

POST http://producao.acrasnfe.acras.com.br/nfe2/autorizar?token=TOKEN&ref=REFERENCIA

Onde REFERENCIA e TOKEN devem ser substituídos pelo identificador único da NFe e pelo seu token de acesso. Como conteúdo do POST deve ser enviado um texto contendo uma representação da NFe a ser autorizada no formato YAML que tem suporte a diversas linguagens de programação.

Consulte a documentação do arquivo de envio de NFe para referência dos campos da NFe. Talvez seja necessário um auxílio do departamento contábil de sua empresa para que você determine a natureza de operação, CFOP e cálculos de impostos de acordo com as operações usuais de sua empresa. Se o seu sistema já estava integrado com o emissor de NFe do SEFAZ de SP, você poderá aproveitar e usar o mesmo formato.
Abaixo mostramos um exemplo de arquivo, em uma operação remessa:

---
natureza_operacao: Remessa
forma_pagamento: 0
data_emissao: 2013-04-15
data_entrada_saida: 2013-04-15
tipo_documento: 1
finalidade_emissao: 1
cnpj_emitente: SEU_CNPJ
nome_emitente: Sua Razão Social Ltda
nome_fantasia_emitente: Fantasia do Emitente
logradouro_emitente: Rua Quinze de Abril
numero_emitente: 999
bairro_emitente: Jd Paulistano
municipio_emitente: São Paulo
uf_emitente: SP
cep_emitente: 01454-600
inscricao_estadual_emitente: SUA_INSCRICAO_ESTADUAL
nome_destinatario: NF-E EMITIDA EM AMBIENTE DE HOMOLOGACAO - SEM VALOR FISCAL
cpf_destinatario: 03055054911
inscricao_estadual_destinatario:
telefone_destinatario: 1196185555
logradouro_destinatario: Rua São Januário
numero_destinatario: 99
bairro_destinatario: Crespo
municipio_destinatario: Manaus
uf_destinatario: AM
pais_destinatario: Brasil
cep_destinatario: 69073178
icms_base_calculo: 0
icms_valor_total: 0
icms_base_calculo_st: 0
icms_valor_total_st: 0
valor_frete: 0.0000
valor_seguro: 0
valor_total: 47.23
valor_produtos: 47.23
valor_ipi: 0
modalidade_frete: 0
items:
- numero_item: 1
  codigo_produto: 1232
  descricao: Cartões de Visita
  cfop: 5923
  unidade_comercial: un
  quantidade_comercial: 100
  valor_unitario_comercial: 0.4723
  valor_unitario_tributavel: 0.4723
  unidade_tributavel: un
  codigo_ncm: 49111090
  quantidade_tributavel: 100
  valor_bruto: 47.23
  icms_situacao_tributaria: 41
  icms_origem: 0
  pis_situacao_tributaria: 07
  cofins_situacao_tributaria: 07

Em ambiente de homologação, o campo nome_destinatario deve ser obrigatoriamente NF-E EMITIDA EM AMBIENTE DE HOMOLOGACAO – SEM VALOR FISCAL. Caso contrário a nota será rejeitada pelo SEFAZ.

Para testar a autorização da NFe, você pode salvar o arquivo de exemplo com o nome remessa.yml e executar o seguinte comando em seu computador:

curl -T remessa.yml 'http://homologacao.acrasnfe.acras.com.br/fe2/autorizar?token=TOKEN&ref=1'

Substituindo o campo TOKEN e lembrando de incrementar a referência caso deseje fazer mais de um teste. Caso o comando seja executado com sucesso, o comando curl não irá gerar nenhuma saída.

Após o envio da NFe, ela irá ser processada de forma assíncrona, ou seja, as requisições serão aceitas imediatamente e enfileiradas para processamento. A NFe poderá ser autorizada em poucos segundos, dependendo da quantidade de requisições.

Operação de Consulta

Após o envio, você poderá consultar o status do processamento, que poderá informar algum erro de validação ou as informações referente a autorização da NFe. As URLs dos ambientes de homologação e produção são:

GET http://homologacao.acrasnfe.acras.com.br/nfe2/consultar?token=TOKEN&ref=REFERENCIA
GET http://producao.acrasnfe.acras.com.br/nfe2/consultar?token=TOKEN&ref=REFERENCIA

Por exemplo, se substituirmos no arquivo remessa.yml o campo “data_emissao” para o ano de 2012, podemos testar uma rejeição de NFe usando o comando abaixo, supondo que a referência tenha sido enviada anteriormente como ’1′:

curl 'http://producao.acrasnfe.acras.com.br/nfe2/consultar?token=TOKEN&ref=1'

O resultado de uma chamada desta URL também virá no formato YAML, conforme abaixo:

---
mensagem_sefaz: "Rejeição: Data de Emissão muito atrasada"
status_sefaz: "228"
status: erro_autorizacao

Para testar uma autorização de NFe, devemos alterar o campo data_emissao e data_entrada_saida para o dia atual e em seguida enviar a NFe:

curl -T remessa.yml 'http://homologacao.acrasnfe.acras.com.br/fe2/autorizar?token=TOKEN&ref=2'

Se consultarmos o status imediatamente depois do envio:

curl 'http://producao.acrasnfe.acras.com.br/nfe2/consultar?token=TOKEN&ref=2'

Podemos obter o resultado:

---
status: processando_autorizacao

Que significa que a nota ainda não foi processada completamente. Após a autorização receberemos uma saída conforme o exemplo abaixo:

---
serie: "1"
chave_nfe: NFe35130413555994000154550010000000021150496225
numero: "2"
mensagem_sefaz: Autorizado o uso da NF-e
status_sefaz: "100"
caminho_xml_nota_fiscal: /arquivos_development/SEU_CNPJ/201304/XMLs/35130413555994000154550010000000021150496225-nfe.xml
caminho_danfe: /arquivos_development/SEU_CNPJ/201304/DANFEs/35130413555994000154550010000000021150496225.pdf
status: autorizado

O caminho do XML e da DANFE são relativos a partir do endereço do servidor utilizado. No exemplo acima a DANFE poderá ser acessada no endereço:

http://homologacao.acrasnfe.acras.com.br/arquivos_development/SEU_CNPJ/201304/DANFEs/35130413555994000154550010000000021150496225.pdf

Operação de Cancelamento

A NFe poderá ser cancelada até 24 horas depois da emissão. Alguns estados permitem um prazo maior para o cancelamento, verifique os detalhes junto com o SEFAZ do seu estado. Para cancelar uma NFe, utilize os seguintes endereços de homologação e produção:

POST http://homologacao.acrasnfe.acras.com.br/nfe2/cancelar?token=TOKEN&ref=REFERENCIA
POST http://producao.acrasnfe.acras.com.br/nfe2/cancelar?token=TOKEN&ref=REFERENCIA

Sendo necessário informar a justificativa do cancelamento no campo “justificativa” do POST. Para testar o cancelamento da referência “2″ do exemplo anterior podemos executar:

curl -F 'justificativa=CNPJ do destinatario incorreto' 'http://homologacao.acrasnfe.acras.com.br/nfe2/cancelar?token=TOKEN&ref=2'

Este comando irá colocar o cancelamento na fila de processamento, após alguns segundos você poderá consultar se o cancelamento foi efetuado corretamente com a mesma operação “Consultar”:

curl 'http://producao.acrasnfe.acras.com.br/nfe2/consultar?token=TOKEN&ref=2'

Que fornecerá um resultado como abaixo:

---
chave_nfe: NFe35130413555994000154550010000000021150496225
status_sefaz: "135"
status: cancelado
caminho_xml_cancelamento: /arquivos_development/SEU_CNPJ/201304/XMLs/35130413555994000154550010000000021150496225-can.xml
mensagem_sefaz: Evento registrado e vinculado a NF-e
caminho_xml_nota_fiscal: /arquivos_development/SEU_CNPJ/201304/XMLs/35130413555994000154550010000000021150496225-nfe.xml

Note que após o cancelamento a DANFE deixa de existir e não poderá mais ser salva.

Operação de Envio e Consula de Carta de Correção eletrônica

Uma Carta de Correção eletrônica (CCe) pode ser utilizada para corrigir eventuais erros na NFe. As seguintes informações não podem ser corrigidas:

  1. As variáveis que determinam o valor do imposto tais como: base de cálculo, aliquota, diferença de preço, quantidade, valor da operação ou da prestação;
  2. A correção de dados cadastrais que implique mudança do remetente ou do destinatário;
  3. A data de emissão ou de saída.

Não existe prazo especificado para emissão de cartas de correção. É possível enviar até 20 correções diferentes, sendo que será válido sempre a última correção enviada. Os endereços são:

Envio:

POST http://homologacao.acrasnfe.acras.com.br/nfe2/emitir_cce?token=TOKEN&ref=REFERENCIA
POST http://producao.acrasnfe.acras.com.br/nfe2/emitir_cce?token=TOKEN&ref=REFERENCIA

Sendo necessário informar a correção da NFe no campo “correcao” do POST. A correção é um texto livre, sem quebras de linha. Exemplo:

curl -F 'correcao=O CEP correto do destinatario é 80210200' 'http://homologacao.acrasnfe.acras.com.br/nfe2/emitir_cce?token=TOKEN&ref=1'

Para consultar o resultado do processamento, utilizamos outras URLs:

GET http://homologacao.acrasnfe.acras.com.br/nfe2/consultar_cce?token=TOKEN&ref=REFERENCIA
GET http://producao.acrasnfe.acras.com.br/nfe2/consultar_cce?token=TOKEN&ref=REFERENCIA

Exemplo:

curl 'http://homologacao.acrasnfe.acras.com.br/nfe2/consultar_cce?token=TOKEN&ref=1'

Cujo resultado será algo como:

---
chave_nfe: NFe35130413555994000154550010000000011319749231
status: autorizado
caminho_xml: /arquivos_development/SEU_CNPJ/201304/XMLs/35130413555994000154550010000000011319749231-cce-01.xml
caminho_pdf: /notas_fiscais/NFe35130413555994000154550010000000011319749231/cartas_correcao/1.pdf
numero_sequencial_evento: 1

Operação de Envio e Consula de Inutilização de Numeração

Em uma situação normal você não precisará informar ao SEFAZ a inutilização de um número da NFe pois a API controla automaticamente a numeração das notas. Porém, se por alguma situação específica for necessário a inutilização de alguma faixa de números você poderá chamar as seguintes operações:

Envio de inutilização de faixa de numeração:

POST http://homologacao.acrasnfe.acras.com.br/nfe2/inutilizar_numeracao?token=TOKEN
POST http://producao.acrasnfe.acras.com.br/nfe2/inutilizar_numeracao?token=TOKEN

A inutilização precisa dos seguintes parâmetros obrigatórios:

  • cnpj – CNPJ da empresa emitente
  • serie –  Série da numeração da NFe que terá uma faixa de numeração inutilizada
  • numero_inicial – Número inicial a ser inutilizado
  • numero_final – Número final a ser inutilizado
  • justificativa – Justificativa da inutilização (mínimo 15 caracteres)

Exemplo:

curl -F 'justificativa=Erro no envio para o SEFAZ' -F cnpj=SEU_CNPJ -F serie=1 -F numero_inicial=231 -F numero_final=231 'http://homologacao.acrasnfe.acras.com.br/nfe2/emitir_cce?token=TOKEN&ref=1'

Para consultar o resultado do processamento, utilizamos outras URLs:

GET http://homologacao.acrasnfe.acras.com.br/nfe2/consultar_inutilizacao_numeracao?token=TOKEN
GET http://producao.acrasnfe.acras.com.br/nfe2/consultar_inutilizacao_numeracao?token=TOKEN&ref=REFERENCIA

A consulta precisa dos mesmos parâmetros utilizados para inutilização, com exceção do campo ‘justificativa’.

Exemplo:

curl -F cnpj=SEU_CNPJ -F serie=1 -F numero_inicial=231 -F numero_final=231 'http://homologacao.acrasnfe.acras.com.br/nfe2/consultar_inutilizacao_numeracao?token=TOKEN'

Cujo resultado será algo como:

--- 
serie: "1"
numero_inicial: "231"
status: autorizado
caminho_xml: /arquivos_development/SEU_CNPJ/201404/XMLs/147762335300017255001000000901000000902-inu.xml
numero_final: "902"

Com isso finalizamos uma visão geral de todas as operações envolvendo a NFe, caso tenha alguma dúvida, não hesite em contatar nosso suporte no e-mail suporte@acras.com.br

Quer integrar seu sistema para emissão de NF-e? Clique aqui, acesse nossa documentação e saiba tudo o que você para fazer a integração do seu sistema com a noss API.

Egon Hilgenstieler

Egon Hilgenstieler

CTO e cofundador do Focus NFe, desenvolvedor, professor de yoga e praticante de meditação. Enquanto não está programando, procura a resposta para a vida, para o universo e para tudo mais.

Inscreva-se em nossa newsletter​

Receba nossos conteúdos exclusivos em primeira mão.

Explore outros conteúdos:

calculadora sob uma mesa com papéis com anotações.
Nota Fiscal
Welker Zigante

O que é DIFAL do ICMS? Entenda como funciona e quem paga!

O termo Diferencial de Alíquota (DIFAL) se refere ao recolhimento do ICMS (Imposto sobre Circulação de Mercadorias e Serviços) e busca promover equidade tributária entre os estados brasileiros.

Empreendedores como proprietários de e-commerces que realizam compras fora do estado e vendem para consumidores finais, precisam considerar as variações nas alíquotas do ICMS entre os estados.

Logo, dada a complexidade dessa legislação, compreender o que é e como funciona o DIFAL pode ser desafiador, especialmente devido às diferentes alíquotas e leis em cada um dos 26 estados e no Distrito Federal relacionadas ao ICMS e aos produtos e serviços tributados.

Acompanhe o nosso post de hoje e compreenda melhor esse processo.

Leia mais »
/nota-tecnica-2016-003
Nota Fiscal
Junior Muniz

Nota Técnica 2016.003: confira a nova tabela de NCM!

A Nota Técnica 2016.003, publicada em dezembro de 2016, é um documento fundamental para a emissão da Nota Fiscal Eletrônica (NF-e). Ela define a tabela de Nomenclatura Comum do Mercosul (NCM) e as Unidades de Medidas Tributáveis (Utrib) a serem utilizadas na NF-e.

Desde que foi lançada, a Nota Técnica 2016.003 passou por diversas alterações, a fim de atualizar a tabela de NCM e Utrib conforme as mudanças da legislação e as necessidades do mercado.

A seguir, abordamos em detalhes todas essas mudanças nas diferentes versões da Nota Técnica e quais códigos foram incluídos e excluídos do documento.

Leia mais »