{ "openapi": "3.1.0", "info": { "title": "Precellence Service — public quote API (read-only)", "version": "1.0.0", "summary": "Prices and conditions of a private chauffeur service in Paris, for AI agents and assistants.", "description": "Read-only API for AI agents and assistants: prices including VAT per vehicle for a trip in Paris and the Île-de-France region (same pricing engine as the website), and the service conditions.\n\nNo key, no account, no personal data. Booking and payment ALWAYS happen on the website: send the traveller to `booking_url` (pre-filled booking link); the website recomputes the same price and guarantees it for 20 minutes. Never take a payment in the conversation.\n\nLimits: 30 units per hour and 200 per day per IP address (1 per computed request, plus 1 for the Google address lookup and 1 for the Google route when they are needed); identical requests within 10 minutes return the same cached answer at no cost. Online booking requires at least 2 h notice.", "contact": { "name": "Precellence Service", "email": "partnerships@precellence-service.com", "url": "https://precellence-service.com/en/developpeurs" }, "termsOfService": "https://precellence-service.com/en/cgv" }, "servers": [ { "url": "https://precellence-service.com" } ], "externalDocs": { "description": "Developers and AI assistants", "url": "https://precellence-service.com/en/developpeurs" }, "x-booking-url": { "description": "Pre-filled booking link: opens the website booking form with the trip filled in and the class selected; the price is recomputed by the server. Payment on the website only.", "template": "https://precellence-service.com/reservation?from={from}&to={to}&date={YYYY-MM-DD}&time={HH:MM}&pax={1-7}&class={business|electric|first|van|ev}&lang={fr|en|ar}", "hourly_template": "https://precellence-service.com/reservation?type=hourly&duration={3-12}&from={address}&date={YYYY-MM-DD}&time={HH:MM}&lang={fr|en|ar}", "example": "https://precellence-service.com/en/reservation?from=15+Avenue+Montaigne%2C+Paris&to=A%C3%A9roport+CDG&date=2026-11-20&time=09%3A30&pax=2&class=first&lang=en", "languages": { "fr": "https://precellence-service.com/reservation", "en": "https://precellence-service.com/en/reservation", "ar": "https://precellence-service.com/ar/reservation" } }, "x-payment": "website_only", "paths": { "/api/public/quote": { "get": { "operationId": "getQuote", "summary": "Price a trip (prices including VAT per vehicle class) and get the pre-filled booking link", "description": "Same parameters as the pre-filled booking link. Addresses are plain text (street number and street, hotel, station, airport, terminal); vague addresses return status `on_request` with a reason. Open CORS (GET). Rate limit: 30/hour and 200/day per IP (variables PUBLIC_QUOTE_RATE_LIMIT_HOUR / PUBLIC_QUOTE_RATE_LIMIT_DAY). Cache: 600 s.", "x-rate-limit": { "per_ip_per_hour": 30, "per_ip_per_day": 200, "units": "1 per computed request, + 1 when Google looks up the text addresses, + 1 when Google computes the route (place and route caches make repeated trips cheaper); cached answers are free", "cache_seconds": 600 }, "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 300 }, "description": "Pickup: address, place, airport or station, as text.", "example": "15 Avenue Montaigne, Paris" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 300 }, "description": "Drop-off, as text. Required unless type=hourly.", "example": "Aéroport CDG" }, { "name": "date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "description": "Pickup date (Paris), YYYY-MM-DD.", "example": "2026-11-20" }, { "name": "time", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,2}[:hH]\\d{2}$" }, "description": "Pickup time (Europe/Paris), HH:MM (9:30 and 9h30 accepted).", "example": "09:30" }, { "name": "pax", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 7 }, "description": "Number of passengers (classes too small are flagged fits_passengers=false and get no booking link).", "example": 2 }, { "name": "class", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "business", "electric", "first", "van", "ev", "special" ] }, "description": "Vehicle class to select in the booking link (business = Mercedes E-Class, electric = Mercedes EQE, first = Mercedes S-Class, van = Mercedes V-Class, ev = Mercedes EQV; special = on request).", "example": "first" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "fr", "en", "ar" ], "default": "fr" }, "description": "Language of messages and of the booking link.", "example": "en" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "oneway", "hourly" ], "default": "oneway" }, "description": "oneway (transfer) or hourly (chauffeur hire, `to` not needed)." }, { "name": "duration", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 3, "maximum": 12 }, "description": "Hours, required with type=hourly (3 to 12)." } ], "responses": { "200": { "description": "Priced (status=priced) or on request (status=on_request, with reason). Cache-Control: short; X-Cache: HIT|MISS.", "headers": { "X-Cache": { "schema": { "type": "string", "enum": [ "HIT", "MISS" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQuote" }, "examples": { "cdg": { "summary": "15 Avenue Montaigne, Paris → Paris-Charles de Gaulle Airport (CDG)", "value": { "ok": true, "status": "priced", "quote_id": "pq_0123456789abcdef", "currency": "EUR", "prices_include_vat": true, "trip": { "type": "oneway", "from": "15 Avenue Montaigne, Paris", "to": "Aéroport CDG", "date": "2026-11-20", "time": "09:30", "timezone": "Europe/Paris", "pickup_at": "2026-11-20T08:30:00.000Z", "passengers": 2, "duration_hours": null, "distance_km": 32.4, "duration_min": 45 }, "selected_class": "first", "from_price_ttc": 115, "classes": [ { "id": "business", "name": "Mercedes E-Class", "category": "Business", "passengers": "1-3", "passengers_max": 3, "luggage": "2-3", "fits_passengers": true, "selected": false, "status": "priced", "price_ttc": 115, "price_ttc_cents": 11500, "price_type": "forfait", "reason": null, "booking_url": "https://precellence-service.com/en/reservation?from=15+Avenue+Montaigne%2C+Paris&to=A%C3%A9roport+CDG&date=2026-11-20&time=09%3A30&pax=2&class=business&lang=en" }, { "id": "electric", "name": "Mercedes EQE", "category": "Electric", "passengers": "1-3", "passengers_max": 3, "luggage": "2-3", "fits_passengers": true, "selected": false, "status": "priced", "price_ttc": 115, "price_ttc_cents": 11500, "price_type": "forfait", "reason": null, "booking_url": "https://precellence-service.com/en/reservation?from=15+Avenue+Montaigne%2C+Paris&to=A%C3%A9roport+CDG&date=2026-11-20&time=09%3A30&pax=2&class=electric&lang=en" }, { "id": "first", "name": "Mercedes S-Class", "category": "First Class", "passengers": "1-3", "passengers_max": 3, "luggage": "2", "fits_passengers": true, "selected": true, "status": "priced", "price_ttc": 240, "price_ttc_cents": 24000, "price_type": "forfait", "reason": null, "booking_url": "https://precellence-service.com/en/reservation?from=15+Avenue+Montaigne%2C+Paris&to=A%C3%A9roport+CDG&date=2026-11-20&time=09%3A30&pax=2&class=first&lang=en" }, { "id": "van", "name": "Mercedes V-Class", "category": "Van / SUV", "passengers": "1-7", "passengers_max": 7, "luggage": "6-7", "fits_passengers": true, "selected": false, "status": "priced", "price_ttc": 159, "price_ttc_cents": 15900, "price_type": "forfait", "reason": null, "booking_url": "https://precellence-service.com/en/reservation?from=15+Avenue+Montaigne%2C+Paris&to=A%C3%A9roport+CDG&date=2026-11-20&time=09%3A30&pax=2&class=van&lang=en" }, { "id": "ev", "name": "Mercedes EQV", "category": "Electric Van", "passengers": "1-7", "passengers_max": 7, "luggage": "6", "fits_passengers": true, "selected": false, "status": "priced", "price_ttc": 159, "price_ttc_cents": 15900, "price_type": "forfait", "reason": null, "booking_url": "https://precellence-service.com/en/reservation?from=15+Avenue+Montaigne%2C+Paris&to=A%C3%A9roport+CDG&date=2026-11-20&time=09%3A30&pax=2&class=ev&lang=en" } ], "reason": null, "booking_url": "https://precellence-service.com/en/reservation?from=15+Avenue+Montaigne%2C+Paris&to=A%C3%A9roport+CDG&date=2026-11-20&time=09%3A30&pax=2&class=first&lang=en", "included": { "tolls": true, "fuel": true, "child_seat": true, "name_board": true, "flight_tracking": true, "no_surcharge_night_weekend_holiday": true, "free_waiting_minutes": { "airport": 60, "station": 30, "address": 15 }, "airport_waiting_counts_from": "actual_landing" }, "conditions": { "min_lead_minutes": 120, "price_guaranteed_minutes_once_opened_on_site": 20, "payment": { "when": "full_amount_at_booking", "where": "website_only" }, "details_url": "https://precellence-service.com/api/public/conditions?lang=en", "terms_url": "https://precellence-service.com/en/cgv" }, "contact": { "phone": "+33158963943", "whatsapp": "+33769700020", "email": "contact@precellence-service.com", "quote_form_url": "https://precellence-service.com/en/devis" }, "notice": "Prices include VAT, per vehicle, computed by the website pricing engine. Booking and payment happen on the website only, through booking_url: the same price is recomputed there, then guaranteed for 20 min. No payment through the assistant.", "generated_at": "2026-10-17T10:00:00.000Z", "valid_until": "2026-10-17T10:20:00.000Z", "tariff_version": "precellence-2026-10", "engine_version": "precellence-engine-1", "api_version": "1.0.0" } } } } } }, "400": { "description": "Invalid parameters (details lists each parameter) or pickup_in_past.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_enabled: the public quote API is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited: try again after Retry-After seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "catalog_unavailable: pricing temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/public/conditions": { "get": { "operationId": "getConditions", "summary": "Services, vehicle classes, fixed-price zones, hourly rates, options, waiting, cancellation, booking rules, contacts", "description": "Generated from the tariff and the reference data in force. Open CORS (GET). Cache: 3600 s.", "parameters": [ { "name": "lang", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "fr", "en", "ar" ], "default": "fr" }, "description": "Language of labels.", "example": "en" } ], "responses": { "200": { "description": "Conditions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conditions" } } } }, "503": { "description": "catalog_unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Reason": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "examples": [ "address_ambiguous", "address_not_found", "too_soon", "prestige_quote", "route_unavailable", "long_distance_on_quote", "disposal_over_max_duration", "electric_over_100km", "no_class_for_passengers" ] }, "message": { "type": "string" }, "end": { "type": "string", "enum": [ "pickup", "dropoff" ] }, "min_lead_minutes": { "type": "integer" } } }, "QuoteClass": { "type": "object", "required": [ "id", "name", "status" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": [ "string", "null" ] }, "passengers": { "type": [ "string", "null" ] }, "passengers_max": { "type": [ "integer", "null" ] }, "luggage": { "type": [ "string", "null" ] }, "fits_passengers": { "type": [ "boolean", "null" ] }, "selected": { "type": "boolean" }, "status": { "type": "string", "enum": [ "priced", "on_request", "unavailable" ] }, "price_ttc": { "type": [ "number", "null" ], "description": "Price including VAT, per vehicle, in EUR." }, "price_ttc_cents": { "type": [ "integer", "null" ] }, "price_type": { "type": [ "string", "null" ] }, "hours": { "type": "integer" }, "km_included": { "type": "integer" }, "reason": { "oneOf": [ { "$ref": "#/components/schemas/Reason" }, { "type": "null" } ] }, "booking_url": { "type": [ "string", "null" ], "format": "uri" } } }, "PublicQuote": { "type": "object", "required": [ "ok", "status", "currency", "classes", "booking_url", "notice", "generated_at", "api_version" ], "properties": { "ok": { "type": "boolean" }, "status": { "type": "string", "enum": [ "priced", "on_request" ] }, "quote_id": { "type": "string" }, "currency": { "type": "string" }, "prices_include_vat": { "type": "boolean" }, "trip": { "type": "object" }, "selected_class": { "type": [ "string", "null" ] }, "from_price_ttc": { "type": [ "number", "null" ] }, "classes": { "type": "array", "items": { "$ref": "#/components/schemas/QuoteClass" } }, "reason": { "oneOf": [ { "$ref": "#/components/schemas/Reason" }, { "type": "null" } ] }, "booking_url": { "type": [ "string", "null" ], "format": "uri", "description": "Pre-filled booking link (payment on the website only)." }, "included": { "type": "object" }, "conditions": { "type": "object" }, "contact": { "type": "object" }, "notice": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" }, "valid_until": { "type": [ "string", "null" ], "format": "date-time" }, "tariff_version": { "type": "string" }, "engine_version": { "type": [ "string", "null" ] }, "api_version": { "type": "string" } } }, "Conditions": { "type": "object", "required": [ "ok", "currency", "classes", "fixed_price_zones", "hourly_hire", "waiting", "cancellation", "booking", "contact" ], "properties": { "ok": { "type": "boolean" }, "currency": { "type": "string" }, "prices_include_vat": { "type": "boolean" }, "languages": { "type": "object" }, "services": { "type": "array" }, "classes": { "type": "array" }, "fixed_price_zones": { "type": "object" }, "long_distance": { "type": "object" }, "hourly_hire": { "type": "object" }, "options": { "type": "object" }, "pricing": { "type": "object" }, "waiting": { "type": "object" }, "cancellation": { "type": "object" }, "booking": { "type": "object" }, "contact": { "type": "object" }, "links": { "type": "object" } } }, "Error": { "type": "object", "required": [ "ok", "error", "message" ], "properties": { "ok": { "const": false }, "error": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } }