Home » Categorias » Soluções Oobj » API Rest

Recebimento de Documentos Fiscais via API Rest

Nº do Artigo: 748 | Avaliação: 3/5 de 2 votos | Última atualização: 27/09/2021 10:55:31

A solução de Recebimento de Documentos Fiscais consulta automaticamente na Sefaz todos os documentos emitidos contra o CNPJ de uma empresa. Para utilizar a solução através da API REST, é necessário ter um usuário para acessar a API(x-auth-token). No artigo Autenticação na API Rest  você encontra mais detalhes sobre o x-auth-token.

Existem vários Endpoints para o serviço de Recebimento de Documentos Fiscais e para cada um, há uma URL específica.

 

Consultar Documentos Recebidos

O usuário poderá realizar uma consulta de todos os documentos recebidos, obtendo um resumo dos dados do DFe. Para isso há dois Endpoints, um que permite obter esse resumo pela Data de Emissão e outro através do NSU (Número Sequencial Único), há também um Endpoint que disponibiliza o último NSU consultado na Sefaz.

 

Importante ressaltarmos que a consulta por NSU busca apenas DFes consultados diretamente na Sefaz e poderá resultar no resumo dos seguintes tipos de documentos:

  • Resumo do DF-e
  • DF-e
  • Evento do Emitente
  • Evento do Fisco

No seu Sistema, ao integrar com a API Rest, o desenvolvedor poderá através do resultado da consulta validar se o documento está autorizado e se há o XML Proc para posteriormente baixar o PDF ou XML do DFe.

Quanto a consulta por Data de Emissão, deve ser levado em consideração que nem sempre o documento é recebido no mesmo dia da data de emissão e nessa consulta é retornado documentos recebidos tanto por Email quanto pela Sefaz.

 

Buscar último NSU Consultado na Sefaz

Esse Endpoint permite a busca do último NSU consultado na Sefaz. Ao receber essa informação o software responsável pela integração poderá iterar sobre o resultado, registrando o último NSU consultado X último NSU buscado, e posteriormente realizar a busca do documento pelo NSU.

A URL é construída da seguinte forma:

http:// ou https:// + /endereço da API Rest + /api/empresas/{empresa}/docs/{ambiente}/{codModelo}/mde/ultimoNsu

Os valores sublinhados devem ser substituídos pelos valores correspondentes:

  • {empresa} : CNPJ da Empresa
  • {ambiente} : hom ou prod
  • {codModelo} : 55, 57, 58 ou 65 (respectivamente, NFe, CTe, MDFe ou NFCe)
http://teste.oobj.com.br/oobj-rest-service/api/empresas/07385111000102/docs/hom/55/mde/ultimoNsu

 

Obter resumo dos DFes Recebidos utilizando NSU

Por esse Endpoint é possível realizar uma consulta resumida de um documento recebido através do NSU .

A URL é construída da seguinte forma:

/http:// ou https:// + /endereço da API Rest + /api/empresas/{empresa}/docs/{ambiente}/{codModelo}/mde/{ultimoNsu}
  • {empresa} : CNPJ da Empresa
  • {ambiente} : hom ou prod
  • {codModelo} : 55, 57, 58 ou 65 (respectivamente, NFe, CTe, MDFe ou NFCe)
  • {ultimoNsu} : NSU da consulta
http://teste.oobj.com.br/oobj-rest-service/api/empresas/07385111000102/docs/hom/55/mde/336

 

Obter resumo dos DFes Recebidos utilizando Data de Emissão

Nesse é possível consultar o resumo de um DF-e pela data de emissão do documento.

A URL é construída da seguinte forma:

/http:// ou https:// + /endereço da API Rest + /api/empresas/{empresa}/docs/{ambiente}/{codModelo}/recebidos/{dataEmissao}
  • {empresa} : CNPJ da Empresa
  • {ambiente} : hom ou prod
  • {codModelo} : 55, 57, 58 ou 65 (respectivamente, NFe, CTe, MDFe ou NFCe)
  • {dataEmissao} : Data de emissão (yyyy-MM-dd)
