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/lang/NotaFiscalXML.html. 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

Se a receita do estado de São Paulo criou um software gratuito para emissão de NFe, por que utilizar um sistema pago?

A pergunta parece não ter resposta, pois quem em sã consciência iria escolher pagar por algo que pode ter de graça?

Ocorre que o sistema gratuito de São Paulo pode ser muito mais caro do que um sistema pago. Veja por quê.

Cadastros: Com o Focus NFe seus cadastros são mantidos de forma segura. Clientes, fornecedores e produtos podem ser cadastrados e mantidos em um sistema central que pode ser acessado de qualquer lugar. Nada precisa ser repetido quando emitir uma nota fiscal.

Calculo de impostos automatizado: Este talvez seja o maior ponto. A NFe envolve um sem número de informações fiscais que devem ser enviadas para a receita. Quando utiliza o sistema gratuito o contribuinte é obrigado a informar cada uma destas informações manualmente. Com o Focus NFe todo o cálculo de impostos é totalmente automático.

Facilidade de emissão: A facilidade de se emitir uma NFe com o Focus NFe é incontestável, basta assistir a este vídeo para conferir: http://focusnfe.com.br/nfe/video_aula_inicial/video_aula_inicial.html

Suporte especializado: O Focus NFe possui um suporte técnico especializado e sempre disponível ao passo que com o sistema gratuito o contribuinte não tem a quem recorrer caso ocorra algum problema no uso do sistema.

Guarda dos arquivos: Nós fazemos a guarda legal de todo documento fiscal emitido pelos nossos clientes por tempo indeterminado. Os arquivos podem ser recuperados a qualquer momento pelo contribuinte ou seu contador.

Sistema financeiro integrado: A partir de 65 notas emitidas por mês o sistema é acompanhado por um sistema financeiro completo integrado com Contas a Pagar e Receber, controle de contas bancárias, emissão de boleto bancário e muito mais. (Para clientes que emitem menos de 65 notas mensais o sistema pode ser ativado por R$30,00 mensais).

Com tantas facilidades, muito tempo é economizado no trato dos documentos fiscais da empresa. Este tempo custa dinheiro, sem dúvida muito mais dinheiro do que o investido em um sistema de qualidade. Saiba quanto custa para ter um sistema de qualidade, é bem menos do que você imagine: Preços.

Infelizmente as prefeituras não adotam um padrão único para emissão de Notas Fiscais de Serviço (NFSe), apesar de existir uma recomendação da ABRASF, cada cidade é livre para decidir o padrão que achar melhor, tornando difícil o trabalho de quem precisa fazer a integração de seu cidade com múltiplas cidades. Para contornar este problema, estamos desenvolvendo a versão 3 de nossa API para emissão de NFSe, que tentará ser o mais homogênea possível, atendendo ao maior número de cidades com um mínimo de mudanças. Abaixo descrevemos o formato de comunicação desta API. A API irá utilizar o padrão REST de comunicação via HTTP, as 3 chamadas possíveis da API são exemplificadas abaixo:

• POST /nfse?ref=REFERENCIA&token=TOKEN – Submete uma nova NFSe para autorização
• GET /nfse/REFERENCIA?token=TOKEN – Recupera informações sobre a NFSe
• DELETE /nfse/REFERENCIA?token=TOKEN  – Cancela uma NFSe

Onde REFERENCIA é a referência do objeto do sistema original (por exemplo, o identificador do banco de dados) e TOKEN é o token de acesso fornecido na contratação do sistema. O token é utilizado para identificar a empresa prestadora do serviço.

Submissão de NFSe

A submissão de uma NFSe irá conter no seu corpo um arquivo YAML descrevendo os dados da nota. Todos os campos são descritos abaixo e as diferenças entre as cidades comentadas. Os campos denotados com (*) são obrigatórios.

