A API de notas tomadas desenvolvida pela TecnoSpeed foi construída para atender a necessidade das empresas de consultar as notas de serviço emitidas contra o seu próprio CNPJ.

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)
   • Coleção de requisições e documentação no Swagger
2. Cadastrar um certificado para a consulta
3. Consultar cidades homologadas (*retorna os dados exigidos pelos municípios para consulta.)
4. Adicionar uma consulta
5. Consultar o protocolo da consulta
6. Consultar todas as notas pelo protocolo
7. Realizar outras consultas 

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.

Coleção de requisições e documentação no Swagger

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/8557d3fbf1e4764d1db2

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

2º Passo - Cadastrar um certificado para a consulta

Primeiro será necessário realizar o cadastro do certificado digital da empresa que teve as notas emitidas contra o seu CNPJ. 

POST

https://api.nfse.tecnospeed.com.br/v1/certificados

Parâmetros

Headers

Body

Retorno

{

    "resposta": {

        "mensagem": "Cadastro efetuado com sucesso",

        "id": "5ebc39a6dd470057349a99aa",

        "nome": "CN=TECNOSPEEDTI SA:29062609000177, OU=Certificado XX XX, O=XX-XX, C=XX, S=XX, L=XX, E=XX, SE=XX XX XX XX XX XX XX",

        "vencimento": "16/04/2021 10:34:00"

    }

}

Com o cadastro do certificado digital realizado, já podemos realizar a primeira consulta de notas tomadas, vamos chamar essa rota de "Adicionar uma consulta de notas"

3º Passo - Consultar cidades homologadas

GET

https://api.nfse.tecnospeed.com.br/v1/cidades

Parâmetros

Headers

Retorno