http://teste.oobj.com.br/oobj-rest-service/api/empresas/12769092000158/docs/hom/55/recebidos/2018-09-19?pagina=1

 

Consultar Documentos Não Recebidos

A Sefaz inicialmente libera apenas o resumo da NF-e sem nenhum tipo de manifesto. Estes resumos não possuem muitos detalhes e para obter o documento completo, é necessário algum tipo de manifesto seja ciência ou confirmação de operação. Caso a empresa não possua a Ciência de Operação automática ativada (Disponível na aplicação da Oobj), o usuário poderá consultar todos os documentos ainda não recebidos, obtendo um resumo dos dados do DFe e decidir se fará ou não o  manifesto. Para isso há um Endpoint, que permite obter esse resumo pela Data de Emissão.

A URL é construída da seguinte forma:

/http:// ou https:// + /endereço da API Rest + /api/empresas/{empresa}/docs/{ambiente}/{codModelo}/nao-recebidos/{dataEmissao}
  • {empresa} : CNPJ da Empresa
  • {ambiente} : hom ou prod
  • {codModelo} : 55, (NF-e)
  • {dataEmissao} : Data de emissão (yyyy-MM-dd)
http://teste.oobj.com.br/oobj-rest-service/api/empresas/12769092000158/docs/hom/55/nao-recebidos/2018-09-19?pagina=1

 

Baixar Documentos Recebidos

Depois de obtidas as informações de todos os documentos emitidos contra o CNPJ consultado, é possível fazer o download do XML e do PDF.

 

Download do XML (GET)

O XML Proc é o Documento Fiscal com Assinatura Digital, que é idêntico ao armazenado na Sefaz e que deve ser guardado pelo contribuinte por no mínimo 5 anos.

Nesse Endpoint, é possível obter o XML Proc de um DFe Emitido ou Recebido. Sempre que esse serviço for utilizado será retornado os DFes emitidos ou recebidos pela empresa informada na URL de forma paginada com 20 elementos (XML Proc), ou seja, ao realizar o primeiro acesso a esse Endpoint, você poderá informar a página que deseja consultar na URL, ou poderá deixar em branco, assim virá a primeira página.

Na resposta da sua consulta nesse serviço, será informado no final a quantidade de itens que há na página, e qual o Total de itens que pode ser obtidos em todas as outras páginas. Dessa forma, basta realizar uma iteração, passando por cada página até que não hajam mais elementos, caso queira obter todos os XML's Proc da sua empresa.

 

A URL é construída da seguinte forma:

http:// ou https:// + /endereço da API Rest + /api/empresas/{empresa}/docs/{ambiente}/{codModelo}/?pagina={numeroPagina}&comXML={true ou false}
  • {empresa} : CNPJ da Empresa
  • {ambiente} : hom ou prod
  • {codModelo} : 55, 57, 58 ou 65 (respectivamente, NFe, CTe, MDFe ou NFCe)
  • {numeroPagina} : numero da pagina (Opcional. Se não informado, o valor 1 é assumido como padrão)
  • {comXml} : true ou false (Opcional. Se não informado, o valor false é assumido como padrão) 

Exemplo com os parâmetros opcionais preenchidos:

http://rest.oobj-dfe.com.br/api/empresas/07385111000102/docs/hom/55?pagina=1&comXml=false

 

Exemplo sem os parâmetros opcionais preenchidos:

http://rest.oobj-dfe.com.br/api/empresas/07385111000102/docs/hom/55

 

Baixar PDF (Documento Auxiliar)

Após o recebimento poderá ser obtido o Documento Auxiliar do DFe em formado PDF. E assim como para Consultar um DFe, há dois Endpoints, um que permite obter o PDF através da série e número e outro por chave de acesso.

 

1. Download de PDF de um DFe através da série e número (GET)