• data_emissao (*): Data/hora de emissão da NFSe. Alguns municípios como São Paulo não utilizam hora e ela será descartada caso seja fornecida.
• status: Status da NFS-e, informar 1 – Normal ou 2 – Cancelado. (Valor padrão: 1).
• natureza_operacao: Natureza da operação. Informar um dos códigos abaixo. Campo ignorado para o município de São Paulo. 1 – Tributação no município 2 – Tributação fora do município 3 – Isenção 4 – Imune 5 – Exigibilidade suspensa por decisão judicial 6 – Exigibilidade suspensa por procedimento administrativo (Valor padrão: 1)
• regime_especial_tributacao: Informar o código de identificação do regime especial de tributação conforme abaixo. Campo ignorado para o município de São Paulo. 1 – Microempresa municipal 2 – Estimativa 3 – Sociedade de profissionais 4 – Cooperativa 5 – MEI – Simples Nacional 6 – ME EPP – Simples Nacional
• optante_simples_nacional(*): Informar verdadeiro ou falso se a empresa for optante pelo Simples Nacional. Campo ignorado pelo município de São Paulo.
• incentivador_cultural: Informe verdadeiro ou falso. Valor padrão: falso. Campo ignorado para o município de São Paulo.
• tributacao_rps: Usado apenas pelo município de São Paulo. Informe o tipo de tributação: T – Operação normal (tributação conforme documento emitido); I – Operação isenta ou não tributável, executadas no Município de São Paulo; F – Operação isenta ou não tributável pelo Município de São Paulo, executada em outro Município; J – ISS Suspenso por Decisão Judicial (neste caso, informar no campo Discriminação dos Serviços, o número do processo judicial na 1a. instância). (Valor padrão “T”)
• servico:
  • valor_servicos(*): Valor dos serviços.
  • valor_deducoes: Valor das deduções.
  • valor_pis: Valor do PIS.
  • valor_cofins: Valor do COFINS.
  • valor_inss: Valor do INSS.
  • valor_ir: Valor do IS.
  • valor_csll: Valor do CSLL
  • iss_retido(*): Informar verdadeiro ou falso se o ISS foi retido.
  • valor_iss: Valor do ISS. Campo ignorado pelo município de São Paulo.
  • valor_iss_retido: Valor do ISS Retido. Campo ignorado pelo município de São Paulo.
  • outras_retencoes: Valor de outras retenções.  Campo ignorado pelo município de São Paulo.
  • base_calculo: Base de cálculo do ISS, valor padrão igual ao valor_servicos. Campo ignorado pelo município de São Paulo.
  • aliquota: Aliquota do ISS.
  • desconto_incondicionado: Valor do desconto incondicionado. Campo ignorado pelo município de São Paulo.
  • desconto_condicionado: Valor do desconto incondicionado. Campo ignorado pelo município de São Paulo.
  • item_lista_servico(*): informar o código da lista de serviços, de acordo com a Lei Complementar 116/2003. Utilize outra tabela para o município de São Paulo.
  • codigo_cnae: Informar o código CNAE. Campo ignorado pelo município de São Paulo.
  • codigo_tributario_municipio: Informar o código tributário de acordo com a tabela de cada município (não há um padrão). Campo ignorado pelo município de São Paulo.
  • discriminacao(*): Discriminação dos serviços.
  • codigo_municipio(*): Informar o código IBGE do município de prestação do serviço.

• prestador:
  • cnpj(*): CNPJ do prestador de serviços.
  • codigo_municipio(*): Código IBGE do município do prestador (consulte lista aqui)
  • inscricao_municipal: Inscrição municipal do prestador de serviços.
• tomador:
  • cpf(*): CPF do tomador, se aplicável.
  • cnpj(*): CNPJ do tomador, se aplicável.
  • inscricao_municipal: Inscrição municipal do tomador
  • razao_social: Razão social ou nome do tomador
  • endereco:
    • logradouro: Nome do logradouro.
    • tipo_logradouro: Tipo do logradouro. Usado apenas para o município de São Paulo. Valor padrão: os 3 primeiros caracteres do logradouro.
    • numero: Número do endereço.
    • complemento: Complemento do endereço.
    • bairro: Bairro
    • codigo_municipio: código IBGE do município.
    • uf: UF do endereço.
    • cep: CEP do endereço.
  • telefone: Telefone do tomador. Campo ignorado para o município de São Paulo.
  • email: Email do tomador.
• intermediario (esta seção é ignorada pelo município de São Paulo)
  • razao_social: Razão social do intermediário do serviço.
  • cpf: CPF  do intermediário do serviço, se aplicável.
  • cnpj: CNPJ  do intermediário do serviço, se aplicável.
  • inscricao_municipal: Inscrição municipal  do intermediário do serviço, se aplicável.
• codigo_obra: Código da obra quando construção civil. Este campo é ignorado pelo município de São Paulo.
• art: Código ART quando construção civil. Este campo é ignorado pelo município de São Paulo.

