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:
- Criar uma conta TecnoSpeed (TecnoAccount)
- Importar a coleção de requisições
- Cadastrar um destinatário para a consulta
- Adicionar consulta de NFe Destinadas
- Consultando o protocolo da consulta
- Consultar as notas do protocolo
- Baixar o XML de uma nota
- Listar os eventos de uma nota
- 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/
3º Passo - Cadastrar um destinatário para a consulta
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
Atributo | Tipo | Descrição |
Content-Type | String | multipart/form-data |
token_sh | String | Token obtido no cadastro do Tecno Account em: https://conta.tecnospeed.com.br/ |
cpfCnpjSoftwareHouse | String | CPF ou CNPJ da Software House que está desenvolvendo o controle das notas tomadas |
cpfCnpjDestinatario | String | CPF ou CNPJ do destinatário das notas fiscais |
Body
Retorno
Atributo | Tipo | Descrição |
uf | String | Código do IBGE referente ao estado onde seu cliente está |
certificado | Binário | Binário do arquivo do certificado digital |
senha | String | Senha do certificado digital |
String | Email do responsável pelo certificado digital |
{
"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
Atributo | Tipo | Descrição |
Content-Type | String | application/json |
token_sh | String | Token obtido no cadastro do Tecno Account em: https://conta.tecnospeed.com.br/ |
cpfCnpjSoftwareHouse | String | CPF ou CNPJ da Software House que está desenvolvendo o controle das notas tomadas |
cpfCnpjDestinatario | String | CPF ou CNPJ do destinatário das notas fiscais |
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.
Atributo | Tipo | Descrição |
periodo | Objeto | Objeto contendo dois campos, "dataInicial" e "dataFinal" |
periodo.dataInicial | String | Data inicial do período de filtro das notas |
periodo.dataFinal | String | Data final do período de filtro das notas |
ultimoNsu | String | Ultimo NSU salvo por você num outro software. Nesta API você não precisa controlar este campo pois fazemos isso por você, portanto este é um parâmetro opcional. |
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
Atributo | Tipo | Descrição |
Content-Type | String | application/json |
token_sh | String | Token obtido no cadastro do Tecno Account em: https://conta.tecnospeed.com.br/ |
cpfCnpjSoftwareHouse | String | CPF ou CNPJ da Software House que está desenvolvendo o controle das notas tomadas |
cpfCnpjDestinatario | String | CPF ou CNPJ do destinatário das notas fiscais |
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.
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
Atributo | Tipo | Descrição |
Content-Type | String | application/json |
token_sh | String | Token obtido no cadastro do Tecno Account em: https://conta.tecnospeed.com.br/ |
cpfCnpjSoftwareHouse | String | CPF ou CNPJ da Software House que está desenvolvendo o controle das notas tomadas |
cpfCnpjDestinatario | String | CPF ou CNPJ do destinatário das notas fiscais |
pagina | String | Inserir o nome da página que deseja consultar |
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.
Comentários
0 comentário
Por favor, entre para comentar.