Consultar documentos fiscais através da API.

Pré-requisito

Para prosseguir com a consulta é necessária uma Nota Fiscal autorizada e o Monitor de Serviços referente ao módulo no qual deseja realizar a consulta, instalado e com ambiente configurado.
Se possuir dúvidas referente ao uso do monitor, consulte o seguinte tópico: Como instalar o serviço do TaxPlus NF-e. 
Sobre a nova configuração do Monitor de Serviços do TaxPlus NFe, segue o vídeo: https://www.sendspace.com/pro/dl/k00ciw

Para realizar a consulta na API, será utilizado o Postman.

	Importante
	Importante lembrar que utilizamos o Postman apenas como exemplo.  No atendimento não prestamos suporte sobre a API escolhida, para a utilização do Postman, por exemplo, o mesmo requer conhecimento mínimo para o seu preenchimento e entendimento de sua funcionalidade.  Sendo de total responsabilidade do leitor da documentação e/ou executor a aplicação das consultas, a documentação apenas traz algumas sugestões.

Processo
1. No monitor de serviços, realize a configuração do ambiente conforme o seu cenário On Premise (Não CCC) ou CCC. Para identificar o ambiente acesse Como identificar se o ambiente SAP Busines One é CCC?
Em caso de dúvidas no ambiente, confira nosso artigo para apoio:
• TaxPlus | Monitor de Serviços | Monitor de Serviço On Premise
• TaxPlus | Monitor de Serviços | Multiplos Monitores - SAP Business One CCC

	Atenção
	Ao atualizar a versão dos Addons e Monitor de Serviços, é necessário desinstalar o Monitor de Serviços da versão anterior, pois, se houver dois monitores, por exemplo, NFe de versões diferentes instalados ao realizar a consulta em API, a mesma irá retornar mensagem de erro relacionada a conflito. Portanto, deve-se desinstalar a versão antiga do monitor permanecendo somente o Monitor da nova versão instalada.

Para realizar a consulta em Ambiente On Premise (Não CCC):

No exemplo será utilizado o Monitor de Serviços do módulo TaxPlus NF-e. 

Após realizar as configurações necessárias, habilite o parâmetro "SAP Buniness One CCC" e clique no botão "Banco do SAP...", informe "Ambiente" e "Banco de Dados" feito isso clique em "Ok". Atenção: Com as informações de "Ambiente" e "Banco de Dados" preenchidas desabilite o parâmetro "SAP Buniness One CCC" (essa configuração é necessária apenas para API identificar qual o Banco de Dados que será utilizado para as operações).



Para realizar a consulta em Ambiente CCC, não há alteração para a configuração e o parâmetro "SAP Buniness One CCC" permanece habilitado:


2. Em Monitor de Serviços acesse a aba "Serviço API NF-e", clique no botão "Token" para gerar o "Token API" que será usado para autenticação na hora da consulta, em seguida em "Salvar" e clique em "Iniciar" para iniciar o serviço (para gerar novo Token clique no botão "Parar" e realize o processo descrito acima novamente). 

	Observação
	Em Monitor de Serviços na aba "Serviço API NF-e" a "Porta API" por padrão é 5000, mas pode ser alterada. O Monitor de Serviço TaxPlus NFe não pode compartilhar da mesma porta que outro monitor, por exemplo, o TaxPlus DFe para este verifique com a infra de sua empresa para disponibilizar outra porta que não seja usada por outra aplicação para colocar no em um dos monitores, pois se os dois tiverem a mesma porta ocorrerá a mensagem de conflito.

3. A estrutura de uma URL de consulta deve seguir o formato padrão, incluindo os elementos: protocolo, domínio (ou endereço de IP), porta (opcional), o caminho e os parâmetros de consulta. Sua estrutura pode variar dependendo da API específica que se está acessando. A estrutura utilizada como exemplo para consultarmos a nota fiscal inclui: protocolo, porta (opcional), o caminho, versão, ambiente e os parâmetros de consulta.

Por exemplo:

URL: http://localhost:5000/api/v3/inv/invent/docs/consultar/pdf

	Importante
	Podem ser utilizadas as versões v1, v2 e v3.  Caso a versão dos Addons e Monitor de Serviços seja antiga será provavelmente utilizada a versão v1 ou v2 para API, mas se foi realizada a atualização dos Addons e Monitor de Serviços para versão recente deverá utilizar a versão v3 para API.  Exemplo em versão recente dos Addons e Monitor de Serviços, ao usar a versão v2 ocasionou o seguinte erro: Após feita correção para versão v3 a consulta foi realizada:

A consulta acima retorna o PDF de uma nota fiscal emitida pelo TaxPlus NF-e.

	Nota
	Endpoint do DANFe simplificado. Endpoint: http://localhost:5000/api/v3/inv/invent/docs/consultar/obterpdfsimplificado Consulta por: batchid + modelo ou chave de acesso.

	Nota
	Para consultar o PDF utilizando a Chave de Acesso da nota, utilize o Endpoint:  http://localhost:5000/api/v3/inv/invent/docs/consultar/obterpdf

4. Segue um exemplo de consulta realizada:
Em Postman insira a consulta e na aba "Authorization", habilite em menu suspenso "API Key" preencha o nome para o campo "Key" e para o campo "Value" informe o Token gerado em Monitor de Serviços:


5. Para realizar a consulta será necessário passar alguns parâmetros, sendo assim, clique em aba "Params". Para a consulta será utilizado como exemplo o "batchId" (número do lote) e "modelo" após os campos preenchidos clique em "Send":

	Nota
	Seguem os Parâmetros que podem ser utilizados: Parâmetro Exemplo Key: entidadeId Value: 615 Key: modelo Value: 55 Key: batchId Value: 12345678 Key: numeroDocumento Value: 00 Key: tipoDocumento Value: 13 Key: datainicial Value: "2024-02-27" Key: datafinal Value: "2024-04-01" Key: cardcode Value: CXXXX Key: status Value: 4 Key: ambiente Value: “SBO_XYZZ” Key: chave Value: MQR16XX Obs.: os parâmetros foram listados apenas para demonstração, o preenchimento de todos os parâmetros não é obrigatório.

Consulta realizada:



6. Após clicar em "Send" o Status Code será informado, tanto em casos de sucesso bem como de falhas, conforme alguns exemplos a seguir:

"200 - OK": Indica que a requisição foi bem sucedida;
"400 - Missing information": Indica que a requisição falhou por falta de informação;
"401 - Unauthorized": Indica que a requisição falhou por falta de autorização ou token inválido (necessário retornar ao monitor de serviços e Atualizar Token);
"404 - Not Found": Indica que o recurso requisitado não foi encontrado;
"504 - Gateway Time-out": Indica que o servidor, enquanto atuando como gateway ou proxy, não conseguiu responder em tempo;

	Dica
	Para a API da Nfe, todos os parâmetros e informações descritas anteriormente serão as mesmas conforme seu ambiente, sendo a única diferença a versão utilizada (v3) colocada na URL de cada processo, segue algumas sugestões de URLs para API da Nfe: Consultar notas - URL: http://localhost:5000/api/v3/inv/invent/docs/consultar Retransmitir nota API - URL: http://localhost:5000/api/v3/inv/invent/docs/retransmitir Emitir pedido de Cancelamento - URL: http://localhost:5000/api/v3/inv/invent/docs/cancelar Consultar PDF - URL: http://localhost:5000/api/v3/inv/invent/docs/consultar/pdf Consultar PDF utilizando a chave de acesso - URL: http://localhost:5000/api/v3/inv/invent/docs/consultar/obterpdf Consultar XML - URL: http://localhost:5000/api/v3/inv/invent/docs/consultar/xml Entidade emissoras - URL: http://localhost:5000/api/v3/inv/invent/docs/consultar/entidadesemissoras

Inutilização API 

Método Post

URL: http://localhost:5000/api/v2/inv/nfe/inutilizacao/nfe

Parâmetro

Key: ArquivoJason                       

Value: [{“entidadeId”:11,”numeroDocumento”:11,”numeroLoteDocumento”:111, "motivo": "teste de   inutilizacao","tipoDocumento":13 }]

Arquivo Jason:

[{"entidadeId": 42,"numeroDocumento": 4334,"numeroLoteDocumento":615134334, "motivo": "teste de   inutilizacao","tipoDocumento":13}]

	Observação
	Caso número do Lote não informado, os outros campos passam a ser obrigatórios.

Exemplo visual:

Referências
Sem referências.