Padrões de resposta

Todas as rotas da nossa API retornam os dados no formato JSON, garantindo uma integração simples e compatível com a maioria das linguagens e frameworks de desenvolvimento.

Além disso, seguimos os padrões de código de status HTTP para indicar o resultado de cada requisição, conforme descrito abaixo:

• 200 - Sucesso: A requisição foi processada com êxito e os dados foram retornados no corpo da resposta.

• 400 - Erro de Requisição: Ocorreu um problema com os dados enviados na requisição. Verifique os parâmetros e tente novamente.

• 403 - Permissão Negada: O usuário não possui permissão para acessar o recurso solicitado. Certifique-se de que suas credenciais e permissões estão corretas.

• 429 - Limite de Requisições Excedido: O número máximo de requisições permitidas foi atingido. Para garantir a estabilidade do sistema, cada usuário pode realizar até 120 requisições por minuto. Se receber este erro, tente aumentar o intervalo entre as requisições. Caso sua demanda exija um limite maior, entre em contato para avaliarmos uma possível ampliação.

• 500 - Erro Interno: Um erro inesperado ocorreu no servidor. Nossa equipe será notificada, mas, caso persista, entre em contato com o suporte.

Informações complementares

Campo status

Todas as rotas retornaram um campo status no corpo da resposta JSON, seguindo o padrão:

• status = "ok": Indica que a requisição foi bem-sucedida (HTTP 200).

• status = "erro": Indica que ocorreu uma falha ao processar a requisição. Essa falha pode ser causada por erros do cliente (HTTP 400, 403), falta de crédito (HTTP 402), limite de requisições (HTTP 429) ou erros do servidor (HTTP 500).

Campo tipo_do_erro

Algumas respostas incluirão o campo tipo_do_erro, que fornece informações um direcionamento simples sobre a natureza do problema. Esse campo facilita a identificação e tratamento do caso, sendo os possíveis erros:

• placa_nao_encontrada ou chassi_nao_encontrado: Situação ocorre quando não é possível obter informações para a placa ou chassi. Isso pode acontecer porque a placa realmente não existe ou porque o serviço de consulta está temporariamente indisponível. Recomenda-se verificar se a placa foi digitada corretamente e, se estiver correta, tentar novamente mais tarde.

• informacao_nao_encontrada: Situação ocorre quando não possuímos a informação para a placa informado.

• servico_indisponivel: Situação em que não foi possível completar a pesquisa. Normalmente em situações que nossos fornecedores encontram-se temporariamente indisponíveis. Recomendamos que repita a requisição novamente em alguns minutos!

• credito_insuficiente: Situação em que o crédito de sua conta é insuficiente para cobrir o valor da consulta em questão.

Exemplos de erros

// Placa informada é inválida.
{
    "status": "erro",
    "mensagem": "Placa informada é invalida. Placa deve possuir o formato conforme exemplos: AAA9999 ou AAA9A99!",
    "request": {
        "placa": "AAA022"
    }
}

// Placa não encontrada em nossa base. 
// Neste caso é retornado o campo tipo_do_erro com o valor placa_nao_encontrada
{
    "status": "erro",
    "tipo_do_erro": "placa_nao_encontrada",
    "mensagem": "Não foi possível obter informações para a placa informada. Verifique se o valor está correto. Caso esteja, o serviço pode estar temporariamente indisponível. Por favor, tente novamente mais tarde!",
    "request": {
        "placa": "AAA0000"
    }
}

// Serviço indisponível. 
// Neste caso é retornado o campo tipo_do_erro com o valor servico_indisponivel
{
    "status": "erro",
    "tipo_do_erro": "servico_indisponivel",
    "mensagem": "Não foi possível completar sua pesquisa. Fornecedores temporariamente indisponíveis. Tente novamente em alguns minutos!",
    "request": {
        "placa": "AAA0000"
    }
}