Nesse Endpoint, o PDF (Documento Auxiliar) do DFe é obtido através da série e número do DFe emitido.

A URL é construída da seguinte forma: 

http:// ou https:// + /endereço da API Rest + /api/empresas/{empresa}/docs/{ambiente}/{codModelo}/{ano}/{serie}/{numero}.pdf

Os valores sublinhados devem ser substituídos pelos valores correspondentes:

  • {empresa} : CNPJ da Empresa
  • {ambiente} : hom ou prod
  • {codModelo} : 55, 57, 58 ou 65 (respectivamente, NFe, CTe, MDFe ou NFCe)
  • {ano} : Ano de Emissão no formado AAAA
  • {serie} : Série do DFe
  • {numero} : Número do DFe
http://rest.oobj-dfe.com.br/api/empresas/07385111000102/docs/hom/55/2018/502/186067.pdf

Observe que a URL é semelhante a URL do Endpoint para Obter o retorno de um DFe através da série e número, sendo necessário adicionar apenas o termo .pdf no final.

 

2. Download de PDF de um DFe através da chave de acesso (GET)

Nesse Endpoint, o PDF (Documento Auxiliar) do DFe é obtido através da Chave de Acesso:

A URL é construída da seguinte forma:

http:// ou https:// + /endereço da API Rest + /api/empresas/{empresa}/docs/{ambiente}/{codModelo}/{chaveAcesso}.pdf
  • {empresa} : CNPJ da Empresa
  • {ambiente} : hom ou prod
  • {codModelo} : 55, 57, 58 ou 65 (respectivamente, NFe, CTe, MDFe ou NFCe)
  • {chaveAcesso} : Chave de Acesso do DFe
http://rest.oobj-dfe.com.br/api/empresas/07385111000102/docs/hom/55/43180307385111000102555020001860671000000000.pdf

 

No seu Sistema, ao integrar com a API Rest, o desenvolvedor poderá escolher qual componente para obter o Documento Auxiliar irá implementar ou se usará os dois.

 

Manifestação do Destinatário

Depois do recebimento do documento, em alguns casos a Sefaz exige que o destinatário emita um evento de Manifestação do Destinatário.

Para Saber tudo sobre este evento acesse nossos artigos abaixo:

A Manifestação do Destinatário pode ser realizada através dos Endpoints para o serviço de Emissão de Eventos Fiscais e para cada um, há uma URL específica.

 

Autorização / Envio de Manifesto (POST)

A emissão de um Manifesto de Destinatário através da API Rest pode ser feita utilizando alguns Layout específicos, como XML Oobj (padrão), XML Sefaz ou TXT-SP.

A URL é construída da seguinte forma: 

http:// ou https:// + /endereço da API Rest + /api/empresas/{empresa}/docs/{ambiente}/{codModelo}/{ano}/{serie}/{numero}/eventos?layout={layoutDFe}

 

Os valores sublinhados devem ser substituídos pelos valores correspondentes abaixo:

  • {empresa} : CNPJ da Empresa
  • {ambiente} : hom ou prod
  • {codModelo} : 55, 57, 58 ou 65 (respectivamente, NFe, CTe, MDFe ou NFCe)
  • {ano} : Ano de Emissão no formado AAAA
  • {serie} : Série do DFe
  • {numero} : Número do DFe
  • {layoutDFe} : oobj, sefaz ou txtsp. Será assumido o valor oobj, caso não informado

Exemplo com o parâmetro opcional layoutDFe preenchido:

http://rest.oobj-dfe.com.br/api/empresas/07385111000102/docs/hom/55/2018/502/186067/eventos?layout=sefaz

 

Exemplo sem o parâmetro opcional layoutDFe preenchido: 

http://rest.oobj-dfe.com.br/api/empresas/07385111000102/docs/hom/55/2018/502/186067/eventos

 

