{ "openapi": "3.0.3", "info": { "title": "Reservly · API de integraciones", "version": "1.0.0", "description": "Primera versión de solo lectura. No crea reservas ni clientes. Usa claves independientes por negocio, creadas en Configuración → Negocio → Integraciones · API. Límite: 60 solicitudes/minuto por clave y 300/minuto por IP. Guarda la clave en tu servidor; no la incluyas en código cliente. Las respuestas exitosas usan {message,data}; los errores {message}. El catálogo no se pagina en esta versión." }, "servers": [ { "url": "https://{businessDomain}/api/v1", "variables": { "businessDomain": { "default": "tunegocio.reservly.cloud", "description": "Dominio del negocio o dominio propio conectado; no reservly.cloud." } } } ], "paths": { "/catalog": { "get": { "summary": "Consultar catálogo público", "operationId": "catalog", "description": "Requiere catalog:read. Aplica las reglas de reservas públicas del negocio.", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "Resultado", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/Catalog" } }, "required": [ "message", "data" ] } } } }, "400": { "description": "Datos inválidos o reservas deshabilitadas", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente, inválida, vencida o revocada; también si pertenece a otro negocio", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permiso insuficiente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Servicio no encontrado o no público", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de solicitudes; Retry-After: 60", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Cotización bloqueada por una regla del negocio", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "catalog:read" } }, "/availability": { "post": { "summary": "Consultar disponibilidad", "operationId": "availability", "description": "Requiere availability:read. Aplica las reglas de reservas públicas del negocio.", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "Resultado", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/Availability" } }, "required": [ "message", "data" ] } } } }, "400": { "description": "Datos inválidos o reservas deshabilitadas", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente, inválida, vencida o revocada; también si pertenece a otro negocio", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permiso insuficiente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Servicio no encontrado o no público", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de solicitudes; Retry-After: 60", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Cotización bloqueada por una regla del negocio", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "availability:read", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailabilityInput" } } } } } }, "/quotes": { "post": { "summary": "Calcular cotización", "operationId": "quote", "description": "Requiere quotes:read. Aplica las reglas de reservas públicas del negocio.", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "Resultado", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/Quote" } }, "required": [ "message", "data" ] } } } }, "400": { "description": "Datos inválidos o reservas deshabilitadas", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente, inválida, vencida o revocada; también si pertenece a otro negocio", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permiso insuficiente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Servicio no encontrado o no público", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de solicitudes; Retry-After: 60", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Cotización bloqueada por una regla del negocio", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "quotes:read", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteInput" } } } } } } }, "components": { "securitySchemes": { "ApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "rk_<64 caracteres hexadecimales>", "description": "Clave de integración, no JWT de usuario." } }, "schemas": { "Error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "AvailabilityInput": { "type": "object", "properties": { "service_id": { "type": "string", "format": "uuid" }, "variant_id": { "type": "string", "format": "uuid" }, "resource_id": { "type": "string", "format": "uuid" }, "location_id": { "type": "string", "format": "uuid" }, "quantity": { "type": "integer", "minimum": 1 }, "addons": { "type": "array", "items": { "type": "object", "properties": { "service_id": { "type": "string", "format": "uuid" }, "quantity": { "type": "integer", "minimum": 1 } }, "required": [ "service_id" ] } }, "date_from": { "type": "string", "format": "date", "description": "Fecha local del negocio." }, "date_to": { "type": "string", "format": "date", "description": "Inclusiva; máximo 42 días. Por defecto date_from." } }, "required": [ "service_id", "date_from" ] }, "QuoteInput": { "type": "object", "properties": { "service_id": { "type": "string", "format": "uuid" }, "variant_id": { "type": "string", "format": "uuid" }, "resource_id": { "type": "string", "format": "uuid" }, "location_id": { "type": "string", "format": "uuid" }, "quantity": { "type": "integer", "minimum": 1 }, "addons": { "type": "array", "items": { "type": "object", "properties": { "service_id": { "type": "string", "format": "uuid" }, "quantity": { "type": "integer", "minimum": 1 } }, "required": [ "service_id" ] } }, "starts_at": { "type": "string", "description": "Fecha y hora local del negocio, YYYY-MM-DD HH:mm, o ISO 8601 con offset explícito." }, "promo_code": { "type": "string" }, "fields": { "type": "object", "additionalProperties": true }, "customer": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } } }, "postal_code": { "type": "string" } }, "required": [ "service_id", "starts_at" ] }, "Catalog": { "type": "object", "properties": { "timezone": { "type": "string" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true } }, "required": [ "id", "name" ] } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "address": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true } }, "required": [ "id", "name" ] } }, "services": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "price": { "type": "number" }, "duration_minutes": { "type": "integer" }, "variants": { "type": "array", "items": { "type": "object" } }, "addons": { "type": "array", "items": { "type": "object" } }, "resources": { "type": "array", "items": { "type": "object" } } }, "required": [ "id", "name", "price", "duration_minutes" ] } } }, "required": [ "timezone", "services", "categories", "locations" ] }, "Availability": { "type": "object", "properties": { "timezone": { "type": "string" }, "duration_minutes": { "type": "integer" }, "days": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "slots": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string" }, "starts_at": { "type": "string", "description": "Hora UTC en YYYY-MM-DD HH:mm:ss." } }, "required": [ "time", "starts_at" ] } } }, "required": [ "date", "slots" ] } } }, "required": [ "timezone", "duration_minutes", "days" ] }, "Quote": { "type": "object", "properties": { "total": { "type": "number" }, "subtotal": { "type": "number" }, "deposit_due": { "type": "number" }, "tax_total": { "type": "number" }, "discount_total": { "type": "number" }, "lines": { "type": "array", "items": { "type": "object" } }, "currency": { "type": "string" }, "duration_minutes": { "type": "integer" } }, "required": [ "total", "deposit_due", "currency", "duration_minutes" ] } } } }