Definição
Esse documento tem por objetivo descrever como funciona a API Rest Consulta Composta, o seu objetivo, os parâmetros da chamada e seus respectivos retornos de suas consultas. O conteúdo desta documentação e as especificações da Consulta Composta estão sujeitos a alterações sem prévio aviso.
Requisição
Consulta Composta
Através do endpoint da Consulta Composta é possível criar uma composição completamente customizavel informado apenas a número do documento ex: CNPJ e parametrizando as fontes de consulta que deseja chamar naquele momento.
URL da Consulta
Para o processo de requisição será necessário o token de acesso, caso ainda não tenha o seu entre em contato com o suporte netrin, o número do documento que deseja inforamor, ex: CNPJ, e o(s) nome(s) do(s) serviço(s) que deseja buscar.
Com estas informações parametrizadas deverá ser realizado uma requisição do tipo GET a url: https://api.netrin.com.br/v1/consulta-composta.
Marcação da Consulta
Tags e Referência
A consulta composta permite a adição de tags à consulta através do parâmetro tags, separadas por vírgula. Essas tags são utilizadas para personalização e categorização dos dados. Outro parâmetro disponível é o reference, que permite incluir uma referência numérica associada à consulta, por exemplo, do seu parceiro dentro do ERP. Ambos os parâmetros são opcionais, ou seja, você pode escolher se deseja utilizá-los ou não na sua chamada à API.
O seguinte retorno será incluído na resposta da consulta:
{
"cnpj": 13384727000161,
"tags": [
"onboarding",
"faturamento"
],
"reference": "156454"
}
Mensagens de retorno
Status Code
| Status Code | Message | Ações |
|---|---|---|
| 200 | Sucesso | - |
| 206 | Retorno Parcial | Avaliar código interno (tabela abaixo) |
| 408 | Timeout | Avaliar código interno (tabela abaixo) |
| 401 | Token Inválido / Expirado | Analisar token |
| 403 | Usuário não possui permissão para acessar este recurso | Contatar Suporte |
| 404 | Parâmetros inválidos | Rever nome do(s) serviço(s) |
| 502 | Falha na chamada | Contatar Suporte |
Códigos Internos
| Códigos Internos | Descrição | Definições |
|---|---|---|
| 601 | Lentidão ao gerar captcha | Contatar Suporte em caso de reincidência |
| 602 | Lentidão do site | Avaliar consumo do serviço |
| 603 | Site fora do ar | Aguardar retorno do site |
| 604 | Em manutenção | Contatar Suporte para prazo de retorno |
| 605 | Parâmetros faltantes para a fonte | Contatar Suporte em caso de dúvida |
| 606 | Não encontrado | Dados não existem na base da fonte de origem |
| 607 | Menor de idade | O documento consultado pertence a um menor de idade |
| 608 | Não foi possível emitir | O site não permitiu emitir o comprovante |
| 609 | Parâmetro(s) inválido(s) | Verificar os valores dos parâmetros fornecidos |
| 610 | Limite de tentativas excedido | Limite diário de tentativas foi excedido |
| 611 | Franquia excedida | O valor contrado foi excedido |
| 612 | Franquia inativa | A franquia foi inativada |
| 613 | Franquia expirada | A franquia não foi renovada |
| 614 | PEP / VIP | O documento pertence a uma pessoa de destaque (ou pessoa renomada) e os dados não podem ser divulgados |
| 615 | Documento bloqueado na base de dados de origem | O documento está bloqueado e não será possível consultá-lo |
| 616 | Documento inativo | O documento está inativo e não será possível consultá-lo |
| 617 | Informações Pessoais identificáveis mínimas (PII) | Dados Pessoais Identificáveis Mínimos (PII) |
| 618 | Pessoa falecida | O documento pertence a um titular falecido |
| 619 | Não possui histórico de crédito | Sem histório de crédito para apresentar |
| 620 | Documento Inválido | O documento consultado é inválido |
| 621 | Limite de erros excedido, temporariamente bloqueado | Mensagem dedicada para o excesso de erros na validação com microdepósito |
| 622 | Serviço temporariamente indisponível | O serviço de consulta não está atualmente disponível. Em caso de dúvida, contate o suporte. |
| 623 | Usuário não possui permissão para acessar este recurso | O serviço consultado não está atualmente liberado. Em caso de dúvida, contate o suporte. |
| 624 | O CPF informado possui restrições para este serviço | O CPF consultado está temporariamente impedido de ser validado através deste serviço |
| 625 | Banco de destino não respondeu à requisição, tente novamente mais tarde | Instabilidade temporária no banco de destino. Tentar novamente mais tarde. |
| 650 | Problemas na busca | Contatar Suporte em caso de reincidência |
Exemplo de retorno
{
"cpf": 00000000000,
"receitaFederal": {
"code": "603",
"message": "Site fora do ar"
},
"sintegra": {
"code": "604",
"message": "Em manutenção"
}
}
Comprovantes das consultas
Com o objetivo de garantir a precisão das informações, o serviço fornecerá, sempre que possível, um comprovante da consulta no formato PDF ou HTML.
No JSON, a tag terá o nome "urlComprovante" e estará acompanhada da URL para um repositório que expirará em 3 meses a partir da data da consulta. É de extrema importância que o desenvolvimento da solução inclua a rotina de download desse arquivo a partir do link, pois isso permitirá a recuperação do documento em caso de auditorias fiscais.
A Netrin não manterá os comprovantes de consultas, sendo necessário baixar e armazenar o documento em uma estrutura própria, pois ele não estará mais disponível após esse período.
Em algumas situações, devido à natureza dos dados históricos, a tag mencionada pode não estar presente nas entregas.
Por último, caso ocorra algum erro na geração do comprovante, a tag "urlComprovante" será preenchida com a mensagem "Não foi possível gerar o link do comprovante."
Desmonstração de requisição
Exemplo de consulta
Neste exemplo estaremos informando o documento (CNPJ) 13384727000161 da Netrin e endereçando a consulta aos serviços:
- Receita Federal: receita-federal-cnpj
- Sintegra: sintegra
- Simples Nacional: simples-nacional
OBS: caso deseje realizar esta chamada, substituir o token 00000000-0000-0000-0000-000000000000 pelo seu token exclusivo.
{
"cnpj": "13384727000161",
"receitaFederal": {
"razaoSocial": "NETRIN CONSULTORIA E SERVICOS EM TECNOLOGIA DA INFORMACAO LTDA.",
"nomeFantasia": "********",
"naturezaJuridica": "206-2 - Sociedade Empresária Limitada",
"logradouro": "AV THEODOMIRO PORTO DA FONSECA",
"numero": "3101",
"complemento": "EDIF 08 SALA E",
"bairro": "DUQUE DE CAXIAS",
"municipio": "SAO LEOPOLDO",
"cep": "93.020-080",
"uf": "RS",
"email": "contabilidade@meta.com.br",
"telefone": "(51) 2101-1371/ (51) 2101-1300",
"efr": "*****",
"situacaoCadastral": "ATIVA",
"dataSituacaocadastral": "17/03/2011",
"dataInicioAtividade": "17/03/2011",
"atividadeEconomica": "62.02-3-00 - Desenvolvimento e licenciamento de programas de computador customizáveis",
"atividadesEconomicasSecundarias": [
"62.03-1-00 - Desenvolvimento e licenciamento de programas de computador não-customizáveis",
"62.01-5-01 - Desenvolvimento de programas de computador sob encomenda",
"62.04-0-00 - Consultoria em tecnologia da informação",
"62.09-1-00 - Suporte técnico, manutenção e outros serviços em tecnologia da informação"
],
"tipoCNPJ": "MATRIZ",
"situacaoEspecial": "********",
"dataSituacaoEspecial": "********",
"motivoSituacao": "",
"porte": "DEMAIS",
"capitalSocial": "R$447.755,00 (Quatrocentos e quarenta e sete mil e setecentos e cinquenta e cinco reais)",
"urlComprovante": "https://..."
},
"simplesNacional": {
"nomeEmpresarial": "NETRIN CONSULTORIA E SERVICOS EM TECNOLOGIA DA INFORMACAO LTDA.",
"situacaoSimplesNacional": "NÃO optante pelo Simples Nacional",
"situacaoSimei": "NÃO enquadrado no SIMEI",
"urlComprovante": "https://..."
},
"sintegra": {
"code": 606,
"message": "Não encontrado",
"urlComprovante": "https://..."
}
}