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

Emissão de DFes na API Rest

Nº do Artigo: 744 | Avaliação: 4,5/5 de 2 votos | Última atualização: 06/12/2021 17:00:45

A Emissão de DF-e (Documento Fiscal Eletrônico) através da API Rest será permitido para o usuário que já possuir o x-auth-token. No artigo Autenticação na API Rest damos mais detalhes sobre o x-auth-token. Existem alguns Endpoints para o serviço de Emissão de Documentos Fiscais e para cada um, há uma URL específica.

 

Autorização / Envio / Emissão de DFe (POST)

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

A URL é construída da seguinte forma: 

http:// ou https:// + /endereço da API Rest + /api/empresas/{empresa}/docs/{ambiente}/{codModelo}?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, 59, 65 ou 99 (respectivamente, NFe, CTe, MDFe, CFe (SAT), NFCe ou NFSe)
  • {layoutDFe} : oobj, sefaz, txt abrasf, json ou txtsp.

 

É possível enviar a requisição de emissão de documento sem o layout. Mas, caso não informado, será assumido o valor oobj.
Exemplo com o parâmetro opcional layoutDFe preenchido:

 

http://rest.oobj-dfe.com.br/api/empresas/07385111000102/docs/prod/55?layout=oobj

 

Exemplo sem o parâmetro opcional layoutDFe preenchido: 

 

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

 

Exemplo de Retorno após envio da requisição de emissão:

 

{
  "mensagem": "/api/empresas/07385111000102/docs/hom/55/2021/503/000690290",
  "tempoMedioMs": 1000,
  "timestamp": 1629117845034
}

 

Obter Retorno de um Documento Fiscal

Após a emissão de um DFe, o usuário deve obter o retorno de processamento do mesmo. Esse retorno poderá ser de Autorização, Rejeição ou Arquivo Inválido. Para isso há dois Endpoints, um que permite obter o o retorno através da série e número e outro por chave de acesso:

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

Nesse Endpoint, o retorno 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}

 

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

  • {empresa} : CNPJ da Empresa
  • {ambiente} : hom ou prod
  • {codModelo} : 55, 57, 58, 59, 65 ou 99 (respectivamente, NFe, CTe, MDFe, CFe (SAT), NFCe ou NFSe)
  • {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/prod/55/2018/502/186067

 

2. Obter o retorno de um DFe através da chave de acesso (GET)

Nesse Endpoint, o retorno 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}

 

  • {empresa} : CNPJ da Empresa
  • {ambiente} : hom ou prod
  • {codModelo} : 55, 57, 58, 59, 65 ou 99 (respectivamente, NFe, CTe, MDFe, CFe (SAT), NFCe ou NFSe)
  • {chaveAcesso} : Chave de Acesso do DFe

 

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

 

No seu Sistema, ao integrar com a API Rest, o desenvolvedor poderá escolher qual componente para obter o retorno irá implementar ou se usará os dois.
Em ambas as requisições para obter o status do documento emitido, o retorno será como o exemplo abaixo:

 

{
  "idLote": 690290,
  "timestamp": 1629115147000,
  "conteudo": "Conteúdo do XML",
  "status": "Rejeitada",
  "chaveAcesso": "43210807385111000102555030006902901414699288",
  "cStat": 866,
  "xMotivo": "Rejeicao: Ausencia de troco quando o valor dos pagamentos informados for maior que o total da nota",
  "codigoUF": 43,
  "numeroProtocolo": null,
  "dataRecebimento": 1629115147000,
  "permiteImpressao": false,
  "tipoEmissao": {
    "codigo": 1,
    "descricao": "Normal"
  }
}

 

Download de PDF (Documento Auxiliar)

