Dúvida 
Como consultar e obter dados de Documentos Fiscais do NFS-e através da API?

Visão Geral 
API  é a sigla para "Application Programming Interface" que significa "Interface de Programação de Aplicativos". Trata-se de um conjunto de regras e protocolos que permite que diferentes softwares se comuniquem entre si. O app Postman será utilizado como ferramenta de suporte à documentação das requisições feitas pela API.

Pré - Requisito
Para dar início é necessário documento de marketing NFS-e autorizada, que se tenha instalado o Monitor de Serviços, e também o app Postman. Para mais informações relacionadas a instalação do Monitor de Serviços acesse Como instalarServiço.

Procedimento

1. Com a NFS-e devidamente autorizada e monitor de serviços instalado, acesse TaxPlux NFS-e → Acompanhamento de NFS-e (Follow-Up)  e localize selecionando o documento autorizado:


2. Com Monitor de Serviços NFS-e aberto clique na Aba "Consulta Dados da NFS-e" para executarmos o serviço de maneira mais funcional:

	Observação
	Para iniciar a configuração é necessário clicar no botão "Parar" para podermos prosseguir:

2. Por padrão tem-se a definição da porta em "Porta API" onde o serviço será executado, neste caso sendo de 5000, mas, podendo ser alterado se necessário. 
No campo "Token Api" (onde é gerado o Token de autenticação da API) podemos gerar o mesmo clicando no botão "Token", sempre que for realizada atualização é necessário gerar um novo Token para ser utilizado na requisição, após atualização clicar no botão "Salvar":


3. Configure o ambiente (caso já exista uma configuração, certifique-se de que as informações lançadas estão corretas).
Para SAP Business One NÃO "CCC", é necessário habilitar na primeira configuração o parâmetro "SAP Business One CCC" para definir o banco de dados que a API irá utilizar. Após a configuração, deverá desmarcar o parâmetro "SAP Business One CCC". O importante é definir o banco!

Clique na aba "Monitor de Serviços" e selecione checkbox "SAP Business One CCC" e clique no botão "Banco do SAP...", surgirá a tela "Bancos de Dados do SAP":


4. Na tela "Bancos de Dados do SAP", no campo "Ambiente" nomeie conforme desejar, e o campo "Banco de Dados" informe nome do banco de dados do qual será realizada consulta e clique em "Ok":

	Nota
	O preenchimento do campo "Ambiente"deve ser realizado sem o uso de caracteres especiais.

5. Concluído o preenchimento clique em "Testar Conexão e Salvar Alterações", em seguida a mensagem "O Teste de Conexão foi realizado com sucesso e os dados foram salvos!" clique em "Ok":


6. Retorne na aba "Consultas Dados da NFS-e" e clique no botão "Iniciar" e clique em "Sim", para Mensagem do Sistema:


7. Ainda na aba "Consultas Dados da NFS-e" após iniciada, selecione e copie Token:


Consulta 

Para enviar as requisições de API será utilizado Postman.

1. 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.

URL: http://localhost:5000/api/v1/Homologacao/nfse/consultar/notafiscal.
Esta consulta irá trazer os dados da nota: número, série, chave de acesso, XML e o PDF da nota.
 

• "localhost:5000": porta 5000;

• "Homologacao": é o ambiente configurado anteriormente;

2. No Postman para exemplificar foi utilizado o método "GET", opção "Body" selecione tipo "raw" via "JSON":


3. Informe o objeto JSON no corpo da requisição passando o nome das suas propriedades e seus valores correspondentes para que a consulta seja realizada. Preencha "XX" com as informações correspondentes:

{

    "entidadeId": "XX",

    "numeroDocumento": "XXXX",

    "tipoDocumento": "XX",

    "nfse": true

}

4. Selecione aba "Authorization" para fornecer as informações de autenticação, escolha "API Key" no menu suspenso para preencher os campos:

• "Key" (Chave): insira o nome do cabeçalho do qual deseja incluir a chave da API. Essa informação pode variar conforme a API específica que você está acessando, no exemplo foi utilizado "Authorization";
• "Value" (Valor): insira o valor da chave da API, recebida em "Token Api" em monitor de serviço (selecione/ copie Token e cole no campo mencionado);
• "Add to" (Adicionar à): caso não esteja selecionado "Header" (Cabeçalho) no menu suspenso, selecione o mesmo para que as informações sejam adicionadas ao cabeçalho informado; 

	Importante
	Certifique-se de que a solicitação esteja configurada corretamente com URL e outros parâmetros necessários.

5. Feito o preenchimento das informações clique em "Send", para enviar a solicitação, a chave da API será incluída nos cabeçalhos, autenticando a solicitação com o servidor da API, retornando a requisição com todos os dados da nota conforme solicitado:


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": Resposta de status de sucesso que indica que a requisição foi bem sucedida;
• "400 - Missing information": Resposta de status de falha que indica que a requisição falhou por falta de informação;
• "401 - Unauthorized": Resposta de status de falha que 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);
• "504 - Gateway Time-out": Resposta de status de falha, indica que o servidor, enquanto atuando como gateway ou proxy, não conseguiu responder em tempo;

Exemplos:


Falha 401:


7. Para realizar cancelamentos pela API:

URL: http://localhost:5000/api/v2/inv/invent/docs/cancelar

Dessa forma, informando o modelo (99) e o lote da NFSe é possível fazer o cancelamento do documento pela API.

   

	Dica
	Na seção "Anexos" há um arquivo contendo alguns exemplos para consulta.

Referências
Sem referências.