Nesta documentação vamos explicar como consultar e manifestar as notas destinadas ao CNPJ do emissor no Manager SaaS via API.
Para realizar o processo teremos dois caminhos possíveis, onde em um deles, realizaremos todos os passos de 1 a 5 e em outro não realizaremos o passo 4, abaixo detalharemos o funcionamento de cada um dos modelos possíveis.
Modelo 1
Este modelo consiste na realização dos 5 passos dispostos na documentação, utilizando este modelo será necessário realizar o 'passo 4', onde neste momento será baixado o XML Destinatário, este modelo é recomendado para empresas que tem menor recepção de notas proveniente de terceiros, optando por este modelo será possível receber até 20 XML Destinatário por hora.
Modelo 2
Este modelo consiste na realização dos passos 1, 2, 3 e 5 dispostos na documentação, utilizando este modelo dispensaremos o 'passo 4', pois o XML Destinatário completo será retornado nas consultas de último NSU subsequentes, este modelo é recomendado para empresas que tem grande recepção de notas proveniente de terceiros, optando por este modelo será possível receber de 1 a 1000 XML Destinatário por hora.
O Passo 5, onde é baixado o XML completo da NFe fica condicionado ao retorno do mesmo na sincronização de NFes Destinadas, logo, enquanto o ultNSU for diferente do maxNSU é possível que haja XML Destinatário disponíveis para serem baixados.
1. Sincronização de NFes Destinadas
Enviar uma requisição do tipo POST na rota /nfe/envia e passar no parâmetro arquivo o texto DOCUMENTO=DFE para verificar e sincronizar as notas de acordo com o NSU (Numero Sequencial Único), disponibilizadas pela Sefaz. Também é possível sincronizar apenas uma nota, informando o parâmetro CHAVENOTA.
Obs: Esta operação pode demorar alguns minutos, dependendo da quantidade de notas destinadas que estão disponíveis na Sefaz.
Outro ponto importante é que nesse primeiro passo todas as consultas devem ser informado no parâmetro "arquivo" DOCUMENTO=DFE
Exemplo: se deseja consulta uma chave específica informa da seguinte maneira o parâmetro arquivo:
DOCUMENTO=DFE
CHAVENOTA=chave da NFe que deseja consulta.
POST
Homologação
https://managersaashom.tecnospeed.com.br:7071/ManagerAPIWeb/nfe/envia
Produção
https://managersaas.tecnospeed.com.br:8081/ManagerAPIWeb/nfe/envia
Headers
| Nome | Descrição | Exemplo |
| Content-Type | Indica o tipo de arquivo | application/x-www-form-urlencoded |
Body
| Nome | Descrição | Exemplo |
| encode | Parâmetro utilizado para evitar que o retorno traga caracteres inválidos. | true |
| grupo | Identificação do grupo do emitente. | edoc |
| cnpj | CNPJ do emitente. | 29062609000177 |
| arquivo |
Parâmetros que podem ser utilizados para realizar a consulta:
DOCUMENTO=DFE, CHAVENOTA=, TIPONSU=, NSU= IMPORTANTE:
|
DOCUMENTO=DFE
CHAVENOTA=41190975405993000261550020000599571016599574
TIPONSU=1
NSU=10
|
Retorno
Exemplo de retorno:
138,Documento localizado,000000000001283,000000000001283
Definição: cStat, Mensagem de retorno, ultNSU, maxNSU
Obs.: Essa requisição faz com que o SaaS realize a sincronização das notas emitidas direto com o Web Service do ambiente Nacional, portanto, essa operação pode demorar alguns minutos dependendo da quantidade de notas destinadas a serem disponibilizadas pela Sefaz.
A Sefaz disponibiliza para consulta apenas as notas emitidas nos últimos 90 dias.
2. Consultar NFes sincronizadas
Consultar a chave das notas que foram sincronizadas e precisam ser manifestadas (Realiza a consulta diretamente na base de dados do SaaS).
Enviar uma requisição do tipo GET na rota /nfe/consulta e passar sempre o número 2 no parâmetro origem para pegar as notas destinadas ao CNPJ. Os demais parâmetros podem possuir valores variados: grupo, cnpj, campos, filtro, limite, ordem.
GET
Homologação
https://managersaashom.tecnospeed.com.br:7071/ManagerAPIWeb/nfe/consulta
Produção
https://managersaas.tecnospeed.com.br:8081/ManagerAPIWeb/nfe/consulta
Querrystring
| Nome | Descrição | Exemplo |
| encode | Parâmetro utilizado para evitar que o retorno traga caracteres inválidos. | true |
| grupo | Identificação do grupo do emitente. | edoc |
| cnpj | CNPJ do emitente. | 29062609000177 |
| campos |
Informações que se deseja consultar.
Campos disponíveis (Mais comuns):
handle - ID do registro no banco de dados.
chave - Chave da NFe.
situacao - Situação da NFe (Autorizada, Rejeitada).
nnf - Número da NFe.
codnf - Código da NFe.
nrecibo - Número do recibo da NFe.
nomeemitente - nome do emitente da nota.
serie - serie da nota.
Origem - Origem do documento.
nprotenvio - Número do protocolo de envio da NFe.
nprotcanc - Número do protocolo de cancelamento da NFe.
modoentrada - Modo de entrada da NFe (Normal, EPEC, SVCAN).
cnpj - CNPJ do emitente da NFe.
motivo - Resposta da Sefaz sobre o processamento da NFe.
dtautorizacao - Data de autorização da NFe.
dtcadadstro - Data de cadastro da NFe no banco de dados.
dtcancelamento - Data do cancelamento da NFe.
dtemissao - Data de emissão da NFe.
email - Email do destinatário da NFe.
docdestinatario - Documento do destinatário da NFe.
nomedestinatario - Nome do destinatário da NFe.
nlote - Número do lote da NFe.
ambiente - Ambiente de emissão da NFe (1 - Produção; 2 - Homologação).
valortotal - Valor total da NFe.
Obs: Para obter o mesmo formato de retorno do envio, utilizar os campos: codnf, chave, cstat, xmotivo
|
codnf, chave, cstat, motivo
|
| filtro |
Filtro da consulta.
|
dtemissao >= '2018-02-01 00:00:00' |
| limite |
Limite de registros que serão recebidos.
|
50 |
| ordem |
Ordem em que serão recebidos os registros (Order By):
ASC - Ascendente pelo campo informado;
DESC - Descendente pelo campo informado;
|
dtemissao ASC |
| origem | Valores aceitos:
1 - Emitidas à Terceiros;
2 - Recebidas de Terceiros (notas destinadas);
3 - Operação Interna;
4 - Todas.
|
2 |
Retorno
Exemplo de retorno:
23/07/2018 00:51:14,31180703981899000169550010001306604869306001,,AUTORIZADA
23/07/2018 08:16:00,32180729617631000136550030000003591009111137,,AUTORIZADA
23/07/2018 12:14:00,35180762603733000178550000000255411689857453,,AUTORIZADA
3. Enviar Manifestação do Destinatário (MDe)
É necessário realizar a manifestação do destinatário para que a Sefaz disponibilize o download completo do XML.
Você deve enviar uma requisição do tipo POST na rota /nfe/envia e passar os seguintes valores no parâmetro arquivo:
DOCUMENTO=MDE, TIPOEVENTO, CHAVENOTA, DHEVENTO, FUSO e JUSTIFICATIVA
Você pode mandar o TIPOEVENTO=2 no parâmetro arquivo para manifestar com a opção "Conhecimento da Operação", e assim a nota não ficar com um evento de manifestação definitivo.
Depois de analisar o XML você pode enviar a manifestação novamente de forma definitiva com a confirmação ou não dessa operação:
Obs: Conforme a NT 2020.001 v 1.50, é possível passar a Sequência do Evento.
| TipoEvento | Descrição |
| 1 | Confirmação da operação. |
| 2 | Ciência da operação. |
| 3 | Desconhecimento da operação. |
| 4 | Operação não Realizada. |
Saiba mais acessando esta documentação: MDe - Tipos e prazos dos eventos de manifestação do destinatário.
POST
Homologação
https://managersaashom.tecnospeed.com.br:7071/ManagerAPIWeb/nfe/envia
Produção
https://managersaas.tecnospeed.com.br:8081/ManagerAPIWeb/nfe/envia
Headers
| Nome | Descrição | Exemplo |
| Content-Type | Indica o tipo de arquivo | application/x-www-form-urlencoded |
Body
| Nome | Descrição | Exemplo |
| encode | Parâmetro utilizado para evitar que o retorno traga caracteres inválidos. | true |
| grupo | Identificação do grupo do emitente. | edoc |
| cnpj | CNPJ do emitente. | 29062609000177 |
| arquivo |
Parâmetros utilizados para realizar a manifestação:
DOCUMENTO=MDE, TIPOEVENTO, CHAVENOTA, DHEVENTO, FUSO,
SEQEVENTO, JUSTIFICATIVA
|
DOCUMENTO=MDE
TIPOEVENTO=2
CHAVENOTA=41180229062609000177550200007000651000000104
DHEVENTO=2018-02-20T18:20:00
FUSO=-03:00
SEQEVENTO=1
|
Os campos de MDE seguem abaixo:
| Campo | Conteúdo | Obrigatório |
| DOCUMENTO | MDE | Sim |
| TIPOEVENTO | 1 ou 2 ou 3 ou 4 | Sim |
| CHAVENOTA | 41180229062609000177550200007000651000000104 | Sim |
| DHEVENTO | 2022-07-29T08:00:00 | Sim |
| Fuso | -03:00 | Sim |
| SEQEVENTO | 1 ou 2 | Sim |
| JUSTIFICATIVA | Tenho desconhecimento desta operação | Apenas para TIPOEVENTO=4 |
| CamposRetorno | Informações da NF-e | Opcional |
| CamposRetornoEvento | Informações do Evento da NF-e | Opcional |
Observação: A Justificativa é obrigatória somente se o Tipo Evento for igual à 4.
Ex: JUSTIFICATIVA=Tenho desconhecimento desta operação.
Retorno
Exemplo de retorno:
AUTORIZADO,29180903295812000108550000000000021000028908,135,Evento registrado e vinculado a NF-e
4. Download do XML da Sefaz
Esse passo é importante pois ele faz o download do XML completo da Sefaz, esse ponto é importante ser feito após a Manifestação Destinatário.
POST
Homologação
https://managersaashom.tecnospeed.com.br:7071/ManagerAPIWeb/nfe/envia
Produção
https://managersaas.tecnospeed.com.br:8081/ManagerAPIWeb/nfe/envia
Headers
| Nome | Descrição | Exemplo |
| Content-Type | Indica o tipo de arquivo | application/x-www-form-urlencoded |
Body
| Nome | Descrição | Exemplo |
| encode | Parâmetro utilizado para evitar que o retorno traga caracteres inválidos. | true |
| grupo | Identificação do grupo do emitente. | edoc |
| cnpj | CNPJ do emitente. | 29062609000177 |
| arquivo |
Parâmetros utilizados para realizar a manifestação:
DOCUMENTO=DNF, CHAVENOTA |
DOCUMENTO=DNF
CHAVENOTA=41190975405993000261550020000599571016599574
ImportaDownload=1
|
Retorno
Exemplo de retorno:
29180903295812000108550000000000021000028908,Autorizado o uso da NF-e
29180903295812000108550000000000021000028908,Importação disparada na pasta importa
5. Download do XML completo da NFe
Realiza o download do XML completo de uma NFe destinada ao CNPJ caso já tenha ocorrido a manifestação e sincronização do evento, por parte da Sefaz.
Para isso, envie uma requisição GET na rota nfe/xml com os parâmetros grupo, cnpj e chavenota.
Caso o XML venha de forma resumida, significa que o evento de manifestação ainda não foi vinculado pela Sefaz, dessa forma, caso a manifestação realmente já tenha sido realizada é necessário aguardar a sincronização do WebService ou se não, enviar a manifestação novamente e então efetuar uma nova sincronização das NFes destinadas (passo 1) para verificar se o XML completo já ficou disponível.
GET
Homologação
https://managersaashom.tecnospeed.com.br:7071/ManagerAPIWeb/nfe/xml
Produção
https://managersaas.tecnospeed.com.br:8081/ManagerAPIWeb/nfe/xml
Querrystring
| Nome | Descrição |
| encode | Parâmetro utilizado para evitar que o retorno traga caracteres inválidos. |
| grupo | Identificação do grupo do emitente. |
| cnpj | CNPJ do emitente. |
| chavenota |
Chave da nota que se deseja obter o XML.
|
Retorno
Exemplo de retorno:
<infNFe Id="NFe41180529062609000177550010020000001020000009" versao="4.00">
<ide>
<cUF>41</cUF>
<cNF>02000000</cNF>
<natOp>VENDA DE MERCADORIA ADQ. DE TERCEIRO - PF E PJ NAO CONTRIBUI</natOp>
<mod>55</mod>
<serie>1</serie>
<nNF>2000000</nNF>
<dhEmi>2018-05-28T17:00:00-03:00</dhEmi>
<dhSaiEnt>2018-05-28T17:00:00-03:00</dhSaiEnt>
<tpNF>1</tpNF>
<idDest>1</idDest>
<cMunFG>4115200</cMunFG>
<tpImp>1</tpImp>
<tpEmis>1</tpEmis>
<cDV>9</cDV>
<tpAmb>2</tpAmb>
<finNFe>1</finNFe>
<indFinal>1</indFinal>
<indPres>1</indPres>
<procEmi>0</procEmi>
<verProc>TecnoERP - 1.2.3</verProc>
</ide>
{.......}
</NFe>
https://www.getpostman.com/collections/1aa15f35866ad64169ed
Comentários
0 comentário
Por favor, entre para comentar.