Neste post, vamos explicar quais são os primeiros passos para começar a utilizar essa API e posteriormente o fluxo principal para realizar uma consulta das notas.

Neste artigo você encontra o como:

1. Criar uma conta TecnoSpeed (TecnoAccount)
2. Importar a coleção de requisições
3. Cadastrar um destinatário para a consulta
4. Adicionar consulta de NFe Destinadas
5. Consultando o protocolo da consulta
6. Consultar as notas do protocolo
7. Baixar o XML de uma nota
8. Listar os eventos de uma nota
9. Baixar o evento de uma nota

1º Passo - Criar uma conta TecnoSpeed (TecnoAccount) 

Primeiramente, se você não possuí um Token de acesso é necessário realizar um cadastro no Tecno Account da Tecnospeed TI no link: https://conta.tecnospeed.com.br/

Clique em Criar uma conta e preencha os dados do formulário

Com a conta criada faça o login e pegue o seu Token

Esse token será utilizado no parâmetro token_sh de todas as requisições, a baixo veremos como importar a collection para utilizar no postman ou utilizar a documentação no Swagger.

2º Passo - Importar a coleção de requisições

Após abrir o aplicativo, para importar uma coleção de requisições, basta clicar no botão "Import", no canto esquerdo da barra superior, selecionar a opção "Import From Link", colar o endereço abaixo e clicar novamente no botão "Import", ou importando o arquivo com as requisições.

Endereço da coleção de requisições:

https://www.getpostman.com/collections/4b9cb2f384524139655d

Também é possível utilizar uma documentação mais técnica gerada pelo Swagger através do link  http://docs.nfe.tecnospeed.com.br/

Este é um passo essencial, pois é aqui onde devem ser cadastrados algumas informações necessárias para fazer uma consulta de Notas Destinadas junto a SEFAZ, além claro, do certificado digital do tipo A1, no formato ".pfx".

Rota:

POST https://api.nfe.tecnospeed.com.br/destinadas/v1/destinatarios

Parâmetros

Headers

Body

Retorno

{
 "uf": "41",
 "cpfCnpj": "0000000000000",
 "certificate": {
  "email": "email@empresa.com",
  "name": "CN=EMPRESA SA:0000000000000, OU=Certificado PJ A1, O=ICP-Brasil, C=BR, S=, L=, E=, SE=00 00 00 00 00 00 00 00,
  "handle": 00000,
  "expiresIn": "2021-04-16T13:34:00.000Z"
 },
 "cpfCnpjSoftwareHouse": "0000000000000",
 "id": "000000000000000000000000"
}

Com o cadastro do destinatário das notas juntamente com o certificado digital realizado, já podemos realizar a primeira consulta de notas destinadas, denominamos essa rota de "Adicionar consulta de NFe Destinadas"

4º Passo - Adicionar consulta de NFe Destinadas

Neste passo abordamos como deve ser feita a consulta das notas destinadas. Basicamente a busca se dá com a criação de um protocolo de consulta, informando o período da busca com uma data inicial e outra final, onde o intervalo máximo de dias entre a data inicial e final é de 31 dias, podendo ser consultadas notas de até 6 meses retroativos.

Também é possível consultar NFe's pela chave, clique aqui e veja como fazer.

Rota:

POST https://api.nfe.tecnospeed.com.br/destinadas/v1/protocolos

Parâmetros

Headers

Body

{
  "periodo": {
    "dataInicial": "2020-09-01",
    "dataFinal": "2020-09-30"
  }
}

Atenção: lembre-se que é necessário que o destinatário já esteja cadastrado juntamente com o certificado digital.

Retorno

{
  "id": "000000000000000000000000",
  "situacao": "PROCESSANDO",
  "cpfCnpjSoftwareHouse": "0000000000000",
  "cpfCnpjDestinatario": "0000000000000",
  "periodo": {
    "dataInicial": "2020-09-01T00:00:00.000Z",
    "dataFinal": "2020-09-30T00:00:00.000Z"
  },
  "criadoEm": "2020-09-28T00:27:33.376Z",
  "atualizadoEm": "2020-09-28T00:27:33.376Z"
}

 A partir deste momento, nossa API irá buscar todas as notas disponíveis no ambienta nacional da SEFAZ, fazer a ciência da nota e disponibiliza-la para você fazer o download de seu XML. Porém só é possível consultar as notas quando a situação do protocolo estiver em "CONCLUIDO". Confira o próximo passo como consultar a situação do protocolo.

5º Passo - Consultando o protocolo da consulta

Este passo é um passo para controle em seu software para acompanhar o andamento do protocolo, e qual o momento correto para consultar as notas localizadas por nossa API nos webservices da SEFAZ.

Existem apenas 3 situações possíveis para um protocolo, são elas:

• PROCESSANDO: Ainda não terminamos de processar sua solicitação, consulte novamente mais tarde.
• CONCLUIDO: Finalizamos as consultas junto ao webservice da SEFAZ, podendo ou não retornar notas. Quando o protocolo estiver nessa situação, é o momento ideal para consultar as notas localizadas.
• ERRO: Ocorreu um erro ao tentar realizar a consulta no webservice da SEFAZ.
  
  

Rota:

GET https://api.nfe.tecnospeed.com.br/destinadas/v1/protocolos/<ID do protocolo retornado no passo anterior>

 Exemplo:

GET https://api.nfe.tecnospeed.com.br/destinadas/v1/protocolos/000000000000000000000000

