{ "openapi": "3.1.0", "info": { "title": "AtlasGuard Partner API", "description": "API for partners to integrate booking sessions with AtlasGuard", "contact": { "name": "AtlasGuard Support" }, "version": "v1" }, "servers": [ { "url": "https://booking-api.atlasguard.net", "description": "Production" } ], "paths": { "/api/admin/partner/create": { "post": { "tags": ["Partner"], "summary": "Create a new partner account", "description": "Creates a partner account and returns API credentials. Admin-only endpoint.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePartnerRequest" } } } }, "responses": { "200": { "description": "Partner created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePartnerResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "HmacAuth": [] } ] } }, "/api/admin/partner/list": { "get": { "tags": ["Partner"], "summary": "List all partner accounts", "description": "Returns an array of all partner accounts. Admin-only endpoint.", "responses": { "200": { "description": "List of partners", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerInfoResponse" } } } } } }, "security": [ { "HmacAuth": [] } ] } }, "/api/partner/booking/create-session/ep": { "post": { "tags": ["PartnerBooking"], "summary": "Create Executive Protection booking session", "description": "Initiates an Executive Protection booking session. Returns a redirect URL to send your user to the AtlasGuard booking form.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBookingRequest" } } } }, "responses": { "200": { "description": "Session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBookingResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "HmacAuth": [] } ] } }, "/api/partner/booking/create-session/st": { "post": { "tags": ["PartnerBooking"], "summary": "Create Secure Transport booking session", "description": "Initiates a Secure Transport booking session. Identical to the EP endpoint but creates an armored vehicle / chauffeur session.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBookingRequest" } } } }, "responses": { "200": { "description": "Session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBookingResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "HmacAuth": [] } ] } }, "/api/partner/booking/status/{bookingSessionId}": { "get": { "tags": ["PartnerBooking"], "summary": "Get booking session status", "description": "Returns the current status and customer details for a booking session.", "parameters": [ { "name": "bookingSessionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The booking session ID from the create-session response." } ], "responses": { "200": { "description": "Booking status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingStatusResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "HmacAuth": [] } ] } }, "/api/partner/booking/list": { "get": { "tags": ["PartnerBooking"], "summary": "List bookings", "description": "Returns all booking sessions associated with the authenticated partner account.", "responses": { "200": { "description": "List of bookings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "HmacAuth": [] } ] } }, "/api/partner/booking/update-payment": { "post": { "tags": ["PartnerBooking"], "summary": "Update booking payment status", "description": "Notifies AtlasGuard of a payment status change for a booking session. Call this after capturing payment on your side.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerUpdatePaymentBookingRequest" } } } }, "responses": { "200": { "description": "Payment status updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePaymentBookingResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "HmacAuth": [] } ] } } }, "components": { "securitySchemes": { "HmacAuth": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "HMAC-SHA256 signed requests. Requires three headers: X-Api-Key, X-Timestamp (Unix epoch seconds), and X-Signature (HMAC-SHA256 of the timestamp string keyed by your API secret, hex-encoded)." } }, "schemas": { "BookingListItemResponse": { "type": "object", "properties": { "bookingSessionId": { "type": "string" }, "customerName": { "type": "string" }, "status": { "type": "string" }, "referenceId": { "type": "string" }, "countryCode": { "type": "string" }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time" }, "bookingNumber": { "type": "string" }, "bookingId": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "redirectUrl": { "type": "string" }, "lastChecked": { "type": "string", "format": "date-time" }, "users": { "type": "array", "items": { "$ref": "#/components/schemas/UserInfo" } } } }, "BookingListResponse": { "type": "object", "properties": { "bookings": { "type": "array", "items": { "$ref": "#/components/schemas/BookingListItemResponse" } }, "totalCount": { "type": "integer", "format": "int32" } } }, "BookingStatusResponse": { "type": "object", "properties": { "bookingSessionId": { "type": "string" }, "status": { "type": "string", "enum": ["pending", "confirmed", "completed", "cancelled"] }, "customer": { "$ref": "#/components/schemas/CustomerInfo" } } }, "CreateBookingRequest": { "required": ["partnerCode", "countryCode", "startDate", "endDate", "referenceId", "returnUrl"], "type": "object", "properties": { "partnerCode": { "type": "string", "minLength": 1, "description": "Your partner code, received on account creation." }, "countryCode": { "type": "string", "minLength": 1, "description": "ISO 3166-1 alpha-2 country code for the mission location." }, "startDate": { "type": "string", "minLength": 1, "description": "Mission start date/time in ISO 8601 format (UTC)." }, "endDate": { "type": "string", "minLength": 1, "description": "Mission end date/time in ISO 8601 format (UTC)." }, "referenceId": { "type": "string", "description": "Your internal booking reference (any string), echoed in all responses." }, "returnUrl": { "type": "string", "description": "URL to redirect the user to after booking completion." } } }, "CreateBookingResponse": { "type": "object", "properties": { "status": { "type": "string" }, "bookingSessionId": { "type": "string" }, "redirectUrl": { "type": "string" } } }, "CreatePartnerRequest": { "required": ["partnerName", "contactEmail"], "type": "object", "properties": { "partnerName": { "type": "string", "maxLength": 200, "minLength": 1, "description": "Display name of the partner organisation." }, "contactEmail": { "type": "string", "format": "email", "maxLength": 256, "minLength": 1, "description": "Primary contact email for the partner account." }, "contactPhone": { "type": "string", "maxLength": 50, "minLength": 1, "description": "Contact phone number." }, "webhookUrl": { "type": "string", "format": "uri", "maxLength": 500, "minLength": 1, "description": "URL to receive booking status webhook events." }, "webhookSecret": { "type": "string", "maxLength": 200, "description": "Secret used to sign webhook payloads (HMAC-SHA256)." }, "allowedIpAddresses": { "type": "string", "description": "CIDR notation of allowed source IPs, comma-separated." }, "rateLimitPerMinute": { "type": "integer", "format": "int32", "description": "Max API requests per minute. Defaults to 60." }, "expiresAt": { "type": "string", "format": "date-time", "description": "ISO 8601 datetime when credentials expire." }, "notes": { "type": "string", "maxLength": 1000, "description": "Internal notes for this partner." } } }, "CreatePartnerResponse": { "type": "object", "properties": { "partnerId": { "type": "string", "format": "uuid" }, "partnerCode": { "type": "string" }, "apiKey": { "type": "string", "description": "API key — include in X-Api-Key header." }, "apiSecret": { "type": "string", "description": "API secret — used to compute HMAC signatures. Store securely." }, "partnerName": { "type": "string" }, "isActive": { "type": "boolean" }, "webhookUrl": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "warning": { "type": "string" } } }, "CustomerInfo": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" } } }, "ErrorResponse": { "type": "object", "properties": { "status": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } }, "PartnerInfoResponse": { "type": "object", "properties": { "partnerId": { "type": "string", "format": "uuid" }, "apiKey": { "type": "string" }, "partnerName": { "type": "string" }, "contactEmail": { "type": "string" }, "isActive": { "type": "boolean" }, "webhookUrl": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "type": "string", "format": "date-time" } } }, "PartnerUpdatePaymentBookingRequest": { "required": ["bookingSessionId", "partnerCode", "status"], "type": "object", "properties": { "bookingSessionId": { "type": "string", "minLength": 1, "description": "The booking session ID to update." }, "partnerCode": { "type": "string", "minLength": 1, "description": "Your partner code." }, "status": { "type": "string", "minLength": 1, "enum": ["paid", "refunded", "failed"], "description": "New payment status." }, "reason": { "type": "string", "description": "Optional reason or reference for the status change." } } }, "UpdatePaymentBookingResponse": { "type": "object", "properties": { "message": { "type": "string" }, "bookingId": { "type": "string", "format": "uuid" }, "bookingNumber": { "type": "string" }, "status": { "type": "string" } } }, "UserInfo": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "fullName": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "dateOfBirth": { "type": "string", "format": "date" } } } } } }