Pular para o conteúdo principal

Solicitação de consulta

Guilherme Ganassin
Atualizado

Introdução

A solicitação da consulta é o método pelo qual o pedido de consulta é efetivamente feito à SCC/Serasa.

Se trata da primeira etapa de um processo assíncrono, onde o sistema integrado com nossa API poderá realizar o pedido de consulta e obterá um protocolo em caso de sucesso. Este protocolo deverá ser consultado na segunda etapa do processo de consulta, para que se tenha acesso ao resultado da consulta desejado.

 

Definições da requisição:

 

Método

POST

 

URL da API

   Homologação:

https://api.consultanegativacao.com.br/v2/homologacao/consultas/assincrona

   Produção:

https://api.consultanegativacao.com.br/v2/consultas/assincrona

 

Headers

Os headers necessários para a autenticação da requisição são:

 Header  Descrição
 cnpjsh  CNPJ da Software House que possui contrato com a Tecnospeed
 tokensh  Token de autenticação da Software House (obtido através deste processo)
 cnpjUsuario

 CNPJ do usuário responsável pela consulta. 

 O CNPJ deve, obrigatoriamente, ter sido cadastrado pela rota de cadastro de empresas, descrito neste link.
 login

 Login de acesso disponibilizado pela SCC.

 O login será disponibilizado após a realização do cadastro da empresa, descrito neste link.
 password

 Senha de acesso disponibilizada pela SCC.

 A senha será disponibilizada após a realização do cadastro da empresa, descrito neste link.

 

Body 

O  JSON enviado na solicitação deve conter os seguintes campos:

 Campo Tipo  Descrição Valores aceitos
 documento string  CPF ou CNPJ que será consultado

 CPF válido e com 11 dígitos

 

 CNPJ válido e com 14 dígitos

 

 Utilizar apenas valores núméricos, sem máscara
 codConsulta numérico

 Código da consulta a ser realizada:

  • 1: Crednet PF ou PJ TOP
  • 600: Relatório Básico PF
  • 601: Relatório Básico PJ
  • 602: Relatório Avançado PF
  • 603: Relatório Avançado PJ 
  • 1
  • 600
  • 601
  • 602
  • 603

 Consulte a tabela de  consultas disponíveis e também a documentação com a descrição das informações retornadas.
 uf  string  UF a ser consultada (apenas para Crednet Light)

 Sigla do estado (UF) oficial ABNT com 2 caracteres.

 Exemplo: "uf": "PR",
 retorno  string  Tipo do retorno da consulta
  • HTML
  • JSON (*)

 Caso opte pelo retorno em HTML, o resultado da consulta será um HTML pronto contendo as informações vindas da Serasa, sem necessidade de tratamento pela SH.

 Caso opte pelo retorno em JSON, o resultado será um JSON que o ERP poderá consumir para obter os dados necessários.

 

 (*) Neste momento apenas o retorno em HTML está disponível, e o JSON será disponibilizado em breve.

 

 

Exemplo de JSON de Envio

{
  "documento": "11111111111",
  "codConsulta": 602,
  "uf": "PR",
  "retorno": "HTML"
}

 

Exemplo de Retorno

Status=200 - Sucesso

{
    "protocolo": "aaaaaa-aa",
    "status": "processando",
    "documento": "11111111111",
    "codConsulta": "602"
}

 

Onde:

Campo Tipo Descrição
protocolo string  Protocolo de recebimento do pedido. Este protocolo deverá ser registrado pelo sistema do cliente e consultado na rota GET que mostra efetivamente o resultado da consulta.
status string  Identifica se a requisição entrou para a fila de processamento da API.
documento string  Documento que foi consultado.
codConsulta strig  Código da consulta solicitada pelo sistema

 

Observação: Cada pedido de consulta realizado com sucesso (ou seja, com geração de um protocolo) gera uma cobrança automática, creditando o valor negociado com nosso setor comercial. Mensalmente tais valores são somados e constarão na fatura do cliente. Por conta disso, a Tecnospeed recomenda que o uso das consultas seja realizado sob controle do ERP e não nos responsabilizamos por consultas indevidas realizadas em nossos sistemas.

 

Status=401 - Falta de autorização

{
    "code": 401,
    "message": "CNPJ ou TOKEN incorretos, verifique sua conta em https://conta.tecnospeed.com.br"
}

 

Onde:

Campo Tipo Descrição
code numérico  Código de erro que identifica a falha na autorização da requisição
message string  Mensagem de erro que orienta quanto ao problema. Neste caso, recomenda-se a validação das credenciais de autenticação da rota

 

Status=422 - Falha de processamento - Autenticação

{
    "code": 422,
    "message": "Unprocessable Entity",
    "errors": [
        {
            "internalCode": 4040,
            "message": "Empresa não encontrada, use a rota de cadastro"
        }
    ]
}

 

Onde:

Campo Tipo Descrição
code numérico  Código de erro que identifica a falha na autorização da requisição
message string  Mensagem de erro que orienta quanto ao problema. Neste caso, recomenda-se a validação das credenciais de autenticação da rota
errors Objeto Lista de erros identificadas e que impossibilitaram o processamento da requisição
internalCode numérico

Código de erro interno

Obs.: Lista de erros em criação pela Tecnospeed
message string Mensagem de erro que orienta quanto ao problema. Neste caso, recomenda-se a criação do usuário pelo fluxo de cadastro da empresa, descrito neste link.

 

Status=422 - Falha de processamento - Integridade dos dados

{
    "code": 422,
    "message": "Unprocessable Entity",
    "errors": [
        {
            "message": "Campo login é obrigatório",
            "internalCode": 4001
        }
    ]
}

 

Onde:

Campo Tipo Descrição
code numérico  Código de erro que identifica a falha na autorização da requisição
message string  Mensagem de erro que orienta quanto ao problema. Neste caso, recomenda-se a validação das credenciais de autenticação da rota
errors Objeto Lista de erros identificadas e que impossibilitaram o processamento da requisição
internalCode numérico

Código de erro interno

Obs.: Lista de erros em criação pela Tecnospeed
message string Mensagem de erro que orienta quanto ao problema. Neste caso, orienta-se que se os campos "login" e "password" foram preenchidos corretamente no header da requisição

 

 

Status=422 - Falha de processamento - Campos obrigatórios

{
    "code": 422,
    "message": "Unprocessable Entity",
    "errors": [
        {
            "message": "Campo documento é obrigatório",
            "internalCode": 4001
        }
    ]
}

 

Onde:

Campo Tipo Descrição
code numérico  Código de erro que identifica a falha na autorização da requisição
message string  Mensagem de erro que orienta quanto ao problema. Neste caso, recomenda-se a validação das credenciais de autenticação da rota
errors Objeto Lista de erros identificadas e que impossibilitaram o processamento da requisição
internalCode numérico

Código de erro interno

Obs.: Lista de erros em criação pela Tecnospeed
message string Mensagem de erro que orienta quanto ao problema. Neste caso, orienta-se que se verifique se todos os campos obrigatórios do body da requisição foram preenchidos adequadamente, inclusive quanto a seus formatos.

 

Status=422 - Falha de processamento - Integridade dos dados

{
    "code": 422,
    "message": "Unprocessable Entity",
    "errors": [
        {
            "message": "11111111111 CPF/CNPJ inválido",
            "internalCode": 4001
        }
    ]
}

 

Onde:

Campo Tipo Descrição
code numérico  Código de erro que identifica a falha na autorização da requisição
message string  Mensagem de erro que orienta quanto ao problema. Neste caso, recomenda-se a validação das credenciais de autenticação da rota
errors Objeto Lista de erros identificadas e que impossibilitaram o processamento da requisição
internalCode numérico

Código de erro interno

Obs.: Lista de erros em criação pela Tecnospeed
message string Mensagem de erro que orienta quanto ao problema. Neste caso, orienta-se que se verifique se o CPF ou CNPJ consultado é válido.

 

Status=422 - Falha de processamento - Integridade dos dados

{
    "code": 422,
    "message": "Unprocessable Entity",
    "errors": [
        {
            "message": "Campo undefined deve ser igual a um dos valores predefinidos:
1,4,600,601,602,603",
            "internalCode": 4003
        }
    ]
}

 

Onde:

Campo Tipo Descrição
code numérico  Código de erro que identifica a falha na autorização da requisição
message string  Mensagem de erro que orienta quanto ao problema. Neste caso, recomenda-se a validação das credenciais de autenticação da rota
errors Objeto Lista de erros identificadas e que impossibilitaram o processamento da requisição
internalCode numérico

Código de erro interno

Obs.: Lista de erros em criação pela Tecnospeed
message string Mensagem de erro que orienta quanto ao problema. Neste caso, orienta-se que se verifique se o campo "codConsulta" está de acordo com a tabela de códigos aceitos.

 

Status=422 - Falha de processamento - Integridade dos dados

{
    "code": 422,
    "message": "Unprocessable Entity",
    "errors": [
        {
            "message": "Campo undefined deve ser igual a um dos valores predefinidos: HTML,JSON",
            "internalCode": 4003
        }
    ]
}

 

Onde:

Campo Tipo Descrição
code numérico  Código de erro que identifica a falha na autorização da requisição
message string  Mensagem de erro que orienta quanto ao problema. Neste caso, recomenda-se a validação das credenciais de autenticação da rota
errors Objeto Lista de erros identificadas e que impossibilitaram o processamento da requisição
internalCode numérico

Código de erro interno

Obs.: Lista de erros em criação pela Tecnospeed
message string Mensagem de erro que orienta quanto ao problema. Neste caso, orienta-se que se verifique se o campo "retorno" respeita os valores definidos na tabela.

 

 

 

 

Artigos relacionados

Comentários

0 comentário

Por favor, entre para comentar.