{"openapi":"3.0.3","info":{"title":"ZapCar API","version":"1.0.0","description":"API de consulta veicular e documentação para integradores. Autenticação por chave Bearer (zc_live_…), gerada no Portal do Cliente. Documentação: https://www.zapcarconsulta.com.br/api-integradores/docs","contact":{"name":"ZapCar","url":"https://www.zapcarconsulta.com.br/fale-conosco","email":"suporte@zapcarconsulta.com.br"}},"servers":[{"url":"https://api.zapcarconsulta.com.br"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"v1","description":"API pública versionada"}],"paths":{"/v1/servicos":{"get":{"operationId":"listarServicos","summary":"Catálogo de serviços e preços","description":"Lista os serviços disponíveis para a conta, com os campos exigidos e o preço que será debitado (já com preço personalizado e Grupo de Desconto da API, quando houver).","tags":["v1"],"responses":{"200":{"description":"Catálogo."}}}},"/v1/saldo":{"get":{"operationId":"consultarSaldo","summary":"Saldo da carteira","description":"Saldo atual da conta em reais.","tags":["v1"],"responses":{"200":{"description":"Saldo."}}}},"/v1/consultas":{"post":{"operationId":"criarConsulta","summary":"Criar consulta (assíncrona)","description":"Debita o saldo e enfileira a consulta. Acompanhe por GET /v1/consultas/{id} (polling) ou pelo webhook query.completed / query.failed. Envie Idempotency-Key para repetir com segurança.","tags":["v1"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"Repetir a mesma requisição com a mesma chave devolve o mesmo resultado sem cobrar de novo."}],"responses":{"201":{"description":"Consulta criada: { id, status: \"processando\", valor_cobrado }."},"400":{"description":"Dados inválidos."},"402":{"description":"Saldo insuficiente."},"422":{"description":"Serviço indisponível."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["servico"],"properties":{"servico":{"type":"string","enum":["consulta","consulta-completa","gravame","renajud","debitos","debitos-estadual","decodificacao-chassi","decodificacao-motor","score-credito","codigo-seguranca","atpve","crlv"],"description":"Slug do serviço (ver GET /v1/servicos)."},"placa":{"type":"string","example":"ABC1D23"},"uf":{"type":"string","example":"SP","description":"Exigida em crlv e debitos-estadual."},"renavam":{"type":"string","description":"Exigido em codigo-seguranca e em algumas UFs do CRLV."},"cpf":{"type":"string","description":"Exigido em algumas UFs do CRLV."},"chassi":{"type":"string","description":"decodificacao-chassi."},"motor":{"type":"string","description":"decodificacao-motor."},"documento":{"type":"string","description":"CPF/CNPJ — score-credito."},"incluir_fipe":{"type":"boolean","description":"Só consulta-completa: embute a Tabela FIPE (cobra o preço da FIPE junto)."}}},"example":{"servico":"consulta-completa","placa":"ABC1D23"}}}}}},"/v1/consultas/{id}":{"get":{"operationId":"statusConsulta","summary":"Status e resultado da consulta","description":"Devolve status (processando | concluido | erro) e, quando concluída, os dados e a URL do PDF.","tags":["v1"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Consulta."},"404":{"description":"Não encontrada para esta conta."}}}},"/v1/consultas/{id}/pdf":{"get":{"operationId":"baixarPdf","summary":"PDF da consulta","description":"Baixa o documento em PDF (binário).","tags":["v1"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"application/pdf"},"400":{"description":"Ainda em processamento (retryable)."}}}},"/v1/consultas/{id}/imagens/{tipo}/{indice}":{"get":{"operationId":"baixarImagem","summary":"Imagem da Consulta Completa","description":"Fotos de leilão e laudo CSV (tipo: leilao | outra | csv-imagem | csv-pdf).","tags":["v1"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"tipo","in":"path","required":true,"schema":{"type":"string"}},{"name":"indice","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Imagem/PDF."},"404":{"description":"Imagem inexistente."}}}},"/v1/fipe":{"post":{"operationId":"consultarFipe","summary":"Tabela FIPE por placa (síncrono)","description":"Devolve os valores FIPE na mesma chamada (sem id, sem polling, sem PDF). Cobrado por requisição; estornado se falhar ou não houver FIPE.","tags":["v1"],"responses":{"200":{"description":"Valores FIPE."},"404":{"description":"Sem FIPE para a placa (estornado)."},"502":{"description":"Falha na fonte (estornado)."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["placa"],"properties":{"placa":{"type":"string","example":"ABC1D23"}}},"example":{"placa":"ABC1D23"}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"zc_live_<64 hex>"}},"schemas":{"Erro":{"type":"object","required":["erro","codigo","retryable"],"properties":{"erro":{"type":"string"},"codigo":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","CUSTOMER_NOT_FOUND","SERVICO_INVALIDO","VALIDATION_ERROR","PLACA_INVALIDA","RENAVAM_INVALIDO","DOCUMENTO_INVALIDO","CHASSI_INVALIDO","MOTOR_INVALIDO","UF_INVALIDA","UF_INDISPONIVEL","CRLV_DADOS_OBRIGATORIOS","DEBITOS_DADOS_OBRIGATORIOS","SERVICO_INDISPONIVEL","IDEMPOTENCY_KEY_INVALIDA","IDEMPOTENCY_KEY_REUSED","IDEMPOTENCY_IN_PROGRESS","SALDO_INSUFICIENTE","CONSULTA_NOT_FOUND","PDF_NOT_READY","PDF_NOT_FOUND","CONSULTA_WITHOUT_DATA","DOCUMENTO_CORROMPIDO","IMAGEM_NOT_FOUND","IMAGEM_TIPO_INVALIDO","IMAGEM_INDICE_INVALIDO","FIPE_INDISPONIVEL","FIPE_ERRO","FIPE_NAO_DISPONIVEL","RATE_LIMITED","CIRCUIT_OPEN","PROVIDER_TIMEOUT","INTERNAL_ERROR","ROTA_NAO_ENCONTRADA"]},"retryable":{"type":"boolean","description":"true = vale repetir a mesma chamada (falha transitória)."},"request_id":{"type":"string"}}}}},"x-codigos-de-erro":{"MISSING_API_KEY":{"http":401,"retryable":false,"descricao":"Cabeçalho Authorization: Bearer <chave> ausente."},"INVALID_API_KEY":{"http":401,"retryable":false,"descricao":"Chave de API inválida ou revogada."},"CUSTOMER_NOT_FOUND":{"http":401,"retryable":false,"descricao":"Conta associada à chave não encontrada."},"SERVICO_INVALIDO":{"http":400,"retryable":false,"descricao":"Slug de serviço desconhecido."},"VALIDATION_ERROR":{"http":400,"retryable":false,"descricao":"Corpo da requisição inválido."},"PLACA_INVALIDA":{"http":400,"retryable":false,"descricao":"Placa em formato inválido."},"RENAVAM_INVALIDO":{"http":400,"retryable":false,"descricao":"RENAVAM inválido."},"DOCUMENTO_INVALIDO":{"http":400,"retryable":false,"descricao":"CPF/CNPJ inválido."},"CHASSI_INVALIDO":{"http":400,"retryable":false,"descricao":"Chassi inválido."},"MOTOR_INVALIDO":{"http":400,"retryable":false,"descricao":"Número do motor inválido."},"UF_INVALIDA":{"http":400,"retryable":false,"descricao":"UF inválida."},"UF_INDISPONIVEL":{"http":400,"retryable":false,"descricao":"UF indisponível para o serviço."},"CRLV_DADOS_OBRIGATORIOS":{"http":400,"retryable":false,"descricao":"Faltam campos exigidos pela UF (CPF/RENAVAM)."},"DEBITOS_DADOS_OBRIGATORIOS":{"http":400,"retryable":false,"descricao":"Faltam campos exigidos pela UF."},"SERVICO_INDISPONIVEL":{"http":422,"retryable":false,"descricao":"Serviço sem preço/indisponível para a conta."},"IDEMPOTENCY_KEY_INVALIDA":{"http":400,"retryable":false,"descricao":"Idempotency-Key fora do formato (8–255 chars)."},"IDEMPOTENCY_KEY_REUSED":{"http":422,"retryable":false,"descricao":"Mesma Idempotency-Key com payload diferente."},"IDEMPOTENCY_IN_PROGRESS":{"http":409,"retryable":true,"descricao":"Requisição idêntica ainda em processamento; repita em instantes."},"SALDO_INSUFICIENTE":{"http":402,"retryable":false,"descricao":"Saldo insuficiente na carteira."},"CONSULTA_NOT_FOUND":{"http":404,"retryable":false,"descricao":"Consulta não encontrada para esta conta."},"PDF_NOT_READY":{"http":400,"retryable":true,"descricao":"Documento ainda em processamento; tente novamente."},"PDF_NOT_FOUND":{"http":404,"retryable":false,"descricao":"PDF não disponível para esta consulta."},"CONSULTA_WITHOUT_DATA":{"http":400,"retryable":false,"descricao":"Consulta sem dados para gerar o documento."},"DOCUMENTO_CORROMPIDO":{"http":422,"retryable":false,"descricao":"O documento armazenado não é um arquivo válido (PDF/PNG/JPEG). Refaça a consulta — repetir o download não resolve."},"IMAGEM_NOT_FOUND":{"http":404,"retryable":false,"descricao":"Imagem inexistente para esta consulta. Consultas concluídas antes de 27/08/2026 não têm imagens armazenadas — reprocesse a consulta."},"IMAGEM_TIPO_INVALIDO":{"http":400,"retryable":false,"descricao":"Tipo de imagem desconhecido. Use leilao, outra, csv-imagem ou csv-pdf."},"IMAGEM_INDICE_INVALIDO":{"http":400,"retryable":false,"descricao":"Índice de imagem inválido (inteiro >= 0)."},"FIPE_INDISPONIVEL":{"http":503,"retryable":true,"descricao":"Provedor FIPE temporariamente indisponível."},"FIPE_ERRO":{"http":502,"retryable":true,"descricao":"Falha transitória ao consultar a FIPE."},"FIPE_NAO_DISPONIVEL":{"http":404,"retryable":false,"descricao":"Sem FIPE para esta placa."},"RATE_LIMITED":{"http":429,"retryable":true,"descricao":"Limite de requisições excedido."},"CIRCUIT_OPEN":{"http":503,"retryable":true,"descricao":"Fornecedor temporariamente indisponível (circuito aberto)."},"PROVIDER_TIMEOUT":{"http":504,"retryable":true,"descricao":"Tempo de resposta do fornecedor excedido."},"INTERNAL_ERROR":{"http":500,"retryable":true,"descricao":"Erro interno inesperado."},"ROTA_NAO_ENCONTRADA":{"http":404,"retryable":false,"descricao":"Rota inexistente."}},"x-webhooks":{"eventos":["query.completed","query.failed"],"assinatura":"HMAC-SHA256 de \"<timestamp>.<corpo bruto>\" com o secret do endpoint, no cabeçalho de assinatura; retry com backoff exponencial."}}