Área do desenvolvedor
O NFe+ também permite a comunicação de softwares externos para a emissão de Notas Fiscais Eletrônicas. Você pode enviar suas notas para nosso sistema via API de comunicação e também retirar nosso cabeçalho para colocar a sua logomarca, e não a nossa.
» Formato dos dados
» Exemplo em HTML
» Exemplo em PHP
» Retorno dos dados
» Mensangens de alerta
» Obter dados das configurações
» Retirar o cabeçalho do NFe+
» Modelo de acesso por frame
Veja como é fácil fazer a integração:
Formato dos dados
As informações enviadas ao nosso sistema podem ser em 2 formatos:
* XML, explicado pelo Manual de Integração do Contribuinte - versão 4.0.1 - NT2009.006
* TXT, de acordo com o Manual de importação-exportação TXT da NF-e (versão 2.0.0 - 24/08/2010)
É importante salientar que, diferentemente do rigor exigido ao enviar as informações para os webservices estaduais, o NFe+ aceita XMLs incompletos, pois os restantes dos dados podem ser preenchidos pelo usuário antes do envio.
O envio das informações deve ser feita por POST. De acordo com o exemplo abaixo:
Exemplo em HTML
<form action="http://CNPJ DA EMPRESA EMISSORA:SENHA DE CONEXÃO@nfe2.nfemais.com.br/api/importarNFe.php" method="post">
<textarea name="nota">XML ou TXT com as informações</textarea>
<button type="submit">Enviar</button>
</form>
Este exemplo em HTML é apenas ilustrativo, pois colocar login e senha direto no HTML não é recomendado, mas você pode fazer isso com outras linguagens. Um outro exemplo é que você pode simular o POST por CURL, veja o exemplo em PHP abaixo:
Exemplo em PHP
<?
//Endereço de conexão
$url = 'http://'. $cnpj .':'. $senha .'@nfe2.nfemais.com.br/api/importarNFe.php';
//Os dados devem estar em UTF-8 e com o urlencode.
$nota = 'nota='. urlencode($xml_ou_txt);
$ch = curl_init();
curl_setopt($ch, CURLOPT_POST, 1); //Número de campos enviados
curl_setopt($ch, CURLOPT_URL, $url); //Endereço de conexão
curl_setopt($ch, CURLOPT_POSTFIELDS, $nota); //Dados da nota (XML ou TXT)
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); //Requer retorno das informações
$retorno = curl_exec($ch); //Executa a comunicação
//O NFe+ retorna as informações em um XML.
$dados = simplexml_load_string($retorno); //Trata o retorno com o SimpleXML
curl_close($ch); //Limpa a memória da conexão.
?>
Retorno dos dados
Após o envio dos dados, o sistema tenta importar e retorna um XML com as seguintes informações:
| Nome do campo -> | Possível retorno |
| importada -> | 1: para sucesso na importação; 0: para erro na importação |
| situacao -> | Importada: quando o sistema conseguiu importar a nota; Não importada: caso o sistema não consiga |
| cod_interno -> | Código interno que a nota foi gravada no NFe+. Não é o mesmo número da nota. |
| alertas -> | Mensagens de alerta que derivam da importação. |
Mensagens de alerta
Segue uma lista de possíveis mensagens para a resposta do campo "alertas".
É possível que apareça mais de 1 alerta durante uma importação.
- Não foi possível extrair os dados do arquivo enviado. (tag infNFe não encontrada ou conteúdo vazio).
- Já há uma nota com esse número e nesta série dentro do sistema. Esta nota foi importada sem o número da NFe, este número poderá ser definido durante a edição.
- Já existem nota(s) emitida(s) com o número maior do que o número importado. Isto não é um erro, apenas um aviso para cuidar o número da NFe importada.
- A série da nota importada é diferente da série de envio atual. Isto não é um erro, apenas um alerta para verificar se a série está correta antes de enviar.
- O CNPJ do emitente é diferente do CNPJ atualmente cadastrado no sistema. O sistema ignorou o CNPJ do emitente do arquivo XML e utilizou os dados do emitente cadastrados nas configurações.
- A nota importada está no ambiente de PRODUÇÃO/TESTE. O sistema está no ambiente de PRODUÇÃO/TESTE. A nota foi transformada para o ambiente de PRODUÇÃO/TESTE.
Obter informações das NFe
Para pegar a situação atual de uma ou mais notas, através da comunicação, há o seguinte endereço:
http://CNPJ DA EMPRESA EMISSORA:SENHA DE CONEXÃO@nfe2.nfemais.com.br/api/infoNFe.php?cods=CODS
Onde CODS pode ser um código (ex: 123) ou alguns códigos separados por vírgula e sem espaço (ex: 123,124,125)
Estes códigos não são o número da nota, e sim, o código interno gerado pelo NFe+ no momento da importação da NFe. Também é o código que aparece na barra de status do navegador ao passar o mouse por cima do link da nota na listagem de notas do NFe+.
O retorno possui as seguintes informações:
- » codigo - código interno do sistema, o mesmo usado na busca pela nota
- » id - número da NFe, é o número que a NFe fica registrada na Sefaz
- » chave - chave de acesso da NFe
- » serie - série da NFe
- » dt_emissao - data que a NFe foi ou será emitida
- » situacao - situação atual da NFe. Esta situação pode ser:
- 10 - Em digitação - A nota está aberta para edição.
- 15 - Rejeitada - A nota foi enviada e rejeitada pela Sefaz. O emitente deve corrigir e reenviar.
- 20 - Assinada - A nota recebeu os dados da assinatura do certificado digital.
- 30 - Validada - A nota passou nos testes básicos da estrutura e está pronta para o envio.
- 35 - Form. Segur. - A nota foi impressa em formulário de segurança e precisa ser emitida assim que possível.
- 40 - Enviada - A nota foi enviada à Sefaz. É necessário verificar se ela foi aceita ou não ("Buscar retorno").
- 50 - Autorizada - A nota foi enviada e autorizada pela Sefaz.
- 70 - Inutilização - Comando de inutilização de um ou mais números. Os números inutilizados não podem ser usados.
- 80 - Denegada - A nota foi denegada pela Sefaz devido a alguma irregularidade fiscal do emitente. Não é possível reutilizá-la.
- 90 - Cancelada - A nota foi cancelada após o envio dela para a Sefaz. É preciso entregar o XML de envio e também o de cancelamento para o destinatário.
- 91 - Inutilizada - A nota foi cancelada no sistema antes do envio. Para a Sefaz é como se ela nunca tivesse existido e o sistema apenas inutiliza o número da nota que não pode mais ser usado.
Obter dados das configurações
Pode haver a necessidade do seu sistema buscar dados das configurações. Para isto, você pode acessar o endereço abaixo, informando o CNPJ da empresa e a senha de comunicação.
http://CNPJ DA EMPRESA EMISSORA:SENHA DE CONEXÃO@nfe2.nfemais.com.br/api/configuracoes.php
Este endereço, quando acessado corretamente, retorna um XML com diversas informações sobre as configurações da empresa. Você pode acessá-lo pelo seu navegador para visualizar as informações retornadas. Talvez você precise de alguma destas informações para a formação do XML ou TXT da Nota Fiscal Eletrônica.
Retirar o cabeçalho do NFe+
O sistema não envia as notas automaticamente para a receita. O usuário precisa entrar na nota e enviá-la. Por isso, a NFe+ disponibiliza um acesso ao sistema sem que apareça o cabeçalho da NFe+. Caso seu software também seja acessado através do navegador, basta chamar o NFe+ por um frame, utilizando o seguinte endereço: http://interno.nfemais.com.br. Se você abrir este endereço em seu navegador, visualizará o sistema sem o cabeçalho e as abas de acesso.
Além do cabeçalho, o endereço também remove as abas que acessam as áreas do sistema. Desta forma, permite que você integre o sistema diretamente no menu de seu software.
Endereços usados pelo software
Com estes endereços você disponibiliza acesso direto às áreas do sistema. Vale lembrar que o usuário precisa estar logado para conseguir o acesso.
http://interno.nfemais.com.br/inicio - (obrigatório) - Este é o endereço principal, nele o seu usuário conseguirá listar e interagir com as notas.
http://interno.nfemais.com.br/configuracoes - (obrigatório) - Endereço da tela de configurações. Este endereço é obrigatório pois o usuário precisará fazer as configurações da empresa e enviar o Certificado Digital.
http://interno.nfemais.com.br/cfop - (opcional - recomendado) - Seção de cadastro dos CFOPs e Naturezas das Operações possíveis. Esta tela não é obrigatória pois o usuário também tem acesso à ela pela tela de Configurações.
http://interno.nfemais.com.br/exportar - (opcional - recomendado) - Tela de download de arquivos. O sistema permita que o usuário baixe vários arquivos XML de uma só vez, zipados.
http://interno.nfemais.com.br/contatos - (opcional) - Seção de cadastro de contatos (clientes e transportadores).
http://interno.nfemais.com.br/produtos - (opcional) - Tela de cadastro de produtos.
http://interno.nfemais.com.br/importar - (opcional) - Esta tela permite que o usuário envie um XML para o sistema e o sistema importará a nota da mesma forma como se ela fosse enviada pela API de comunicação.
http://interno.nfemais.com.br/recebidas - (opcional) - Esta área serve como depósito para o usuário guargar os XMLs das notas que ele recebeu dos fornecedores.
http://interno.nfemais.com.br/sair - (opcional) - Este endereço faz o sistema desconectar o usuário.
Modelo de acesso por frame
Você pode visualizar e baixar um modelo feito por nós que demonstra como pode ser feito o acesso ao NFe+ com a sua próprio logomarca. Este modelo pode ser utilizado, modificado e redistribuído.
