API Quelvian — v1

Especificación OpenAPI 3.0

Spec completa en formato YAML:

Descargar openapi.yaml

Importable en Postman, Insomnia, Swagger UI o cualquier cliente compatible OpenAPI 3.0.

Autenticación

Cada request requiere el header Authorization: Bearer qvn_live_{32-hex}. La API key se genera en Settings → API Keys del workspace. Cada key tiene scopes específicos (ej. read:reservations) y opcionalmente fecha de expiración.

curl -i https://app.quelvian.com/api/v1/reservations \
  -H "Authorization: Bearer qvn_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Endpoints disponibles

• GET/api/v1/reservations

  Scope: read:reservations

  Listar reservas con filtros opcionales (status, date_from, date_to, page, per_page).

• GET/api/v1/reservations/{id}

  Scope: read:reservations

  Obtener una reserva por ID.

• GET/api/v1/properties

  Scope: read:properties

  Listar propiedades (paginado).

• GET/api/v1/conversations

  Scope: read:conversations

  Listar conversaciones del Inbox.

• GET/api/v1/conversations/{id}

  Scope: read:conversations

  Obtener una conversación por ID.

• POST/api/v1/messages

  Scope: write:messages

  Crear mensaje outbound en una conversación (body: conversation_id, content).

• GET/api/v1/webhooks

  Scope: read:webhooks

  Listar webhooks outbound configurados.

Rate limiting

Las rutas /api/v1/* están limitadas a 60 requests/minuto/IP. Si superas el límite recibirás un 429 Too Many Requests con header Retry-After indicando segundos a esperar.

Versionado y deprecación

Esta es la v1. Cambios breaking se versionarán como /api/v2/ con período de transición ≥ 90 días. Cambios non-breaking (nuevos endpoints, campos opcionales) se añadirán a v1.

Soporte

Si encuentras un bug, necesitas un nuevo endpoint o quieres reportar abuso: formulario de contacto o dani@quelvian.com.