API to integrate your software with Focus NFe
If you understand portuguese, look here. This post is intended for non-English speakers, it shows how to integrate your software with Focus NFe. If you don’t know what is NFe take a look here. To test our API one can use the cURL tool, not needing to write a single line of code, that’s how we will show how our API works.
Authentication
We will use an access token to give access to test and production environments. For each environment will be provided a different token.
Reference (id)
You will have to provide an unique id for Each NFe that will be issued. This reference can be any string, most commonly it is used the primary key in the application’s. It is not recommended that you use the NFe numeration, for it is our system that will assign the numbers for the NFes. Sending a NFe The following URLs are used to send NFes to our software. The first one is used to send NFes to the test (homologação) environment and the second is to send NFes to the production (produção) environment:
POST http://homologacao.acrasnfe.acras.com.br/nfe2/autorizar?token=TOKEN&ref=REFERENCE
POST http://producao.acrasnfe.acras.com.br/nfe2/autorizar?token=TOKEN&ref=REFERENCE
TOKEN and REFERENCE must be changed by yout access token (provided by our support team) and the internal reference of the NFe in your software. The content of the POST must be the communication file, wich is a YAML file built under this specification (portuguese only): http://www.focusnfe.com.br/nfe/. The following example shows a communication file:
--- 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
In test environment it is mandatory to use the following name to the adressee (destinatario) of the NFe: NF-E EMITIDA EM AMBIENTE DE HOMOLOGACAO – SEM VALOR FISCAL. Given your communication file name is remessa.yml, the curl command will be:
curl -T remessa.yml 'http://homologacao.acrasnfe.acras.com.br/fe2/autorizar?token=TOKEN&ref=1'
After sending the NFe, Focus NFe will process the information asynchronously, meaning you must come back and query the result after a while. Querying NFe The URLs to query the status of a NFe are:
GET http://homologacao.acrasnfe.acras.com.br/nfe2/consultar?token=TOKEN&ref=REFERENCE
GET http://producao.acrasnfe.acras.com.br/nfe2/consultar?token=TOKEN&ref=REFERENCE
Possible Results
- mensagem_sefaz: "Rejeição: Data de Emissão muito atrasada" status_sefaz: "228" status: erro_autorizacao
Meaning the NFe was not authorized with the resulting message (only in portuguese)
— status: processando_autorizacao
Meaning the NFe is still being processed.
— 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
caminho_danfe is the relative path to the DANFe PDF file. caminho_xml is the relative path to the XML file
Cancellation
After authorized, the NFe can be cancelled within 24 ours. The service URLs to do that are.
POST http://homologacao.acrasnfe.acras.com.br/nfe2/cancelar?token=TOKEN&ref=REFERENCE
POST http://producao.acrasnfe.acras.com.br/nfe2/cancelar?token=TOKEN&ref=REFERENCE
Other than the main parameters, the only one to be filled is “justificativa” wich is the reason that the NFe is being cancelled.
curl -F ‘justificativa=CNPJ do destinatario incorreto’ ‘http://homologacao.acrasnfe.acras.com.br/nfe2/cancelar?token=TOKEN&ref=2′
Then you can query the NFe again. If the cancellation is succeeded you will get this status file:
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
