Guía del desarrollador - API Celebrae

Guía para integrar tu aplicación con Celebrae mediante la API pública.

Índice

Flujo de integración
Quick start
Arquitectura
Autenticación
Flujo típico: crear reserva
Webhooks
Idempotencia
Buenas prácticas

Flujo de integración

sequenceDiagram
    participant Dev as Tu app
    participant API as API Celebrae
    participant Webhook as Tu webhook

    Note over Dev,API: 1. Obtener credenciales (soporte Celebrae)
    Dev->>API: GET /shops (Authorization)
    API-->>Dev: Lista de shops

    Dev->>API: GET /shops/:id/experiences
    API-->>Dev: Experiencias disponibles

    Dev->>API: POST /bookings (Idempotency-Key)
    API-->>Dev: Booking creado

    Note over API,Webhook: 2. Webhook asíncrono
    API->>Webhook: POST booking.created
    Webhook-->>API: 200 OK

Quick start

1. Obtener credenciales

Si tienes un local en Celebrae, crea tus credenciales desde el panel: Mi local → API y webhooks → Credenciales. Obtendrás:

client_id (ej. ce_abc123...)
secret (guárdalo de forma segura, solo se muestra una vez)

2. Probar la conexión

curl -H "Authorization: Bearer TU_CLIENT_ID:TU_SECRET" \
  https://api.celebrae.com/api/v1/shops

3. Crear una reserva

curl -X POST \
  -H "Authorization: Bearer TU_CLIENT_ID:TU_SECRET" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-123" \
  -d '{
    "kit_id": "uuid-experiencia",
    "shop_id": "uuid-shop",
    "booking_date": "2024-06-15",
    "booking_time": "10:00",
    "number_of_people": 2,
    "buyer_name": "Juan Pérez",
    "buyer_email": "juan@ejemplo.com"
  }' \
  https://api.celebrae.com/api/v1/bookings

Arquitectura

Modelo de datos

Shop: Negocio/local (tu partner tiene acceso a uno o varios)
Experience (kit): Experiencia ofertada (tour, clase, etc.)
Extra: Add-on de una experiencia (fotos, transporte, etc.)
Booking: Reserva asociada a una experiencia

Relaciones

Shop 1──* Experience 1──* Extra
Shop 1──* Order 1──* Booking

Reservas vía API

Las reservas creadas por API tienen payment_source: 'external':

No pasan por el checkout de Celebrae
El pago se gestiona en tu sistema
Se dispara el webhook booking.created para sincronización

Restricciones:

No se genera flujo de pago CELEBRAE; el pago se gestiona fuera.
Posibles restricciones en QR, validación en punto de venta y notificaciones según configuración del producto.
Para integraciones con proveedores externos (Turitop, Octo, etc.), contacta a soporte.

Autenticación

Formato

Authorization: Bearer <client_id>:<secret>

Seguridad

Nunca expongas el secret en frontend o código público
Usa variables de entorno en tu servidor
Rota el secret si sospechas que se ha comprometido (contacta a soporte)

Multi-tenant

Tu API client puede tener acceso a varios shops. Cada petición se filtra automáticamente por los shops asociados.

Flujo típico: crear reserva

Paso 1: Listar shops

GET /api/v1/shops

Obtienes los shops a los que tienes acceso.

Paso 2: Listar experiencias del shop

GET /api/v1/shops/{shop_id}/experiences

Paso 3: Obtener detalle y extras

GET /api/v1/experiences/{experience_id}?include=extras

Paso 4: Crear reserva

POST /api/v1/bookings
Headers: Idempotency-Key: <uuid-unico>
Body: { kit_id, shop_id, booking_date, booking_time, number_of_people, buyer_name, buyer_email, ... }

Paso 5: Recibir webhook (opcional)

Si configuraste un endpoint, recibirás booking.created con los datos de la reserva.

Webhooks

Configuración

Los endpoints de webhook se configuran por el equipo Celebrae. Proporciona:

URL HTTPS de tu servidor
Eventos que quieres recibir (ej. booking.created)

Verificación

Siempre verifica la firma X-Celebrae-Signature:

function verifyWebhook(payload, signature, timestamp, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${payload}`)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex')
  );
}

Respuesta

Responde 200 OK lo antes posible. Procesa el payload de forma asíncrona si es necesario.

Reintentos

Celebrae reintenta automáticamente con exponential backoff si tu endpoint falla. Los reintentos se pueden consultar en GET /api/v1/webhooks/deliveries.

Idempotencia

Para POST /bookings es obligatorio el header Idempotency-Key.

Comportamiento

Misma key + mismo body: Devuelve la respuesta anterior (no crea duplicado)
Misma key + body distinto: 409 Conflict
Key nueva: Procesa y crea la reserva

Ejemplo

const idempotencyKey = crypto.randomUUID();
// O: hash de (user_id + booking_params) si quieres deduplicar por lógica de negocio

fetch('/api/v1/bookings', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${clientId}:${secret}`,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(bookingData),
});

Buenas prácticas

1. Manejo de errores

Comprueba siempre el status de la respuesta y el cuerpo en formato Problem Details:

const res = await fetch(url, options);
const data = await res.json();
if (!res.ok) {
  // data.title, data.detail, data.code
  throw new Error(data.detail || data.title);
}

2. Reintentos

Para errores 5xx o de red, implementa reintentos con backoff. No reintentes en 4xx (excepto 429).

3. Rate limiting

Respeta los límites (si se aplican). El header Retry-After puede indicar cuándo reintentar.

4. Logs

No registres credenciales ni tokens. Sí puedes loguear client_id (sin secret) para debugging.

5. Webhooks

Verifica siempre la firma
Responde 200 rápido
Usa X-Celebrae-Idempotency-Key para deduplicar en tu lado si lo enviamos

Recursos

API Reference - Especificación completa de endpoints
Developer Portal - Análisis de gaps - Qué falta para un portal completo