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:
- 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;
- A correção de dados cadastrais que implique mudança do remetente ou do destinatário;
- 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.
