{"openapi":"3.1.0","info":{"title":"Servicialo","description":"Discover and book professional services autonomously. Servicialo is an open protocol that lets AI agents find service providers, check availability, and schedule appointments without authentication.","version":"1.0.0","contact":{"name":"Coordínalo","url":"https://coordinalo.com","email":"contacto@coordinalo.com"},"termsOfService":"https://coordinalo.com/terminos","license":{"name":"Servicialo Protocol","url":"https://servicialo.com"}},"servers":[{"url":"https://coordinalo.com","description":"Coordínalo network (LATAM). Published organizations span Chile, México, Colombia, Argentina, and other Spanish-speaking markets. Currencies returned in local denomination (CLP, MXN, COP, ARS, etc.)."}],"paths":{"/api/servicialo/registry":{"get":{"operationId":"listOrganizations","summary":"Find service organizations","description":"Discover Servicialo-compatible organizations. Filter by vertical (e.g. \"kinesiologia\", \"psicologia\") or location (e.g. \"Providencia\", \"Santiago\"). Returns org slugs needed for all other endpoints.","parameters":[{"name":"vertical","in":"query","schema":{"type":"string"},"description":"Filter by industry vertical (e.g. \"kinesiologia\", \"psicologia\", \"consultoria\")"},{"name":"location","in":"query","schema":{"type":"string"},"description":"Filter by location/city (e.g. \"Providencia\", \"Santiago\")"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":10},"description":"Maximum number of results"}],"responses":{"200":{"description":"List of organizations","content":{"application/json":{"schema":{"type":"object","properties":{"servicialo_version":{"type":"string"},"total":{"type":"integer"},"data":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string","description":"Organization identifier, used in all other endpoints"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"vertical":{"type":"string","nullable":true},"location":{"type":"string","nullable":true},"service_count":{"type":"integer"},"provider_count":{"type":"integer"},"endpoints":{"type":"object","properties":{"services":{"type":"string"},"availability":{"type":"string"},"book":{"type":"string"}}}}}}}}}}}}}},"/api/servicialo/{orgSlug}/manifest":{"get":{"operationId":"getOrgManifest","summary":"Get organization details with services and next available slots","description":"Returns organization info, all discoverable services, and the next 3 available time slots for each service. Good starting point after discovering an org via the registry.","parameters":[{"name":"orgSlug","in":"path","required":true,"schema":{"type":"string"},"description":"Organization slug from the registry"}],"responses":{"200":{"description":"Organization manifest with services and preview slots","content":{"application/json":{"schema":{"type":"object","properties":{"org":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"timezone":{"type":"string"}}},"services":{"type":"array","items":{"$ref":"#/components/schemas/ServiceWithSlots"}}}}}}},"404":{"description":"Organization not found"}}}},"/api/servicialo/{orgSlug}/services":{"get":{"operationId":"listServices","summary":"List all bookable services for an organization","description":"Returns the full catalog of active, discoverable services including prices, durations, modalities, and booking policies.","parameters":[{"name":"orgSlug","in":"path","required":true,"schema":{"type":"string"},"description":"Organization slug"}],"responses":{"200":{"description":"Service catalog","content":{"application/json":{"schema":{"type":"object","properties":{"servicialo_version":{"type":"string"},"organization":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"}}},"services":{"type":"array","items":{"$ref":"#/components/schemas/Service"}}}}}}},"404":{"description":"Organization not found"}}}},"/api/servicialo/{orgSlug}/availability":{"get":{"operationId":"getAvailability","summary":"Get available booking slots","description":"Check availability for a specific service. Three modes: (1) single date with \"date\", (2) next N slots with \"next\", (3) date range with \"from\" and \"days\". Returns time slots with provider info.","parameters":[{"name":"orgSlug","in":"path","required":true,"schema":{"type":"string"},"description":"Organization slug"},{"name":"serviceId","in":"query","required":true,"schema":{"type":"string"},"description":"Service ID from the services endpoint"},{"name":"providerId","in":"query","schema":{"type":"string"},"description":"Optional provider ID. If omitted, uses first available provider."},{"name":"date","in":"query","schema":{"type":"string","format":"date"},"description":"Single date mode: YYYY-MM-DD. Mutually exclusive with next/from."},{"name":"next","in":"query","schema":{"type":"integer","minimum":1,"maximum":50},"description":"Next N slots mode: return next N available slots from today."},{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"Range mode start date: YYYY-MM-DD. Use with \"days\"."},{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":90,"default":7},"description":"Range mode: number of days to search (default 7)."}],"responses":{"200":{"description":"Available time slots","content":{"application/json":{"schema":{"type":"object","properties":{"slots":{"type":"array","items":{"$ref":"#/components/schemas/Slot"}},"service":{"type":"object","properties":{"id":{"type":"string"},"duration_minutes":{"type":"integer"}}},"timezone":{"type":"string"}}}}}},"404":{"description":"Organization or service not found"}}}},"/api/servicialo/{orgSlug}/book":{"post":{"operationId":"bookSession","summary":"Book a session","description":"Atomically creates a session with associated sale and service order. The slot is validated for conflicts and provider availability inside a database transaction. No authentication required.","parameters":[{"name":"orgSlug","in":"path","required":true,"schema":{"type":"string"},"description":"Organization slug"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookingRequest"}}}},"responses":{"201":{"description":"Session booked successfully","headers":{"X-Booking-Lane":{"schema":{"type":"string","enum":["identity-confirmed","permissive"]},"description":"Coordinalo-specific. Indicates which lane the request was evaluated under. Not part of the protocol contract."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookingResponse"}}}},"400":{"description":"Invalid data, past date, or outside provider hours","headers":{"X-Booking-Lane":{"schema":{"type":"string","enum":["identity-confirmed","permissive"]}}}},"402":{"description":"Prepayment required — use the checkout endpoint first","headers":{"X-Booking-Lane":{"schema":{"type":"string","enum":["identity-confirmed","permissive"]}}}},"404":{"description":"Organization, service, or provider not found","headers":{"X-Booking-Lane":{"schema":{"type":"string","enum":["identity-confirmed","permissive"]}}}},"409":{"description":"Slot conflict — provider already booked at this time","headers":{"X-Booking-Lane":{"schema":{"type":"string","enum":["identity-confirmed","permissive"]}}}},"429":{"description":"Rate limit exceeded. Sending humanIntentConfirmed=true asserts human review and may avoid this limit.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Booking-Lane":{"schema":{"type":"string","enum":["identity-confirmed","permissive"]}}}}}}},"/api/servicialo/{orgSlug}/sessions/{sessionId}":{"get":{"operationId":"getSessionStatus","summary":"Get session status and lifecycle details","description":"Returns the current state of a session using the Servicialo 9-state lifecycle: solicitado, agendado, confirmado, en_curso, completado, documentado, facturado, cobrado, verificado.","parameters":[{"name":"orgSlug","in":"path","required":true,"schema":{"type":"string"}},{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Session details with lifecycle state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionStatus"}}}},"404":{"description":"Session not found"}}}},"/api/servicialo/{orgSlug}/sessions/{sessionId}/cancel":{"post":{"operationId":"cancelSession","summary":"Cancel a session","description":"Cancel a scheduled session. Returns cancellation policy applied.","parameters":[{"name":"orgSlug","in":"path","required":true,"schema":{"type":"string"}},{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500,"description":"Cancellation reason"},"cancelledBy":{"type":"string","enum":["client","provider","admin","system"],"default":"system"}}}}}},"responses":{"200":{"description":"Session cancelled"},"404":{"description":"Session not found"}}}},"/api/servicialo/{orgSlug}/sessions/{sessionId}/confirm":{"post":{"operationId":"confirmSession","summary":"Confirm a scheduled session","description":"Confirm a session that is in \"agendado\" state.","parameters":[{"name":"orgSlug","in":"path","required":true,"schema":{"type":"string"}},{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Session confirmed"},"404":{"description":"Session not found"}}}}},"components":{"schemas":{"Service":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"price":{"type":"number"},"currency":{"type":"string"},"price_unit":{"type":"string","nullable":true},"modality":{"type":"string","nullable":true},"duration_minutes":{"type":"integer","nullable":true},"category":{"type":"string","nullable":true},"requirements":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}},"ServiceWithSlots":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"duration_minutes":{"type":"integer"},"price":{"type":"number"},"currency":{"type":"string"},"next_slots":{"type":"array","items":{"$ref":"#/components/schemas/Slot"}},"booking_policy":{"type":"object","properties":{"prepayment":{"type":"object","properties":{"required":{"type":"boolean"},"amount":{"type":"number","nullable":true},"currency":{"type":"string","nullable":true}}}}}}},"Slot":{"type":"object","properties":{"date":{"type":"string","format":"date"},"start":{"type":"string","format":"date-time","description":"Slot start in UTC"},"end":{"type":"string","format":"date-time","description":"Slot end in UTC"},"provider":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}},"BookingRequest":{"type":"object","required":["clientEmail","serviceId","scheduledAt"],"properties":{"clientEmail":{"type":"string","format":"email","description":"Client email address"},"clientName":{"type":"string","description":"Client first name"},"clientLastName":{"type":"string","description":"Client last name"},"clientPhone":{"type":"string","description":"Client phone number"},"serviceId":{"type":"string","description":"Service ID from the services endpoint"},"providerId":{"type":"string","description":"Provider ID from availability slots. Recommended."},"scheduledAt":{"type":"string","format":"date-time","description":"ISO 8601 datetime for the appointment (must be in the future)"},"duration":{"type":"integer","description":"Duration in minutes (defaults to service duration)"},"notes":{"type":"string","maxLength":2000,"description":"Optional notes for the appointment"},"humanIntentConfirmed":{"type":"boolean","default":false,"description":"Optional. When true, the caller asserts a human reviewed and confirmed this booking. Bookings with humanIntentConfirmed=false may be subject to rate limits."}}},"BookingResponse":{"type":"object","properties":{"servicialo_version":{"type":"string"},"success":{"type":"boolean"},"session":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"derived_state":{"type":"string"},"derived_state_index":{"type":"integer"},"scheduled_at":{"type":"string","format":"date-time"},"duration_minutes":{"type":"integer"},"service":{"type":"string"},"client_email":{"type":"string"}}},"order_id":{"type":"string"},"venta_id":{"type":"string"}}},"SessionStatus":{"type":"object","properties":{"servicialo_version":{"type":"string"},"session":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"derived_state":{"type":"string","enum":["solicitado","agendado","confirmado","en_curso","completado","documentado","facturado","cobrado","verificado"],"description":"Servicialo 9-state lifecycle. Index maps to position: 0=solicitado, 1=agendado, 2=confirmado, 3=en_curso, 4=completado, 5=documentado, 6=facturado, 7=cobrado, 8=verificado"},"derived_state_index":{"type":"integer","minimum":0,"maximum":8,"description":"Numeric index (0-8) matching derived_state position. Higher = more progressed."},"scheduled_at":{"type":"string","format":"date-time"},"duration_minutes":{"type":"integer"},"service":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"provider":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"client":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"}}}}}}}}}}