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:

Nota Fiscal Complementar: o que é e como fazer essa NF-e?
Nota Fiscal
João Vallim

Nota fiscal complementar: o que é e em quais casos usar

A Nota Fiscal Complementar é um documento utilizado para auxiliar a uma Nota Fiscal emitida que possui erros ou necessita de ajustes de informações.

No entanto, seja para corrigir valores, impostos ou produtos, a NF Complementar, por vezes, causa dúvidas quanto ao seu preenchimento e sua utilidade.

Acompanhe o artigo de hoje e saiba mais sobre como emitir esse documento, como utilizá-lo e outras informações relevantes para evitar confusões.

Leia mais »
CST
Nota Fiscal
Welker Zigante

CST: saiba o que é o Código de Situação Tributária e qual usar!

O termo CST (Código de Situação Tributária) gera muitas dúvidas sobre como aplicá-lo aos negócios. Devido à variedade de siglas, termos e códigos ligados à tributação empresarial, não é difícil que confusões aconteçam.

Por isso, entender o que é o CST e saber qual código usar em cada situação é fundamental para garantir uma gestão otimizada da emissão de notas e outros documentos fiscais.

Acompanhe o nosso artigo de hoje e esclareça suas dúvidas.
Boa leitura!

Leia mais »
nota-tecnica-2015-002
Nota Fiscal
Ludmila Ferreira

Nota Técnica 2015.002: Web Service de distribuição de DF-e

A Nota Técnica 2015.002, publicada em 11 de fevereiro de 2015, trata de alterações relacionadas ao âmbito do Sistema Público de Escrituração Digital (SPED) e da Nota Fiscal Eletrônica (NF-e).

Na prática, foram alteradas regras e erros foram corrigidos no lançamento das diversas versões da Nota Técnica, como abordaremos a seguir.

Leia mais »