Introdução

A API do Focus NFe permite que você emita ou consulte documentos fiscais (NFe, NFSe, NFCe) a partir do seu sistema, seja qual for a tecnologia que ele utilize através da geração de dados em um formato simplificado, sem a necessidade de gerar a assinatura digital destes documentos. A API ainda gerencia toda a comunicação com os servidores da SEFAZ de cada estado ou com os servidores da prefeitura, no caso de NFSe.

Através desta documentação deverá ser possível fazer a integração com a API do Focus NFe, caso alguma dúvida permaneça você pode entrar em contato com o suporte especializado através do e-mail suporte@acras.com.br.

Como ler este documento?

Você deverá ler primeiramente a introdução, em seguida, a seção sobre o documento que você irá emitir (NFe, NFCe ou NFSe).

Caso você emita NFe ou NFCe, você deverá ler também sobre os backups.

Caso você emita NFe ou NFSe, você poderá ler também sobre os gatilhos. O uso de gatilhos no sistema é opcional.

Caso você tenha interesse em obter as notas emitidas contra a sua empresa, leia a seção de manifestação.

Se sua empresa irá administrar vários clientes que emitem notas, pode ser interessante você ler sobre a seção de revenda.

Qual documento fiscal você precisa emitir?

Dependendo da atividade da sua empresa você deverá emitir um ou mais destes documentos que irão representar frente ao governo qualquer operação com mercadoria ou serviços:

NFe - Nota Fiscal Eletrônica. Utilizado para indústrias, distribuidores em geral ou empresas que vendem para clientes fora de seu estado. Neste caso é aceitável uma nota demorar vários minutos para ser autorizada. Existe um padrão nacional. O documento é de competência do estado.
NFCe - Nota Fiscal ao Consumidor Eletrônica. Utilizado para empresas de varejo, que trabalham diretamente com o consumidor final. Neste caso há a preocupação da nota ser emitida em poucos segundos. Existe um padrão nacional. O documento é de competência do estado.
NFSe - Nota Fiscal de Serviços Eletrônica. Utilizado para a maioria dos prestadores de serviços. É aceitável a nota demorar vários minutos para ser autorizada. Esta nota é de competência da prefeitura. Existe uma recomendação nacional que cada prefeitura implementa como bem entender.
CTe - Conhecimento de Transporte Eletrônico. Usado para prestadores de serviços de transporte. Existe um padrão nacional. Documento de competência do estado.

Existe algumas exceções no país, por exemplo Brasília pode utilizar NFe para serviços e Manaus utiliza NFCe em alguns casos para notas de serviços. Na dúvida, consulte o contador da sua empresa.

Visão geral do processo de emissão de um documento

A emissão de NFe e NFSe são processadas de forma assíncrona. NFCe é processada de forma síncrona.

A emissão de documentos síncronos (NFCe) é simples:

Você envia pela API os dados do documento
A API devolve como resposta da requisição se o documento foi emitido ou não, e qual a mensagem de erro

Já a emissão de documentos de forma assíncrona são feitos da seguinte forma:

Você envia pela API os dados do documento
A API faz uma primeira validação do formato dos dados. Se houver alguma inconsistência, é devolvida uma mensagem de erro. Se estiver tudo ok, o documento é aceito para processamento posterior. Ou seja, ele vai para uma fila onde será eventualmente processado.
Sua aplicação irá fazer uma nova consulta para verificar o status do processamento
Nossa API irá informar se o documento ainda está sendo processado, ou se o processamento já finalizou. Neste último caso informa a mensagem de erro ou os dados do documento gerado caso a nota tenha sido autorizada.
Caso o documento ainda esteja em processamento, sua aplicação deverá agendar uma nova consulta dentro de alguns segundos.

Alternativamente, você poderá usar o conceito de gatilhos. Neste caso você informa a API qual endereço de sua aplicação deverá ser chamado quando uma nota for autorizada. Neste caso funcionaria assim:

