{ "openapi": "3.1.0", "info": { "title": "EuroVDC Public API", "description": "Domain search, WHOIS lookup, product listing, AI suggestions and agent checkout for EuroVDC hosting platform. Use any language server (en/tr/de/bg); responses follow the request URL language.\n\n**Rate limits:** WHOIS 30/60s; AI 5/min + 15/hour; agent_cart 10/hour (public). Partner keys via `Authorization: Bearer evdc_...`. **Agent commerce:** cart → quote → Phase 1 browser, Phase 2 Stripe Checkout Session, Phase 3 `POST agent_checkout_pay` with Shared Payment Granted Token (`spt_...`). **ChatGPT ACP:** `POST /acp/checkout_sessions` (site root server) with `Idempotency-Key` + `API-Version: 2026-04-17`.", "version": "1.14.0", "contact": { "name": "EuroVDC Support", "email": "support@eurovdc.eu", "url": "https://www.eurovdc.eu/en/contact" } }, "servers": [ { "url": "https://www.eurovdc.eu/en/api", "description": "English" }, { "url": "https://www.eurovdc.eu/tr/api", "description": "Turkish" }, { "url": "https://www.eurovdc.eu/de/api", "description": "German" }, { "url": "https://www.eurovdc.eu/bg/api", "description": "Bulgarian" }, { "url": "https://www.eurovdc.eu", "description": "Site root (ChatGPT ACP adapter)" } ], "paths": { "/ping": { "get": { "operationId": "ping", "summary": "API health check", "description": "Returns pong + optional `agent_api` metadata when a valid partner key is sent.", "security": [], "responses": { "200": { "description": "API is alive", "content": { "application/json": { "examples": { "success": { "summary": "Success", "value": { "code": 1, "status": "success", "message": { "pong": true, "timestamp": "2026-06-21T12:00:00+00:00", "agent_api": { "authenticated": false, "tier": "public" } } } } } } } } } } }, "/search_domain": { "post": { "operationId": "searchDomain", "summary": "Check domain availability across multiple TLDs", "description": "Checks whether a domain name is available for registration. Returns availability status and pricing for each TLD.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "description": "Domain name to search (e.g. mycompany or mycompany.com)", "example": "mycompany" }, "tld": { "type": "string", "description": "Optional TLD without dot (default: com)", "example": "com" } } } } } }, "responses": { "200": { "description": "Domain availability results with pricing per TLD", "content": { "application/json": { "examples": { "success": { "summary": "Success", "value": { "code": 1, "status": "success", "message": { "currency": { "code": "EUR", "prefix": "€", "suffix": " EUR" }, "domains": [ { "domain": "mybrand.com", "status": "available", "price": { "register": { "1": "12.99" }, "renew": { "1": "14.99" } } } ] } } } } } } } } } }, "/whois": { "post": { "operationId": "whoisLookup", "summary": "WHOIS lookup for a domain", "description": "Returns registration details, owner, expiration date, nameservers and registrar for a domain.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "description": "Full domain name to look up (e.g. example.com)", "example": "example.com" } } } } } }, "responses": { "200": { "description": "WHOIS registration data", "content": { "application/json": { "examples": { "success": { "summary": "Success", "value": { "code": 1, "status": "success", "message": { "domain": "example.com", "registrar": "Example Registrar Inc.", "created": "2000-01-01", "expires": "2027-01-01", "nameservers": [ "ns1.example.com", "ns2.example.com" ] } } } } } } }, "429": { "description": "Rate limit exceeded (30 requests per 60 seconds)", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimited": { "summary": "Too many requests", "value": { "code": 0, "status": "error", "message": "Too many requests. Please wait.", "retry_after": 45 } } } } } } } } }, "/tlds": { "get": { "operationId": "listTlds", "summary": "List all available TLDs with pricing", "description": "Returns all supported TLD extensions with registration, renewal and transfer prices in EUR.", "responses": { "200": { "description": "TLD price list", "content": { "application/json": { "examples": { "success": { "summary": "Success", "value": { "code": 1, "status": "success", "message": { "currency": { "code": "EUR", "prefix": "€" }, "pricing": { "com": { "register": { "1": "12.99" }, "renew": { "1": "14.99" } }, "net": { "register": { "1": "14.99" }, "renew": { "1": "16.99" } } } } } } } } } } } } }, "/top_tlds": { "get": { "operationId": "topTlds", "summary": "List popular TLDs", "description": "Returns the most commonly used TLD extensions.", "responses": { "200": { "description": "Popular TLD list", "content": { "application/json": { "examples": { "success": { "summary": "Success", "value": { "code": 1, "status": "success", "message": [ { "tld": "com", "price": "12.99€" }, { "tld": "net", "price": "14.99€" } ] } } } } } } } } }, "/list_products/{type}": { "get": { "operationId": "listProducts", "summary": "List hosting/VPS/SSL/email/VPN products", "description": "Returns all available products and plans with pricing. Each product includes landing_url, purchase_url, and billing_periods for agent checkout.", "parameters": [ { "name": "type", "in": "path", "required": false, "schema": { "type": "string", "enum": [ "all", "hostingaccount", "server", "ssl", "email", "vpn", "other" ], "default": "all" }, "description": "Product type filter" } ], "responses": { "200": { "description": "Product list with plans, landing_url, purchase_url, billing_periods", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 1 }, "status": { "type": "string", "example": "success" }, "message": { "type": "array", "items": { "$ref": "#/components/schemas/ProductListItem" } } } }, "examples": { "success": { "summary": "Success", "value": { "code": 1, "status": "success", "message": [ { "pid": 23, "name": "Cloud VPS Small", "type": "server", "gid": 2, "landing_url": "https://www.eurovdc.eu/en/cloud-server", "purchase_url": "https://www.eurovdc.eu/en/api/agent_cart_add", "billing_periods": [ { "cycle": "monthly", "months": 1, "price_eur": "14.99", "setup_fee_eur": "0.00", "total_eur": "14.99" } ], "pricing": { "EUR": { "monthly": "14.99", "prefix": "€" } }, "has_tax": true } ] } } } } } } } } }, "/ai_suggest": { "post": { "operationId": "aiDomainSuggest", "summary": "AI-powered domain name suggestions", "description": "Describe a business idea and get brandable domain name candidates with availability checked across 100+ TLDs.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "description": "Plain language description of the business or project", "example": "An online store selling handmade organic soap" } } } } } }, "responses": { "200": { "description": "Suggested domain names with availability status", "content": { "application/json": { "examples": { "success": { "summary": "Success", "value": { "code": 1, "status": "success", "message": { "suggestions": [ { "domain": "organicsoapshop.com", "status": "available", "price": "12.99€" }, { "domain": "puresoap.eu", "status": "available", "price": "9.99€" } ] } } } } } } }, "429": { "description": "Rate limit exceeded (5/min burst or 15/hour per IP)", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimited": { "summary": "Too many requests", "value": { "code": 0, "status": "error", "message": "Too many requests. Please wait.", "retry_after": 45 } } } } } } } } }, "/ai_server_suggest": { "post": { "operationId": "aiServerSuggest", "summary": "AI-powered VPS/server plan recommendation", "description": "Describe your workload and get an instant recommendation for the best-fit VPS or cloud server plan with pricing. Requires products[] from list_products/server (MCP recommend_server tool fetches this automatically).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt", "products" ], "properties": { "prompt": { "type": "string", "description": "Plain language description of the server workload", "example": "I need a server to run a Node.js app with 10k daily users" }, "products": { "type": "array", "description": "Server products from list_products/server (pid, name, cpu, ram, hdd, price, usecase)", "items": { "type": "object" } } } }, "examples": { "nodeApp": { "summary": "Node.js workload", "value": { "prompt": "Node.js API with 10k daily users", "products": [ { "pid": 23, "name": "Cloud VPS Small", "cpu": 4, "ram": 8, "hdd": 80, "price": 14.99, "usecase": "Web apps" } ] } } } } } }, "responses": { "200": { "description": "Recommended server plan with specs and pricing", "content": { "application/json": { "examples": { "success": { "summary": "Success", "value": { "code": 1, "status": "success", "best_pid": 23, "alternative_pid": 24, "reason": "8 GB RAM and 4 vCPU fit Node.js workload with headroom.", "alt_reason": "Next tier adds NVMe and more CPU for growth." } } } } } }, "429": { "description": "Rate limit exceeded (5/min burst or 15/hour per IP)", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimited": { "summary": "Too many requests", "value": { "code": 0, "status": "error", "message": "Too many requests. Please wait.", "retry_after": 45 } } } } } } } } }, "/agent_domain_fields": { "get": { "operationId": "agentDomainFields", "summary": "WHMCS domain additional fields for agent checkout (.tr etc.)", "description": "Returns required WHMCS additional fields per TLD. Use before `agent_cart_add` for ccTLDs (.tr, .uk, …). Optional `?tld=tr` for a single TLD.", "parameters": [ { "name": "tld", "in": "query", "required": false, "schema": { "type": "string", "example": "tr" }, "description": "TLD without dot; omit for all TLDs with additional fields" } ], "responses": { "200": { "description": "Domain additional field definitions", "content": { "application/json": [] } } } } }, "/agent_cart_add": { "post": { "operationId": "agentCartAdd", "summary": "Add product or domain to agent cart and get checkout URL", "description": "Creates or updates a server-side cart (24h TTL). Returns checkout_url — open in a browser to hydrate the basket and continue to payment. Use list_products to find product_id (pid) and billing_cycle.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "integer", "description": "WHMCS product ID from list_products", "example": 42 }, "billing_cycle": { "type": "string", "enum": [ "monthly", "quarterly", "semiannually", "annually", "biennially", "triennially" ], "example": "monthly" }, "domain": { "type": "string", "description": "Full domain for register/transfer", "example": "mybrand.com" }, "domain_action": { "type": "string", "enum": [ "register", "transfer" ], "default": "register" }, "period": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1, "description": "Registration period in years" }, "eppcode": { "type": "string", "description": "Required for domain_action transfer" }, "idprotection": { "type": "boolean", "default": false }, "dns_management": { "type": "boolean", "default": false }, "email_forwarding": { "type": "boolean", "default": false }, "additional_fields": { "type": "object", "description": "WHMCS additional field values keyed by field name (see GET agent_domain_fields). Array of {name, default} also accepted.", "additionalProperties": true }, "cart_id": { "type": "string", "description": "Existing cart ID to append items" }, "merge": { "type": "boolean", "default": true, "description": "When false, replaces cart items" }, "items": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "integer" }, "billing_cycle": { "type": "string" }, "domain": { "type": "string" }, "domain_action": { "type": "string" } } } } } }, "examples": { "hostingProduct": { "summary": "Add VPS plan", "value": { "product_id": 42, "billing_cycle": "monthly" } }, "domainRegister": { "summary": "Register domain", "value": { "domain": "mybrand.com", "domain_action": "register" } }, "trDomainRegister": { "summary": "Register .tr domain with additional fields", "value": { "domain": "ornek.tr", "domain_action": "register", "additional_fields": { "Alan Adı Başvuru": "Bireysel Başvuru", "TC Kimlik No": "12345678901", "Ad Soyad": "Ad Soyad" } } } } } } }, "responses": { "200": { "description": "Cart summary with checkout_url, redirect_url, subtotal_eur, expires_at", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 1 }, "status": { "type": "string", "example": "success" }, "message": { "$ref": "#/components/schemas/AgentCartSummary" } } }, "examples": { "success": { "summary": "Success", "value": { "code": 1, "status": "success", "message": { "cart_id": "ac_abc123xyz", "lang": "en", "items_count": 1, "subtotal_eur": "14.99", "checkout_url": "https://www.eurovdc.eu/en/agent/checkout/ac_abc123xyz", "redirect_url": "https://www.eurovdc.eu/en/basket", "expires_at": "2026-06-22T12:00:00+00:00", "commerce": { "protocol": "eurovdc-agent-commerce-v1", "phase": "browser_handoff", "currency": "EUR", "total": { "amount": "14.99", "currency": "EUR" }, "checkout_url": "https://www.eurovdc.eu/en/agent/checkout/ac_abc123xyz", "payment_status": "pending_user_action" } } } } } } } }, "429": { "description": "Agent cart hourly limit exceeded", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimited": { "summary": "Too many requests", "value": { "code": 0, "status": "error", "message": "Too many requests. Please wait.", "retry_after": 45 } } } } } }, "503": { "description": "Agent commerce disabled (AGENT_COMMERCE_ENABLED=false)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCommerceDisabled" } } } } } } }, "/agent_cart/{cart_id}": { "get": { "operationId": "agentCartGet", "summary": "Get agent cart summary", "parameters": [ { "name": "cart_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cart summary with checkout_url", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/AgentCartSummary" } } }, "examples": { "success": { "summary": "Success", "value": { "code": 1, "status": "success", "message": { "cart_id": "ac_abc123xyz", "lang": "en", "items_count": 1, "subtotal_eur": "14.99", "checkout_url": "https://www.eurovdc.eu/en/agent/checkout/ac_abc123xyz", "redirect_url": "https://www.eurovdc.eu/en/basket", "expires_at": "2026-06-22T12:00:00+00:00", "commerce": { "protocol": "eurovdc-agent-commerce-v1", "phase": "browser_handoff", "currency": "EUR", "total": { "amount": "14.99", "currency": "EUR" }, "checkout_url": "https://www.eurovdc.eu/en/agent/checkout/ac_abc123xyz", "payment_status": "pending_user_action" } } } } } } } }, "404": { "description": "Cart not found or expired" } } } }, "/agent_checkout_quote": { "post": { "operationId": "agentCheckoutQuoteCreate", "summary": "Create locked price quote from agent cart (15 min TTL)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "cart_id" ], "properties": { "cart_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Locked quote with commerce envelope", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/AgentQuoteSummary" } } }, "examples": { "success": { "summary": "Success", "value": { "code": 1, "status": "success", "message": { "quote_id": "aq_demo123", "cart_id": "ac_abc123xyz", "status": "quoted", "total_eur": "14.99", "expires_at": "2026-06-21T12:15:00+00:00", "checkout_url": "https://www.eurovdc.eu/en/agent/checkout/ac_abc123xyz", "prepare_enabled": true, "prepare_url": "https://www.eurovdc.eu/en/api/agent_checkout_prepare", "commerce": { "protocol": "eurovdc-agent-commerce-v1", "phase": "browser_handoff" } } } } } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimited": { "summary": "Too many requests", "value": { "code": 0, "status": "error", "message": "Too many requests. Please wait.", "retry_after": 45 } } } } } } } } }, "/agent_checkout_quote/{quote_id}": { "get": { "operationId": "agentCheckoutQuoteGet", "summary": "Get quote by ID", "parameters": [ { "name": "quote_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Quote summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/AgentQuoteSummary" } } }, "examples": { "success": { "summary": "Success", "value": { "code": 1, "status": "success", "message": { "quote_id": "aq_demo123", "cart_id": "ac_abc123xyz", "status": "quoted", "total_eur": "14.99", "expires_at": "2026-06-21T12:15:00+00:00", "checkout_url": "https://www.eurovdc.eu/en/agent/checkout/ac_abc123xyz", "prepare_enabled": true, "prepare_url": "https://www.eurovdc.eu/en/api/agent_checkout_prepare", "commerce": { "protocol": "eurovdc-agent-commerce-v1", "phase": "browser_handoff" } } } } } } } }, "404": { "description": "Quote not found or expired" } } } }, "/agent_checkout_prepare": { "post": { "operationId": "agentCheckoutPrepare", "summary": "Prepare in-agent payment session (ACP Phase 2 — feature flag)", "description": "Returns payment session when AGENT_COMMERCE_PHASE2 is enabled; otherwise returns browser_handoff fallback with checkout_url.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "quote_id" ], "properties": { "quote_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Stripe Checkout Session ready (Phase 2) or existing session reused", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/AgentPrepareSummary" } } }, "examples": { "success": { "summary": "Success", "value": { "code": 1, "status": "success", "message": { "quote_id": "aq_demo123", "cart_id": "ac_abc123xyz", "status": "requires_payment", "payment_provider": "stripe", "payment_method": "checkout_session", "payment_status": "unpaid", "stripe_session_id": "cs_test_demo", "stripe_checkout_url": "https://checkout.stripe.com/c/pay/cs_test_demo", "total_eur": "14.99", "expires_at": "2026-06-21T12:15:00+00:00", "status_url": "https://www.eurovdc.eu/en/api/agent_checkout_status/aq_demo123", "commerce": { "protocol": "eurovdc-agent-commerce-v1", "phase": "stripe_checkout_session", "payment_status": "requires_payment" } } } } } } } }, "400": { "description": "Phase 2 disabled — response includes browser_handoff checkout_url fallback", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimited": { "summary": "Too many requests", "value": { "code": 0, "status": "error", "message": "Too many requests. Please wait.", "retry_after": 45 } } } } } } } } }, "/agent_checkout_status/{quote_id}": { "get": { "operationId": "agentCheckoutStatus", "summary": "Poll quote payment status (ACP Phase 2)", "description": "Syncs with Stripe Checkout Session when present. Returns payment_status paid/unpaid and omits stripe_checkout_url after payment.", "parameters": [ { "name": "quote_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Quote payment status", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/AgentPrepareSummary" } } }, "examples": { "success": { "summary": "Success", "value": { "code": 1, "status": "success", "message": { "quote_id": "aq_demo123", "cart_id": "ac_abc123xyz", "status": "paid", "payment_provider": "stripe", "payment_status": "paid", "paid_at": "2026-06-21T12:20:00+00:00", "total_eur": "14.99", "status_url": "https://www.eurovdc.eu/en/api/agent_checkout_status/aq_demo123", "commerce": { "protocol": "eurovdc-agent-commerce-v1", "phase": "stripe_checkout_session", "payment_status": "paid" } } } } } } } }, "404": { "description": "Quote not found or expired" } } } }, "/agent_checkout_pay": { "post": { "operationId": "agentCheckoutPay", "summary": "Pay quote with Shared Payment Granted Token (ACP Phase 3)", "description": "Instant in-agent payment using Stripe `spt_...` token. Requires AGENT_COMMERCE_PHASE3. Skips browser redirect.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "quote_id", "shared_payment_granted_token" ], "properties": { "quote_id": { "type": "string" }, "shared_payment_granted_token": { "type": "string", "example": "spt_1234567890" } } } } } }, "responses": { "200": { "description": "Payment succeeded — quote paid + fulfillment triggered", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/AgentPrepareSummary" } } }, "examples": { "success": { "summary": "Success", "value": { "code": 1, "status": "success", "message": { "quote_id": "aq_demo123", "cart_id": "ac_abc123xyz", "status": "paid", "payment_provider": "stripe", "payment_status": "paid", "paid_at": "2026-06-21T12:20:00+00:00", "total_eur": "14.99", "status_url": "https://www.eurovdc.eu/en/api/agent_checkout_status/aq_demo123", "commerce": { "protocol": "eurovdc-agent-commerce-v1", "phase": "stripe_checkout_session", "payment_status": "paid" } } } } } } } }, "400": { "description": "Phase 3 disabled or invalid token" }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimited": { "summary": "Too many requests", "value": { "code": 0, "status": "error", "message": "Too many requests. Please wait.", "retry_after": 45 } } } } } } } } }, "/agent_checkout_fulfill": { "post": { "operationId": "agentCheckoutFulfill", "summary": "Create WHMCS order from paid quote (logged-in client)", "description": "Requires active user session. Idempotent when quote already fulfilled via Stripe webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "quote_id" ], "properties": { "quote_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "WHMCS order + invoice created and marked paid" }, "401": { "description": "Login required" } } } }, "/acp/checkout_sessions": { "post": { "operationId": "acpCheckoutSessionCreate", "summary": "ACP: create checkout session (ChatGPT)", "description": "Maps to agent cart + quote. Returns `continue_url` for Phase 1 browser handoff.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unique key for safe POST retries (24h replay cache)" }, { "name": "API-Version", "in": "header", "required": true, "schema": { "type": "string", "example": "2026-04-17" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object" } }, "metadata": { "type": "object" }, "buyer": { "type": "object" } } } } } }, "responses": { "201": { "description": "CheckoutSession created" }, "400": { "description": "Invalid request" }, "409": { "description": "Idempotency-Key reused with different body" }, "410": { "description": "Agent commerce disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCommerceDisabled" } } } } } } }, "/acp/checkout_sessions/{session_id}": { "get": { "operationId": "acpCheckoutSessionGet", "summary": "ACP: retrieve checkout session", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "example": "cs_…" } } ], "responses": { "200": { "description": "CheckoutSession" }, "404": { "description": "Not found" }, "405": { "description": "Agent commerce disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCommerceDisabled" } } } } } }, "post": { "operationId": "acpCheckoutSessionUpdate", "summary": "ACP: update session (buyer, metadata.additional_fields)", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unique key for safe POST retries (24h replay cache)" }, { "name": "API-Version", "in": "header", "required": true, "schema": { "type": "string", "example": "2026-04-17" } } ], "responses": { "200": { "description": "Updated CheckoutSession" }, "404": { "description": "Not found" }, "405": { "description": "Agent commerce disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCommerceDisabled" } } } } } } }, "/acp/checkout_sessions/{session_id}/complete": { "post": { "operationId": "acpCheckoutSessionComplete", "summary": "ACP: complete / handoff to continue_url", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unique key for safe POST retries (24h replay cache)" }, { "name": "API-Version", "in": "header", "required": true, "schema": { "type": "string", "example": "2026-04-17" } } ], "responses": { "200": { "description": "ready_for_payment with continue_url" }, "404": { "description": "Not found" }, "405": { "description": "Agent commerce disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCommerceDisabled" } } } } } } }, "/acp/checkout_sessions/{session_id}/cancel": { "post": { "operationId": "acpCheckoutSessionCancel", "summary": "ACP: cancel checkout session", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unique key for safe POST retries (24h replay cache)" }, { "name": "API-Version", "in": "header", "required": true, "schema": { "type": "string", "example": "2026-04-17" } } ], "responses": { "200": { "description": "Canceled session" }, "404": { "description": "Not found" }, "405": { "description": "Paid session not cancelable" }, "406": { "description": "Agent commerce disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCommerceDisabled" } } } } } } } }, "components": { "securitySchemes": { "AgentApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "evdc_…", "description": "Optional partner agent API key for higher rate limits. Alternative header: `X-Agent-Api-Key`. Contact support@eurovdc.eu." } }, "schemas": { "BillingPeriod": { "type": "object", "properties": { "cycle": { "type": "string", "example": "monthly" }, "months": { "type": "integer", "example": 1 }, "price_eur": { "type": "string", "example": "14.99" }, "setup_fee_eur": { "type": "string", "example": "0.00" }, "total_eur": { "type": "string", "example": "14.99" } } }, "RateLimitError": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Too many requests. Please wait." }, "retry_after": { "type": "integer", "description": "Seconds until retry (mirrors Retry-After header)", "example": 45 } } }, "AgentCommerceDisabled": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Agent commerce is temporarily disabled" }, "error_code": { "type": "string", "example": "agent_commerce_disabled" }, "retry": { "type": "boolean", "example": false } } }, "AgentCartError": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "status": { "type": "string", "example": "error" }, "message": { "type": "string" }, "error_code": { "type": "string", "example": "missing_additional_fields" }, "missing_fields": { "type": "array", "items": { "type": "string" } } } }, "ProductListItem": { "type": "object", "properties": { "pid": { "type": "integer", "example": 23 }, "name": { "type": "string" }, "type": { "type": "string", "example": "server" }, "gid": { "type": "integer" }, "landing_url": { "type": "string", "format": "uri" }, "purchase_url": { "type": "string", "format": "uri", "description": "Browser deep link (hosting) or POST agent_cart_add endpoint (VPS/SSL/email/VPN)" }, "billing_periods": { "type": "array", "items": { "$ref": "#/components/schemas/BillingPeriod" } }, "pricing": { "type": "object" }, "has_tax": { "type": "boolean" } } }, "AgentCartSummary": { "type": "object", "properties": { "cart_id": { "type": "string" }, "lang": { "type": "string" }, "items_count": { "type": "integer" }, "subtotal_eur": { "type": "string" }, "checkout_url": { "type": "string", "format": "uri" }, "redirect_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" }, "items": { "type": "array", "items": { "type": "object" } }, "commerce": { "type": "object", "description": "ACP Phase 1 envelope (browser_handoff)", "properties": { "protocol": { "type": "string", "example": "eurovdc-agent-commerce-v1" }, "phase": { "type": "string", "example": "browser_handoff" }, "currency": { "type": "string", "example": "EUR" }, "line_items": { "type": "array" }, "checkout_url": { "type": "string", "format": "uri" }, "payment_status": { "type": "string", "example": "pending_user_action" } } } } }, "AgentQuoteSummary": { "type": "object", "properties": { "quote_id": { "type": "string" }, "cart_id": { "type": "string" }, "status": { "type": "string", "example": "quoted" }, "total_eur": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "checkout_url": { "type": "string", "format": "uri" }, "prepare_enabled": { "type": "boolean" }, "prepare_url": { "type": "string", "format": "uri" }, "commerce": { "type": "object" } } }, "AgentPrepareSummary": { "type": "object", "properties": { "quote_id": { "type": "string" }, "cart_id": { "type": "string" }, "status": { "type": "string", "example": "requires_payment" }, "payment_provider": { "type": "string", "example": "stripe" }, "payment_method": { "type": "string", "example": "checkout_session" }, "payment_status": { "type": "string", "example": "unpaid" }, "stripe_session_id": { "type": "string" }, "stripe_checkout_url": { "type": "string", "format": "uri" }, "checkout_url": { "type": "string", "format": "uri" }, "total_eur": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "status_url": { "type": "string", "format": "uri" }, "paid_at": { "type": "string", "format": "date-time", "nullable": true }, "commerce": { "type": "object" } } } }, "headers": { "RetryAfter": { "description": "Seconds to wait before retrying (HTTP 429)", "schema": { "type": "integer", "example": 45 } } } } }