{ "openapi": "3.0.3", "info": { "title": "Saint-Barth Yachting — Jicky Marine partner API", "version": "1.0", "description": "See integration-api.html for lifecycle, fees, webhook signatures, retries and test-to-production procedure. This profile only manages the authenticated partner’s own bookings. Sandbox and production use different keys.", "contact": { "name": "Sébastien Loret", "email": "sebastien.loret@hertzstbarth.com" } }, "servers": [ { "url": "https://sandbox.stbarth-yachting.com", "description": "Isolated sandbox" }, { "url": "https://stbarth-yachting.com", "description": "Production" } ], "security": [ { "ApiKey": [] } ], "paths": { "/api/v1/catalog": { "get": { "summary": "Partner catalogue and effective policies", "description": "", "parameters": [ { "in": "query", "name": "lang", "schema": { "type": "string", "enum": [ "fr", "en" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string" }, "partner": { "type": "object" }, "policies": { "type": "object" }, "yachts": { "type": "array", "items": { "type": "object" } }, "services": { "type": "array", "items": { "type": "object" } }, "extras": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "description": "Invalid input / missing Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or wrong-environment key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden operation / closed partner window", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Booking not found for this partner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict / invalid state transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/availability": { "get": { "summary": "Live charter availability", "description": "", "parameters": [ { "in": "query", "name": "date", "required": true, "schema": { "type": "string", "format": "date" } }, { "in": "query", "name": "yachtId", "schema": { "type": "integer", "minimum": 1 } }, { "in": "query", "name": "yachtSlug", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input / missing Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or wrong-environment key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden operation / closed partner window", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Booking not found for this partner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict / invalid state transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/quote": { "post": { "summary": "Calculate authoritative price", "description": "", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "serviceId", "bookingDate", "numGuests" ], "properties": { "serviceId": { "type": "integer", "minimum": 1 }, "bookingDate": { "type": "string", "format": "date" }, "numGuests": { "type": "integer", "minimum": 1 }, "extras": { "type": "array", "items": { "type": "object", "required": [ "extraId", "quantity" ], "properties": { "extraId": { "type": "integer", "minimum": 1 }, "quantity": { "type": "integer", "minimum": 1 } } } } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input / missing Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or wrong-environment key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden operation / closed partner window", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Booking not found for this partner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict / invalid state transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/bookings": { "post": { "summary": "Create a HOLD with idempotency", "description": "Jicky customer identity fields are optional. Same idempotency key + body replays the cached response. Existing externalReference + new key returns HTTP 200 / already_exists without mutation.", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBooking" } } } }, "responses": { "200": { "description": "Existing externalReference", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResponse" } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResponse" } } } }, "400": { "description": "Invalid input / missing Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or wrong-environment key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden operation / closed partner window", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Booking not found for this partner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict / invalid state transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/bookings/{reference}": { "get": { "summary": "Retrieve own booking", "description": "", "parameters": [ { "in": "path", "name": "reference", "required": true, "schema": { "type": "string" }, "description": "Warren referenceCode or stable FileMaker externalReference, not numeric id" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResponse" } } } }, "400": { "description": "Invalid input / missing Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or wrong-environment key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden operation / closed partner window", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Booking not found for this partner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict / invalid state transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/reservations/{id}/partner-edit": { "put": { "summary": "Edit own operational booking or move schedule", "description": "Jicky API account HOLDs: free changes enabled in both environments, only while future, unpaid, uninvoiced and unexpired (48h). Changes do not reset expiry. Confirmed bookings retain the free-window/payment/invoice guards. Schedule moves are repriced and conflict-checked atomically; discounted/custom-extra bookings require admin.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "numGuests": { "type": "integer", "minimum": 1 }, "specialRequests": { "type": "string", "maxLength": 2000, "nullable": true }, "bookingDate": { "type": "string", "format": "date" }, "serviceId": { "type": "integer", "minimum": 1 }, "yachtId": { "type": "integer", "minimum": 1 } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input / missing Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or wrong-environment key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden operation / closed partner window", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Booking not found for this partner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict / invalid state transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/reservations/{id}/partner-notes": { "put": { "summary": "Update private partner notes", "description": "", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "notes": { "type": "string", "nullable": true } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input / missing Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or wrong-environment key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden operation / closed partner window", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Booking not found for this partner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict / invalid state transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/reservations/{id}/confirm": { "post": { "summary": "Confirm pending account HOLD without recording payment", "description": "", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input / missing Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or wrong-environment key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden operation / closed partner window", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Booking not found for this partner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict / invalid state transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/reservations/{id}/cancel": { "post": { "summary": "Cancel in authorized partner window", "description": "Free cancellation enabled for Jicky API account HOLDs that are future, unpaid, uninvoiced and unexpired. Confirmed bookings have no HOLD exemption; reject with 403 if fees apply. Cancellation is terminal. Recorded actions and policy refusals notify SBY; sandbox does not send real management emails.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input / missing Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or wrong-environment key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden operation / closed partner window", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Booking not found for this partner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict / invalid state transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/reservations/{id}/cancellation-estimate": { "get": { "summary": "Booking-specific cancellation estimate", "description": "", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input / missing Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or wrong-environment key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden operation / closed partner window", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Booking not found for this partner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict / invalid state transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/cancellation-policy": { "get": { "summary": "General cancellation simulation", "description": "", "parameters": [ { "in": "query", "name": "bookingDate", "required": true, "schema": { "type": "string", "format": "date" } }, { "in": "query", "name": "totalAmount", "schema": { "type": "number", "minimum": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input / missing Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or wrong-environment key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden operation / closed partner window", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Booking not found for this partner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict / invalid state transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "schemas": { "Error": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" } } } } }, { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } ] }, "CreateBooking": { "type": "object", "required": [ "yachtId", "serviceId", "bookingDate", "numGuests" ], "properties": { "yachtId": { "type": "integer", "minimum": 1 }, "serviceId": { "type": "integer", "minimum": 1 }, "bookingDate": { "type": "string", "format": "date" }, "numGuests": { "type": "integer", "minimum": 1 }, "externalReference": { "type": "string", "minLength": 1, "maxLength": 100 }, "specialRequests": { "type": "string", "maxLength": 2000, "nullable": true }, "extras": { "type": "array", "items": { "type": "object", "required": [ "extraId", "quantity" ], "properties": { "extraId": { "type": "integer", "minimum": 1 }, "quantity": { "type": "integer", "minimum": 1 } } } }, "sendToCustomer": { "type": "boolean", "default": false }, "customer": { "type": "object", "properties": { "firstName": { "type": "string", "maxLength": 100 }, "lastName": { "type": "string", "maxLength": 100 }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "phone": { "type": "string", "maxLength": 50 }, "country": { "type": "string", "maxLength": 100 } } } } }, "Booking": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "referenceCode": { "type": "string" }, "externalReference": { "type": "string", "nullable": true }, "bookingDate": { "type": "string", "format": "date" }, "yachtId": { "type": "integer", "minimum": 1 }, "yachtName": { "type": "string" }, "serviceId": { "type": "integer", "minimum": 1 }, "timeSlotId": { "type": "integer", "minimum": 1 }, "numGuests": { "type": "integer", "minimum": 1 }, "specialRequests": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "confirmed", "deposit_paid", "paid", "completed", "cancelled", "no_show", "already_exists" ] }, "paymentStatus": { "type": "string" }, "totalAmount": { "type": "number" }, "currency": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "BookingResponse": { "type": "object", "properties": { "version": { "type": "string" }, "replayed": { "type": "boolean" }, "booking": { "$ref": "#/components/schemas/Booking" } } }, "Webhook": { "type": "object", "required": [ "version", "environment", "eventId", "event", "occurredAt", "booking" ], "properties": { "version": { "type": "string" }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] }, "eventId": { "type": "string", "format": "uuid" }, "event": { "type": "string", "enum": [ "booking.created", "booking.updated", "booking.cancelled" ] }, "occurredAt": { "type": "string", "format": "date-time" }, "booking": { "type": "object", "description": "Operational fields only; optional aliases are configured in the partner portal. No customer identity or private notes." } } } } } }