Exemplo de um arquivo YAML:

data_emissao: 2013-05-31T12:00:00-03:00
incentivador_cultural: false
natureza_operacao: "1"
optante_simples_nacional: false
prestador: 
 cnpj: 06901848000133
 inscricao_municipal: 080204613599
 codigo_municipio: 4106902
servico: 
 aliquota: 0.05
 base_calculo: 200.0
 discriminacao: "Servico de hospedagem de sites"
 iss_retido: "2"
 item_lista_servico: "801"
 valor_iss: 10.0
 valor_liquido: 200.0
 valor_servicos: 200.0
status: "1"
tomador: 
 cpf: 03055054912
 endereco: 
   bairro: Centro
   cep: "80000000"
   codigo_municipio: "4106902"
   logradouro: "Rua Emiliano Perneta"
   numero: "845"
   uf: PR
 razao_social: "Egon Hilgenstieler"

Consulte o suporte técnico para possíveis exceções no seu município.

Consulta

Após a emissão, a consulta da situação do processamento poderá ser feita em um segundo momento para obter as informações da NFSe gerada ou dos erros de processamento. O retorno é também em formato YAML. Parâmetros:

• token: O token secreto de sua empresa
• ref: Número da referência

Exemplo de chamada e retorno:

GET /nfse/<REFERECIA>?token=<seu_token>

uri: https://nfe.prefeitura.sp.gov.br/contribuinte/notaprint.aspx?inscricao=112312&nf=14&verificacao=P2UJ4QGT

codigo_verificacao: P2UJ4QGT
data_emissao: 2012-08-12 03:00:00 Z
numero: "14"
status: autorizado

Retorno: HTTP status 200 (Ok) ou HTTP status 404 (Not Found) se não encontrada NFSe associada a referência Campos de retorno:

• uri: Endereço disponibilizado pela prefeitura para visualização da NFSe
• codigo_verificacao: Código de verificação da NFSe
• data_emissao: Data de emissão
• numero: Número da NFSe
• status: “autorizado” se a NFSe foi emitida com sucesso ou “erro_autorizacao” caso contrário
• erros: Array de mensagens de erro caso a nota fiscal não tenha sido emitida com sucesso.

Lately we have seen lots of foreign developers facing the challenge of developing NFe solutions for brazilian companies. As we now have some customers in this situation we will release content in english to make it easy for these developers to accomplish this challenge.

What is the NFe (Nota Fiscal Eletrônica or Electronic Invoice)

Until 2008 invoices in Brazil were issued in paper. Any company could get the authorization to print a certain number of unfilled invoices so they could fill it and send to their customers.
Since 2008 Brazilian government has adopted an electornic invoice system, making it mandatory to any brazilian company that sells products.
The electronic version of invoices are issued one by one and pre-filled by the company. Meaning that each and every sale (or importing) transaction is informed to the government that authorizes one by one. Obviously this is made in an automated way, called NFe.
The process of issuing a NFe

First of all one should fill a XML file containing, information about the issuer, the receiver, the products, the taxes (wich are very, very complicated in Brazil), the way it will be transported, how it will be paid and so on.

The second step will be to digitally sign this XML document using a digital certificate compliant with ICP-Brasil standards.

Third step is to communicate with the government servers, using SOAP technology. Government receives the transaction and “tells” you the estimated time it will have an answer (rarely being more than 5 seconds).

After that time we query the server to see if it have an answer. If the invoice is authorized then we are able to generate the DANFe (short for Auxiliar Document of the NFe). By law we have to inform the receiver via email that the NFe is successfully issued.

By law the issuer must keep the XML file for at least 5 years.

Focus NFe service

As it turns out, the XML file is very complicated, it has many fields and rules according to the type of the company and the kind of taxes it pays. Furthermore the communication with government computers may be tricky as each state has it’s own servers and there are redundancy servers with little communication specificities.

The Focus NFe service has a simple text file for communication and a very simple return file as well. All the details and communication with each server in the country is handled by our service. The generation of DANFe is handled by Focus NFe. The service also sends the NFe to the receiver and keeps the XML file safe for as long as the service contract is active.

Brazilian fiscal law is complicated and is constantly changing. We keep our service compliant to the law at all times, and every time it is possible, we do not change the communication files layout. (It is important to say that the API do not calculate taxes, so changes in taxes must be handled by the programmer).