{"openapi":"3.1.0","info":{"title":"Datacar API","version":"1.0.0","description":"API de dados de veículos do **Datacar** — preço FIPE, histórico e ficha técnica consolidados de\n**fontes abertas** (Tabela FIPE, Inmetro PBE Veicular, Wikidata, NHTSA vPIC), com identificação por\ncódigo FIPE, chassi (VIN) e placa.\n\nCada campo vem com **proveniência** (quais fontes concordam, quais divergem) e **confiança** de 0 a 1,\npara que seu sistema decida o que publicar automaticamente e o que revisar.\n\n### Autenticação\nEnvie sua chave em `Authorization: Bearer dc_live_…` (ou `X-API-Key`). Chaves `dc_test_…` são para homologação.\n\n### Limites\nCada chave tem um rate limit por minuto (headers `RateLimit-*`) e a organização tem uma cota mensal\n(headers `X-Quota-*`). Somente consultas que retornam dados consomem cota; `304 Not Modified`, `202`, `404`,\nvalidações e o catálogo FIPE são gratuitos. A consulta por placa consome mais unidades (provedor pago).\n\n### Erros\nTodos os erros seguem a RFC 9457 (`application/problem+json`) com um `code` estável.","contact":{"name":"Datacar","url":"https://datacar.digitalmart.com.br","email":"dev@datacar.digitalmart.com.br"}},"servers":[{"url":"https://datacar.digitalmart.com.br/api","description":"Produção"}],"security":[{"apiKey":[]}],"tags":[{"name":"Veículos","description":"Ficha completa por código FIPE e ano"},{"name":"Identificação","description":"Placa e chassi (VIN)"},{"name":"Busca","description":"Busca textual e filtros"},{"name":"Catálogo FIPE","description":"Marcas, modelos e anos para seletores"},{"name":"Sincronização","description":"Feed incremental (inclui a virada mensal da FIPE)"},{"name":"Webhooks","description":"Notificações assinadas de mudanças"},{"name":"Conta","description":"Consumo e limites"},{"name":"Utilitários","description":"Validação de código FIPE"}],"externalDocs":{"description":"Guia de integração","url":"https://0.0.0.0:3000/docs"},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Chave de API no formato `dc_live_…` ou `dc_test_…`."}},"schemas":{"VehicleResponse":{"type":"object","properties":{"data":{"anyOf":[{"$ref":"#/components/schemas/Vehicle"},{"$ref":"#/components/schemas/FlatVehicle"}]},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]},"Vehicle":{"type":"object","properties":{"id":{"type":"string","description":"Identificador estável: `<código FIPE>:<ano>-<combustível>`.","example":"005340-6:2015-3"},"fipe_code":{"type":"string","example":"005340-6"},"model_year":{"type":["integer","null"],"description":"null para 0 km.","example":2015},"zero_km":{"type":"boolean"},"fipe_fuel_code":{"type":"integer","description":"Combustível na FIPE: 1 gasolina, 2 álcool, 3 diesel, 4 elétrico, 5 flex, 6 híbrido.","example":3},"vehicle_type":{"type":["string","null"],"enum":["car","motorcycle","truck",null],"example":"car"},"brand":{"type":["string","null"],"example":"Volkswagen"},"model":{"type":["string","null"],"example":"Amarok"},"version":{"type":["string","null"],"example":"High.CD 2.0 16V TDI 4x4 Dies. Aut"},"fipe_description":{"type":["string","null"],"example":"AMAROK High.CD 2.0 16V TDI 4x4 Dies. Aut"},"fuel":{"type":["string","null"],"enum":["gasoline","ethanol","diesel","flex","electric","hybrid","plugin_hybrid","cng","other",null],"example":"diesel"},"body_type":{"type":["string","null"],"enum":["hatchback","sedan","wagon","suv","pickup","minivan","coupe","convertible","van","truck","bus","motorcycle","scooter","other",null],"example":"pickup"},"cabin":{"type":["string","null"],"enum":["single","extended","double",null],"description":"Somente picapes.","example":"double"},"doors":{"type":["integer","null"],"example":4},"seats":{"type":["integer","null"]},"engine":{"type":["object","null"],"properties":{"displacement_cc":{"type":["integer","null"]},"displacement_l":{"type":["number","null"]},"cylinders":{"type":["integer","null"]},"valves":{"type":["integer","null"]},"aspiration":{"type":["string","null"],"enum":["natural","turbo","supercharged",null]},"power_cv":{"type":["integer","null"]},"torque_kgfm":{"type":["number","null"]},"electric":{"type":["boolean","null"]},"hybrid":{"type":["boolean","null"]}},"required":["displacement_cc","displacement_l","cylinders","valves","aspiration","power_cv","torque_kgfm","electric","hybrid"],"example":{"displacement_cc":2000,"displacement_l":2,"cylinders":4,"valves":16,"aspiration":"turbo","power_cv":180,"torque_kgfm":42.8,"electric":false,"hybrid":false}},"transmission":{"type":["object","null"],"properties":{"type":{"type":["string","null"],"enum":["manual","automatic","cvt","automated","dct",null]},"gears":{"type":["integer","null"]}},"required":["type","gears"],"example":{"type":"automatic","gears":8}},"drivetrain":{"type":["string","null"],"enum":["4x2","4x4","awd",null],"example":"4x4"},"dimensions":{"type":["object","null"],"properties":{"length_mm":{"type":["integer","null"]},"width_mm":{"type":["integer","null"]},"height_mm":{"type":["integer","null"]},"wheelbase_mm":{"type":["integer","null"]}},"required":["length_mm","width_mm","height_mm","wheelbase_mm"]},"weight_kg":{"type":["integer","null"]},"trunk_l":{"type":["integer","null"]},"fuel_tank_l":{"type":["integer","null"]},"consumption":{"type":["object","null"],"properties":{"gasoline_city_km_l":{"type":["number","null"]},"gasoline_highway_km_l":{"type":["number","null"]},"ethanol_city_km_l":{"type":["number","null"]},"ethanol_highway_km_l":{"type":["number","null"]},"diesel_city_km_l":{"type":["number","null"]},"diesel_highway_km_l":{"type":["number","null"]},"range_km":{"type":["number","null"]},"co2_g_km":{"type":["number","null"]},"energy_rating":{"type":["string","null"],"enum":["A","B","C","D","E",null]}},"required":["gasoline_city_km_l","gasoline_highway_km_l","ethanol_city_km_l","ethanol_highway_km_l","diesel_city_km_l","diesel_highway_km_l","range_km","co2_g_km","energy_rating"],"description":"Inmetro PBE Veicular (km/l), autonomia de elétricos e classificação A–E."},"price":{"type":["object","null"],"properties":{"amount":{"type":"number"},"amount_cents":{"type":"integer"},"currency":{"type":"string","enum":["BRL"]},"reference_month":{"type":"string","example":"2026-10"},"fipe_reference":{"type":["string","null"],"description":"Tabela de referência FIPE.","example":"338"}},"required":["amount","amount_cents","currency","reference_month","fipe_reference"],"description":"Preço médio da Tabela FIPE no mês de referência mais recente."},"price_history":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string"},"amount":{"type":"number"},"amount_cents":{"type":"integer"}},"required":["month","amount","amount_cents"]},"description":"Histórico mensal do preço FIPE. Incluído com `include=history`."},"manufacturer":{"type":["string","null"],"example":"Grupo Volkswagen"},"country_of_origin":{"type":["string","null"]},"images":{"type":"object","properties":{"url":{"type":["string","null"],"format":"uri"},"alternatives":{"type":"array","items":{"type":"string","format":"uri"}}},"required":["url","alternatives"],"description":"Fotos ilustrativas do modelo (Wikimedia Commons, licenças livres)."},"fiscal":{"type":"object","properties":{"hs_code":{"type":["string","null"],"example":"8704.21"},"description":{"type":["string","null"]}},"required":["hs_code","description"],"description":"Subposição do SH (6 primeiros dígitos do NCM). Confirme com sua contabilidade."},"quality":{"type":"object","properties":{"score":{"type":"integer","minimum":0,"maximum":100,"description":"Completude ponderada pela confiança.","example":78},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/VehicleWarning"}}},"required":["score","warnings"]},"sources":{"type":"array","items":{"type":"string"},"description":"Fontes que contribuíram.","example":["parallelum","brasil-api","wikidata","inmetro-pbe"]},"provenance":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/FieldProvenance"},"description":"Proveniência por campo. Incluído com `include=provenance`."}},"required":["id","fipe_code","model_year","zero_km","fipe_fuel_code","vehicle_type","brand","model","version","fipe_description","fuel","body_type","cabin","doors","seats","engine","transmission","drivetrain","dimensions","weight_kg","trunk_l","fuel_tank_l","consumption","price","manufacturer","country_of_origin","images","fiscal","quality","sources"]},"VehicleWarning":{"type":"object","properties":{"code":{"type":"string","example":"conflict"},"field":{"type":"string","example":"price"},"message":{"type":"string","example":"Fontes divergem sobre preço FIPE: parallelum × brasil-api."}},"required":["code","message"]},"FieldProvenance":{"type":"object","properties":{"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Concordância ponderada entre as fontes (0–1).","example":0.97},"sources":{"type":"array","items":{"type":"string"},"description":"Fontes que concordam com o valor escolhido. `inferred:fipe` = lido da descrição FIPE.","example":["parallelum","brasil-api"]},"dissent":{"type":"array","items":{"type":"string"},"description":"Fontes que informaram um valor diferente.","example":[]}},"required":["confidence","sources","dissent"]},"FlatVehicle":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"description":"Projeção plana com chaves em português, pronta para DMS, ERPs e planilhas (`view=flat`).","example":{"id":"005340-6:2015-3","codigo_fipe":"005340-6","ano_modelo":2015,"marca":"Volkswagen","modelo":"Amarok","combustivel":"Diesel","carroceria":"Picape","cabine":"Dupla","motor_litros":2,"turbo":true,"cambio":"Automático","tracao":"4x4","preco_fipe":96781,"mes_referencia":"2026-10"}},"Meta":{"type":"object","properties":{"request_id":{"type":"string"},"revision":{"type":"integer","description":"Incrementa a cada mudança no conteúdo (inclusive preço FIPE)."},"updated_at":{"type":"string","format":"date-time"}},"required":["request_id"]},"Processing":{"type":"object","properties":{"status":{"type":"string","enum":["processing"]},"fipe_code":{"type":"string"},"retry_after_seconds":{"type":"integer"},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["status","fipe_code","retry_after_seconds","meta"]},"Problem":{"type":"object","properties":{"type":{"type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string","example":"invalid_fipe_code"},"detail":{"type":"string"},"instance":{"type":"string"},"request_id":{"type":"string"},"errors":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}},"required":["path","message"]}}},"required":["type","title","status","code","detail","instance"]},"FipeYear":{"type":"object","properties":{"id":{"type":"string","example":"005340-6:2015-3"},"year":{"type":"string","description":"Valor para o path `{year}`.","example":"2015-3"},"model_year":{"type":["integer","null"]},"zero_km":{"type":"boolean"},"fipe_fuel_code":{"type":"integer"},"fuel_label":{"type":["string","null"],"example":"Diesel"},"in_catalog":{"type":"boolean","description":"Já consolidado no Datacar (resposta imediata)."},"price":{"type":["object","null"],"properties":{"amount":{"type":"number"},"amount_cents":{"type":"integer"},"reference_month":{"type":"string"}},"required":["amount","amount_cents","reference_month"]}},"required":["id","year","model_year","zero_km","fipe_fuel_code","fuel_label","in_catalog","price"]},"BatchItem":{"type":"object","properties":{"input":{"type":"string"},"id":{"type":["string","null"]},"status":{"type":"string","enum":["ready","processing","not_found","invalid"]},"data":{"anyOf":[{"$ref":"#/components/schemas/Vehicle"},{"type":"object","additionalProperties":{}},{"type":"null"}]},"revision":{"type":["integer","null"]}},"required":["input","id","status","data","revision"]},"BatchRequest":{"type":"object","properties":{"vehicles":{"type":"array","items":{"type":"string","maxLength":30},"minItems":1,"maxItems":100,"description":"Itens `<código FIPE>:<ano>` (o combustível é opcional: `005340-6:2015`).","example":["005340-6:2015-3","004516-0:2023-5","004516-0:0km"]},"view":{"type":"string","enum":["full","flat"],"default":"full"},"include":{"type":"string"},"wait_ms":{"type":"integer","minimum":0,"maximum":15000,"default":0,"description":"Tempo máximo para consultar ao vivo os veículos ainda não catalogados. 0 = apenas enfileirar."}},"required":["vehicles"]},"SearchHit":{"type":"object","properties":{"score":{"type":"number"},"vehicle":{"$ref":"#/components/schemas/Vehicle"}},"required":["score","vehicle"]},"CatalogItem":{"type":"object","properties":{"code":{"type":"string","example":"59"},"name":{"type":"string","example":"VW - VolksWagen"}},"required":["code","name"]},"PlateFipeMatch":{"type":"object","properties":{"fipe_code":{"type":"string"},"description":{"type":["string","null"]},"model_year":{"type":["integer","null"]},"fipe_fuel_code":{"type":["integer","null"]},"score":{"type":["integer","null"],"description":"Similaridade informada pelo provedor (0–100)."},"vehicle_id":{"type":["string","null"],"description":"Use em GET /v1/vehicles/{fipe_code}/{year}."}},"required":["fipe_code","description","model_year","fipe_fuel_code","score","vehicle_id"]},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"description":{"type":["string","null"]},"events":{"type":"array","items":{"type":"string","enum":["vehicle.enriched","vehicle.updated"]}},"active":{"type":"boolean"},"disabled_reason":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}},"required":["id","url","description","events","active","disabled_reason","created_at"]}},"parameters":{}},"paths":{"/api/v1/vehicles/{fipe_code}/{year}":{"get":{"tags":["Veículos"],"summary":"Consultar veículo por código FIPE e ano","description":"Retorna a ficha consolidada: identificação, preço FIPE do mês, especificações (motor, câmbio, tração, carroceria, cabine, portas), consumo Inmetro, fotos, SH/NCM e proveniência por campo. Veículos ainda não catalogados são consultados ao vivo — se levar mais que `wait_ms`, a resposta é `202`. Respostas trazem `ETag`; envie `If-None-Match` para receber `304` sem consumir cota.","parameters":[{"schema":{"type":"string","minLength":7,"maxLength":10,"description":"Código FIPE, com ou sem hífen (o dígito verificador é conferido).","example":"005340-6"},"required":true,"description":"Código FIPE, com ou sem hífen (o dígito verificador é conferido).","name":"fipe_code","in":"path"},{"schema":{"type":"string","minLength":3,"maxLength":10,"description":"Ano modelo, opcionalmente com o código de combustível da FIPE (`2015-3`). Use `0km` para zero quilômetro. Sem combustível, o Datacar resolve o único (ou o primeiro) disponível.","example":"2015-3"},"required":true,"description":"Ano modelo, opcionalmente com o código de combustível da FIPE (`2015-3`). Use `0km` para zero quilômetro. Sem combustível, o Datacar resolve o único (ou o primeiro) disponível.","name":"year","in":"path"},{"schema":{"type":"string","enum":["full","flat"],"default":"full","description":"`flat` retorna a projeção plana em português."},"required":false,"description":"`flat` retorna a projeção plana em português.","name":"view","in":"query"},{"schema":{"type":"string","description":"Lista separada por vírgulas. Suportado: `provenance`, `history`.","example":"provenance,history"},"required":false,"description":"Lista separada por vírgulas. Suportado: `provenance`, `history`.","name":"include","in":"query"},{"schema":{"type":"string","description":"Campos de primeiro nível a retornar (sparse fieldset).","example":"id,brand,model,price"},"required":false,"description":"Campos de primeiro nível a retornar (sparse fieldset).","name":"fields","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":15000,"description":"Tempo máximo de espera pelo enriquecimento ao vivo de um veículo novo.","example":4000},"required":false,"description":"Tempo máximo de espera pelo enriquecimento ao vivo de um veículo novo.","name":"wait_ms","in":"query"}],"responses":{"200":{"description":"Veículo encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleResponse"}}}},"202":{"description":"Consulta em andamento — tente novamente após `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Processing"}}}},"304":{"description":"Não modificado desde o `ETag` informado"},"400":{"description":"Requisição inválida","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Chave ausente ou inválida","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Sem permissão (escopo ou IP)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Não encontrado","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit ou cota mensal excedidos","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Fontes temporariamente indisponíveis","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/vehicles/{fipe_code}":{"get":{"tags":["Veículos"],"summary":"Anos e combustíveis de um código FIPE","description":"Lista os anos modelo (e combustíveis) que a FIPE publica para o código, indicando quais já estão no catálogo do Datacar. Não consome cota.","parameters":[{"schema":{"type":"string","minLength":7,"maxLength":10,"description":"Código FIPE, com ou sem hífen (o dígito verificador é conferido).","example":"005340-6"},"required":true,"description":"Código FIPE, com ou sem hífen (o dígito verificador é conferido).","name":"fipe_code","in":"path"}],"responses":{"200":{"description":"Anos disponíveis, do mais novo para o mais antigo","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FipeYear"}},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]}}}},"400":{"description":"Requisição inválida","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Chave ausente ou inválida","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Sem permissão (escopo ou IP)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Não encontrado","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit ou cota mensal excedidos","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Fontes temporariamente indisponíveis","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/vehicles/{fipe_code}/{year}/prices":{"get":{"tags":["Veículos"],"summary":"Histórico de preços FIPE","description":"Série mensal do preço FIPE guardada pelo Datacar (os espelhos públicos só mantêm os últimos meses). Requer o veículo no catálogo; consome 1 consulta.","parameters":[{"schema":{"type":"string","minLength":7,"maxLength":10,"description":"Código FIPE, com ou sem hífen (o dígito verificador é conferido).","example":"005340-6"},"required":true,"description":"Código FIPE, com ou sem hífen (o dígito verificador é conferido).","name":"fipe_code","in":"path"},{"schema":{"type":"string","minLength":3,"maxLength":10,"description":"Ano modelo, opcionalmente com o código de combustível da FIPE (`2015-3`). Use `0km` para zero quilômetro. Sem combustível, o Datacar resolve o único (ou o primeiro) disponível.","example":"2015-3"},"required":true,"description":"Ano modelo, opcionalmente com o código de combustível da FIPE (`2015-3`). Use `0km` para zero quilômetro. Sem combustível, o Datacar resolve o único (ou o primeiro) disponível.","name":"year","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":240,"default":36},"required":false,"name":"months","in":"query"}],"responses":{"200":{"description":"Histórico, do mais antigo para o mais recente","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"prices":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string"},"amount":{"type":"number"},"amount_cents":{"type":"integer"}},"required":["month","amount","amount_cents"]}},"change_12m":{"type":["number","null"],"description":"Variação em 12 meses (fração; -0.08 = -8%).","example":-0.08}},"required":["id","prices","change_12m"]},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]}}}},"400":{"description":"Requisição inválida","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Chave ausente ou inválida","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Sem permissão (escopo ou IP)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Não encontrado","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit ou cota mensal excedidos","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/vehicles/batch":{"post":{"tags":["Veículos"],"summary":"Consultar até 100 veículos","description":"Ideal para cargas iniciais de estoque. Itens já catalogados retornam imediatamente; itens com combustível informado e ainda não catalogados são enfileirados (`processing`) — acompanhe pelo webhook `vehicle.enriched` ou repita a chamada. Só itens `ready` consomem cota.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchRequest"}}}},"responses":{"200":{"description":"Resultado por item, na mesma ordem da entrada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BatchItem"}},"summary":{"type":"object","properties":{"ready":{"type":"number"},"processing":{"type":"number"},"not_found":{"type":"number"},"invalid":{"type":"number"}},"required":["ready","processing","not_found","invalid"]},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","summary","meta"]}}}},"401":{"description":"Chave ausente ou inválida","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Sem permissão (escopo ou IP)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Parâmetros inválidos","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit ou cota mensal excedidos","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/vehicles/{fipe_code}/{year}/sources":{"get":{"tags":["Veículos"],"summary":"Evidências por fonte","description":"Registro normalizado que cada fonte retornou na última consulta — útil para auditoria e revisão humana. Requer o combustível no ano (`2015-3`).","parameters":[{"schema":{"type":"string","minLength":7,"maxLength":10,"description":"Código FIPE, com ou sem hífen (o dígito verificador é conferido).","example":"005340-6"},"required":true,"description":"Código FIPE, com ou sem hífen (o dígito verificador é conferido).","name":"fipe_code","in":"path"},{"schema":{"type":"string","minLength":3,"maxLength":10,"description":"Ano modelo, opcionalmente com o código de combustível da FIPE (`2015-3`). Use `0km` para zero quilômetro. Sem combustível, o Datacar resolve o único (ou o primeiro) disponível.","example":"2015-3"},"required":true,"description":"Ano modelo, opcionalmente com o código de combustível da FIPE (`2015-3`). Use `0km` para zero quilômetro. Sem combustível, o Datacar resolve o único (ou o primeiro) disponível.","name":"year","in":"path"}],"responses":{"200":{"description":"Registros por fonte","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"status":{"type":"string","enum":["ok","not_found","error"]},"record":{"type":["object","null"],"additionalProperties":{}},"error":{"type":["string","null"]},"latency_ms":{"type":["number","null"]},"fetched_at":{"type":"string","format":"date-time"}},"required":["source","status","record","error","latency_ms","fetched_at"]}},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]}}}},"400":{"description":"Requisição inválida","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Chave ausente ou inválida","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Sem permissão (escopo ou IP)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Não encontrado","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/vehicles/{fipe_code}/{year}/refresh":{"post":{"tags":["Veículos"],"summary":"Forçar nova consulta às fontes","description":"Reprocessa o veículo em todas as fontes com prioridade alta. Mudanças disparam o webhook `vehicle.updated`. Requer o combustível no ano (`2015-3`).","parameters":[{"schema":{"type":"string","minLength":7,"maxLength":10,"description":"Código FIPE, com ou sem hífen (o dígito verificador é conferido).","example":"005340-6"},"required":true,"description":"Código FIPE, com ou sem hífen (o dígito verificador é conferido).","name":"fipe_code","in":"path"},{"schema":{"type":"string","minLength":3,"maxLength":10,"description":"Ano modelo, opcionalmente com o código de combustível da FIPE (`2015-3`). Use `0km` para zero quilômetro. Sem combustível, o Datacar resolve o único (ou o primeiro) disponível.","example":"2015-3"},"required":true,"description":"Ano modelo, opcionalmente com o código de combustível da FIPE (`2015-3`). Use `0km` para zero quilômetro. Sem combustível, o Datacar resolve o único (ou o primeiro) disponível.","name":"year","in":"path"}],"responses":{"202":{"description":"Reprocessamento enfileirado","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["queued"]},"id":{"type":"string"},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["status","id","meta"]}}}},"400":{"description":"Requisição inválida","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Chave ausente ou inválida","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Sem permissão (escopo ou IP)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit ou cota mensal excedidos","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/fipe/{fipe_code}":{"get":{"tags":["Utilitários"],"summary":"Validar código FIPE","description":"Confere o formato e o dígito verificador e indica o tipo de veículo pela numeração. Não consome cota.","parameters":[{"schema":{"type":"string","minLength":7,"maxLength":10,"description":"Código FIPE, com ou sem hífen (o dígito verificador é conferido).","example":"005340-6"},"required":true,"description":"Código FIPE, com ou sem hífen (o dígito verificador é conferido).","name":"fipe_code","in":"path"}],"responses":{"200":{"description":"Código válido","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"fipe_code":{"type":"string"},"check_digit":{"type":"integer"},"vehicle_type":{"type":"string","enum":["car","motorcycle","truck"]}},"required":["fipe_code","check_digit","vehicle_type"]},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]}}}},"400":{"description":"Requisição inválida","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Chave ausente ou inválida","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/vehicles":{"get":{"tags":["Busca"],"summary":"Buscar veículos no catálogo","description":"Busca textual sem acento e tolerante a erros sobre marca, modelo e versão (entende abreviações da FIPE: \"turbo\" encontra \"TB\", \"automático\" encontra \"Aut.\"), com filtros por tipo, combustível, carroceria, ano e faixa de preço FIPE. Cobre os veículos já consolidados no Datacar.","parameters":[{"schema":{"type":"string","maxLength":200,"example":"onix 1.0 turbo automatico"},"required":false,"name":"q","in":"query"},{"schema":{"type":"string","maxLength":100,"example":"Chevrolet"},"required":false,"name":"brand","in":"query"},{"schema":{"type":"string","maxLength":100,"example":"Onix"},"required":false,"name":"model","in":"query"},{"schema":{"type":"string","enum":["car","motorcycle","truck"]},"required":false,"name":"vehicle_type","in":"query"},{"schema":{"type":"string","enum":["gasoline","ethanol","diesel","flex","electric","hybrid","plugin_hybrid","cng","other"]},"required":false,"name":"fuel","in":"query"},{"schema":{"type":"string","enum":["hatchback","sedan","wagon","suv","pickup","minivan","coupe","convertible","van","truck","bus","motorcycle","scooter","other"]},"required":false,"name":"body_type","in":"query"},{"schema":{"type":"integer","minimum":1950,"maximum":2100},"required":false,"name":"year_from","in":"query"},{"schema":{"type":"integer","minimum":1950,"maximum":2100},"required":false,"name":"year_to","in":"query"},{"schema":{"type":["number","null"],"minimum":0,"description":"Em reais.","example":50000},"required":false,"description":"Em reais.","name":"price_min","in":"query"},{"schema":{"type":["number","null"],"minimum":0,"description":"Em reais.","example":120000},"required":false,"description":"Em reais.","name":"price_max","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":100},"required":false,"name":"min_quality","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":1000,"default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Resultados ordenados por relevância","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SearchHit"}},"has_more":{"type":"boolean"},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","has_more","meta"]}}}},"400":{"description":"Requisição inválida","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Chave ausente ou inválida","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Sem permissão (escopo ou IP)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Parâmetros inválidos","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit ou cota mensal excedidos","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/changes":{"get":{"tags":["Sincronização"],"summary":"Feed de alterações (sincronização incremental)","description":"Lista veículos alterados desde `since` — inclusive a atualização mensal do preço FIPE —, do mais antigo para o mais recente, com paginação por cursor estável. Guarde o `next_cursor` e chame periodicamente. Com `scope=catalog` (padrão) retorna apenas veículos que sua organização já consultou (sem custo); `scope=all` cobra 1 consulta por item.","parameters":[{"schema":{"type":"string","format":"date-time","example":"2026-10-01T00:00:00Z"},"required":false,"name":"since","in":"query"},{"schema":{"type":"string","maxLength":200},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["catalog","all"],"default":"catalog"},"required":false,"name":"scope","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Página do feed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"revision":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"},"vehicle":{"$ref":"#/components/schemas/Vehicle"}},"required":["revision","updated_at","vehicle"]}},"next_cursor":{"type":["string","null"],"description":"Null quando não há mais itens. Guarde o último cursor recebido."},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","next_cursor","meta"]}}}},"400":{"description":"Requisição inválida","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Chave ausente ou inválida","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Sem permissão (escopo ou IP)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Parâmetros inválidos","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit ou cota mensal excedidos","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/catalog/{vehicle_type}/brands":{"get":{"tags":["Catálogo FIPE"],"summary":"Marcas","description":"Marcas da Tabela FIPE para o tipo de veículo. Para seletores em cascata; não consome cota.","parameters":[{"schema":{"type":"string","enum":["car","motorcycle","truck"],"description":"`car`, `motorcycle` ou `truck`.","example":"car"},"required":true,"description":"`car`, `motorcycle` ou `truck`.","name":"vehicle_type","in":"path"}],"responses":{"200":{"description":"Marcas","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogItem"}},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]}}}},"400":{"description":"Requisição inválida","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Chave ausente ou inválida","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Sem permissão (escopo ou IP)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Não encontrado","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit ou cota mensal excedidos","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Fontes temporariamente indisponíveis","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/catalog/{vehicle_type}/brands/{brand_id}/models":{"get":{"tags":["Catálogo FIPE"],"summary":"Modelos de uma marca","description":"Cada modelo da FIPE corresponde a uma versão (um código FIPE). Não consome cota.","parameters":[{"schema":{"type":"string","enum":["car","motorcycle","truck"],"description":"`car`, `motorcycle` ou `truck`.","example":"car"},"required":true,"description":"`car`, `motorcycle` ou `truck`.","name":"vehicle_type","in":"path"},{"schema":{"type":"string","pattern":"^\\d{1,6}$","example":"59"},"required":true,"name":"brand_id","in":"path"}],"responses":{"200":{"description":"Modelos","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogItem"}},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]}}}},"400":{"description":"Requisição inválida","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Chave ausente ou inválida","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Sem permissão (escopo ou IP)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Não encontrado","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit ou cota mensal excedidos","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Fontes temporariamente indisponíveis","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/catalog/{vehicle_type}/brands/{brand_id}/models/{model_id}/years":{"get":{"tags":["Catálogo FIPE"],"summary":"Anos de um modelo","description":"Anos modelo e combustível (`2015-3`, `32000-5` = 0 km). Para chegar à ficha, use GET /v1/vehicles/{fipe_code}/{year}; o código FIPE vem na primeira consulta ou em GET /v1/vehicles?brand=…","parameters":[{"schema":{"type":"string","enum":["car","motorcycle","truck"],"description":"`car`, `motorcycle` ou `truck`.","example":"car"},"required":true,"description":"`car`, `motorcycle` ou `truck`.","name":"vehicle_type","in":"path"},{"schema":{"type":"string","pattern":"^\\d{1,6}$","example":"59"},"required":true,"name":"brand_id","in":"path"},{"schema":{"type":"string","pattern":"^\\d{1,8}$","example":"5585"},"required":true,"name":"model_id","in":"path"}],"responses":{"200":{"description":"Anos","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogItem"}},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]}}}},"400":{"description":"Requisição inválida","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Chave ausente ou inválida","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Sem permissão (escopo ou IP)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Não encontrado","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit ou cota mensal excedidos","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Fontes temporariamente indisponíveis","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/plates/{plate}":{"get":{"tags":["Identificação"],"summary":"Identificar veículo pela placa","description":"Placa antiga (ABC1234) ou Mercosul (ABC1D23). Retorna marca, modelo, anos, cor, combustível, município/UF, situação e os códigos FIPE compatíveis; com `include=vehicle` traz também a ficha completa da melhor correspondência.\n\nNão há base aberta de placas no Brasil: a consulta usa um provedor parceiro e **consome mais de uma consulta** da cota quando encontra a placa (10 por padrão, configurável). Nenhum dado do proprietário é retornado ou guardado; o chassi vem mascarado. Requer o escopo `plates:read`.","parameters":[{"schema":{"type":"string","minLength":7,"maxLength":8,"example":"ABC1D23"},"required":true,"name":"plate","in":"path"},{"schema":{"type":"string","enum":["vehicle"]},"required":false,"name":"include","in":"query"}],"responses":{"200":{"description":"Placa encontrada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"plate":{"type":"string","description":"Formato Mercosul.","example":"ABC1C34"},"plate_old_format":{"type":["string","null"],"example":"ABC1234"},"brand":{"type":["string","null"]},"model":{"type":["string","null"]},"version":{"type":["string","null"]},"manufacture_year":{"type":["integer","null"]},"model_year":{"type":["integer","null"]},"color":{"type":["string","null"]},"fuel":{"type":["string","null"]},"vin_masked":{"type":["string","null"],"example":"9BW**********3456"},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"situation":{"type":["string","null"]},"fipe_matches":{"type":"array","items":{"$ref":"#/components/schemas/PlateFipeMatch"}},"vehicle":{"allOf":[{"$ref":"#/components/schemas/Vehicle"},{"type":["object","null"]}]}},"required":["plate","plate_old_format","brand","model","version","manufacture_year","model_year","color","fuel","vin_masked","city","state","situation","fipe_matches"]},"meta":{"allOf":[{"$ref":"#/components/schemas/Meta"},{"type":"object","properties":{"cached":{"type":"boolean"}},"required":["cached"]}]}},"required":["data","meta"]}}}},"400":{"description":"Requisição inválida","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Chave ausente ou inválida","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Sem permissão (escopo ou IP)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Não encontrado","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit ou cota mensal excedidos","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"501":{"description":"Recurso não habilitado neste ambiente","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Fontes temporariamente indisponíveis","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/vin/{vin}":{"get":{"tags":["Identificação"],"summary":"Decodificar chassi (VIN)","description":"Lê a estrutura ISO 3779 do chassi (fabricante pelo WMI, país, ano modelo, fábrica, dígito verificador) e consulta a base aberta NHTSA vPIC. Sugere as versões FIPE do catálogo compatíveis. Consome 1 consulta quando a vPIC identifica o veículo; só a leitura local é gratuita.","parameters":[{"schema":{"type":"string","minLength":17,"maxLength":20,"example":"9BWAB45U3FT123456"},"required":true,"name":"vin","in":"path"}],"responses":{"200":{"description":"Chassi decodificado","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"vin":{"type":"string"},"wmi":{"type":"string"},"manufacturer":{"type":["string","null"]},"region":{"type":["string","null"]},"model_year":{"type":["integer","null"]},"model_year_candidates":{"type":"array","items":{"type":"integer"}},"plant_code":{"type":"string"},"serial":{"type":"string"},"check_digit_valid":{"type":["boolean","null"],"description":"Obrigatório só na América do Norte; null quando a 9ª posição não é um dígito."},"decoded":{"type":["object","null"],"properties":{"make":{"type":["string","null"]},"model":{"type":["string","null"]},"trim":{"type":["string","null"]},"model_year":{"type":["integer","null"]},"vehicle_type":{"type":["string","null"]},"body_type":{"type":["string","null"]},"doors":{"type":["integer","null"]},"displacement_cc":{"type":["integer","null"]},"cylinders":{"type":["integer","null"]},"power_cv":{"type":["integer","null"]},"fuel":{"type":["string","null"]},"drivetrain":{"type":["string","null"]},"transmission":{"type":["string","null"]},"plant_country":{"type":["string","null"]}},"required":["make","model","trim","model_year","vehicle_type","body_type","doors","displacement_cc","cylinders","power_cv","fuel","drivetrain","transmission","plant_country"],"description":"NHTSA vPIC (domínio público). null quando indisponível."},"fipe_candidates":{"type":"array","items":{"type":"object","properties":{"vehicle_id":{"type":"string"},"fipe_description":{"type":["string","null"]},"model_year":{"type":["integer","null"]},"price_cents":{"type":["integer","null"]}},"required":["vehicle_id","fipe_description","model_year","price_cents"]}}},"required":["vin","wmi","manufacturer","region","model_year","model_year_candidates","plant_code","serial","check_digit_valid","decoded","fipe_candidates"]},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]}}}},"400":{"description":"Requisição inválida","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Chave ausente ou inválida","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Sem permissão (escopo ou IP)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit ou cota mensal excedidos","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/usage":{"get":{"tags":["Conta"],"summary":"Consumo do mês","responses":{"200":{"description":"Consumo e limites","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"organization":{"type":"string"},"period":{"type":"string","example":"2026-10"},"quota":{"type":"integer"},"used":{"type":"integer"},"remaining":{"type":"integer"},"rate_limit_per_minute":{"type":"integer"},"key":{"type":"object","properties":{"id":{"type":"string"},"environment":{"type":"string","enum":["live","test"]},"scopes":{"type":"array","items":{"type":"string"}}},"required":["id","environment","scopes"]}},"required":["organization","period","quota","used","remaining","rate_limit_per_minute","key"]},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]}}}},"401":{"description":"Chave ausente ou inválida","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Sem permissão (escopo ou IP)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/webhooks":{"get":{"tags":["Webhooks"],"summary":"Listar endpoints","responses":{"200":{"description":"Endpoints","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]}}}},"401":{"description":"Chave ausente ou inválida","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Sem permissão (escopo ou IP)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"tags":["Webhooks"],"summary":"Cadastrar endpoint","description":"O `secret` de assinatura é exibido **somente nesta resposta**. Use-o para validar o header `Datacar-Signature` (HMAC-SHA256). A URL precisa ser HTTPS e pública.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2000,"format":"uri","example":"https://erp.minhalivraria.com.br/webhooks/datacar"},"events":{"type":"array","items":{"type":"string","enum":["vehicle.enriched","vehicle.updated"]},"minItems":1,"example":["vehicle.updated","vehicle.enriched"]},"description":{"type":"string","maxLength":200}},"required":["url","events"]}}}},"responses":{"201":{"description":"Endpoint criado","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/WebhookEndpoint"},{"type":"object","properties":{"secret":{"type":"string","example":"whsec_…"}},"required":["secret"]}]},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]}}}},"400":{"description":"Requisição inválida","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Chave ausente ou inválida","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Sem permissão (escopo ou IP)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Parâmetros inválidos","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/webhooks/{id}":{"delete":{"tags":["Webhooks"],"summary":"Remover endpoint","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Removido"},"401":{"description":"Chave ausente ou inválida","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Sem permissão (escopo ou IP)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Não encontrado","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"webhooks":{}}