Nesse Endpoint será enviado o conteúdo do Evento Fiscal nos Layouts XML Oobj (padrão), XML Sefaz ou TXT-SP.

 

Obter retorno de um Manifesto (GET)

Nesse Endpoint, o retorno de um Manifesto o Destinatário pode ser obtido no mesmo Layout que foi usado na Emissão / Envio.

A URL é construída da seguinte forma: 

http:// ou https:// + /endereço da API Rest + /api/empresas/{empresa}/docs/{ambiente}/{codModelo}/{ano}/{serie}/{numero}/eventos/{tipoEvento}

 

Os valores sublinhados devem ser substituídos pelos valores correspondentes abaixo:

  • {empresa} : CNPJ da Empresa
  • {ambiente} : hom ou prod
  • {codModelo} : 55, 57, 58 ou 65 (respectivamente, NFe, CTe, MDFe ou NFCe)
  • {ano} : Ano de Emissão no formado AAAA
  • {serie} : Série do DFe
  • {numero} : Número do DFe
  • {tipoEvento} : Código que representa o tipo do evento
http://rest.oobj-dfe.com.br/api/empresas/07385111000102/docs/hom/55/2018/502/186067/eventos/110110

 

Consultar Eventos

O XML Proc do Evento Fiscal com Assinatura Digital, que é idêntico ao armazenado na Sefaz e deve ser guardado pelo contribuinte por no mínimo 5 anos.

 

Obter todos os Eventos de um DFe (GET)

Nesse Endpoint, é possível obter o XML Proc de todos os Eventos relacionados à um DFe.

A URL é construída da seguinte forma:

http:// ou https:// + /endereço da API Rest + /api/empresas/{empresa}/docs/{ambiente}/{codModelo}/{ano}/{serie}/{numero}/eventos

Os valores sublinhados devem ser substituídos pelos valores correspondentes abaixo:

  • {empresa} : CNPJ da Empresa
  • {ambiente} : hom ou prod
  • {codModelo} : 55, 57, 58 ou 65 (respectivamente, NFe, CTe, MDFe ou NFCe)
  • {ano} : Ano de Emissão no formado AAAA
  • {serie} : Série do DFe
  • {numero} : Número do DFe
http://rest.oobj-dfe.com.br/api/empresas/07385111000102/docs/hom/55/2018/502/186067/eventos

 

Configurações do MDe

As configurações do MDe podem ser realziadas tanto via API tanto via monitor.

No Monitor Oobj:

Na Api Rest

 

Para realizar testes com a API Rest, e ter mais detalhes sobre a Emissão de Documentos Fiscais, acesse a documentação completa através do link: http://rest.oobj-dfe.com.br/swagger-ui.html#/Documento32Fiscal
3 (2)
Avaliação do Artigo (2 Votos)
Avaliar esse artigo
Anexos
Não há anexos para este artigo.
Artigos Relacionados RSS Feed
Emissão de DFes na API Rest
Visualizado 464 vezes desde 13/03/2018
Consulta Cadastro Centralizado de Contribuinte - Consulta Cadastro API Rest
Visualizado 748 vezes desde 14/01/2021
Criar Aplicativo no Monitor Oobj
Visualizado 245 vezes desde 12/04/2018
Emissão de Eventos Fiscais na API Rest
Visualizado 353 vezes desde 16/03/2018
Configurando Contingência Automática no Monitor da Oobj via API Rest
Visualizado 236 vezes desde 23/08/2021
API REST: Ano contido no documento não é o mesmo do informado no serviço - Como resolver?
Visualizado 296 vezes desde 08/01/2019
Inutilização de Numeração na API Rest
Visualizado 456 vezes desde 16/03/2018
Geração de chave AC (Assinatura do Contribuinte) para SAT na API Rest
Visualizado 1124 vezes desde 26/12/2019
Relatórios na API Rest
Visualizado 718 vezes desde 19/08/2021
Integração API Rest
Visualizado 626 vezes desde 09/03/2018
Materiais