{
  "openapi": "3.1.0",
  "info": {
    "title": "Tactivo External API",
    "version": "1.0.0",
    "license": {
      "name": "Proprietary",
      "url": "https://tactivo.es/terminos-de-servicio"
    },
    "termsOfService": "https://tactivo.es/terminos-de-servicio",
    "description": "API de Tactivo para integraciones autorizadas por una clínica. Cada token identifica una sola clínica, aplica únicamente los permisos concedidos y queda sujeto a los Términos de Servicio y a la documentación técnica. Para desarrollar y validar una integración existe un entorno de pruebas permanente con datos ficticios y un token público de sandbox; la guía, la referencia y las novedades están en https://tactivo.es/api."
  },
  "servers": [
    {
      "url": "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "ExternalApiBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "ta_api_…",
        "description": "Credencial privada, revocable y vinculada a una sola clínica. Debe conservarse en el backend del Proveedor Autorizado y usarse solo para los permisos y fines aprobados."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "examples": [
              "SLOT_UNAVAILABLE",
              "CLIENT_AMBIGUOUS",
              "CLIENT_ALREADY_EXISTS",
              "APPOINTMENT_REQUIRES_RECEPTION",
              "IDEMPOTENCY_CONFLICT",
              "RATE_LIMITED",
              "DAILY_WRITE_LIMIT",
              "SERVICE_NOT_BOOKABLE",
              "PROFESSIONAL_NOT_BOOKABLE",
              "PROFESSIONAL_CHOICE_DISABLED",
              "LOCATION_NOT_BOOKABLE",
              "APPOINTMENT_OUTSIDE_BOOKING_WINDOW",
              "INVALID_CLIENT_DATA",
              "INVALID_STARTS_AT",
              "TOKEN_EXPIRED",
              "TOKEN_REVOKED"
            ],
            "example": "SLOT_UNAVAILABLE"
          }
        }
      },
      "Service": {
        "type": "object",
        "required": [
          "id",
          "name",
          "duration_minutes"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "example": "Fisioterapia"
          },
          "duration_minutes": {
            "type": "integer",
            "minimum": 1,
            "example": 60
          }
        }
      },
      "Professional": {
        "type": "object",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "example": "Ana García"
          }
        }
      },
      "Location": {
        "type": "object",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "example": "Clínica Centro"
          }
        }
      },
      "Slot": {
        "type": "object",
        "required": [
          "starts_at",
          "ends_at",
          "professional_id",
          "professional_name",
          "location_id"
        ],
        "properties": {
          "starts_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-09-01T10:00:00+02:00"
          },
          "ends_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-09-01T11:00:00+02:00"
          },
          "professional_id": {
            "type": "string",
            "format": "uuid"
          },
          "professional_name": {
            "type": "string",
            "example": "Ana García"
          },
          "location_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "location_name": {
            "type": [
              "string",
              "null"
            ],
            "example": "Clínica Centro"
          }
        }
      },
      "ClientCandidate": {
        "type": "object",
        "required": [
          "id",
          "name",
          "last_name",
          "exact_match"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "example": "María"
          },
          "last_name": {
            "type": "string",
            "example": "López"
          },
          "masked_phone": {
            "type": [
              "string",
              "null"
            ],
            "example": "******123"
          },
          "masked_dni": {
            "type": [
              "string",
              "null"
            ],
            "example": "*****123"
          },
          "exact_match": {
            "type": "boolean"
          }
        }
      },
      "Client": {
        "type": "object",
        "required": [
          "id",
          "name",
          "last_name",
          "is_guest"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "example": "María"
          },
          "last_name": {
            "type": "string",
            "example": "López"
          },
          "is_guest": {
            "type": "boolean",
            "const": true
          }
        }
      },
      "Appointment": {
        "type": "object",
        "required": [
          "id",
          "starts_at",
          "ends_at",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "client_id": {
            "type": "string",
            "format": "uuid"
          },
          "starts_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-09-01T10:00:00+02:00"
          },
          "ends_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-09-01T11:00:00+02:00"
          },
          "status": {
            "type": "string",
            "example": "pendiente"
          },
          "service_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "service_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "professional_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "professional_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "location_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "location_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "modifiable": {
            "type": "boolean"
          },
          "restriction_code": {
            "type": [
              "string",
              "null"
            ],
            "example": null
          }
        }
      },
      "CancelledAppointment": {
        "type": "object",
        "required": [
          "id",
          "client_id",
          "status",
          "deleted"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "client_id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "const": "cancelada"
          },
          "deleted": {
            "type": "boolean",
            "description": "false: la cita queda en la agenda con estado «cancelada». true: la clínica elimina las citas al cancelarlas (la cancelación se conserva en la ficha del cliente) y el hueco queda libre."
          },
          "already_cancelled": {
            "type": "boolean",
            "description": "La cita ya estaba cancelada: no se repite ningún aviso."
          }
        }
      },
      "ClientSearchRequest": {
        "type": "object",
        "minProperties": 1,
        "properties": {
          "name": {
            "type": "string"
          },
          "last_name": {
            "type": "string"
          },
          "phone": {
            "type": "string"
          },
          "dni": {
            "type": "string"
          }
        },
        "example": {
          "phone": "+34 600 111 222"
        }
      },
      "ClientCreateRequest": {
        "type": "object",
        "required": [
          "name",
          "last_name",
          "phone"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "last_name": {
            "type": "string"
          },
          "phone": {
            "type": "string",
            "description": "Número de teléfono válido, con o sin prefijo internacional. Ejemplo: +34600111222."
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "format": "email"
          },
          "dni": {
            "type": [
              "string",
              "null"
            ]
          },
          "gender": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "hombre",
              "mujer",
              null
            ],
            "description": "Sexo del cliente."
          },
          "birth_date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Fecha de nacimiento en formato YYYY-MM-DD. No se aceptan fechas futuras.",
            "example": "1990-05-12"
          },
          "address": {
            "type": [
              "string",
              "null"
            ],
            "description": "Dirección."
          },
          "occupation": {
            "type": [
              "string",
              "null"
            ],
            "description": "Ocupación."
          },
          "sport": {
            "type": [
              "string",
              "null"
            ],
            "description": "Actividad física."
          },
          "origins": {
            "anyOf": [
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "Orígenes del cliente como etiquetas de texto. Las que no existan en el catálogo de la clínica se crean automáticamente. En PATCH, null elimina todos los orígenes.",
            "example": [
              "Google",
              "Derivación"
            ]
          },
          "legal_guardian_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Nombre y apellidos del responsable legal del menor."
          },
          "legal_guardian_identity_document_type": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "dni",
              "nie",
              null
            ],
            "description": "Tipo de documento del responsable legal."
          },
          "legal_guardian_identity_number": {
            "type": [
              "string",
              "null"
            ],
            "description": "Número de documento del responsable legal."
          },
          "billing_info_enabled": {
            "type": "boolean",
            "description": "Activa el responsable de facturación en modo manual. Al desactivarlo se borran los datos manuales."
          },
          "billing_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Nombre del responsable de facturación."
          },
          "billing_last_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Apellidos del responsable de facturación."
          },
          "billing_tax_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "NIF del responsable de facturación."
          },
          "billing_address": {
            "type": [
              "string",
              "null"
            ],
            "description": "Dirección del responsable de facturación."
          },
          "review_opt_out": {
            "type": "boolean",
            "description": "Excluye al cliente de las solicitudes de valoración."
          }
        },
        "example": {
          "name": "María",
          "last_name": "López",
          "phone": "+34600111222",
          "email": "maria@example.com",
          "gender": "mujer",
          "birth_date": "1990-05-12",
          "origins": [
            "Google"
          ]
        }
      },
      "AppointmentCreateRequest": {
        "type": "object",
        "required": [
          "client_id",
          "service_id",
          "professional_id",
          "starts_at"
        ],
        "properties": {
          "client_id": {
            "type": "string",
            "format": "uuid"
          },
          "service_id": {
            "type": "string",
            "format": "uuid"
          },
          "professional_id": {
            "type": "string",
            "format": "uuid"
          },
          "location_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "starts_at": {
            "type": "string",
            "format": "date-time"
          },
          "note": {
            "type": "string",
            "maxLength": 2000,
            "description": "Nota del cliente para el equipo (p. ej. «llegaré unos minutos antes»). La ve solo el personal, como la nota de la reserva online."
          }
        }
      },
      "AppointmentNoteRequest": {
        "type": "object",
        "required": [
          "client_id",
          "note"
        ],
        "properties": {
          "client_id": {
            "type": "string",
            "format": "uuid"
          },
          "note": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          }
        }
      },
      "AppointmentMoveRequest": {
        "type": "object",
        "required": [
          "client_id",
          "starts_at"
        ],
        "properties": {
          "client_id": {
            "type": "string",
            "format": "uuid"
          },
          "starts_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AppointmentCancelRequest": {
        "type": "object",
        "required": [
          "client_id"
        ],
        "properties": {
          "client_id": {
            "type": "string",
            "format": "uuid"
          },
          "reason": {
            "type": "string",
            "maxLength": 500
          }
        }
      },
      "ClientUpdateRequest": {
        "type": "object",
        "description": "Edición parcial: solo los campos presentes se actualizan y un valor null vacía el campo. La foto no se puede informar por API.",
        "properties": {
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "last_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "phone": {
            "type": [
              "string",
              "null"
            ],
            "description": "Número válido, o null para vaciarlo. Un valor incompleto devuelve CLIENT_PHONE_INVALID."
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "format": "email"
          },
          "dni": {
            "type": [
              "string",
              "null"
            ]
          },
          "gender": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "hombre",
              "mujer",
              null
            ],
            "description": "Sexo del cliente."
          },
          "birth_date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Fecha de nacimiento en formato YYYY-MM-DD. No se aceptan fechas futuras.",
            "example": "1990-05-12"
          },
          "address": {
            "type": [
              "string",
              "null"
            ],
            "description": "Dirección."
          },
          "occupation": {
            "type": [
              "string",
              "null"
            ],
            "description": "Ocupación."
          },
          "sport": {
            "type": [
              "string",
              "null"
            ],
            "description": "Actividad física."
          },
          "origins": {
            "anyOf": [
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "Orígenes del cliente como etiquetas de texto. Las que no existan en el catálogo de la clínica se crean automáticamente. En PATCH, null elimina todos los orígenes.",
            "example": [
              "Google",
              "Derivación"
            ]
          },
          "legal_guardian_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Nombre y apellidos del responsable legal del menor."
          },
          "legal_guardian_identity_document_type": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "dni",
              "nie",
              null
            ],
            "description": "Tipo de documento del responsable legal."
          },
          "legal_guardian_identity_number": {
            "type": [
              "string",
              "null"
            ],
            "description": "Número de documento del responsable legal."
          },
          "billing_info_enabled": {
            "type": "boolean",
            "description": "Activa el responsable de facturación en modo manual. Al desactivarlo se borran los datos manuales."
          },
          "billing_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Nombre del responsable de facturación."
          },
          "billing_last_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Apellidos del responsable de facturación."
          },
          "billing_tax_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "NIF del responsable de facturación."
          },
          "billing_address": {
            "type": [
              "string",
              "null"
            ],
            "description": "Dirección del responsable de facturación."
          },
          "review_opt_out": {
            "type": "boolean",
            "description": "Excluye al cliente de las solicitudes de valoración."
          }
        },
        "example": {
          "phone": "+34600444555",
          "sport": "Ciclismo"
        }
      },
      "CreatedClient": {
        "type": "object",
        "required": [
          "id",
          "client_number",
          "name",
          "last_name",
          "is_guest"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "client_number": {
            "type": "string",
            "example": "00006"
          },
          "created": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "example": "2026-09-18"
          },
          "name": {
            "type": "string",
            "example": "María"
          },
          "last_name": {
            "type": "string",
            "example": "López"
          },
          "phone": {
            "type": [
              "string",
              "null"
            ],
            "example": "+34600111222"
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "format": "email",
            "example": "maria@example.com"
          },
          "dni": {
            "type": [
              "string",
              "null"
            ],
            "example": "12345678Z"
          },
          "is_guest": {
            "type": "boolean",
            "const": false
          },
          "gender": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "hombre",
              "mujer",
              null
            ],
            "description": "Sexo del cliente."
          },
          "birth_date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Fecha de nacimiento en formato YYYY-MM-DD. No se aceptan fechas futuras.",
            "example": "1990-05-12"
          },
          "address": {
            "type": [
              "string",
              "null"
            ],
            "description": "Dirección."
          },
          "occupation": {
            "type": [
              "string",
              "null"
            ],
            "description": "Ocupación."
          },
          "sport": {
            "type": [
              "string",
              "null"
            ],
            "description": "Actividad física."
          },
          "origins": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Etiquetas de origen del catálogo de la clínica.",
            "example": [
              "Google"
            ]
          },
          "legal_guardian_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Nombre y apellidos del responsable legal del menor."
          },
          "legal_guardian_identity_document_type": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "dni",
              "nie",
              null
            ],
            "description": "Tipo de documento del responsable legal."
          },
          "legal_guardian_identity_number": {
            "type": [
              "string",
              "null"
            ],
            "description": "Número de documento del responsable legal."
          },
          "billing_info_enabled": {
            "type": "boolean",
            "description": "Activa el responsable de facturación en modo manual. Al desactivarlo se borran los datos manuales."
          },
          "billing_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Nombre del responsable de facturación."
          },
          "billing_last_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Apellidos del responsable de facturación."
          },
          "billing_tax_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "NIF del responsable de facturación."
          },
          "billing_address": {
            "type": [
              "string",
              "null"
            ],
            "description": "Dirección del responsable de facturación."
          },
          "review_opt_out": {
            "type": "boolean",
            "description": "Excluye al cliente de las solicitudes de valoración."
          }
        }
      },
      "ClientDetail": {
        "type": "object",
        "description": "Ficha completa de la pestaña Datos. GET /clients/{client_number} añade treatment_status y has_account como contexto de solo lectura.",
        "allOf": [
          {
            "$ref": "#/components/schemas/CreatedClient"
          },
          {
            "type": "object",
            "properties": {
              "treatment_status": {
                "type": [
                  "string",
                  "null"
                ],
                "enum": [
                  "en_tratamiento",
                  "alta_parcial",
                  "alta",
                  null
                ]
              },
              "has_account": {
                "type": "boolean",
                "description": "True si el cliente tiene cuenta de usuario; en ese caso el email no se puede editar."
              }
            }
          }
        ]
      },
      "BonusAssignmentCreateRequest": {
        "type": "object",
        "required": [
          "client_number",
          "bonus_id"
        ],
        "additionalProperties": false,
        "properties": {
          "client_number": {
            "type": "string",
            "pattern": "^[A-Za-z0-9]+$",
            "description": "Número visible del cliente dentro de la clínica.",
            "example": "00006"
          },
          "bonus_id": {
            "type": "string",
            "format": "uuid",
            "description": "Identificador devuelto por GET /bonuses."
          },
          "starts_on": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Primer día de vigencia en formato YYYY-MM-DD. Si se omite, se usa la fecha actual de Europe/Madrid."
          }
        },
        "example": {
          "client_number": "00006",
          "bonus_id": "11111111-2222-4333-8444-555555555555",
          "starts_on": "2026-09-22"
        }
      },
      "BonusAssignmentCreated": {
        "type": "object",
        "required": [
          "id",
          "client_id",
          "client_number",
          "bonus_id",
          "bonus_name",
          "status",
          "price",
          "amount_paid",
          "paid_in_full",
          "initial_credits",
          "remaining_credits"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "client_id": {
            "type": "string",
            "format": "uuid"
          },
          "client_number": {
            "type": "string"
          },
          "bonus_id": {
            "type": "string",
            "format": "uuid"
          },
          "bonus_name": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "active"
            ]
          },
          "assigned_at": {
            "type": "string",
            "format": "date-time"
          },
          "starts_on": {
            "type": "string",
            "format": "date"
          },
          "expires_on": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "price": {
            "type": "number"
          },
          "amount_paid": {
            "type": "number",
            "const": 0
          },
          "paid_in_full": {
            "type": "boolean"
          },
          "payment_method": {
            "type": "null"
          },
          "initial_credits": {
            "type": "integer"
          },
          "remaining_credits": {
            "type": "integer"
          },
          "regularized_class_credits": {
            "type": "integer"
          },
          "regularized_appointments": {
            "type": "integer"
          }
        }
      },
      "OccupancyFigures": {
        "type": "object",
        "required": [
          "working_days",
          "scheduled_minutes",
          "blocked_minutes",
          "available_minutes",
          "occupied_minutes",
          "free_minutes",
          "occupancy_pct"
        ],
        "properties": {
          "working_days": {
            "type": "integer",
            "description": "Días con horario de cada profesional que suma la fila."
          },
          "scheduled_minutes": {
            "type": "number"
          },
          "blocked_minutes": {
            "type": "number"
          },
          "available_minutes": {
            "type": "number"
          },
          "occupied_minutes": {
            "type": "number"
          },
          "free_minutes": {
            "type": "number"
          },
          "occupancy_pct": {
            "type": [
              "number",
              "null"
            ]
          }
        }
      },
      "OccupancyRow": {
        "type": "object",
        "required": [
          "professional_id",
          "professional_name",
          "period_start",
          "period_end",
          "working_days",
          "scheduled_minutes",
          "blocked_minutes",
          "available_minutes",
          "occupied_minutes",
          "free_minutes",
          "occupancy_pct"
        ],
        "properties": {
          "professional_id": {
            "type": "string",
            "format": "uuid"
          },
          "professional_name": {
            "type": "string"
          },
          "period_start": {
            "type": "string",
            "format": "date"
          },
          "period_end": {
            "type": "string",
            "format": "date"
          },
          "working_days": {
            "type": "integer",
            "description": "Días con horario de cada profesional que suma la fila."
          },
          "scheduled_minutes": {
            "type": "number"
          },
          "blocked_minutes": {
            "type": "number"
          },
          "available_minutes": {
            "type": "number"
          },
          "occupied_minutes": {
            "type": "number"
          },
          "free_minutes": {
            "type": "number"
          },
          "occupancy_pct": {
            "type": [
              "number",
              "null"
            ]
          }
        },
        "example": {
          "professional_id": "11111111-2222-4333-8444-555555555555",
          "professional_name": "Laura Sanz",
          "period_start": "2026-10-01",
          "period_end": "2026-10-31",
          "working_days": 22,
          "scheduled_minutes": 7920,
          "blocked_minutes": 240,
          "available_minutes": 7680,
          "occupied_minutes": 5130,
          "free_minutes": 2550,
          "occupancy_pct": 66.8
        }
      }
    }
  },
  "paths": {
    "/health": {
      "get": {
        "operationId": "get_health",
        "summary": "Estado de la API",
        "security": [],
        "responses": {
          "200": {
            "description": "Estado básico de la API"
          },
          "4XX": {
            "description": "Petición no admitida por el gateway"
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "operationId": "get_openapi_document",
        "summary": "Contrato OpenAPI 3.1",
        "security": [],
        "responses": {
          "200": {
            "description": "Contrato público vigente"
          },
          "4XX": {
            "description": "Petición no admitida por el gateway"
          }
        }
      }
    },
    "/company": {
      "get": {
        "summary": "Datos de la clínica",
        "description": "Devuelve la configuración principal de la clínica asociada al token.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Clínica encontrada.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o expirado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token sin permiso para consultar la clínica.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Límite de peticiones superado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "get_company",
        "x-tactivo-required-scopes": [
          "company:read"
        ]
      }
    },
    "/clients/{client_number}": {
      "get": {
        "summary": "Ficha completa de un cliente",
        "description": "Devuelve todos los campos de la pestaña Datos del cliente identificado por su número de cliente, único por clínica. La respuesta añade treatment_status y has_account como contexto de solo lectura.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "client_number",
            "in": "path",
            "required": true,
            "description": "Número de cliente visible en la clínica (ej. 00006).",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9]+$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Cliente encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Número de cliente inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o expirado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token sin permiso para consultar clientes.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Cliente no encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Límite de peticiones superado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "get_clients_client_number",
        "x-tactivo-required-scopes": [
          "clients:read"
        ]
      },
      "patch": {
        "summary": "Editar cliente",
        "description": "Edita parcialmente los campos de la pestaña Datos del cliente identificado por su número de cliente: solo se actualizan los campos presentes en el cuerpo y un valor null los vacía. Un teléfono informado debe ser válido (CLIENT_PHONE_INVALID). El email no se puede cambiar mientras el cliente tenga cuenta de usuario (CLIENT_EMAIL_LOCKED, 409); un DNI repetido en la clínica devuelve CLIENT_ALREADY_EXISTS (409). Los orígenes se envían como etiquetas y se crean en el catálogo si no existen; null elimina todos.",
        "operationId": "patch_clients_client_number",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "x-tactivo-required-scopes": [
          "clients:write"
        ],
        "parameters": [
          {
            "name": "client_number",
            "in": "path",
            "required": true,
            "description": "Número de cliente visible en la clínica (ej. 00006).",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9]+$"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "description": "Identificador único del intento. Debe reutilizarse al reintentar exactamente la misma operación.",
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 200,
              "example": "crm-contact-123-update"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ClientUpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cliente actualizado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ClientDetail"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Petición inválida",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Token ausente, inválido, revocado o caducado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Token sin permisos para esta operación",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Cliente no encontrado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "DNI duplicado, email bloqueado por cuenta de usuario o conflicto de idempotencia",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Límite de 120 peticiones por minuto y token superado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/bonus-assignments": {
      "get": {
        "summary": "bonus-assignments",
        "description": "Asignaciones y ventas de bonos de la clínica. Los campos de cobro (amount_paid, paid_in_full, payment_method, invoice_id, purchase_reference) y el filtro invoice_id requieren finance:read. vat_percentage es el IVA del bono al venderlo; al facturarlo se aplica el IVA que tenga el bono en ese momento. amount_paid es lo pagado por cualquier vía (también lo que paga una entidad o se trajo del programa anterior); los pagos uno a uno, con su fecha y forma, están en GET /cash-movements.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Número máximo de filas por página. Por defecto 50, máximo 200.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Desplazamiento de página para paginación por offset.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "id",
            "in": "query",
            "description": "Filtra por ID de asignación.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "bonus_id",
            "in": "query",
            "description": "Filtra por ID de bono.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "client_id",
            "in": "query",
            "description": "Filtra por ID de cliente.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "invoice_id",
            "in": "query",
            "description": "Filtra por ID de factura. Requiere finance:read.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Filtra por estado.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "description": "Fecha/hora ISO mínima de assigned_at.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "description": "Fecha/hora ISO máxima de assigned_at.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Listado paginado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "required": [
                        "limit",
                        "offset",
                        "next_offset"
                      ],
                      "properties": {
                        "limit": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 200
                        },
                        "offset": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "next_offset": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "minimum": 0
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Parámetro inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o expirado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token sin permiso para este recurso.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Límite de peticiones superado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "get_bonus_assignments",
        "x-tactivo-required-scopes": [
          "bonuses:read"
        ]
      },
      "post": {
        "summary": "Asignar bono pendiente de cobro",
        "description": "Asigna a un cliente un bono del catálogo de la clínica. Conserva el precio, los créditos y la caducidad vigentes del catálogo, pero no registra ningún cobro ni movimiento de Caja: la asignación queda pendiente por el precio completo. La clínica debe registrar posteriormente el cobro en Tactivo. La asignación puede consumir inmediatamente créditos para regularizar citas o clases compatibles que estuvieran pendientes.",
        "operationId": "post_bonus_assignments",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "x-tactivo-required-scopes": [
          "bonuses:write"
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "description": "Identificador único del intento. Debe reutilizarse al reintentar exactamente la misma operación.",
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 200,
              "example": "crm-bonus-sale-123"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BonusAssignmentCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Bono asignado y pendiente de cobro",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/BonusAssignmentCreated"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Petición inválida",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Token ausente, inválido, revocado o caducado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Token sin permiso para asignar bonos",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Cliente o bono no encontrado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflicto de idempotencia",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "El bono no tiene créditos de servicio configurados",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Límite de 120 peticiones por minuto y token superado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/bonus-service-credits": {
      "get": {
        "summary": "bonus-service-credits",
        "description": "Detalle de créditos por servicio dentro de cada bono.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Número máximo de filas por página. Por defecto 50, máximo 200.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Desplazamiento de página para paginación por offset.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "bonus_id",
            "in": "query",
            "description": "Filtra por ID de bono.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "service_id",
            "in": "query",
            "description": "Filtra por ID de servicio.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Listado paginado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "required": [
                        "limit",
                        "offset",
                        "next_offset"
                      ],
                      "properties": {
                        "limit": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 200
                        },
                        "offset": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "next_offset": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "minimum": 0
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Parámetro inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o expirado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token sin permiso para este recurso.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Límite de peticiones superado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "get_bonus_service_credits",
        "x-tactivo-required-scopes": [
          "bonuses:read"
        ]
      }
    },
    "/bonuses": {
      "get": {
        "summary": "bonuses",
        "description": "Catálogo de bonos de la clínica.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Número máximo de filas por página. Por defecto 50, máximo 200.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Desplazamiento de página para paginación por offset.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "id",
            "in": "query",
            "description": "Filtra por ID de bono.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Listado paginado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "required": [
                        "limit",
                        "offset",
                        "next_offset"
                      ],
                      "properties": {
                        "limit": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 200
                        },
                        "offset": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "next_offset": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "minimum": 0
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Parámetro inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o expirado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token sin permiso para este recurso.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Límite de peticiones superado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "get_bonuses",
        "x-tactivo-required-scopes": [
          "bonuses:read"
        ]
      }
    },
    "/clients": {
      "get": {
        "summary": "clients",
        "description": "Clientes de la clínica, sin contenido clínico libre ni documentos. id es el identificador que usan client (GET /events), client_id (GET /bonus-assignments, GET /subscription-charges y demás) y las rutas /booking.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Número máximo de filas por página. Por defecto 50, máximo 200.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Desplazamiento de página para paginación por offset.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "id",
            "in": "query",
            "description": "Filtra por ID de cliente.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "client_number",
            "in": "query",
            "description": "Filtra por número de cliente.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "created_date",
            "in": "query",
            "description": "Filtra clientes creados en una fecha YYYY-MM-DD.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Busca por nombre, apellidos, email o teléfono.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "is_guest",
            "in": "query",
            "description": "Filtra por invitado true/false.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "treatment_status",
            "in": "query",
            "description": "Filtra por estado de tratamiento.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Listado paginado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "required": [
                        "limit",
                        "offset",
                        "next_offset"
                      ],
                      "properties": {
                        "limit": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 200
                        },
                        "offset": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "next_offset": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "minimum": 0
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Parámetro inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o expirado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token sin permiso para este recurso.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Límite de peticiones superado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "get_clients",
        "x-tactivo-required-scopes": [
          "clients:read"
        ]
      },
      "post": {
        "summary": "Crear cliente",
        "description": "Crea un cliente normal en la lista de la clínica, sin cita, con todos los campos editables de la pestaña Datos salvo la foto. Nombre, apellidos y teléfono son obligatorios; el teléfono debe ser un número internacional válido (CLIENT_PHONE_INVALID). El resto de campos son opcionales. Se permite compartir teléfono; un DNI repetido en la clínica devuelve CLIENT_ALREADY_EXISTS (409). Los orígenes se envían como etiquetas y se crean en el catálogo si no existen. No sustituye a POST /booking/clients, que crea un invitado para reservar.",
        "operationId": "post_clients",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "x-tactivo-required-scopes": [
          "clients:write"
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "description": "Identificador único del intento. Debe reutilizarse al reintentar exactamente la misma operación.",
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 200,
              "example": "crm-contact-123"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ClientCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Cliente creado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ClientDetail"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Petición inválida",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Token ausente, inválido, revocado o caducado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Token sin permisos para esta operación",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Cliente duplicado o conflicto de idempotencia",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Límite de 120 peticiones por minuto y token superado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/company-schedules": {
      "get": {
        "summary": "company-schedules",
        "description": "Horario general de la clínica.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Número máximo de filas por página. Por defecto 50, máximo 200.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Desplazamiento de página para paginación por offset.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Listado paginado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "required": [
                        "limit",
                        "offset",
                        "next_offset"
                      ],
                      "properties": {
                        "limit": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 200
                        },
                        "offset": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "next_offset": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "minimum": 0
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Parámetro inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o expirado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token sin permiso para este recurso.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Límite de peticiones superado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "get_company_schedules",
        "x-tactivo-required-scopes": [
          "catalog:read"
        ]
      }
    },
    "/events": {
      "get": {
        "summary": "events",
        "description": "Citas, clases y bloqueos de agenda de la clínica. Los campos de cobro (paid, paid_at, payment_amount, payment_method, cost, service_snapshot_vat_percentage, bonus_assignment_id) y el filtro paid requieren finance:read. service_snapshot_vat_percentage es el IVA del servicio al crear la cita; al facturarla se aplica el IVA que tenga el servicio en ese momento.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Número máximo de filas por página. Por defecto 50, máximo 200.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Desplazamiento de página para paginación por offset.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "id",
            "in": "query",
            "description": "Filtra por ID de evento.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "description": "Filtra por tipo appointment/class/block.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Filtra por appointment_status.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "paid",
            "in": "query",
            "description": "Filtra por pagado true/false. Requiere finance:read.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "client_id",
            "in": "query",
            "description": "Filtra por cliente contenido en el array client.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "professional_id",
            "in": "query",
            "description": "Filtra por profesional contenido en el array professional.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "service_id",
            "in": "query",
            "description": "Filtra por ID de servicio.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "location_id",
            "in": "query",
            "description": "Filtra por ID de ubicación.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "room_id",
            "in": "query",
            "description": "Filtra por ID de sala.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "description": "Fecha/hora ISO mínima de datetime.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "description": "Fecha/hora ISO máxima de datetime.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Listado paginado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "required": [
                        "limit",
                        "offset",
                        "next_offset"
                      ],
                      "properties": {
                        "limit": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 200
                        },
                        "offset": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "next_offset": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "minimum": 0
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Parámetro inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o expirado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token sin permiso para este recurso.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Límite de peticiones superado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "get_events",
        "x-tactivo-required-scopes": [
          "calendar:read"
        ]
      }
    },
    "/entities": {
      "get": {
        "summary": "entities",
        "description": "Entidades de la clínica (mutuas, aseguradoras, federaciones, clubes...) con los clientes cuya ficha las tiene como responsable de facturación (clients: client_number, name, last_name). irpf_retention_percentage es la retención que practica la entidad; external_billing indica que la entidad se factura fuera de Tactivo.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Número máximo de filas por página. Por defecto 50, máximo 200.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Desplazamiento de página para paginación por offset.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "id",
            "in": "query",
            "description": "Filtra por ID de entidad.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Busca por nombre o NIF.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Listado paginado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "required": [
                        "limit",
                        "offset",
                        "next_offset"
                      ],
                      "properties": {
                        "limit": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 200
                        },
                        "offset": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "next_offset": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "minimum": 0
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Parámetro inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o expirado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token sin permiso para este recurso.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Límite de peticiones superado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "get_entities",
        "x-tactivo-required-scopes": [
          "finance:read"
        ]
      }
    },
    "/event-bonus-usages": {
      "get": {
        "summary": "event-bonus-usages",
        "description": "Consumos de bonos aplicados a eventos.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Número máximo de filas por página. Por defecto 50, máximo 200.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Desplazamiento de página para paginación por offset.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "event_id",
            "in": "query",
            "description": "Filtra por ID de evento.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "client_id",
            "in": "query",
            "description": "Filtra por ID de cliente.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "assignment_id",
            "in": "query",
            "description": "Filtra por ID de asignación de bono.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Listado paginado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "required": [
                        "limit",
                        "offset",
                        "next_offset"
                      ],
                      "properties": {
                        "limit": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 200
                        },
                        "offset": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "next_offset": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "minimum": 0
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Parámetro inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o expirado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token sin permiso para este recurso.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Límite de peticiones superado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "get_event_bonus_usages",
        "x-tactivo-required-scopes": [
          "finance:read"
        ]
      }
    },
    "/expenses": {
      "get": {
        "summary": "expenses",
        "description": "Gastos de la clínica sin adjuntos ni notas libres.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Número máximo de filas por página. Por defecto 50, máximo 200.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Desplazamiento de página para paginación por offset.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "id",
            "in": "query",
            "description": "Filtra por ID de gasto.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "description": "Filtra por tipo puntual/recurrente.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "description": "Filtra por categoría.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "description": "Fecha/hora ISO mínima de occurred_at.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "description": "Fecha/hora ISO máxima de occurred_at.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Listado paginado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "required": [
                        "limit",
                        "offset",
                        "next_offset"
                      ],
                      "properties": {
                        "limit": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 200
                        },
                        "offset": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "next_offset": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "minimum": 0
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Parámetro inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o expirado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token sin permiso para este recurso.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Límite de peticiones superado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "get_expenses",
        "x-tactivo-required-scopes": [
          "finance:read"
        ]
      }
    },
    "/inventory-sale-lines": {
      "get": {
        "summary": "inventory-sale-lines",
        "description": "Líneas de detalle de ventas de inventario.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Número máximo de filas por página. Por defecto 50, máximo 200.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Desplazamiento de página para paginación por offset.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "sale_id",
            "in": "query",
            "description": "Filtra por ID de venta.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "product_id",
            "in": "query",
            "description": "Filtra por ID de producto.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Listado paginado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "required": [
                        "limit",
                        "offset",
                        "next_offset"
                      ],
                      "properties": {
                        "limit": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 200
                        },
                        "offset": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "next_offset": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "minimum": 0
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Parámetro inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o expirado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token sin permiso para este recurso.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Límite de peticiones superado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "get_inventory_sale_lines",
        "x-tactivo-required-scopes": [
          "finance:read"
        ]
      }
    },
    "/inventory-sales": {
      "get": {
        "summary": "inventory-sales",
        "description": "Ventas de inventario de la clínica.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Número máximo de filas por página. Por defecto 50, máximo 200.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Desplazamiento de página para paginación por offset.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "id",
            "in": "query",
            "description": "Filtra por ID de venta.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "client_id",
            "in": "query",
            "description": "Filtra por ID de cliente.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "invoice_id",
            "in": "query",
            "description": "Filtra por ID de factura.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Filtra por estado.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "description": "Fecha/hora ISO mínima de sold_at.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "description": "Fecha/hora ISO máxima de sold_at.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Listado paginado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "required": [
                        "limit",
                        "offset",
                        "next_offset"
                      ],
                      "properties": {
                        "limit": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 200
                        },
                        "offset": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "next_offset": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "minimum": 0
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Parámetro inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o expirado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token sin permiso para este recurso.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Límite de peticiones superado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "get_inventory_sales",
        "x-tactivo-required-scopes": [
          "finance:read"
        ]
      }
    },
    "/invoices": {
      "get": {
        "summary": "invoices",
        "description": "Facturas emitidas de la clínica. recipient_nif_country es el país (ISO 3166-1 alfa-2) del pasaporte o documento extranjero del destinatario; null si recipient_nif es un NIF español. is_annulled indica una anulación fiscal efectiva: su cobro no aplica aunque status siga en pendiente o cobrada. Una rectificativa con rectification_type S (por sustitución) lleva los importes completos correctos y sustituye rectified_base_amount, rectified_vat_amount y rectified_surcharge_amount; una con I (por diferencias) lleva solo el ajuste. indirect_tax es el impuesto con el que se emitió: iva o igic (clínica canaria); vat_percentage y el de cada línea son tipos de ese impuesto.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Número máximo de filas por página. Por defecto 50, máximo 200.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Desplazamiento de página para paginación por offset.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "id",
            "in": "query",
            "description": "Filtra por ID de factura.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "recipient_id",
            "in": "query",
            "description": "Filtra por ID de destinatario.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Filtra por estado.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "description": "Fecha mínima YYYY-MM-DD de issue_date.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "description": "Fecha máxima YYYY-MM-DD de issue_date.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Listado paginado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "required": [
                        "limit",
                        "offset",
                        "next_offset"
                      ],
                      "properties": {
                        "limit": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 200
                        },
                        "offset": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "next_offset": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "minimum": 0
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Parámetro inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o expirado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token sin permiso para este recurso.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Límite de peticiones superado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "get_invoices",
        "x-tactivo-required-scopes": [
          "finance:read"
        ]
      }
    },
    "/cash-movements": {
      "get": {
        "summary": "cash-movements",
        "description": "Movimientos de Caja: cada cobro, devolución o corrección con su fecha (occurred_at), importe, forma de pago y origen, incluidos los cobros a entidades (que la app muestra aparte, en Caja › Entidades). amount es positivo si entra dinero y negativo si sale; una devolución o corrección es un movimiento nuevo y nunca modifica uno anterior. source_type indica el origen y qué identificador lo enlaza: appointment (source_event_id, una cita de GET /events), bonus_assignment (source_bonus_assignment_id, de GET /bonus-assignments), class_subscription (source_class_subscription_charge_id, cuota mensual de una suscripción), inventory_sale (source_inventory_sale_id), free_invoice (source_invoice_id) o entity_receivable (cobro a una entidad: entity_receivable trae la entidad, la cita, bono, cuota o venta que paga, el importe y la retención de IRPF). La suma de amount de un origen es lo cobrado neto al cliente; lo que paga una entidad está en sus movimientos entity_receivable. Las sesiones consumidas con un bono no generan movimiento: su cobro es el del bono. Si el origen se borra después del cobro, el movimiento se conserva, aunque su identificador puede quedar vacío o dejar de aparecer en los otros listados. La fecha de un movimiento puede ser anterior a su registro (un cobro con fecha atrasada) o corregirse después: created_from devuelve lo registrado desde una fecha.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Número máximo de filas por página. Por defecto 50, máximo 200.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Desplazamiento de página para paginación por offset.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "id",
            "in": "query",
            "description": "Filtra por ID de movimiento.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "source_type",
            "in": "query",
            "description": "Filtra por origen: appointment, bonus_assignment, class_subscription, inventory_sale, free_invoice, entity_receivable.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "payment_method",
            "in": "query",
            "description": "Filtra por forma de pago (Efectivo, TPV, Bizum...).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "event_id",
            "in": "query",
            "description": "Filtra por ID de cita.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "bonus_assignment_id",
            "in": "query",
            "description": "Filtra por ID de bono vendido.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "description": "Fecha/hora ISO mínima de occurred_at.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "description": "Fecha/hora ISO máxima de occurred_at.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "created_from",
            "in": "query",
            "description": "Fecha/hora ISO mínima de created_at (cuándo se registró en Tactivo).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Listado paginado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "required": [
                        "limit",
                        "offset",
                        "next_offset"
                      ],
                      "properties": {
                        "limit": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 200
                        },
                        "offset": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "next_offset": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "minimum": 0
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Parámetro inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o expirado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token sin permiso para este recurso.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Límite de peticiones superado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "get_cash_movements",
        "x-tactivo-required-scopes": [
          "finance:read"
        ]
      }
    },
    "/subscription-charges": {
      "get": {
        "summary": "subscription-charges",
        "description": "Cuotas mensuales de las suscripciones de clase de los clientes: mes (period_month, primer día del mes), plan, importe con IVA incluido (amount; full_month_amount es la cuota entera y prorated indica que se prorrateó), IVA, lo pagado (amount_paid) y su estado. paid_at es cuándo quedó pagada del todo en Tactivo, no la fecha de cada pago. Con payment_method Entidad, status paid y amount_paid significan que la cuota corre a cargo de la entidad desde que se crea, no que la entidad la haya pagado. Los pagos reales, con fecha y forma, están en GET /cash-movements: source_type class_subscription con source_class_subscription_charge_id, o entity_receivable con entity_receivable.source_class_subscription_charge_id.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Número máximo de filas por página. Por defecto 50, máximo 200.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Desplazamiento de página para paginación por offset.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "id",
            "in": "query",
            "description": "Filtra por ID de cuota.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "client_id",
            "in": "query",
            "description": "Filtra por ID de cliente.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Filtra por estado.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "description": "Mes mínimo YYYY-MM-DD de period_month.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "description": "Mes máximo YYYY-MM-DD de period_month.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Listado paginado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "required": [
                        "limit",
                        "offset",
                        "next_offset"
                      ],
                      "properties": {
                        "limit": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 200
                        },
                        "offset": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "next_offset": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "minimum": 0
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Parámetro inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o expirado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token sin permiso para este recurso.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Límite de peticiones superado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "get_subscription_charges",
        "x-tactivo-required-scopes": [
          "finance:read"
        ]
      }
    },
    "/locations": {
      "get": {
        "summary": "locations",
        "description": "Ubicaciones de la clínica.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Número máximo de filas por página. Por defecto 50, máximo 200.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Desplazamiento de página para paginación por offset.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "id",
            "in": "query",
            "description": "Filtra por ID de ubicación.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Listado paginado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "required": [
                        "limit",
                        "offset",
                        "next_offset"
                      ],
                      "properties": {
                        "limit": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 200
                        },
                        "offset": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "next_offset": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "minimum": 0
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Parámetro inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o expirado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token sin permiso para este recurso.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Límite de peticiones superado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "get_locations",
        "x-tactivo-required-scopes": [
          "catalog:read"
        ]
      }
    },
    "/professional-locations": {
      "get": {
        "summary": "professional-locations",
        "description": "Relación entre profesionales y ubicaciones.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Número máximo de filas por página. Por defecto 50, máximo 200.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Desplazamiento de página para paginación por offset.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "professional_id",
            "in": "query",
            "description": "Filtra por profesional.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "location_id",
            "in": "query",
            "description": "Filtra por ubicación.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Listado paginado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "required": [
                        "limit",
                        "offset",
                        "next_offset"
                      ],
                      "properties": {
                        "limit": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 200
                        },
                        "offset": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "next_offset": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "minimum": 0
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Parámetro inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o expirado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token sin permiso para este recurso.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Límite de peticiones superado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "get_professional_locations",
        "x-tactivo-required-scopes": [
          "catalog:read"
        ]
      }
    },
    "/professional-schedules": {
      "get": {
        "summary": "professional-schedules",
        "description": "Horarios por profesional.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Número máximo de filas por página. Por defecto 50, máximo 200.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Desplazamiento de página para paginación por offset.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "professional_id",
            "in": "query",
            "description": "Filtra por profesional.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Listado paginado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "required": [
                        "limit",
                        "offset",
                        "next_offset"
                      ],
                      "properties": {
                        "limit": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 200
                        },
                        "offset": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "next_offset": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "minimum": 0
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Parámetro inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o expirado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token sin permiso para este recurso.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Límite de peticiones superado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "get_professional_schedules",
        "x-tactivo-required-scopes": [
          "catalog:read"
        ]
      }
    },
    "/professional-services": {
      "get": {
        "summary": "professional-services",
        "description": "Relación entre profesionales y servicios.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Número máximo de filas por página. Por defecto 50, máximo 200.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Desplazamiento de página para paginación por offset.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "professional_id",
            "in": "query",
            "description": "Filtra por profesional.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "service_id",
            "in": "query",
            "description": "Filtra por servicio.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Listado paginado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "required": [
                        "limit",
                        "offset",
                        "next_offset"
                      ],
                      "properties": {
                        "limit": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 200
                        },
                        "offset": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "next_offset": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "minimum": 0
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Parámetro inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o expirado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token sin permiso para este recurso.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Límite de peticiones superado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "get_professional_services",
        "x-tactivo-required-scopes": [
          "catalog:read"
        ]
      }
    },
    "/rooms": {
      "get": {
        "summary": "rooms",
        "description": "Salas de la clínica.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Número máximo de filas por página. Por defecto 50, máximo 200.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Desplazamiento de página para paginación por offset.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "id",
            "in": "query",
            "description": "Filtra por ID de sala.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "location_id",
            "in": "query",
            "description": "Filtra por ubicación.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Listado paginado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "required": [
                        "limit",
                        "offset",
                        "next_offset"
                      ],
                      "properties": {
                        "limit": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 200
                        },
                        "offset": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "next_offset": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "minimum": 0
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Parámetro inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o expirado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token sin permiso para este recurso.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Límite de peticiones superado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "get_rooms",
        "x-tactivo-required-scopes": [
          "catalog:read"
        ]
      }
    },
    "/service-locations": {
      "get": {
        "summary": "service-locations",
        "description": "Relación entre servicios y ubicaciones.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Número máximo de filas por página. Por defecto 50, máximo 200.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Desplazamiento de página para paginación por offset.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "service_id",
            "in": "query",
            "description": "Filtra por servicio.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "location_id",
            "in": "query",
            "description": "Filtra por ubicación.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Listado paginado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "required": [
                        "limit",
                        "offset",
                        "next_offset"
                      ],
                      "properties": {
                        "limit": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 200
                        },
                        "offset": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "next_offset": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "minimum": 0
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Parámetro inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o expirado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token sin permiso para este recurso.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Límite de peticiones superado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "get_service_locations",
        "x-tactivo-required-scopes": [
          "catalog:read"
        ]
      }
    },
    "/subscription-plan-services": {
      "get": {
        "summary": "subscription-plan-services",
        "description": "Servicios de clase incluidos en cada plan de suscripción del catálogo.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Número máximo de filas por página. Por defecto 50, máximo 200.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Desplazamiento de página para paginación por offset.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "plan_id",
            "in": "query",
            "description": "Filtra por ID de plan.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "service_id",
            "in": "query",
            "description": "Filtra por ID de servicio.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Listado paginado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "required": [
                        "limit",
                        "offset",
                        "next_offset"
                      ],
                      "properties": {
                        "limit": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 200
                        },
                        "offset": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "next_offset": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "minimum": 0
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Parámetro inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o expirado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token sin permiso para este recurso.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Límite de peticiones superado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "get_subscription_plan_services",
        "x-tactivo-required-scopes": [
          "catalog:read"
        ]
      }
    },
    "/subscription-plans": {
      "get": {
        "summary": "subscription-plans",
        "description": "Catálogo de planes de suscripción de clase. No incluye altas de clientes ni cobros.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Número máximo de filas por página. Por defecto 50, máximo 200.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Desplazamiento de página para paginación por offset.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "id",
            "in": "query",
            "description": "Filtra por ID de plan.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Filtra por estado del plan.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Listado paginado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "required": [
                        "limit",
                        "offset",
                        "next_offset"
                      ],
                      "properties": {
                        "limit": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 200
                        },
                        "offset": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "next_offset": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "minimum": 0
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Parámetro inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o expirado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token sin permiso para este recurso.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Límite de peticiones superado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "get_subscription_plans",
        "x-tactivo-required-scopes": [
          "catalog:read"
        ]
      }
    },
    "/services": {
      "get": {
        "summary": "services",
        "description": "Catálogo de servicios de la clínica.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Número máximo de filas por página. Por defecto 50, máximo 200.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Desplazamiento de página para paginación por offset.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "id",
            "in": "query",
            "description": "Filtra por ID de servicio.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "service_type",
            "in": "query",
            "description": "Filtra por tipo de servicio.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Listado paginado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "required": [
                        "limit",
                        "offset",
                        "next_offset"
                      ],
                      "properties": {
                        "limit": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 200
                        },
                        "offset": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "next_offset": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "minimum": 0
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Parámetro inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o expirado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token sin permiso para este recurso.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Límite de peticiones superado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "get_services",
        "x-tactivo-required-scopes": [
          "catalog:read"
        ]
      }
    },
    "/staff": {
      "get": {
        "summary": "staff",
        "description": "Miembros de staff: admin, coordinator y professional.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Número máximo de filas por página. Por defecto 50, máximo 200.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Desplazamiento de página para paginación por offset.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "id",
            "in": "query",
            "description": "Filtra por ID de profesional.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Busca por nombre, apellidos, email o teléfono.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "role",
            "in": "query",
            "description": "Filtra por rol staff.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Listado paginado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "required": [
                        "limit",
                        "offset",
                        "next_offset"
                      ],
                      "properties": {
                        "limit": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 200
                        },
                        "offset": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "next_offset": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "minimum": 0
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Parámetro inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o expirado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token sin permiso para este recurso.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Límite de peticiones superado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "get_staff",
        "x-tactivo-required-scopes": [
          "catalog:read"
        ]
      }
    },
    "/work-logs": {
      "get": {
        "summary": "work-logs",
        "description": "Registros de fichaje sin notas libres.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Número máximo de filas por página. Por defecto 50, máximo 200.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Desplazamiento de página para paginación por offset.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "id",
            "in": "query",
            "description": "Filtra por ID del registro.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "professional_id",
            "in": "query",
            "description": "Filtra por profesional.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "description": "Fecha mínima YYYY-MM-DD de work_date.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "description": "Fecha máxima YYYY-MM-DD de work_date.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Listado paginado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "required": [
                        "limit",
                        "offset",
                        "next_offset"
                      ],
                      "properties": {
                        "limit": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 200
                        },
                        "offset": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "next_offset": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "minimum": 0
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Parámetro inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o expirado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token sin permiso para este recurso.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Límite de peticiones superado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "get_work_logs",
        "x-tactivo-required-scopes": [
          "worklogs:read"
        ]
      }
    },
    "/booking/services": {
      "get": {
        "summary": "Servicios reservables",
        "description": "Servicios de cita que este token puede reservar: por defecto, los que la clínica ofrece en su reserva online; a petición de la clínica, Tactivo puede habilitar todos sus servicios de cita para una integración concreta.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Service"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Petición inválida",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Token ausente, inválido, revocado o caducado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Token sin permisos para esta operación",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Límite de 120 peticiones por minuto y token superado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "operationId": "get_booking_services",
        "x-tactivo-required-scopes": [
          "catalog:read"
        ]
      }
    },
    "/booking/professionals": {
      "get": {
        "summary": "Profesionales compatibles",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "service_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Profesionales",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Professional"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Petición inválida",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Token ausente, inválido, revocado o caducado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Token sin permisos para esta operación",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Límite de 120 peticiones por minuto y token superado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "operationId": "get_booking_professionals",
        "x-tactivo-required-scopes": [
          "catalog:read"
        ]
      }
    },
    "/booking/locations": {
      "get": {
        "summary": "Ubicaciones compatibles",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "service_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "professional_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ubicaciones",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Location"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Petición inválida",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Token ausente, inválido, revocado o caducado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Token sin permisos para esta operación",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Límite de 120 peticiones por minuto y token superado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "operationId": "get_booking_locations",
        "x-tactivo-required-scopes": [
          "catalog:read"
        ]
      }
    },
    "/booking/availability": {
      "get": {
        "summary": "Huecos disponibles",
        "description": "Huecos reservables con su hora, profesional y sede. Si la clínica no deja elegir profesional en su reserva online, devuelve un solo hueco por hora y sede, con uno de los profesionales libres, y no admite professional_id.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "service_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "professional_id",
            "in": "query",
            "description": "Solo huecos de ese profesional. Si la clínica no deja elegir profesional en su reserva online, responde 422 PROFESSIONAL_CHOICE_DISABLED.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "appointment_id",
            "in": "query",
            "description": "Para mover una cita: solo huecos de su profesional y su sede, que el cambio conserva, sin contar como ocupada la propia cita. Se admite aunque la clínica no deje elegir profesional; no se combina con professional_id ni location_id (400 AVAILABILITY_FILTER_CONFLICT). Si su profesional no se ofrece en la reserva online (o está en exclude_professional_id), responde 422 APPOINTMENT_REQUIRES_RECEPTION.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "location_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Huecos concretos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "min_notice_hours"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Slot"
                      }
                    },
                    "min_notice_hours": {
                      "type": "integer",
                      "minimum": 0,
                      "description": "Antelación mínima de reserva de la clínica, en horas. No se devuelven huecos que empiecen antes de ahora más esta antelación: un día sin huecos puede deberse a ella y no a una agenda llena."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Petición inválida",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Token ausente, inválido, revocado o caducado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Token sin permisos para esta operación",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Límite de 120 peticiones por minuto y token superado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "operationId": "get_booking_availability",
        "x-tactivo-required-scopes": [
          "calendar:read"
        ]
      }
    },
    "/booking/availability/summary": {
      "get": {
        "summary": "Huecos disponibles resumidos",
        "description": "Pensado para agentes de voz y chat. Mismos filtros, antelación y regla de elegir profesional que /availability, con el rango recortado a from + 89 días. Devuelve todas las horas libres por día en hora local (cada una con su índice tras #) y el detalle reservable de una página de huecos desde offset. Para ver el detalle de una hora fuera de la página, repite con los mismos parámetros y offset igual a su índice, y comprueba que local_date y local_time siguen siendo los elegidos antes de reservar: el índice cambia si entre medias se ocupa o caduca un hueco. location_name solo aparece si los huecos son de más de una sede. Si la consulta llega al límite de huecos, truncated=true y la lista es completa hasta complete_through: pide un rango más corto o, si la clínica deja elegir profesional, filtra por profesional.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "service_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "professional_id",
            "in": "query",
            "description": "Solo huecos de ese profesional. Si la clínica no deja elegir profesional en su reserva online, responde 422 PROFESSIONAL_CHOICE_DISABLED.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "appointment_id",
            "in": "query",
            "description": "Para mover una cita: solo huecos de su profesional y su sede, que el cambio conserva, sin contar como ocupada la propia cita. Se admite aunque la clínica no deje elegir profesional; no se combina con professional_id ni location_id (400 AVAILABILITY_FILTER_CONFLICT). Si su profesional no se ofrece en la reserva online (o está en exclude_professional_id), responde 422 APPOINTMENT_REQUIRES_RECEPTION.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "location_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "timezone",
            "in": "query",
            "description": "Zona de local_date, local_time y bookable_from. Por defecto, la de la clínica: Europe/Madrid o, en Canarias, Atlantic/Canary.",
            "schema": {
              "type": "string",
              "example": "Europe/Madrid"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "es",
                "en"
              ],
              "default": "es"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "exclude_professional_id",
            "in": "query",
            "description": "Ids de profesionales que este canal no debe ofrecer, separados por comas (como mucho 20). Pensado para fijarlo en la configuración del agente, no para que lo elija el modelo.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 16
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Horas por día y página de huecos reservables",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "time_zone",
                    "min_notice_hours",
                    "total_slots",
                    "days",
                    "offset",
                    "has_more",
                    "next_offset",
                    "slots"
                  ],
                  "properties": {
                    "time_zone": {
                      "type": "string"
                    },
                    "min_notice_hours": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "bookable_from": {
                      "type": "object",
                      "description": "Primera fecha y hora local reservable por la antelación mínima; solo si es mayor que cero.",
                      "properties": {
                        "local_date": {
                          "type": "string"
                        },
                        "weekday": {
                          "type": "string"
                        },
                        "local_time": {
                          "type": "string"
                        }
                      }
                    },
                    "total_slots": {
                      "type": "integer"
                    },
                    "truncated": {
                      "type": "boolean"
                    },
                    "complete_through": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date",
                      "description": "Último día local con la lista completa cuando truncated=true."
                    },
                    "days": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "date": {
                            "type": "string",
                            "format": "date"
                          },
                          "weekday": {
                            "type": "string"
                          },
                          "times": {
                            "type": "string",
                            "description": "Horas locales «HH:MM#índice» separadas por espacios."
                          }
                        }
                      }
                    },
                    "offset": {
                      "type": "integer"
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_offset": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "slots": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "index": {
                            "type": "integer"
                          },
                          "local_date": {
                            "type": "string"
                          },
                          "weekday": {
                            "type": "string"
                          },
                          "local_time": {
                            "type": "string"
                          },
                          "starts_at_for_booking": {
                            "type": "string",
                            "format": "date-time",
                            "description": "Valor literal para starts_at al reservar o cambiar la cita."
                          },
                          "professional_id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "professional_name": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "location_id": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "uuid"
                          },
                          "location_name": {
                            "type": [
                              "string",
                              "null"
                            ]
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Petición inválida",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Token ausente, inválido, revocado o caducado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Token sin permisos para esta operación",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Límite de 120 peticiones por minuto y token superado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "operationId": "get_booking_availability_summary",
        "x-tactivo-required-scopes": [
          "calendar:read"
        ]
      }
    },
    "/booking/clients/search": {
      "post": {
        "summary": "Buscar clientes",
        "description": "Devuelve como máximo diez candidatos; teléfono y DNI se ocultan parcialmente. Por nombre solo se busca con nombre y apellido juntos (al menos 2 letras cada uno): un nombre o un apellido sueltos no devuelven candidatos. Un teléfono puede pertenecer a varias personas. exact_match indica coincidencia del contacto o DNI, no identidad única. Confirma la persona antes de usar su id; no selecciones automáticamente el primer candidato, incluso si solo hay uno.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ClientSearchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Candidatos mínimos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "ambiguous"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "maxItems": 10,
                      "items": {
                        "$ref": "#/components/schemas/ClientCandidate"
                      }
                    },
                    "ambiguous": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Petición inválida",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Token ausente, inválido, revocado o caducado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Token sin permisos para esta operación",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Límite de 120 peticiones por minuto y token superado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "operationId": "post_booking_clients_search",
        "x-tactivo-required-scopes": [
          "clients:read"
        ]
      }
    },
    "/booking/clients": {
      "post": {
        "summary": "Crear invitado",
        "description": "Permite compartir teléfono con otros clientes. Un DNI repetido en la clínica devuelve CLIENT_ALREADY_EXISTS (409). Usa una misma Idempotency-Key para reintentar y una distinta para cada persona.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "description": "Identificador único del intento. Debe reutilizarse al reintentar exactamente la misma operación.",
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 200,
              "example": "call-20260822-appointment-1"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ClientCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Cliente creado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Client"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Petición inválida",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Token ausente, inválido, revocado o caducado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Token sin permisos para esta operación",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Cliente duplicado o conflicto de idempotencia",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Límite de 120 peticiones por minuto y token superado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "operationId": "post_booking_clients",
        "x-tactivo-required-scopes": [
          "clients:write"
        ]
      }
    },
    "/booking/clients/{client_id}/appointments": {
      "get": {
        "summary": "Próximas citas del cliente",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "client_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Citas de los próximos 90 días",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Appointment"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Petición inválida",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Token ausente, inválido, revocado o caducado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Token sin permisos para esta operación",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Límite de 120 peticiones por minuto y token superado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "operationId": "get_booking_clients_client_id_appointments",
        "x-tactivo-required-scopes": [
          "calendar:read"
        ]
      }
    },
    "/booking/appointments": {
      "post": {
        "summary": "Crear cita pendiente y sin cobrar",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "description": "Identificador único del intento. Debe reutilizarse al reintentar exactamente la misma operación.",
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 200,
              "example": "call-20260822-appointment-1"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AppointmentCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Cita creada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Appointment"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Petición inválida",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Token ausente, inválido, revocado o caducado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Token sin permisos para esta operación",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Hueco ocupado o conflicto de idempotencia",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Combinación no reservable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Límite de 120 peticiones por minuto y token superado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "operationId": "post_booking_appointments",
        "x-tactivo-required-scopes": [
          "calendar:write"
        ]
      }
    },
    "/booking/appointments/{appointment_id}": {
      "patch": {
        "summary": "Mover una cita conservando cliente, servicio, profesional y ubicación",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "appointment_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "description": "Identificador único del intento. Debe reutilizarse al reintentar exactamente la misma operación.",
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 200,
              "example": "call-20260822-appointment-1"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AppointmentMoveRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cita movida",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Appointment"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Petición inválida",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Token ausente, inválido, revocado o caducado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Token sin permisos para esta operación",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Hueco ocupado o conflicto de idempotencia",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "La cita requiere recepción",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Límite de 120 peticiones por minuto y token superado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "operationId": "patch_booking_appointments_appointment_id",
        "x-tactivo-required-scopes": [
          "calendar:write"
        ]
      }
    },
    "/booking/reception-followup": {
      "post": {
        "summary": "Avisar a recepción sobre una llamada no resuelta",
        "description": "Requiere calendar:write. Notifica solo a administradores y coordinadores de la clínica asociada al token. La misma call_id no duplica avisos. El push y la campana muestran solo el motivo y el teléfono; caller_name, client_id, note y callback_preference se ven al abrir el aviso en Tactivo. Son opcionales y nunca impiden el aviso: los textos largos se recortan y un client_id que no sea de un cliente de la clínica se descarta.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "call_id",
                  "reason"
                ],
                "properties": {
                  "call_id": {
                    "type": "string",
                    "minLength": 8,
                    "maxLength": 120
                  },
                  "callback_phone": {
                    "type": "string",
                    "maxLength": 30
                  },
                  "reason": {
                    "type": "string",
                    "enum": [
                      "booking_help",
                      "change_help",
                      "question",
                      "other"
                    ]
                  },
                  "caller_name": {
                    "type": "string",
                    "maxLength": 120,
                    "description": "Nombre de quien llama, si lo ha dado."
                  },
                  "client_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Ficha de cliente identificada en la llamada; debe ser de la misma clínica."
                  },
                  "note": {
                    "type": "string",
                    "maxLength": 500,
                    "description": "Qué necesita, en una o dos frases."
                  },
                  "callback_preference": {
                    "type": "string",
                    "maxLength": 120,
                    "description": "Cuándo prefiere que le llamen, por ejemplo «por la tarde»."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Aviso creado o llamada ya notificada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "notified": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Petición inválida",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Token ausente, inválido, revocado o caducado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Token sin permisos para esta operación",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Límite de 120 peticiones por minuto y token superado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "operationId": "post_booking_reception_followup",
        "x-tactivo-required-scopes": [
          "calendar:write"
        ]
      }
    },
    "/booking/appointments/{appointment_id}/note": {
      "post": {
        "summary": "Añadir una nota del cliente a su cita",
        "description": "Requiere calendar:write. Añade el texto en una línea nueva de la nota de la reserva, que ve solo el personal. La cita debe ser del cliente y no estar cancelada. El cliente no recibe ningún aviso.",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "appointment_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "description": "Identificador único del intento. Debe reutilizarse al reintentar exactamente la misma operación.",
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 200,
              "example": "call-20260822-appointment-1"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AppointmentNoteRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Nota añadida",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "client_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "noted": {
                          "type": "boolean",
                          "const": true
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Petición inválida",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Token ausente, inválido, revocado o caducado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Token sin permisos para esta operación",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Cita cancelada o conflicto de idempotencia",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Límite de 120 peticiones por minuto y token superado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "operationId": "post_booking_appointments_appointment_id_note",
        "x-tactivo-required-scopes": [
          "calendar:write"
        ]
      }
    },
    "/booking/appointments/{appointment_id}/cancel": {
      "post": {
        "summary": "Cancelar y retirar una cita",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "parameters": [
          {
            "name": "appointment_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "description": "Identificador único del intento. Debe reutilizarse al reintentar exactamente la misma operación.",
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 200,
              "example": "call-20260822-appointment-1"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AppointmentCancelRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cita cancelada (o eliminada, según la clínica)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CancelledAppointment"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Petición inválida",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Token ausente, inválido, revocado o caducado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Token sin permisos para esta operación",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "La cita requiere recepción",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Límite de 120 peticiones por minuto y token superado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "operationId": "post_booking_appointments_appointment_id_cancel",
        "x-tactivo-required-scopes": [
          "calendar:write"
        ]
      }
    },
    "/occupancy": {
      "get": {
        "summary": "Ocupación por profesional",
        "description": "Ocupación de cada profesional en un periodo, con las mismas cifras que el Dashboard y el Analista de Tactivo. Por cada profesional con horario devuelve los minutos de horario (semanal, semana A/B u horario especial de cada día), bloqueados (solo lo que los bloqueos tapan del horario), disponibles (horario menos bloqueos), ocupados (citas y clases no canceladas dentro de lo disponible; las no presentadas cuentan) y libres (disponibles menos ocupados). occupancy_pct es ocupados ÷ disponibles × 100 con un decimal, calculado con las sumas de cada fila y nunca promediando días; es null si todo el horario estaba bloqueado. Cuenta el personal con agenda (sin archivar y sin recepción). Fechas en Europe/Madrid, ambas incluidas; los días futuros cuentan lo ya programado. Los horarios semanales no se versionan: un periodo pasado se calcula con el horario vigente y los horarios especiales de cada fecha.",
        "operationId": "get_occupancy",
        "security": [
          {
            "ExternalApiBearer": []
          }
        ],
        "x-tactivo-required-scopes": [
          "metrics:read"
        ],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": true,
            "description": "Primer día del periodo (YYYY-MM-DD, entre 2000 y 2100).",
            "schema": {
              "type": "string",
              "format": "date",
              "example": "2026-10-01"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": true,
            "description": "Último día del periodo (YYYY-MM-DD). Como mucho 366 días; con group_by=day, 92.",
            "schema": {
              "type": "string",
              "format": "date",
              "example": "2026-10-31"
            }
          },
          {
            "name": "group_by",
            "in": "query",
            "description": "professional: una fila por profesional para todo el periodo; day, week (lunes a domingo) o month: una fila por profesional y tramo, recortada al periodo pedido.",
            "schema": {
              "type": "string",
              "enum": [
                "professional",
                "day",
                "week",
                "month"
              ],
              "default": "professional"
            }
          },
          {
            "name": "professional_id",
            "in": "query",
            "description": "Solo este profesional (identificador de GET /staff).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ocupación del periodo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "from",
                    "to",
                    "group_by",
                    "data",
                    "totals"
                  ],
                  "properties": {
                    "from": {
                      "type": "string",
                      "format": "date"
                    },
                    "to": {
                      "type": "string",
                      "format": "date"
                    },
                    "group_by": {
                      "type": "string",
                      "enum": [
                        "professional",
                        "day",
                        "week",
                        "month"
                      ]
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/OccupancyRow"
                      }
                    },
                    "totals": {
                      "description": "Todo el equipo considerado en el periodo.",
                      "$ref": "#/components/schemas/OccupancyFigures"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Petición inválida: INVALID_FROM_DATE, INVALID_TO_DATE, INVALID_DATE_RANGE, DATE_RANGE_TOO_LONG, INVALID_GROUP_BY o INVALID_PROFESSIONAL_ID",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Token ausente, inválido, revocado o caducado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Token sin permiso metrics:read",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "PROFESSIONAL_NOT_FOUND: el profesional no tiene agenda en la clínica",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Límite de 120 peticiones por minuto y token superado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  }
}