Parâmetros

Headers

Retorno

{
  "id": "000000000000000000000000",
  "situacao": "PROCESSANDO",
  "cpfCnpjSoftwareHouse": "0000000000000",
  "cpfCnpjDestinatario": "0000000000000",
  "periodo": {
    "dataInicial": "2020-05-01T00:00:00.000Z",
    "dataFinal": "2020-05-21T00:00:00.000Z"
  },
  "criadoEm": "2020-09-24T11:10:15.846Z",
  "atualizadoEm": "2020-09-24T11:10:15.846Z"
}

Um protocolo com a situação "CONCLUIDO" a API terminou de consultar as notas destinadas disponíveis na SEFAZ e estão disponíveis para serem consultadas através da rota Consultar todas as notas pelo protocolo.

6º Passo - Listar as notas do protocolo

Através da rota abaixo é possível retornar todas as notas vinculadas ao protocolo.

Atenção: O retorno será paginado a cada 100 registros, devendo utilizar o parâmetro de consulta (query string) "pagina", para avançar.

Exemplo:
http://api.nfse.tecnospeed.com.br/v1/tomadas/741fd8ee-982d-4041-94ce-5d6eaad2c8dc?pagina=proximapagina

ou

http://api.nfse.tecnospeed.com.br/v1/tomadas/741fd8ee-982d-4041-94ce-5d6eaad2c8dc?pagina=2

Rota:

GET https://api.nfe.tecnospeed.com.br/destinadas/v1/protocolos/<ID do protocolo criado>/notas

Exemplo:

GET https://api.nfe.tecnospeed.com.br/destinadas/v1/protocolos/000000000000000000000000/notas

Parâmetros

Headers

Retorno

{
  "protocolo": "000000000000000000000000",
  "paginacao": {
      "numeroDeNotas": 7,
      "mumeroDePaginas": 1,
      "pagina": 1
  },
  "notas": [
    {
      "id": "000000000000000000000000",
      "nsu": "00000000000000",
      "tipo": "nfeProc",
      "chave": "00000000000000000000000000000000000000000000",
      "numero": "1",
      "serie": "1",
      "emitente": "0000000000000",
      "valor": 79.00,
      "dataEmissao": "2020-09-15T00:49:11.000Z",
      "criadoEm": "2020-09-21T11:21:26.602Z",
      "atualizadoEm": "2020-09-24T10:37:58.631Z",
      "xmlUrl": "https://api.nfe.tecnospeed.com.br/destinadas/v1/notas/00000000000000000000000000000000000000000000"
    }
  ]
}

7º Passo - Baixar o XML de uma nota

Com o protocolo concluído, você teve acesso as informações básicas das notas que foram emitidas contra o destinatário, dentre essas informações foi a chave da nota que deverá ser utilizada para o download do XML de nossa API, através da rota abaixo.

Rota:

GET https://api.nfe.tecnospeed.com.br/destinadas/v1/notas/<chave da nota>

Exemplo:

https://api.nfe.tecnospeed.com.br/destinadas/v1/notas/00000000000000000000000000000000000000000000

Atenção: Esta rota não segue o padrão de retorno em JSON, mas sim em XML, disponibilizando na íntegra o XML da Nota Fiscal emitida contra o CNPJ/CPF do destinatário em questão.

8º Passo - Listar os eventos de uma nota

Assim como a API busca na SEFAZ as notas fiscais de um determinado destinatário, é possível visualizar os eventos de uma Nota Fiscal Eletrônica específica e fazer o download dos mesmos através da rota abaixo.

Rota:

GET https://api.nfe.tecnospeed.com.br/destinadas/v1/notas/<chave da nota>/eventos

Exemplo:

https://api.nfe.tecnospeed.com.br/destinadas/v1/notas/11111111111111111111111111111111111111111111/eventos

Retorno

[
  {
    "protocolo": "000000000000000000000000",
    "nsu": "000000000000001",
    "tipo": "resEvento",
    "descricao": "CT-e Autorizado para NF-e",
    "eventoId": "ID6106001111111111111111111111111111111111111111111101",
    "chaveNFe": "11111111111111111111111111111111111111111111",
    "emitente": "11111111111111",
    "dataEmissao": "2020-08-14T01:45:10.000Z",
    "criadoEm": "2020-10-24T22:40:43.968Z",
    "atualizadoEm": "2020-10-24T22:40:43.968Z",
    "download": false,
    "xml": "https://api.nfe.tecnospeed.com.br/destinadas/v1/notas/11111111111111111111111111111111111111111111/eventos/ID6106001111111111111111111111111111111111111111111101"
  }
]

9º Passo - Baixar o XML de um evento da NFe

Com o concluído, você teve acesso as informações básicas das notas que foram emitidas contra o destinatário, dentre essas informações foi a chave da nota que deverá ser utilizada para o download do XML de nossa API, através da rota abaixo.

Rota:

GET https://api.nfe.tecnospeed.com.br/destinadas/v1/notas/<chave da nota>/eventos/<ID do Evento na SEFAZ>

Exemplo:

https://api.nfe.tecnospeed.com.br/destinadas/v1/notas/11111111111111111111111111111111111111111111/eventos/ID6106001111111111111111111111111111111111111111111101

Atenção: Esta rota não segue o padrão de retorno em JSON, mas sim em XML, disponibilizando na íntegra o XML do evento.

Se preferir, você pode importar nossas collections, que estão disponíveis abaixo, no seu client REST preferido.