Você envia pela API os dados do documento
A API faz uma primeira validação do formato dos dados. Informa sobre inconsistência ou avisa que a nota foi aceita para processamento, como no cenário anterior.
Quando a nota for processada, a API irá ativamente lhe informar através de um HTTP POST no endereço combinado o resultado do processamento.

Autenticação

A autenticação é feita através de um token. Ao habilitar a API para sua empresa forneceremos uma string secreta e única que será usada para efetuar todas as operações. A autenticação poderá ser feita usando o método HTTP Basic Auth (saiba mais em https://en.wikipedia.org/wiki/Basic_access_authentication) fornecendo o token como nome de usuário e deixando a senha em branco.

Caso não seja possível utilizar método HTTP Basic Auth você pode também enviar sempre o parâmetro “token” informando o seu token de acesso. Porém nós recomendamos o uso de HTTP Basic Auth pois isto aumenta a segurança impedindo a gravação do token em históricos do navegador, logs de acesso, etc.

Referência

A referência é a forma que utilizamos para identificar a sua emissão em nossa API, por isso, ela deve ser única para cada token de acesso que você receba. A referência pode ser alfanumérica, contudo, não são permitidos caracteres especiais. É comum a utilização do identificador da tabela em banco de dados que representa uma nota fiscal no seu sistema.

Uma referência pode ser reutilizada caso ocorra erro na autorização. Mas uma vez que a nota seja autorizada (mesmo que posteriormente cancelada), a referência usada não poderá mais ser usada em outro envio.

Ambiente

A API do Focus NFe oferece dois ambientes para emissão de notas: homologação e produção.

Homologação

O ambiente de homologação serve para envio de notas fiscais com a finalidade de teste. As notas emitidas aqui não possuem validade fiscal/tributária.

Produção

Este é o ambiente com validade fiscal e tributária, pois isso, recomendamos que utilize este ambiente apenas quando for iniciar o processo de envio de notas válidas.

O endereço dos servidores são os seguintes:

Homologação: https://homologacao.focusnfe.com.br

Produção: https://api.focusnfe.com.br

Considerações sobre o uso de SSL

<?php
# Em PHP normalmente é necessária uma configuração adicional.
# Em muitos sites você irá encontrar a solução abaixo,
# para ignorar a validação do certificado:

$ch = curl_init();
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

# Porém o correto seria indicar para confiar na unidade certificadora
$ch = curl_init();
curl_setopt($ch, CURLOPT_CAINFO, "/pasta/no/servidor/ca.crt");
?>

Verifique em sua linguagem de programação se é necessário alguma configuração adicional para uso de SSL. Pode ser necessário indicar explicitamente a confiar na autoridade certificadora que emitiu o certificado SSL. Em especial na linguagem Java é necessário adicionar todos os certificados, inclusive de toda cadeia da empresa certificadora.

Para poder baixar os certificados de nosso servidor, você pode executar o seguinte comando em algum console linux:

openssl s_client -showcerts -connect api.focusnfe.com.br:443

Isto irá listar todos os certificados entre "-----BEGIN CERTIFICATE-----" e "-----END CERTIFICATE-----". Apenas salve todos estes certificados em arquivos separados e importe para a sua ferramenta de armazenamento de certificados. Entre em contato com nosso suporte caso encontre problemas neste processo.

Padrão REST

A API utiliza o padrão de arquitetura REST https://pt.wikipedia.org/wiki/REST. Neste padrão, são utilizados verbos ou métodos HTTP (GET, POST, DELETE) em conjunto com determinados recursos disponíveis através de uma URL para representar uma determinada ação. Por exemplo, o verbo GET é usado para representar algum tipo de visualização dos dados de um dado recurso, e o verbo POST é usado para criar um novo recurso e o verbo DELETE representa uma exclusão.

Abaixo alguns exemplos de requisições:

Método	URL (recurso)	Ação
POST	/v2/nfe?ref=REFERENCIA	Cria uma nota fiscal e a envia para processamento.
GET	/v2/nfe/REFERENCIA	Consulta a nota fiscal com a referência informada e o seu status de processamento
DELETE	/v2/nfe/REFERENCIA	Cancela uma nota fiscal com a referência informada

Você deve substituir REFERENCIA pela referência gerada pela sua aplicação.

A API utiliza o formato JSON para transferência de dados.

Sempre que é feita uma chamada HTTP é devolvido um código de retorno. Este código irá informar também se a requisição foi aceita ou se ocorreu algum erro, da seguinte forma:

Códigos que iniciam com “2” representam ação que foi completada com sucesso, por exemplo: 200, 201.
Códigos que inicial com “4” ou "5" representam algum erro na requisição, por exemplo: 404, 402, etc.

Abaixo listamos os códigos HTTP que nossa API pode devolver:

Código HTTP	Significado	Explicação
200	Ok	Este código é devolvido quando uma consulta resulta em sucesso.
201	Criado	Este código é devolvido quando uma requisição é aceita para processamento.
400	Requisição inválida	Este erro é devolvido quando falta alguma informação na requisição ou ela é inválida por algum outro motivo. Por exemplo quando falta algum parâmetro obrigatório.
403	Permissão negada	Este erro é devolvido quando ocorre algum problema de permissão envolvendo o token de acesso.
404	Não encontrado	Este erro é devolvido quando não é encontrado algum recurso que é pesquisado.
415	Mídia inválida	Este erro é devolvido quando não é reconhecido o formato JSON enviado, devido a alguma falha de sintaxe.
422	Entidade improcessável	Não existe erro na requisição (sintaxe), porém há algum erro de semântica (por exemplo, tentar cancelar uma nota já cancelada)
429	Muitas requisições	Você ultrapassou o limite de requisições por minuto. Veja o limite de requisições
500	Erro interno do servidor	Ocorreu algum erro inesperado. Contate o suporte técnico.

Note que se o código HTTP devolvido for de sucesso não implica que uma nota tenha sido autorizada com sucesso. Por exemplo, você pode enviar uma nota fiscal para autorização, nossa API devolver o status 201 (criado) (pois não havia nenhum erro aparente na nota fiscal) porém ao ser processada pela SEFAZ ou prefeitura verificou-se que a data de emissão estava muito atrasada. Ou seja, os códigos HTTP são utilizados para verificar se a transação está ok no nível de comunicação da sua aplicação com a nossa API (e não com o SEFAZ).

Erros

Exemplo de mensagem de erro

{
  "codigo": "nao_encontrado",
  "mensagem": "Nota fiscal não encontrada"
}

As mensagens de erro serão apresentadas em qualquer operação sempre que for devolvido um código HTTP que começa com 4. A mensagem será um objeto com os seguintes atributos:

codigo - O código da mensagem
mensagem - A descrição mais detalhada do que ocorreu
erros - (Opcional) Quando for possível detalhar o erro, ele será informado neste array de objetos

Abaixo listamos os códigos de erro mais comuns.

Código HTTP	Código do erro	Significado
400	requisicao_invalida	Faltou informar algum campo na requisição. Este campo é informando na mensagem do erro
400	empresa_nao_habilitada	Empresa ainda não habilitada para emitir o documento que você precisa. Habilite no seu painel ou contate o suporte técnico
400	nfe_cancelada	Foi feita uma tentativa de cancelar uma nota já cancelada
403	permissao_negada	Sua aplicação por algum motivo se encontra bloqueada para uso. Contate o nosso suporte
404	nao_encontrado	Ocorre quando o recurso que você está procurando (NFe, NFCe ou NFSe) não é encontrado
422	nfe_nao_autorizada	Foi feita alguma operação com a nota que só é aplicável se ela estiver autorizada (por exemplo a ação de cancelamento)
422	nfe_autorizada	Foi solicitado o processamento de uma nota já autorizada
422	em_processamento	Foi solicitado o processamento de uma nota que já está em processamento

NFe

Através da API NFe é possível:

Emitir NFe utilizando dados simplificados. Este processo por default é assíncrono. Ou seja, após a emissão a nota será enfileirada para processamento. Em alguns estados é possível configurar a emissão para envio síncrono quando possível.
Cancelar NFe.
Consultar o status de NFe emitidas.
Encaminhar uma NFe por email
Emitir Carta de Correção.
Inutilizar uma faixa de numeração de NFe

URLs

Método	URL (recurso)	Ação
POST	/v2/nfe?ref=REFERENCIA	Cria uma nota fiscal e a envia para processamento.
GET	/v2/nfe/REFERENCIA	Consulta a nota fiscal com a referência informada e o seu status de processamento
DELETE	/v2/nfe/REFERENCIA	Cancela uma nota fiscal com a referência informada
POST	/v2/nfe/REFERENCIA/carta_correcao	Cria uma carta de correção para a nota fiscal com a referência informada.
POST	/v2/nfe/REFERENCIA/email	Envia um email com uma cópia da nota fiscal com a referência informada
POST	/v2/nfe/inutilizacao	Inutiliza uma numeração da nota fiscal

Campos obrigatórios de uma NFe

Atualmente, a NFe possui centenas de campos para os mais variados tipos e formas de operações, por isso, criamos uma página exclusiva que mostra todos os campos da nossa API para o envio de NFe. Nela, você pode buscar os campos pela TAG XML ou pela nossa tradução para API.

Documentação completa dos campos (versão 4.00 da NFe)

Abaixo, iremos mostrar os campos de uso obrigatório para emissão de uma Nota Fiscal Eletrônica.

Abaixo um exemplo de dados de uma nota (usando a versão 4.00 da NFe):

{
  "natureza_operacao":"Remessa",
  "data_emissao":"2017-04-15",
  "data_entrada_saida":"2017-04-15",
  "tipo_documento":1,
  "finalidade_emissao":1,
  "cnpj_emitente":"SEU_CNPJ",
  "cpf_emitente": "SEU_CPF",
  "nome_emitente":"Sua Raz\u00e3o Social Ltda",
  "nome_fantasia_emitente":"Fantasia do Emitente",
  "logradouro_emitente":"Rua Quinze de Abril",
  "numero_emitente":999,
  "bairro_emitente":"Jd Paulistano",
  "municipio_emitente":"S\u00e3o 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":null,
  "telefone_destinatario":1196185555,
  "logradouro_destinatario":"Rua S\u00e3o Janu\u00e1rio",
  "numero_destinatario":99,
  "bairro_destinatario":"Crespo",
  "municipio_destinatario":"Manaus",
  "uf_destinatario":"AM",
  "pais_destinatario":"Brasil",
  "cep_destinatario":69073178,
  "valor_frete":0.0,
  "valor_seguro":0,
  "valor_total":47.23,
  "valor_produtos":47.23,
  "modalidade_frete":0,
  "items": [
    {
      "numero_item":1,
      "codigo_produto":1232,
      "descricao":"Cartu00f5es 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"
    }
  ]
}

Geral

natureza_operacao: Descrição da natureza da operação a ser realizada pela nota fiscal.
data_emissao: Data da emissão da NFe. Formato padrão ISO, exemplo: “2016-12-25T12:00-0300”.
tipo_documento: Tipo da NFe. Valores possíveis:

0 – Nota Fiscal de Entrada;

1 – Nota Fiscal de Saída.

local_destino: Local onde a operação irá acontecer. Valores possíveis:

1 – Operação interna;

2 – Operação interestadual;

3 – Operação com exterior.

finalidade_emissao: Indicar qual a finalidade da emissão da nota. Valores possíveis:

1 – Normal;

2 – Complementar;

3 – Nota de ajuste;

4 – Devolução.

consumidor_final: Indicar se a operação é com consumidor final. Valores possíveis:

0 – Normal;

1 – Consumidor final.

presenca_comprador: Informar como foi a presença do comprador. Valores possíveis:

0 – Não se aplica (por exemplo, para a Nota Fiscal complementar ou de ajuste);

1 – Operação presencial;

2 – Operação não presencial, pela Internet;

3 – Operação não presencial, Teleatendimento;

4 – NFC-e em operação com entrega em domicílio;

9 – Operação não presencial, outros.

Emitente

cnpj_emitente: CNPJ do emitente da nota. Deve ser usado esse campo ou o "cpf_emitente".
cpf_emitente: CPF do emitente da nota. Deve ser usado esse campo ou o "cnpj_emitente".
inscricao_estadual_emitente: Informar a Inscrição Estadual do emitente.
logradouro_emitente: Logradouro do emitente.
numero_emitente: Número do logradouro do emitente.
bairro_emitente: Bairro do emitente.
municipio_emitente: Município do emitente.
uf_emitente: UF do emitente.
regime_tributario_emitente: Informar qual o regime tributário do emitente. Valores possíveis:

1 – Simples Nacional;

2 – Simples Nacional – excesso de sublimite de receita bruta;

3 – Regime Normal.

Destinatário

nome_destinatario: Nome completo do destinatário.
cnpj_destinatario: CNPJ da empresa destinatária.
cpf_destinatario: CPF do destinatário. Caso utilize este campo, não enviar o campo “cnpf_destinatario”.
inscricao_estadual_destinatario: Informar a Inscrição Estadual do destinatário.
logradouro_destinatario: Logradouro do destinatário.
numero_destinatario: Número do logradouro do destinatário.
bairro_destinatario: Bairro do destinatário.
municipio_destinatario: Município do destinatário.
uf_destinatario: UF do destinatário.
indicador_inscricao_estadual_destinatario: Indicador da Inscrição Estadual do destinatário. Valores possíveis:

1 – Contribuinte ICMS (informar a IE do destinatário);

2 – Contribuinte isento de Inscrição no cadastro de Contribuintes do ICMS;

9 – Não Contribuinte, que pode ou não possuir Inscrição Estadual no Cadastro de Contribuintes do ICMS.

Itens

Uma NFe irá conter um ou mais itens no campo “items” que poderão conter os campos abaixo:

numero_item: Numeração que indica qual a posição do item na nota, deve ser usado numeração sequencial a partir do número “1”.
codigo_produto: Código do produto.
descricao: Descrição do produto.
cfop: Código Fiscal da Operação, CFOP da operação válido para NFe.
quantidade_comercial: Quantidade da mercadoria.
quantidade_tributavel: Quantidade tributavel da mercadoria. Caso não se aplique, utilize o mesmo valor do campo quantidade_comercial.
valor_unitario_comercial: Valor unitário da mercadoria.
valor_unitario_tributavel: Valor unitário tributável da mercadoria. Caso não se aplique, utilize o mesmo valor do campo valor_unitario_comercial.
unidade_comercial: Unidade comercial do produto. Você pode utilizar valores como “KG”, “L”, “UN” entre outros. * Caso não se aplique, use “UN”.
unidade_tributavel: Unidade tributável do produto. Caso não se aplique, utilize o mesmo valor do campo unidade_comercial.
valor_bruto: Valor bruto do produto.
código_ncm: Código NCM do produto. Este código possui 8 dígitos.
inclui_no_total: Valor do item (valor_bruto) compõe valor total da NFe (valor_produtos)?. Valores possíveis:

0 – Não;

1 – Sim.

icms_origem: Informar a origem do ICMS. Valores possíveis:

0 – Nacional;

1 – Estrangeira (importação direta);

2 – Estrangeira (adquirida no mercado interno);

3 – Nacional com mais de 40% de conteúdo estrangeiro;

4 – Nacional produzida através de processos produtivos básicos;

5 – Nacional com menos de 40% de conteúdo estrangeiro;

6 – Estrangeira (importação direta) sem produto nacional similar;

7 – Estrangeira (adquirida no mercado interno) sem produto nacional similar;

icms_situacao_tributaria: Informar qual a situação do ICMS para a operação. Valores possíveis:

00 – Tributada integralmente;

10 – Tributada e com cobrança do ICMS por substituição tributária;

20 – Tributada com redução de base de cálculo;

30 – Isenta ou não tributada e com cobrança do ICMS por substituição tributária;

40 – Isenta;

41 – Não tributada;

50 – Suspensão;

51 – Diferimento (a exigência do preenchimento das informações do ICMS diferido fica a critério de cada UF);

60 – Cobrado anteriormente por substituição tributária;

70 – Tributada com redução de base de cálculo e com cobrança do ICMS por substituição tributária; 90 – Outras (regime Normal);

101 – Ttributada pelo Simples Nacional com permissão de crédito;

102 – Tributada pelo Simples Nacional sem permissão de crédito;

103 – Isenção do ICMS no Simples Nacional para faixa de receita bruta;

201 – Tributada pelo Simples Nacional com permissão de crédito e com cobrança do ICMS por substituição tributária;

202 – Tributada pelo Simples Nacional sem permissão de crédito e com cobrança do ICMS por substituição tributária;

203 – Isenção do ICMS nos Simples Nacional para faixa de receita bruta e com cobrança do ICMS por substituição tributária;

300 – Imune;

400 – Não tributada pelo Simples Nacional;

500 – ICMS cobrado anteriormente por substituição tributária (substituído) ou por antecipação;

900 – Outras (regime Simples Nacional);

pis_situacao_tributaria: Informar qual a situação do PIS para a operação. Valores possíveis: 01 – Operação tributável: base de cálculo = valor da operação (alíquota normal – cumulativo/não cumulativo);

02 – Operação tributável: base de cálculo = valor da operação (alíquota diferenciada);

03 – Operação tributável: base de cálculo = quantidade vendida × alíquota por unidade de produto;

04 – Operação tributável: tributação monofásica (alíquota zero);

05 – Operação tributável: substituição tributária;

06 – Operação tributável: alíquota zero;

07 – Operação isenta da contribuição;

08 – Operação sem incidência da contribuição;

09 – Operação com suspensão da contribuição;

49 – Outras operações de saída;

50 – Operação com direito a crédito: vinculada exclusivamente a receita tributada no mercado interno;

51 – Operação com direito a crédito: vinculada exclusivamente a receita não tributada no mercado interno;

52 – Operação com direito a crédito: vinculada exclusivamente a receita de exportação;

53 – Operação com direito a crédito: vinculada a receitas tributadas e não-tributadas no mercado interno;

54 – Operação com direito a crédito: vinculada a receitas tributadas no mercado interno e de exportação;

55 – Operação com direito a crédito: vinculada a receitas não-tributadas no mercado interno e de exprtação;

56 – Operação com direito a crédito: vinculada a receitas tributadas e não-tributadas no mercado interno e de exportação;

60 – Crédito presumido: operação de aquisição vinculada exclusivamente a receita tributada no mercado interno;

61 – Crédito presumido: operação de aquisição vinculada exclusivamente a receita não-tributada no mercado interno;

62 – Crédito presumido: operação de aquisição vinculada exclusivamente a receita de exportação;

63 – Crédito presumido: operação de aquisição vinculada a receitas tributadas e não-tributadas no mercado interno;

64 – Crédito presumido: operação de aquisição vinculada a receitas tributadas no mercado interno e de exportação;

65 – Crédito presumido: operação de aquisição vinculada a receitas não-tributadas no mercado interno e de exportação;

66 – Crédito presumido: operação de aquisição vinculada a receitas tributadas e não-tributadas no mercado interno e de exportação;

67 – Crédito presumido: outras operações;

70 – Operação de aquisição sem direito a crédito;

71 – Operação de aquisição com isenção;

72 – Operação de aquisição com suspensão;

73 – Operação de aquisição a alíquota zero;

74 – Operação de aquisição sem incidência da contribuição;

75 – Operação de aquisição por substituição tributária;

98 – Outras operações de entrada;

99 – Outras operações;

cofins_situacao_tributaria: Informar qual a situação do CONFINS para a operação. Valores possíveis:

01 – Operação tributável: base de cálculo = valor da operação (alíquota normal – cumulativo/não cumulativo);