{"openapi":"3.1.0","info":{"title":"Advixy Agent Booking API","version":"0.2.4","description":"Provider-independent API for discovering Advixy consultations and their first-invoice discount terms, checking availability and preparing explicitly confirmed bookings.","contact":{"url":"https://advixy.com/contacto/"}},"servers":[{"url":"https://agents.advixy.com"}],"tags":[{"name":"Discovery"},{"name":"Availability"},{"name":"Booking"}],"paths":{"/v1/services":{"get":{"operationId":"listServices","tags":["Discovery"],"summary":"List Advixy appointment services","parameters":[{"name":"language","in":"query","schema":{"type":"string","enum":["es","en","it"],"default":"es"}}],"responses":{"200":{"description":"Service catalog","content":{"application/json":{"schema":{"type":"object","required":["services"],"properties":{"services":{"type":"array","items":{"$ref":"#/components/schemas/Service"}}}}}}}}}},"/v1/services/{serviceId}/availability":{"get":{"operationId":"getAvailability","tags":["Availability"],"summary":"Get live Calendly availability or a safe fallback","parameters":[{"name":"serviceId","in":"path","required":true,"schema":{"type":"string","enum":["consultation_online_60","consultation_in_person_60"]}},{"name":"start_time","in":"query","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"end_time","in":"query","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"timezone","in":"query","schema":{"type":"string","default":"Europe/Madrid"}}],"responses":{"200":{"description":"Availability result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Availability"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/v1/booking-intents":{"post":{"operationId":"prepareBooking","tags":["Booking"],"summary":"Prepare a booking and return the exact summary the user must confirm","description":"This operation never books an appointment. Show summary to the user and ask for explicit confirmation before calling confirmBooking.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrepareBookingInput"}}}},"responses":{"201":{"description":"Prepared intent; explicit confirmation is still required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreparedIntent"}}}},"400":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/v1/booking-intents/{intentId}/confirm":{"post":{"operationId":"confirmBooking","tags":["Booking"],"summary":"Confirm a prepared booking after explicit user consent","description":"Call only after the user has explicitly approved the unchanged summary. The summary hash prevents silent changes.","parameters":[{"name":"intentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmBookingInput"}}}},"responses":{"200":{"description":"Confirmed free booking or trusted Stripe Checkout action for a paid booking","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ConfirmedBooking"},{"$ref":"#/components/schemas/CheckoutRequiredBooking"}]}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/v1/booking-intents/{intentId}":{"get":{"operationId":"getBookingStatus","tags":["Booking"],"summary":"Get booking status after Stripe Checkout","parameters":[{"name":"intentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Current booking status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookingStatus"}}}},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}}},"components":{"responses":{"Error":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"},"request_id":{"type":"string"}}}}}}}}},"schemas":{"Service":{"type":"object","required":["id","name","description","duration_minutes","mode","status","payment_required","price","credit_eligible","credit_policy","booking_url","live_availability","direct_booking"],"properties":{"id":{"type":"string","enum":["consultation_online_60","consultation_in_person_60"]},"name":{"type":"string"},"description":{"type":"string"},"duration_minutes":{"type":"integer","minimum":15},"mode":{"type":"string","enum":["online","in_person"]},"status":{"type":"string","enum":["active","draft","disabled"]},"payment_required":{"type":"boolean"},"price":{"oneOf":[{"type":"null"},{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"number"},"currency":{"const":"EUR"}}}]},"credit_eligible":{"type":"boolean"},"credit_policy":{"description":"Localized first-invoice discount terms. Explain that the benefit is applied only on the first invoice and is never refunded to the consultation payment method before confirming an eligible booking.","oneOf":[{"type":"null"},{"$ref":"#/components/schemas/CreditPolicy"}]},"booking_url":{"type":["string","null"],"format":"uri"},"live_availability":{"type":"boolean"},"direct_booking":{"type":"boolean"}}},"CreditPolicy":{"type":"object","required":["qualifying_event","window_days_after_consultation","benefit","application","refund_to_consultation_payment_method","must_disclose_before_booking_confirmation","terms"],"properties":{"qualifying_event":{"const":"becomes_advixy_client"},"window_days_after_consultation":{"const":15},"benefit":{"const":"paid_consultation_amount_discounted_on_first_invoice"},"application":{"const":"first_invoice_discount"},"refund_to_consultation_payment_method":{"const":false,"description":"The consultation payment is never returned to the payment method. The benefit is applied only as a discount on the first invoice."},"must_disclose_before_booking_confirmation":{"const":true},"terms":{"type":"string","description":"Terms localized to the requested service-catalog language."}}},"Availability":{"type":"object","required":["serviceId","mode","timezone","startTime","endTime","slots"],"properties":{"serviceId":{"type":"string","enum":["consultation_online_60","consultation_in_person_60"]},"mode":{"type":"string","enum":["live","fallback_only","disabled"]},"timezone":{"type":"string"},"startTime":{"type":"string","format":"date-time"},"endTime":{"type":"string","format":"date-time"},"slots":{"type":"array","items":{"type":"object","required":["startTime"],"properties":{"startTime":{"type":"string","format":"date-time"},"endTime":{"type":["string","null"],"format":"date-time"},"schedulingUrl":{"type":["string","null"],"format":"uri"}}}},"fallbackUrl":{"type":["string","null"],"format":"uri"},"reason":{"type":"string"}}},"PrepareBookingInput":{"type":"object","additionalProperties":false,"required":["service_id","start_time","timezone","language","name","email","idempotency_key"],"properties":{"service_id":{"type":"string","enum":["consultation_online_60","consultation_in_person_60"]},"start_time":{"type":"string","format":"date-time"},"timezone":{"type":"string","examples":["Europe/Madrid"]},"language":{"type":"string","enum":["es","en","it"]},"name":{"type":"string","minLength":2,"maxLength":120},"email":{"type":"string","format":"email","maxLength":254},"idempotency_key":{"type":"string","minLength":16,"maxLength":128},"questions_and_answers":{"type":"array","maxItems":20,"items":{"type":"object","required":["question","answer","position"],"properties":{"question":{"type":"string"},"answer":{"type":"string"},"position":{"type":"integer","minimum":0}}}}}},"PreparedIntent":{"type":"object","required":["intentId","status","summary","summaryHash","expiresAt","confirmationRequired"],"properties":{"intentId":{"type":"string","format":"uuid"},"status":{"const":"prepared"},"summary":{"$ref":"#/components/schemas/BookingSummary"},"summaryHash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"expiresAt":{"type":"string","format":"date-time"},"confirmationRequired":{"const":true}}},"BookingSummary":{"type":"object","required":["serviceId","serviceName","durationMinutes","mode","startTime","timezone","paymentRequired","priceAmount","priceCurrency","creditPolicy","attendeeEmailMasked"],"properties":{"serviceId":{"type":"string","enum":["consultation_online_60","consultation_in_person_60"]},"serviceName":{"type":"string"},"durationMinutes":{"type":"integer","minimum":15},"mode":{"type":"string","enum":["online","in_person"]},"startTime":{"type":"string","format":"date-time"},"timezone":{"type":"string"},"paymentRequired":{"type":"boolean"},"priceAmount":{"type":["number","null"]},"priceCurrency":{"type":["string","null"],"enum":["EUR",null]},"creditPolicy":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/CreditPolicy"}]},"attendeeEmailMasked":{"type":"string"}}},"ConfirmBookingInput":{"type":"object","additionalProperties":false,"required":["summary_hash","user_confirmed"],"properties":{"summary_hash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"user_confirmed":{"const":true,"description":"Must reflect a fresh, explicit approval by the human user."}}},"CheckoutRequiredBooking":{"type":"object","required":["intentId","status","paymentProvider","checkoutUrl","checkoutExpiresAt","pollUrl","confirmationRequired"],"properties":{"intentId":{"type":"string","format":"uuid"},"status":{"const":"checkout_required"},"paymentProvider":{"const":"stripe"},"checkoutUrl":{"type":"string","format":"uri"},"checkoutExpiresAt":{"type":"string","format":"date-time"},"pollUrl":{"type":"string","format":"uri"},"confirmationRequired":{"const":false}}},"BookingStatus":{"type":"object","required":["intentId","status","serviceId","startTime","timezone","paymentRequired"],"properties":{"intentId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["prepared","checkout_pending","processing","confirmed","failed","expired"]},"serviceId":{"type":"string","enum":["consultation_online_60","consultation_in_person_60"]},"startTime":{"type":"string","format":"date-time"},"timezone":{"type":"string"},"paymentRequired":{"type":"boolean"},"checkoutExpiresAt":{"type":"string","format":"date-time"},"booking":{"$ref":"#/components/schemas/ConfirmedBooking"},"failureCode":{"type":"string"}}},"ConfirmedBooking":{"type":"object","required":["intentId","status","serviceId","startTime","timezone","providerReference"],"properties":{"intentId":{"type":"string","format":"uuid"},"status":{"const":"confirmed"},"serviceId":{"type":"string","enum":["consultation_online_60","consultation_in_person_60"]},"startTime":{"type":"string","format":"date-time"},"timezone":{"type":"string"},"providerReference":{"type":"string"},"cancelUrl":{"type":["string","null"],"format":"uri"},"rescheduleUrl":{"type":["string","null"],"format":"uri"}}}}}}