{ "openapi": "3.1.0", "info": { "title": "AnyCar API", "version": "2.1.0", "summary": "API REST de dados veiculares pela placa para empresas (B2B).", "description": "API da AnyCar para dados veiculares pela placa. Duas superfícies num só contrato: (1) fluxo público do site (B2C, tag consumidor), que qualquer cliente ou agente de IA usa para ver planos, fazer a prévia gratuita, gerar o pagamento Pix de uma consulta e acompanhar o resultado, sem autenticação; (2) API contratada para empresas (B2B, demais tags), com API key, para consultas avulsas de leilão, sinistro, gravame, restrições, roubo e furto, recall, FIPE e dados cadastrais em modelo pay-per-use. A conta empresarial é criada em https://anycar.com.br/para-empresas/criar-conta com ativação automática e imediata; a API key fica no portal do cliente (https://empresas.anycar.com.br), em Configurações. Documentação para desenvolvedores: https://anycar.com.br/developers\n\nVersionamento e depreciação: o contrato atual é a versão 2. Toda resposta carrega o cabeçalho X-Api-Version; o cliente pode fixar a versão enviando X-Api-Version: 2 na requisição (valor não suportado responde 400). Mudanças compatíveis (campos novos) entram na própria versão 2. Mudança incompatível vira versão nova, anunciada na versão antiga com os cabeçalhos Deprecation (RFC 9745) e Sunset (RFC 8594) com no mínimo 90 dias de antecedência, além de aviso por e-mail aos integradores cadastrados.\n\nLimites de uso: endpoints com limite de requisições retornam os cabeçalhos RateLimit e RateLimit-Policy (padrão IETF, com o trio RateLimit-Limit/Remaining/Reset de compatibilidade) em toda resposta; ao exceder, a resposta é 429 com Retry-After em segundos. Use esses cabeçalhos para se auto-regular.", "termsOfService": "https://anycar.com.br/termos-condicoes", "contact": { "name": "Suporte AnyCar", "email": "suporte@anycar.com.br", "url": "https://anycar.com.br/fale-conosco" } }, "servers": [ { "url": "https://api.anycar.com.br", "description": "Produção" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "consumidor", "description": "Fluxo público do site (B2C), sem autenticação: planos e preços, prévia gratuita pela placa, pagamento Pix e acompanhamento da consulta. Protegido por rate limit por IP e antibot; use com moderação e apenas para compras reais." }, { "name": "consultas", "description": "Consultas avulsas de dados veiculares pela placa (pay-per-use)." }, { "name": "laudo", "description": "Laudo veicular completo: solicitação assíncrona com entrega por webhook." }, { "name": "vistoria", "description": "Vistoria veicular vinculada a um veículo consultado." }, { "name": "conta", "description": "Status do contrato e das consultas habilitadas para a empresa autenticada." }, { "name": "infra", "description": "Health check e utilitários sem autenticação." } ], "paths": { "/health": { "get": { "operationId": "verificarSaudeApi", "tags": [ "infra" ], "summary": "Health check da API", "description": "Verifica se a API está no ar. Não requer autenticação e não gera cobrança.", "security": [], "responses": { "200": { "description": "API operacional.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } }, "headers": { "X-Api-Version": { "$ref": "#/components/headers/X-Api-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } } }, "400": { "description": "Requisição inválida (inclui X-Api-Version não suportado).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroResponse" } } } }, "429": { "description": "Limite de requisições por IP excedido. Aguarde o intervalo do Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroResponse" } } }, "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } } }, "parameters": [ { "$ref": "#/components/parameters/VersaoApi" } ] } }, "/api/status": { "get": { "operationId": "listarConsultasHabilitadas", "tags": [ "conta" ], "summary": "Lista as consultas habilitadas para a empresa", "description": "Retorna os tipos de consulta liberados no contrato da empresa autenticada, com categoria, grupo e disponibilidade. Use esta operação para descobrir quais valores de `tipo` podem ser enviados em POST /api/consultar. Não gera cobrança.", "responses": { "200": { "description": "Lista de consultas habilitadas.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusApisResponse" } } }, "headers": { "X-Api-Version": { "$ref": "#/components/headers/X-Api-Version" } } }, "401": { "$ref": "#/components/responses/NaoAutorizado" }, "403": { "$ref": "#/components/responses/AcessoNegado" }, "500": { "$ref": "#/components/responses/ErroInterno" }, "400": { "description": "Requisição inválida (inclui X-Api-Version não suportado).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroResponse" } } } } }, "parameters": [ { "$ref": "#/components/parameters/VersaoApi" } ] } }, "/api/consultar": { "post": { "operationId": "consultarDadosVeiculares", "tags": [ "consultas" ], "summary": "Executa uma consulta avulsa de dados veiculares", "description": "Executa uma consulta do tipo informado e retorna os dados na mesma resposta (síncrona). O campo `tipo` identifica a consulta (ex.: leilão, sinistro, gravame, FIPE); os tipos disponíveis dependem do contrato e podem ser listados em GET /api/status. A maioria das consultas exige `placa` (formato antigo ABC1234 ou Mercosul ABC1D23). Cobrança: pré-pago debita do saldo a cada consulta bem-sucedida; pós-pago é faturado depois. Quando o fornecedor upstream demora, a API responde HTTP 200 com `processando: true` e header Retry-After; repita a MESMA chamada após alguns segundos, o resultado fica em cache e não ha cobrança duplicada.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsultarRequest" }, "examples": { "leilao": { "summary": "Consulta de passagem por leilão", "value": { "tipo": "veicular-leilao-1", "placa": "ABC1D23" } }, "comPdf": { "summary": "Consulta com PDF do resultado", "value": { "tipo": "veicular-fipe", "placa": "ABC1234", "pdf": true } } } } } }, "responses": { "200": { "description": "Consulta concluida (`status: true` com `dados`) ou ainda em processamento (`status: false` com `processando: true`; repita a chamada após o intervalo do header Retry-After).", "headers": { "Retry-After": { "description": "Presente apenas na variante `processando`: segundos sugeridos antes de repetir a chamada.", "schema": { "type": "integer" } }, "X-Api-Version": { "$ref": "#/components/headers/X-Api-Version" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ConsultaResponse" }, { "$ref": "#/components/schemas/ConsultaProcessandoResponse" } ] } } } }, "400": { "description": "Requisição inválida: campo obrigatorio ausente, tipo inexistente ou não habilitado no contrato.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroResponse" } } } }, "401": { "$ref": "#/components/responses/NaoAutorizado" }, "402": { "description": "Saldo insuficiente (contas pré-pago). Faca uma recarga no portal do cliente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaldoInsuficienteResponse" } } } }, "403": { "description": "Acesso negado: placa bloqueada para consulta, IP fora da whitelist da empresa ou contrato suspenso por inadimplência.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroResponse" } } } }, "424": { "description": "Fornecedor upstream falhou ao processar a consulta. Não houve cobrança; tente novamente mais tarde.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsultaResponse" } } } }, "500": { "$ref": "#/components/responses/ErroInterno" } }, "parameters": [ { "$ref": "#/components/parameters/VersaoApi" } ] } }, "/api/laudo/planos": { "get": { "operationId": "listarPlanosLaudo", "tags": [ "laudo" ], "summary": "Lista os planos de laudo veicular disponíveis", "description": "Retorna os planos de laudo (nome, preco e itens inclusos) disponíveis para a empresa autenticada. Quando a empresa tem preço negociado vigente, `PlaValor` já vem personalizado e `personalizado` e true. Use o `PlaId` retornado aqui em POST /api/laudo/consultar. Não gera cobrança.", "responses": { "200": { "description": "Planos de laudo disponíveis.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanosLaudoResponse" } } }, "headers": { "X-Api-Version": { "$ref": "#/components/headers/X-Api-Version" } } }, "401": { "$ref": "#/components/responses/NaoAutorizado" }, "403": { "$ref": "#/components/responses/AcessoNegado" }, "500": { "$ref": "#/components/responses/ErroInterno" }, "400": { "description": "Requisição inválida (inclui X-Api-Version não suportado).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroResponse" } } } } }, "parameters": [ { "$ref": "#/components/parameters/VersaoApi" } ] } }, "/api/laudo/consultar": { "post": { "operationId": "solicitarLaudoVeicular", "tags": [ "laudo" ], "summary": "Solicita um laudo veicular completo (assincrono)", "description": "Cria uma solicitação de laudo veicular para a placa informada no plano escolhido. A operação é assíncrona: a resposta confirma a criação e o laudo pronto é entregue no webhook do tipo `laudos` configurado no portal do cliente (Configurações, Webhooks). Cobrança: pré-pago verifica e debita o saldo na criação; pós-pago é faturado depois.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaudoConsultarRequest" }, "examples": { "laudoCompleto": { "summary": "Solicitação de laudo", "value": { "PlaId": 12, "placa": "ABC1D23" } } } } } }, "responses": { "200": { "description": "Solicitação de laudo criada. O resultado sera enviado ao webhook `laudos`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaudoCriadoResponse" } } }, "headers": { "X-Api-Version": { "$ref": "#/components/headers/X-Api-Version" } } }, "400": { "description": "Requisição inválida: plano inexistente ou placa invalida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroResponse" } } } }, "401": { "$ref": "#/components/responses/NaoAutorizado" }, "402": { "description": "Saldo insuficiente (contas pré-pago).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaldoInsuficienteResponse" } } } }, "403": { "$ref": "#/components/responses/AcessoNegado" }, "500": { "$ref": "#/components/responses/ErroInterno" } }, "parameters": [ { "$ref": "#/components/parameters/VersaoApi" } ] } }, "/api/vistoria": { "post": { "operationId": "solicitarVistoriaVeicular", "tags": [ "vistoria" ], "summary": "Cria uma solicitação de vistoria veicular", "description": "Cria uma vistoria para um veículo já conhecido pela plataforma, na categoria informada. A categoria deve estar habilitada para a empresa; consulte as categorias disponíveis com o suporte ou no portal do cliente.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VistoriaRequest" }, "examples": { "vistoria": { "summary": "Solicitação de vistoria", "value": { "placa": "ABC1D23", "categoria": { "id": 1 } } } } } } }, "responses": { "200": { "description": "Vistoria criada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VistoriaCriadaResponse" } } }, "headers": { "X-Api-Version": { "$ref": "#/components/headers/X-Api-Version" } } }, "400": { "description": "Requisição inválida: placa invalida, veículo não encontrado ou categoria inexistente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroResponse" } } } }, "401": { "$ref": "#/components/responses/NaoAutorizado" }, "403": { "$ref": "#/components/responses/AcessoNegado" }, "500": { "$ref": "#/components/responses/ErroInterno" } }, "parameters": [ { "$ref": "#/components/parameters/VersaoApi" } ] } }, "/publico/precos/{pagId}": { "get": { "operationId": "listarPlanosDoSite", "tags": [ "consumidor" ], "summary": "Lista os planos e preços da consulta veicular do site", "description": "Retorna o catálogo de planos da consulta veicular exibido no site (nomes, preços e itens inclusos). O catálogo do funil principal usa pagId 1. O retorno inclui variantes de canal com nomes repetidos e preços distintos: para o fluxo do site, use os planos com PtId 1 (ex.: Consulta Básica, Simples e Completa) e ignore pacotes (PtId 2) e demais variantes. Use o PlaId escolhido em POST /publico/solicitar-pagamento. Não requer autenticação e não gera cobrança.", "security": [], "parameters": [ { "$ref": "#/components/parameters/VersaoApi" }, { "name": "pagId", "in": "path", "required": true, "description": "Identificador do catálogo de planos. O site usa 1 para o funil de consulta pela placa.", "schema": { "type": "integer", "examples": [ 1 ] } } ], "responses": { "200": { "description": "Catálogo de planos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanosSiteResponse" } } }, "headers": { "X-Api-Version": { "$ref": "#/components/headers/X-Api-Version" } } }, "500": { "$ref": "#/components/responses/ErroInterno" }, "400": { "description": "Requisição inválida (inclui X-Api-Version não suportado).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroResponse" } } } } } } }, "/publico/test-drive": { "post": { "operationId": "criarPreviaGratuita", "tags": [ "consumidor" ], "summary": "Cria a prévia gratuita de um veículo pela placa", "description": "Inicia a consulta gratuita (prévia) de um veículo: marca, modelo e ano, sem cadastro e sem custo. A resposta traz um id; acompanhe o resultado em GET /publico/test-drive/{id}. Protegido por antibot e limite de uso por IP: para volume, use a API contratada (B2B).", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "placa" ], "properties": { "placa": { "type": "string", "description": "Placa do veículo, formato antigo (ABC1234) ou Mercosul (ABC1D23).", "pattern": "^[A-Za-z]{3}[0-9][A-Za-z0-9][0-9]{2}$", "examples": [ "ABC1D23" ] } } } } } }, "responses": { "200": { "description": "Prévia criada (`status: true` com `id` para acompanhar) ou recusada (`status: false` com o motivo em `msg`, por exemplo limite gratuito excedido).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviaCriadaResponse" } } }, "headers": { "X-Api-Version": { "$ref": "#/components/headers/X-Api-Version" } } }, "500": { "$ref": "#/components/responses/ErroInterno" }, "400": { "description": "Requisição inválida (inclui X-Api-Version não suportado).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroResponse" } } } } }, "parameters": [ { "$ref": "#/components/parameters/VersaoApi" } ] } }, "/publico/test-drive/{id}": { "get": { "operationId": "obterPreviaGratuita", "tags": [ "consumidor" ], "summary": "Consulta o resultado da prévia gratuita", "description": "Retorna o resultado da prévia gratuita num envelope { status, aguardar, data }. Enquanto `aguardar` é true, o card em `data` vem mascarado (processando): repita a chamada a cada ~2 segundos. Quando `aguardar` é false, `data` traz marca, modelo, ano e cor legíveis (renavam e chassi seguem mascarados, disponíveis apenas no laudo pago) e `data.encontrado` diz se o veículo foi localizado.", "security": [], "parameters": [ { "$ref": "#/components/parameters/VersaoApi" }, { "name": "id", "in": "path", "required": true, "description": "Identificador retornado por POST /publico/test-drive.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Envelope do resultado; card válido quando `aguardar` é false.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviaResultadoResponse" } } }, "headers": { "X-Api-Version": { "$ref": "#/components/headers/X-Api-Version" } } }, "500": { "$ref": "#/components/responses/ErroInterno" }, "400": { "description": "Requisição inválida (inclui X-Api-Version não suportado).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroResponse" } } } } } } }, "/publico/solicitar-pagamento": { "post": { "operationId": "criarPagamentoPixConsulta", "tags": [ "consumidor" ], "summary": "Gera o pagamento Pix de uma consulta veicular", "description": "Cria a cobrança Pix de uma consulta veicular para a placa e o plano escolhidos. A resposta traz o codigo Pix copia e cola (brcode) e o QR code em base64; apresente ao cliente para pagar no app do banco. A confirmação é automática após o pagamento: acompanhe em GET /publico/solicitar-pagamento/{id}. O Pix expira em 4 horas. Sempre responde HTTP 200; erros de validação vêm com `status: false` e o motivo em `msg`. Rate limit: 30 requisições por IP a cada 10 minutos.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagamentoPixRequest" }, "examples": { "pix": { "summary": "Consulta Completa via Pix", "value": { "PlaId": 3, "email": "cliente@example.com", "nome": "Cliente Exemplo", "telefone": "11999998888", "placa": "ABC1D23", "metodo": "pix" } } } } } }, "responses": { "200": { "description": "Pix gerado (`status: true` com `dados.brcode`) ou recusado (`status: false` com o motivo em `msg`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagamentoPixCriadoResponse" } } }, "headers": { "X-Api-Version": { "$ref": "#/components/headers/X-Api-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } } }, "429": { "description": "Limite de requisições por IP excedido. Aguarde antes de tentar novamente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroResponse" } } }, "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "$ref": "#/components/responses/ErroInterno" }, "400": { "description": "Requisição inválida (inclui X-Api-Version não suportado).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroResponse" } } } } }, "parameters": [ { "$ref": "#/components/parameters/VersaoApi" } ] } }, "/publico/solicitar-pagamento/{id}": { "get": { "operationId": "verificarPagamentoPix", "tags": [ "consumidor" ], "summary": "Verifica o status do pagamento Pix", "description": "Consulta a situação do pagamento criado em POST /publico/solicitar-pagamento. Faça polling a cada poucos segundos. Importante: `status: true` na resposta significa apenas que a leitura funcionou; o pagamento está confirmado quando `liberado` vier true. Nesse momento a consulta veicular já foi criada automaticamente: o campo `ConId` (criptografado) é o identificador para acompanhar o laudo em GET /publico/consultas/{id}/status, e `transacaoToken` é o código de recuperação que o cliente também recebe por e-mail e SMS (utilizável em GET /publico/resultado-codigo/{codigo}).", "security": [], "parameters": [ { "$ref": "#/components/parameters/VersaoApi" }, { "name": "id", "in": "path", "required": true, "description": "Identificador da transação retornado na criação do Pix.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Situação atual da transação. Pagamento confirmado quando `liberado: true`; então `ConId` aponta a consulta gerada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagamentoStatusResponse" } } }, "headers": { "X-Api-Version": { "$ref": "#/components/headers/X-Api-Version" } } }, "500": { "$ref": "#/components/responses/ErroInterno" }, "400": { "description": "Requisição inválida (inclui X-Api-Version não suportado).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroResponse" } } } } } } }, "/publico/consultas/{id}/status": { "get": { "operationId": "acompanharConsultaVeicular", "tags": [ "consumidor" ], "summary": "Acompanha o processamento de uma consulta veicular paga", "description": "Retorna a situação do laudo de uma consulta paga: processando, concluida ou nao-localizada. Quando `aguarda` é false, o laudo está pronto no site. O cliente também recebe o resultado por e-mail com um código de recuperação.", "security": [], "parameters": [ { "$ref": "#/components/parameters/VersaoApi" }, { "name": "id", "in": "path", "required": true, "description": "Identificador criptografado da consulta: o campo `ConId` retornado por GET /publico/solicitar-pagamento/{id} após a confirmação (ou por GET /publico/resultado-codigo/{codigo}).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Situação da consulta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsultaSituacaoResponse" } } }, "headers": { "X-Api-Version": { "$ref": "#/components/headers/X-Api-Version" } } }, "500": { "$ref": "#/components/responses/ErroInterno" }, "400": { "description": "Requisição inválida (inclui X-Api-Version não suportado).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroResponse" } } } } } } }, "/publico/resultado-codigo/{codigo}": { "get": { "operationId": "recuperarConsultaPorCodigo", "tags": [ "consumidor" ], "summary": "Recupera uma consulta paga pelo código de acesso", "description": "Localiza uma consulta já paga pelo código de recuperação enviado por e-mail e SMS na compra. Útil quando o cliente perdeu o link do laudo. Rate limit: 30 requisições por IP a cada 5 minutos.", "security": [], "parameters": [ { "$ref": "#/components/parameters/VersaoApi" }, { "name": "codigo", "in": "path", "required": true, "description": "Código de recuperação recebido por e-mail ou SMS na compra (o mesmo valor de `transacaoToken` na resposta do status do pagamento).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Consulta localizada (`status: true` com o identificador do laudo) ou código inválido/não pago (`status: false`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResultadoCodigoResponse" } } }, "headers": { "X-Api-Version": { "$ref": "#/components/headers/X-Api-Version" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } } }, "429": { "description": "Limite de requisições por IP excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroResponse" } } }, "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "$ref": "#/components/responses/ErroInterno" }, "400": { "description": "Requisição inválida (inclui X-Api-Version não suportado).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroResponse" } } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key da empresa, obtida no portal do cliente (https://empresas.anycar.com.br) em Configurações. Envie o token puro no header `x-api-key`. Opcionalmente a empresa pode restringir o uso por whitelist de IP no mesmo portal." } }, "responses": { "NaoAutorizado": { "description": "API key ausente, inválida ou integração desativada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroResponse" } } } }, "AcessoNegado": { "description": "Acesso negado: IP fora da whitelist da empresa ou contrato suspenso por inadimplência.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroResponse" } } } }, "ErroInterno": { "description": "Erro interno do servidor. Nenhum dado sensível é exposto no corpo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErroResponse" } } } } }, "schemas": { "HealthResponse": { "type": "object", "description": "Resposta do health check.", "required": [ "status", "msg", "timestamp" ], "properties": { "status": { "type": "boolean", "description": "true quando a API está operacional." }, "msg": { "type": "string", "description": "Mensagem de status legível." }, "timestamp": { "type": "string", "format": "date-time", "description": "Data e hora do servidor em ISO 8601 (UTC)." } } }, "ErroResponse": { "type": "object", "description": "Formato padrão de erro da API. `status` é sempre false e `msg` explica o problema em português.", "required": [ "status", "msg" ], "properties": { "status": { "type": "boolean", "const": false, "description": "Sempre false em respostas de erro." }, "msg": { "type": "string", "description": "Descrição do erro e, quando aplicável, como resolver." }, "code": { "type": "string", "description": "Código estável do erro, presente em alguns cenários (ex.: contrato inadimplente)." } } }, "SaldoInsuficienteResponse": { "type": "object", "description": "Erro de saldo insuficiente em contas pré-pago, com o detalhamento do valor que falta.", "required": [ "status", "msg" ], "properties": { "status": { "type": "boolean", "const": false }, "msg": { "type": "string" }, "data": { "type": "object", "properties": { "saldoAtual": { "type": "number", "description": "Saldo atual da empresa em reais." }, "valorConsulta": { "type": "number", "description": "Valor da consulta solicitada em reais." }, "faltando": { "type": "number", "description": "Quanto falta de saldo em reais." } } } } }, "ConsultarRequest": { "type": "object", "description": "Corpo da consulta avulsa. Além dos campos listados, alguns tipos aceitam ou exigem campos próprios (ex.: `renavam`, `chassi`, `documento`); a validação indica no erro qual campo falta. Os tipos habilitados para a sua empresa estão em GET /api/status.", "required": [ "tipo" ], "properties": { "tipo": { "type": "string", "description": "Identificador do tipo de consulta contratado. Exemplos comuns: veicular-dados-basicos, veicular-dados-avancados, veicular-leilão-1, veicular-sinistro-1, veicular-gravame, veicular-roubo-furto, veicular-fipe, veicular-fipe-plus, veicular-recall, veicular-renajud-plus, veicular-renainf, veicular-indice-risco, veicular-histórico-proprietários, veicular-comunicado-venda.", "examples": [ "veicular-leilao-1", "veicular-sinistro-1", "veicular-fipe", "veicular-gravame", "veicular-dados-basicos" ] }, "placa": { "type": "string", "description": "Placa do veículo, formato antigo (ABC1234) ou Mercosul (ABC1D23). Obrigatória na maioria dos tipos veiculares.", "pattern": "^[A-Za-z]{3}[0-9][A-Za-z0-9][0-9]{2}$", "examples": [ "ABC1D23", "ABC1234" ] }, "pdf": { "type": "boolean", "default": false, "description": "Quando true e a consulta tem sucesso, gera um PDF do resultado e devolve a URL em `consulta.pdf`." } }, "additionalProperties": true }, "ConsultaMeta": { "type": "object", "description": "Metadados da execução da consulta.", "required": [ "id", "tempo", "debitado", "tipoFaturamento" ], "properties": { "id": { "type": "integer", "description": "Identificador único da consulta (protocolo). Guarde para auditoria e suporte." }, "tempo": { "type": "number", "description": "Tempo de processamento em segundos." }, "debitado": { "type": "boolean", "description": "true quando o valor foi debitado do saldo (pré-pago)." }, "saldoRestante": { "type": [ "number", "null" ], "description": "Saldo restante em reais após a consulta (null em contas pós-pago)." }, "tipoFaturamento": { "type": "string", "enum": [ "pre-pago", "pos-pago" ], "description": "Modelo de cobrança da empresa." }, "pdf": { "type": "string", "format": "uri", "description": "URL do PDF do resultado, presente quando o corpo da requisição enviou `pdf: true` e a consulta teve sucesso." } } }, "ConsultaResponse": { "type": "object", "description": "Resultado de uma consulta avulsa. `dados` varia conforme o tipo consultado.", "required": [ "status", "consulta", "msg" ], "properties": { "status": { "type": "boolean", "description": "true quando a consulta foi executada com sucesso." }, "consulta": { "$ref": "#/components/schemas/ConsultaMeta" }, "msg": { "type": "string", "description": "Mensagem sobre o resultado." }, "dados": { "description": "Payload do resultado, com estrutura própria de cada tipo de consulta." } } }, "ConsultaProcessandoResponse": { "type": "object", "description": "A consulta não concluiu dentro do tempo limite e segue processando em segundo plano. Não houve cobrança. Repita a MESMA chamada após o intervalo do header Retry-After; o resultado pronto é servido do cache sem custo duplicado.", "required": [ "status", "processando", "msg" ], "properties": { "status": { "type": "boolean", "const": false }, "processando": { "type": "boolean", "const": true }, "msg": { "type": "string" }, "consulta": { "type": "object", "properties": { "id": { "type": "integer", "description": "Protocolo da consulta em processamento." } } } } }, "StatusApisResponse": { "type": "object", "description": "Consultas habilitadas no contrato da empresa autenticada.", "required": [ "status", "consultadoEm", "total", "apis" ], "properties": { "status": { "type": "boolean" }, "consultadoEm": { "type": "string", "format": "date-time", "description": "Momento da leitura." }, "total": { "type": "integer", "description": "Quantidade de consultas habilitadas." }, "apis": { "type": "array", "items": { "$ref": "#/components/schemas/ApiHabilitada" } } } }, "ApiHabilitada": { "type": "object", "description": "Uma consulta habilitada no contrato.", "required": [ "tipo", "descricao", "status" ], "properties": { "tipo": { "type": "string", "description": "Valor a enviar no campo `tipo` de POST /api/consultar." }, "descricao": { "type": "string", "description": "Nome comercial da consulta." }, "categoria": { "type": [ "string", "null" ], "description": "Categoria da consulta (ex.: Veicular)." }, "grupo": { "type": [ "string", "null" ], "description": "Agrupamento da consulta." }, "status": { "type": "boolean", "description": "false quando a consulta está temporariamente indisponível." }, "saude": { "type": "integer", "description": "Indicador percentual de disponibilidade do servico." } } }, "PlanosLaudoResponse": { "type": "object", "description": "Planos de laudo disponíveis para a empresa.", "required": [ "status", "planos" ], "properties": { "status": { "type": "boolean" }, "msg": { "type": "string" }, "planos": { "type": "array", "items": { "$ref": "#/components/schemas/PlanoLaudo" } } } }, "PlanoLaudo": { "type": "object", "description": "Um plano de laudo veicular.", "required": [ "PlaId", "PlaNome", "PlaValor" ], "properties": { "PlaId": { "type": "integer", "description": "Identificador do plano. Use em POST /api/laudo/consultar." }, "PlaNome": { "type": "string", "description": "Nome do plano." }, "PlaValor": { "type": "number", "description": "Preço em reais. Já considera preço negociado da empresa quando existir." }, "PlaValorPromo": { "type": [ "number", "null" ], "description": "Preço promocional de tabela, quando aplicável." }, "personalizado": { "type": "boolean", "description": "true quando o preço retornado é negociado da empresa." }, "detalhes": { "type": "array", "description": "Itens inclusos no plano.", "items": { "type": "object", "properties": { "descricao": { "type": "string" }, "subdescricao": { "type": [ "string", "null" ] }, "status": { "type": "boolean", "description": "true quando o item esta incluso no plano." } } } } } }, "LaudoConsultarRequest": { "type": "object", "description": "Solicitação de laudo veicular.", "required": [ "PlaId", "placa" ], "properties": { "PlaId": { "type": "integer", "description": "Plano de laudo escolhido, obtido em GET /api/laudo/planos." }, "placa": { "type": "string", "description": "Placa do veículo, formato antigo ou Mercosul.", "pattern": "^[A-Za-z]{3}[0-9][A-Za-z0-9][0-9]{2}$" } } }, "LaudoCriadoResponse": { "type": "object", "description": "Confirmação da solicitação de laudo. O laudo pronto chega no webhook `laudos` configurado no portal do cliente.", "required": [ "status", "msg" ], "properties": { "status": { "type": "boolean" }, "msg": { "type": "string" }, "dados": { "description": "Dados da solicitação criada (protocolo e situação)." } } }, "VistoriaRequest": { "type": "object", "description": "Solicitação de vistoria veicular.", "required": [ "placa", "categoria" ], "properties": { "placa": { "type": "string", "description": "Placa do veículo, formato antigo ou Mercosul.", "pattern": "^[A-Za-z]{3}[0-9][A-Za-z0-9][0-9]{2}$" }, "categoria": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "integer", "description": "Identificador da categoria de vistoria habilitada para a empresa." } } } } }, "VistoriaCriadaResponse": { "type": "object", "description": "Confirmação da criação da vistoria.", "required": [ "status", "msg" ], "properties": { "status": { "type": "boolean" }, "msg": { "type": "string" }, "dados": { "description": "Dados da vistoria criada." } } }, "PlanosSiteResponse": { "type": "object", "description": "Catálogo de planos da consulta veicular do site.", "required": [ "status", "planos" ], "properties": { "status": { "type": "boolean" }, "planos": { "type": "array", "items": { "$ref": "#/components/schemas/PlanoSite" } } } }, "PlanoSite": { "type": "object", "description": "Um plano de consulta veicular vendido no site. Atenção: o catálogo traz variantes de canal com o MESMO nome e preços diferentes; o campo PtId distingue o tipo (1 = consulta avulsa do funil do site, 2 = pacotes da área do cliente; outros valores são variantes de canal). Para comprar o plano exibido no site, filtre PtId 1 e confirme o valor com o cliente antes de gerar o Pix.", "required": [ "PlaId", "PlaNome", "PlaValor" ], "properties": { "PlaId": { "type": "integer", "description": "Identificador do plano. Use em POST /publico/solicitar-pagamento." }, "PlaNome": { "type": "string", "description": "Nome do plano (ex.: Básica, Simples, Completa)." }, "PlaValor": { "type": "number", "description": "Preço em reais." }, "PlaValorPromo": { "type": [ "number", "null" ], "description": "Preço cheio de referência, quando o plano está em promoção." }, "detalhes": { "type": "array", "description": "Itens inclusos no plano.", "items": { "type": "object", "properties": { "descricao": { "type": "string" }, "status": { "type": "boolean", "description": "true quando o item está incluso." } } } }, "PtId": { "type": "integer", "description": "Tipo/canal do plano: 1 = consulta avulsa do funil do site; 2 = pacote da área do cliente; outros valores são variantes de canal." }, "PlaVisualizacao": { "type": "string", "description": "Canal de exibição do plano (ex.: ambos, minha-conta)." }, "PlaPrioridade": { "type": "integer", "description": "Ordem de exibição (menor aparece primeiro dentro do tipo)." } } }, "PreviaCriadaResponse": { "type": "object", "description": "Confirmação da criação da prévia gratuita.", "required": [ "status" ], "properties": { "status": { "type": "boolean" }, "id": { "type": "string", "description": "Identificador para acompanhar em GET /publico/test-drive/{id}." }, "msg": { "type": "string", "description": "Motivo, quando a prévia é recusada." } } }, "PagamentoPixRequest": { "type": "object", "description": "Dados para gerar o Pix de uma consulta veicular.", "required": [ "PlaId", "email", "nome", "telefone", "placa", "metodo" ], "properties": { "PlaId": { "type": "integer", "description": "Plano escolhido, de GET /publico/precos/1." }, "email": { "type": "string", "format": "email", "description": "E-mail do cliente; recebe o laudo e o código de recuperação." }, "nome": { "type": "string", "description": "Nome do cliente." }, "telefone": { "type": "string", "description": "Telefone celular do cliente, com DDD (apenas números)." }, "placa": { "type": "string", "description": "Placa do veículo a consultar.", "pattern": "^[A-Za-z]{3}[0-9][A-Za-z0-9][0-9]{2}$" }, "metodo": { "type": "string", "enum": [ "pix" ], "description": "Método de pagamento. Use pix; pagamento com cartão é exclusivo do site." }, "documento": { "type": [ "string", "null" ], "description": "CPF ou CNPJ do cliente (opcional)." } } }, "PagamentoPixCriadoResponse": { "type": "object", "description": "Cobrança Pix criada. Apresente `dados.brcode` (copia e cola) ou o QR code ao cliente.", "required": [ "status", "msg" ], "properties": { "status": { "type": "boolean" }, "msg": { "type": "string" }, "id": { "type": "string", "description": "Identificador da transação; use em GET /publico/solicitar-pagamento/{id}." }, "dados": { "type": "object", "properties": { "brcode": { "type": "string", "description": "Código Pix copia e cola." }, "brcode_base64": { "type": "string", "description": "QR code do Pix em PNG base64 (sem o prefixo data URI)." }, "dataExpira": { "type": "string", "format": "date-time", "description": "Validade do Pix (4 horas após a criação)." }, "valor": { "type": "number", "description": "Valor da cobrança em reais." } } } } }, "PagamentoStatusResponse": { "type": "object", "description": "Situação da transação Pix. Atenção à semântica: `status: true` significa apenas que a leitura foi feita com sucesso; quem indica pagamento confirmado é `liberado`. Faça polling até `liberado: true` e então use `ConId` para acompanhar o laudo.", "required": [ "status", "msg" ], "properties": { "status": { "type": "boolean", "description": "true quando a leitura da transação funcionou. NÃO indica pagamento; veja `liberado`." }, "msg": { "type": "string" }, "liberado": { "type": "boolean", "description": "true quando o Pix foi confirmado e a consulta veicular foi criada." }, "transacaoToken": { "type": "string", "description": "Código de recuperação da compra (vazio enquanto não pago). É o mesmo código que o cliente recebe por e-mail e SMS e que funciona em GET /publico/resultado-codigo/{codigo}. Guarde e entregue ao cliente." }, "ConId": { "type": [ "string", "null" ], "description": "Identificador criptografado da consulta veicular gerada (null enquanto não existir). Use este valor como {id} em GET /publico/consultas/{id}/status para acompanhar o laudo." } } }, "ConsultaSituacaoResponse": { "type": "object", "description": "Situação do processamento do laudo.", "required": [ "status", "msg" ], "properties": { "status": { "type": "boolean" }, "msg": { "type": "string" }, "aguarda": { "type": "boolean", "description": "true enquanto o laudo ainda está sendo processado." }, "situacao": { "type": "string", "enum": [ "processando", "concluida", "nao-localizada" ], "description": "Estado atual da consulta." } } }, "ResultadoCodigoResponse": { "type": "object", "description": "Resultado da recuperação por código.", "required": [ "status", "msg" ], "properties": { "status": { "type": "boolean" }, "msg": { "type": "string" }, "ConId": { "type": "string", "description": "Identificador criptografado da consulta. Mesmo formato usado em GET /publico/consultas/{id}/status e no acesso ao laudo no site." } } }, "PreviaResultadoResponse": { "type": "object", "description": "Resultado da prévia gratuita. O card em `data` só é válido quando `aguardar` é false; enquanto true, os campos vêm mascarados com asteriscos (processando). Faça polling até `aguardar: false`.", "required": [ "status", "aguardar", "data" ], "properties": { "status": { "type": "boolean", "description": "true quando a leitura funcionou (não indica veículo encontrado)." }, "aguardar": { "type": "boolean", "description": "true enquanto a prévia ainda está processando." }, "data": { "$ref": "#/components/schemas/PreviaCard" } } }, "PreviaCard": { "type": "object", "description": "Card do veículo da prévia gratuita. `encontrado` indica se o veículo foi localizado; renavam e chassi são sempre mascarados na prévia (disponíveis apenas no laudo pago).", "properties": { "status": { "type": "boolean" }, "encontrado": { "type": "boolean", "description": "true quando o veículo foi localizado." }, "placa": { "type": "string" }, "marca": { "type": "string" }, "modelo": { "type": "string" }, "anoModelo": { "type": "string" }, "anoFabricacao": { "type": "string" }, "cor": { "type": "string" }, "renavam": { "type": "string", "description": "Sempre mascarado na prévia; disponível apenas no laudo pago." }, "chassi": { "type": "string", "description": "Sempre mascarado na prévia; disponível apenas no laudo pago." }, "logo": { "type": [ "string", "null" ], "description": "URL do logo da marca, quando disponível." } } } }, "headers": { "RateLimit": { "description": "Campo estruturado IETF: \"\";r=;t=.", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "Politica do limite: \"\";q=;w=.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Cota da janela atual (compatibilidade).", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requisições restantes na janela (compatibilidade).", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos até a janela resetar (compatibilidade).", "schema": { "type": "integer" } }, "Retry-After": { "description": "Segundos a aguardar antes de repetir a requisição.", "schema": { "type": "integer" } }, "X-Api-Version": { "description": "Versão do contrato da API que gerou esta resposta.", "schema": { "type": "string", "const": "2" } } }, "parameters": { "VersaoApi": { "name": "X-Api-Version", "in": "header", "required": false, "description": "Fixa a versão do contrato. Valor atual: 2. Valor não suportado responde 400. Omitir equivale à versão atual.", "schema": { "type": "string", "enum": [ "2" ] } } } } }