Se o DFe for autorizado ou emitido em Contingência, após realizar a Emissão poderá obter o Documento Auxiliar do DFe em formado PDF. E assim como para Retornar 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, 59, 65 ou 99 (respectivamente, NFe, CTe, MDFe, CFe (SAT), NFCe ou NFSe)
  • {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/prod/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, 59, 65 ou 99 (respectivamente, NFe, CTe, MDFe, CFe (SAT), NFCe ou NFSe)
  • {chaveAcesso} : Chave de Acesso do DFe

 

http://rest.oobj-dfe.com.br/api/empresas/07385111000102/docs/prod/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.

 

Abaixo, exemplo de como é gerado o PDF através do postman utilizando o ano, numero e série do documento:

 

Obter XML Proc (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 de sua consulta, 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, 59, 65 ou 99 (respectivamente, NFe, CTe, MDFe, CFe (SAT), NFCe ou NFSe)
  • {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/listar/2021-08-01/2021-08-31/emitente?comXml=true

 

Exemplo sem os parâmetros opcionais preenchidos:

http://rest.oobj-dfe.com.br/api/empresas/07385111000102/docs/hom/55/2021-08-01/2021-08-31/emitente

 

Abaixo exemplo de retorno da requisição sem as informações do XML. Repare que no fim é informado a quantidade de documentos listados na consulta, o número de páginas e a quantidade por páginas:

 

{
  "registros": [
    {
      "idLote": 690080,
      "timestamp": 1628768264000,
      "conteudo": null,
      "status": "Autorizada",
      "chaveAcesso": "43210807385111000102555030006900801942526750",
      "cStat": 100,
      "xMotivo": "Autorizado o uso da NF-e",
      "codigoUF": 43,
      "numeroProtocolo": "143210000564607",
      "dataRecebimento": 1628768264000,
      "permiteImpressao": true,
      "tipoEmissao": {
        "codigo": 1,
        "descricao": "Normal"
      }
    },
    {
      "idLote": 690290,
      "timestamp": 1629115147000,
      "conteudo": null,
      "status": "Autorizada",
      "chaveAcesso": "43210807385111000102555030006902901414699288",
      "cStat": 100,
      "xMotivo": "Autorizado o uso da NF-e",
      "codigoUF": 43,
      "numeroProtocolo": "143210000570609",
      "dataRecebimento": 1629115147000,
      "permiteImpressao": true,
      "tipoEmissao": {
        "codigo": 1,
        "descricao": "Normal"
      }
    },
    {
      "idLote": 690373,
      "timestamp": 1629203958000,
      "conteudo": null,
      "status": "Autorizada",
      "chaveAcesso": "43210807385111000102555030006903731678924922",
      "cStat": 100,
      "xMotivo": "Autorizado o uso da NF-e",
      "codigoUF": 43,
      "numeroProtocolo": "143210000572778",
      "dataRecebimento": 1629203958000,
      "permiteImpressao": true,
      "tipoEmissao": {
        "codigo": 1,
        "descricao": "Normal"
      }
    }
  ],
  "pagina": 1,
  "numeroTotal": 3,
  "numeroElementos": 3,
  "maximoPorPagina": 20
}

  

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-teste.oobj.com.br/swagger-ui.html#/
4,5 (2)
Avaliação do Artigo (2 Votos)
Avaliar esse artigo
Anexos
Não há anexos para este artigo.
Artigos Relacionados RSS Feed
Recebimento de Documentos Fiscais via API Rest
Visualizado 521 vezes desde 16/03/2018
Gerenciamento de Empresas na API Rest
Visualizado 334 vezes desde 16/03/2018
Autenticação na API Rest
Visualizado 1100 vezes desde 09/03/2018
Integração API Rest
Visualizado 523 vezes desde 09/03/2018
Manutenção de CSC (Código de Segurança do Contribuinte) na API Rest
Visualizado 246 vezes desde 16/03/2018
Configurar MDe na Api Rest
Visualizado 309 vezes desde 27/09/2018
API REST: Ano contido no documento não é o mesmo do informado no serviço - Como resolver?
Visualizado 252 vezes desde 08/01/2019
Relatórios na API Rest
Visualizado 593 vezes desde 19/08/2021
Consultar MDF-e não encerrado via API Rest
Visualizado 245 vezes desde 23/08/2021
Geração de DADFe sem valor fiscal na API Rest
Visualizado 323 vezes desde 25/05/2020
Materiais