{
"acoes": {
"consultaCidadeHomologada": {
"url": "https://api.nfse.tecnospeed.com.br/v1/cidades/{codigoIbge}",
"metodo": "GET",
"descricao": "Consulta de uma cidade específica pelo código do IBGE."
}
},
"resposta": [
{
"nome": "ABAETEMG",
"padrao": "ISSLEGAL",
"consultarNotasTomada": true,
"prestadorObrigatorioTomadas": true,
"tipoComunicacao": "Rest",
"codigoIbge": "3100203",
"multiservicos": false,
"certificado": false,
"login": false,
"senha": true
},

4º Passo - Adicionar uma consulta

POST

https://api.nfse.tecnospeed.com.br/v1/tomadas

Parâmetros

Headers

Body

{
 "codigoCidade": "4115200",
 "prestador": {
   "cpfCnpj": "99999999999999",
   "inscricaoMunicipal": "99999" 
 }, 
 "destinatario": {
   "cpfCnpj": "29062609000177",
   "inscricaoMunicipal": "99999"
 },
 "periodo": {
   "inicial": "2020-03-01",
   "final": "2020-03-20"
 }
}

Atenção! Caso o município tenha autenticação por Login e Senha será necessário que esses parâmetros sejam enviados na requisição dentro do grupo "autenticacao" conforme exemplo abaixo:

{
 "codigoCidade": "4115200",
 "prestador": {
   "cpfCnpj": "99999999999999",
   "inscricaoMunicipal": "99999" 
 },
 "destinatario": {
   "cpfCnpj": "29062609000177",
   "inscricaoMunicipal": "99999",
   "autenticacao": {
     "login": "teste",
     "senha": "12345"
   }
 },
 "periodo": {
   "inicial": "2020-03-01",
   "final": "2020-03-20"
 }
}

Atenção! Exigibilidade dos parâmetros InscricaoMunicipal e CpfCNPJ do prestador varia de município para município. Para consultaras exigências de cada município na consulta de tomadas, acesse: Lista de municípios homologados ou utilize a rota: Consultar cidades homologadas.

Retorno

{

    "acoes": {

        "consultaProtocolo": {

            "rota": "https://api.nfse.tecnospeed.com.br/v1/tomadas/741fd8ee-982d-4041-94ce-5d6eaad299cs",

            "metodo": "GET",

            "descricao": "Consulta de situação do protocolo."

        }

    },

    "resposta": {

        "mensagem": "Nota(as) em processamento",

        "protocolo": "741fd8ee-982d-4041-94ce-5d6eaad299cs"

    }

}

 Nesse momento a requisição "Adicionar uma consulta" está sendo processada https://atendimento.tecnospeed.com.br/hc/pt-br/articles/360047699014 e podemos consultar a situação dessa requisição através da rota Consultar Protocolo.

5º Passo - Consultando o protocolo da consulta

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 a prefeitura, podendo ou não retornar notas.
• ERRO -> Ocorreu um erro ao tentar realizar a consulta junto a prefeitura.

Obs.: Esta consulta deve ser feita no mínimo 1 hora depois da adição da consulta realizada pela rota  Adicionar uma consulta de notas

GET

https://api.nfse.tecnospeed.com.br/v1/tomadas/Número do protocolo retornado na rota Adicionar uma consulta de notas

 Exemplo: https://api.nfse.tecnospeed.com.br/v1/tomadas/741fd8ee-982d-4041-94ce-5d6eaad2xx88

Parâmetros

Headers

Retorno

{

    "acoes": {

        "consultaNotas": {

            "rota": "https://api.nfse.tecnospeed.com.br/v1/tomadas/741fd8ee-982d-4041-94ce-5d6eaad2c8dc/notas",

            "metodo": "GET",

            "descricao": "Consulta todas as notas vinculadas ao protocolo."

        }

    },

    "resposta": {

        "protocolo": "741fd8ee-982d-4041-94ce-5d6eaad2c8dc",

        "situacao": "CONCLUIDO",

        "totalDeNotas": 32

    }

}

 Com a "situação": "CONCLUIDO" a API terminou de consultar as notas tomadas na prefeitura e já estão disponíveis para serem consultadas através da rota Consultar todas as notas pelo protocolo.

6º Passo - Consultar todas as notas pelo protocolo

Essa consulta retorna todas as notas vinculadas ao protocolo.

Obs.: Esta consulta deve ser feita no mínimo 1 hora depois da adição da consulta realizada pela rota  Adicionar uma consulta de notas

O retorno será paginado a cada 100 registros, devendo utilizar o parâmetro de consulta "pagina", para avançar.

Utilize a ação "proximaPagina" na resposta da requisição para facilitar a implementação, parando a iteração somente quando não mais encontrar a ação de "proximaPagina".

Observação: Os campos retornadas em cada nota podem variar de acordo com a prefeitura.

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

ou

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

GET

https://api.nfse.tecnospeed.com.br/v1/tomadas/Número do protocolo retornado na rota  Adicionar uma consulta de notas/notas

Exemplo: https://api.nfse.tecnospeed.com.br/v1/tomadas/741fd8ee-982d-4041-94ce-5d6eaad2xx88/notas

Parâmetros

Headers

Retorno

{
 "acoes": {
 "consultaNota": {
 "url": "https://api.nfse.tecnospeed.com.br/v1/tomadas/741fd8ee-982d-4041-94ce-5d6eaad2c8dc/notas/{id}",
 "metodo": "GET",
 "descricao": "Consulta de uma nota especifica."
 },
 "downloadXml": {
 "url": "https://api.nfse.tecnospeed.com.br/v1/tomadas/741fd8ee-982d-4041-94ce-5d6eaad2c8dc/notas/{id}/xml",
 "metodo": "GET",
 "descricao": "Download do XML de uma nota especifica."
 }
 },
 "resposta": {
 "protocolo": "741fd8ee-982d-4041-94ce-5d6eaad2c8dc",
 "situacao": "CONCLUIDO",
 "totalDeNotas": 1,
 "notas": [
 {
 "id": "5ebc444299abc6087c3971d4",
 "prestador": {
 "endereco": {
 "endereco": "AVENIDA CANDIDO DE ABREU",
 "numero": "999",
 "complemento": "",
 "bairro": "Centro Civico",
 "codigoCidade": "4106902",
 "cep": "80530902"
 },
 "razaoSocial": "TESTE TESTE",
 "cpfCnpj": "99999999999999",
 "inscricaoMunicipal": "9999"
 },
 "tomador": {
 "endereco": {
 "endereco": "Av Duque De Caxias",
 "numero": "882",
 "complemento": "",
 "bairro": "Zona 07",
 "codigoCidade": "4115200",
 "cep": "87020025"
 },
 "razaoSocial": "TECNOSPEED S/A",
 "cpfCnpj": "29062609000177",
 "inscricaoMunicipal": "",
 "email": "financeiro@tecnospeed.com.br",
 "telefone": "44984211165"
 },
 "rps": {
 "serie": "1",
 "numero": "39497",
 "dataEmissao": "2020-03-03T19:41:26.000Z"
 },
 "nfse": {
 "numero": "44742",
 "dataAutorizacao": "2020-03-03T00:00:00.000Z",
 "codigoVerificacao": "XXXXXXXXX"
 },
 "iss": {
 "aliquota": 0,
 "retido": 0,
 "valor": 0
 },
 "retencao": {
 "pis": 0,
 "cofins": 0,
 "inss": 0,
 "ir": 0,
 "csll": 0
 },
 "protocolo": "741fd8ee-982d-4041-94ce-5d6eaad2c8dc",
 "situacao": "AUTORIZADA",
 "discriminacaoServico": "SERVICO DE EXAMES DE ACUIDADE VISUAL T 1.00 UN Marco/2020 SERVICO DE FONOAUDIOLOGIA T 1.00 UN Marco/2020 \"Ampla Isencao Fiscal nos Termos da CF/88, art.150, inc VI, alinea C\" \"Lei Federal 2613/1995 arts. 12 e 13\" \"Decreto-lei 9403/1946 art. 5,paragrafo Unico \" \"Decreto 57375/65 (art.12)\" Os servicos referentes a esta NFS-e sao Imunes do ISS. .",
 "codigoTributacaoMunicipio": "402",
 "valorServicos": 24,
 "valorDeducoes": 0,
 "xml": "https://api.nfse.tecnospeed.com.br/v1/tomadas/741fd8ee-982d-4041-94ce-5d6eaad2c8dc/notas/5ebc444299abc6087c3971d4/xml",
 "criadoEm": "2020-05-13T19:02:26.630Z",
 "atualiadoEm": "2020-05-13T19:02:26.630Z"
 }
 ]
 }
}

6º Passo - Outras consultas

Ainda existem mais duas formas de consultar esses retornos de notas da API que são elas:

• Consultar a nota pelo Id
  • Utilize essa rota para consultar uma nota específica à partir de seu ID. Utilize o ID obtido na consulta do protocolo.

• Consultar a nota pelo Id retornando o XML da nota
  • Essa rota não segue o padrão de retorno da API, pois recupera diretamente o XML da nota consultada. Utilize o ID obtido na consulta do protocolo.

Obs.: Esta consulta deve ser feita no mínimo 1 hora depois da adição da consulta realizada pela rota  Adicionar uma consulta de notas

Caso queira consultar os certificados cadastrados, utilize a rota:

Consultar certificado