Una API de reservas compacta y con permisos limitados.

Endpoints

Autorización, envoltorios y trazabilidad de solicitudes

GET /api/partner/v1/catalog?locale=en&limit=2 HTTP/1.1
Authorization: Bearer fnx_test_example_key_not_a_real_credential
Accept-Language: en
Origin: https://partner.example

HTTP/1.1 200 OK
Cache-Control: private, no-store
Referrer-Policy: no-referrer
X-Request-Id: <request_id>
X-RateLimit-Limit: <limit>
X-RateLimit-Remaining: <remaining>
X-RateLimit-Reset: <unix_seconds>

{
  "data": { "services": [], "next_cursor": null },
  "meta": { "request_id": "<request_id>", "version": "v1" }
}

Política de permisos y credenciales

Crear reserva

POST /api/partner/v1/bookings HTTP/1.1
Authorization: Bearer fnx_test_example_key_not_a_real_credential
Idempotency-Key: 7b1d9ed1-7f34-4ddf-9e01-example
Content-Type: application/json

{
  "service_id": "<published_service_id>",
  "location_id": "<optional_allowed_location_id>",
  "date": "2026-09-21",
  "start_time": "10:00",
  "external_reference": "partner-order-1042",
  "customer": {
    "name": "Test customer",
    "phone": "+15550001111",
    "consent_to_contact": true
  }
}

Estructura actual de la reserva

• Partner API v1 crea un servicio por reserva. El campo documentado service_id es singular; se rechazan los campos inventados service_ids o composition_mode.
• La reserva compuesta secuencial o paralela está disponible mediante el widget firmado de Feny y el flujo propio, donde el motor canónico valida combinaciones, capacidad del personal y reglas vigentes.
• No expongas una credencial Partner API en el navegador. Usa el id y la versión públicos del widget para incrustaciones y mantén las llamadas API en un servidor de confianza.

Paginación y lecturas limitadas

GET /api/partner/v1/catalog?locale=en&limit=25&cursor=<next_cursor> HTTP/1.1
Authorization: Bearer fnx_test_example_key_not_a_real_credential

{
  "data": {
    "services": ["..."],
    "next_cursor": "<opaque_cursor_or_null>"
  },
  "meta": { "request_id": "<request_id>", "version": "v1" }
}

Reglas de paginación

• Las lecturas de catálogo y especialistas aceptan limit de 1 a 50 (25 por defecto). Disponibilidad acepta de 1 a 96 (48 por defecto).
• Envía next_cursor exactamente como se recibe. Es opaco y no debe decodificarse, construirse, compartirse entre consultas no relacionadas ni usarse tras cambiar filtros.
• El next_cursor de disponibilidad representa el inicio del último hueco devuelto para esa consulta exacta. Un next_cursor nulo indica que no hay otra página.
• La disponibilidad es una lectura actual, no una reserva. Vuelve a consultarla y deja que la creación realice la comprobación final de capacidad en el servidor.

Acciones idempotentes de reserva

POST /api/partner/v1/bookings/<pbr_reference>/actions/cancel HTTP/1.1
Authorization: Bearer fnx_test_example_key_not_a_real_credential
Idempotency-Key: 11111111-2222-4333-8444-example
Content-Type: application/json

{ "expected_version": 3 }

Política de idempotencia y versiones

• Usa una Idempotency-Key de 16–128 caracteres por escritura lógica. Tras un resultado incierto, repite la solicitud exacta; usa una clave nueva para otra operación.
• Nunca reutilices una clave de idempotencia con datos distintos. La API devuelve 409 idempotency_key_reused en lugar de decidir qué solicitud es válida.
• Recupera la reserva antes de cancelar o reprogramar y envía su última versión como expected_version. Una versión obsoleta puede devolver 409 booking_version_conflict.
• No incluyas datos del cliente, credenciales ni otros valores sensibles en Idempotency-Key o external_reference.

Errores y reintentos