Arquivo da tag: api

API para envio de NFe usando o formato de arquivo do SEFAZ-SP

Além de usar o nosso formato YAML para autorização de Nota Fiscal eletrônica você pode agora optar pelo formato reconhecido pelo emissor do SEFAZ-SP.

As URLs de comunicação continuam as mesmas, basta alterar o conteúdo enviado que o sistema reconhece automaticamente o formato enviado. Consulte a API para envio de NFe para consultar as URLs disponíveis.

O arquivo TXT segue uma estrutura hierárquica de grupos, que são determinados por letras (conforme o Manual de Integração do Contribuinte) e a delimitação dos campos de cada grupo pelo caractere “|” , denominado coloquialmente como pipe. Para entender a organização dos arquivos e saber como preencher os dados, você deverá consultar dois manuais:

  1. Manual do Layout TXT do SEFAZ-SP
  2. Manual de Integração do contribuinte

A descrição dos campos se encontra na página 7 do manual do layout TXT, e você deve comparar com a descrição do manual de integração do contribuinte, onde os campos são detalhados no Anexo I, a partir da página 148, do manual do contribuinte. Por exemplo, os dados do emitente são descritos na seguinte linha no layout TXT:

C|XNome|XFant|IE|IEST|IM|CNAE|CRT|

No manual do contribuinte você encontra a seção com a mesma letra “C – Identificação do Emitente da Nota Fiscal eletrônica” na página 153 onde você encontra a descrição de cada campo (xNome, xFant, IE, IEST, IM, CNAE e CRT). Faça o mesmo com o restante dos campos (veja que você pode omitir vários campos) e você poderá submeter o arquivo para autorização.

No momento a API está preparada para aceitar uma NFe por arquivo. Para submeter várias NFes basta realizar uma chamada na API para cada arquivo.

API para envio de NFe

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:

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

 

API para envio de NFSe para o município de São Paulo

Aviso: Esta forma de envio está obsoleta. Utilize o formato unificado para envio de NFSe. O formato abaixo continua funcional apenas para fins de suporte a aplicações legadas.

O Focus NFe disponibiliza um webservice com dois serviços:  a emissão e a consulta de status da NFSe. Sua empresa é autenticada com um “token” secreto que você deverá repassar para o webservice a cada requisição.  Além disso, deverá ser informada uma referência única para cada nota fiscal emitida. Esta referência pode ser, por exemplo, o identificador da fatura no seu banco de dados. É necessária esta referência para que seja possívevl consultar posteriormente o status da NFSe.

Emissão

Para a emissão, você deverá passar dentro de uma requisição POST, o conteúdo de um arquivo no formato YAML com as informações da nota. O formato YAML tem biblioteca pronta em PHP e em diversas outras linguagens de programação de forma que é possível transformar um Hash em YAML com apenas um comando.

A requisição de emissão de NFSe é assíncrona, ou seja, quando a solicitação de emissão é recebida, o retorno é imediato pois a requisição vai para uma fila de processamento para poder lidar com grandes volumes de dados.

Endereço: http://producao.acrasnfe.acras.com.br/nfse2/sao_paulo/autorizar

Parâmetros:

  • token: O token secreto de sua empresa
  • ref: Número da referência
  • Arquivo YAML é enviado no corpo do POST

Exemplo:

POST /nfse2/sao_paulo/autorizar?token=<seu_token>&ref=123
cnpj_prestador: 13339994000123
data_emissao: 2012-08-12
tributacao_rps: T
valor_servicos: 1
valor_deducoes: 0
codigo_servico: 06939
aliquota_servicos: 0.02
iss_retido: false
cpf_cnpj_tomador:
  cpf: 11123242134
razao_social_tomador: PATRICIA TUPYNAMBA
endereco_tomador:
  tipo_logradouro: R
  logradouro: Guararapes
  numero_endereco: 495 A
  complemento_endereco: ap 102
  bairro: BROOKLIN PAULISTA
  cidade: 3550308
  uf: SP
  cep: 4561000
email_tomador: ptupynamba@gmail.com
discriminacao: Serviços de composição gráfica

Retorno: HTTP status 202 (Accepted) ou HTTP status 400 (Bad request) se já existe uma nota autorizada com a mesma referência.

Campos do arquivo YAML:

  • cnpj_prestador: É o cnpj de sua empresa
  • data_emissao: Data de emissão da NFSe
  • tributacao_rps: 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_servicos: Valor do serviços
  • valor_deducoes: Valor das deduções
  • codigo_servico: Código do serviço de acordo com a tabela disponibilizada pela prefeitura.
  • aliquota_servicos: Alíquota dos serviços
  • iss_retido: Informe “true” para ISS retido e “false” caso contrário
  • cpf_cnpj_tomador: Informe abaixo deste campo o subcampo “cnpj” ou “cpf” do tomador, se aplicável
  • razao_social_tomador: Informe o nome ou razão social do tomador.
  • endereco_tomador: Informe os campos  “tipo_logradouro”, “logradouro”, “numero_endereco”, “complemento_endereco”, “bairro”, “cidade”, “uf”, “cep” para especificar o endereço do tomador de serviços.
  • email_tomador: Email do tomador de serviços
  • discriminacao: Discriminação dos serviços. Pode conter várias linhas

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.

Endereço: http://producao.acrasnfe.acras.com.br/nfse2/sao_paulo/consultar

Parâmetros:

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

Exemplo de chamada e retorno:

GET /nfse2/sao_paulo/consultar?token=<seu_token>&ref=123

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.

t