Saltar al contenido principal

Partner Management Features

APIs operativas usadas por organizaciones partner autenticadas después del onboarding.

1. Settings (/api/partner-settings)​

  • GET /api/partner-settings
  • PATCH /api/partner-settings/profile
  • PATCH /api/partner-settings/business
  • PATCH /api/partner-settings/branding
  • POST /api/partner-settings/api-keys/regenerate
  • PATCH /api/partner-settings/api
  • PATCH /api/partner-settings/notifications
  • PATCH /api/partner-settings/billing
  • GET /api/partner-settings/commission
  • PATCH /api/partner-settings/commission
La comisión la controla admin

PATCH /api/partner-settings/commission solo acepta customRates[]. Enviar defaultRate, o intentar cambiar la tasa de pago, responde 403 error.partner.commission_rate_admin_only. La tasa de pago se cambia por la API admin de partners.

webhookUrl en configuración API

PATCH /api/partner-settings/api con webhookUrl debe ser HTTPS público. Las URLs privadas y de metadata se rechazan. La entrega no sigue redirecciones.

2. Users (/api/partners/users)​

  • POST /api/partners/users
  • GET /api/partners/users
  • GET /api/partners/users/statistics
  • GET /api/partners/users/:userId
  • PATCH /api/partners/users/:userId
  • DELETE /api/partners/users/:userId
  • POST /api/partners/users/invite
  • GET /api/partners/users/:userId/permissions
  • POST /api/partners/users/:userId/update-access
Invite pendiente + email manual

POST /api/partners/users/invite crea una membresía pendiente (isActive=false). No envía correo (emailDelivery=pending_manual). Los roles distintos de client se rechazan. Las cuentas nuevas quedan en el rol client hasta que aceptan.

3. Reports (/api/partner-reports)​

  • GET /api/partner-reports/revenue
  • GET /api/partner-reports/performance
  • GET /api/partner-reports/top-destinations
  • GET /api/partner-reports/daily-revenue
  • GET /api/partner-reports/monthly-trend
  • GET /api/partner-reports/commission
  • GET /api/partner-reports/cenote-comparison
  • GET /api/partner-reports/owned-venues — reservas e ingresos de los cenotes que operas. Query startDate y endDate (YYYY-MM-DD). Requiere partner.view_reports y partner.view_cenotes.

4. Reservations (/api/partner-reservations)​

  • GET /api/partner-reservations
  • GET /api/partner-reservations/stats
  • GET /api/partner-reservations/:id
  • POST /api/partner-reservations
  • PATCH /api/partner-reservations/:id
  • POST /api/partner-reservations/:id/cancel
Create body en paridad WEB

POST /api/partner-reservations (y el público POST /api/partner/reservations) aceptan los mismos campos core de booking WEB: ageBreakdown?, nationality?, transportationType?, pickup, additionalServices?, couponCode?, promotionId?, locale?, paymentMethod?, más guest/contact. Los filtros de lista honran alias dateFrom/dateTo y sortDirection junto a startDate/endDate/sortOrder.

5. Webhooks (/api/partners/webhooks)​

  • POST /api/partners/webhooks/test — partner JWT + permissions (partner.manage_settings); endpoint de prueba del partner
  • POST /api/partners/webhooks/trigger — solo JWT de admin. El usuario partner llama POST /api/partners/webhooks/test (partner.manage_settings).

El CRUD de webhooks del portal vive en /api/partner-portal/webhooks* y exige HTTPS público + sin redirects + DNS fijado en test/entrega saliente.

6. Sandbox (/api/partner-sandbox) — live​

información

Sandbox está disponible cuando el almacenamiento sandbox está provisionado. Requiere una API key sk_test_. Esas claves no valen en /api/partner/* (error.partner.sandbox_key_not_allowed_on_production_api). Generate está topado (máximo 50 por tipo de recurso).

  • POST /api/partner-sandbox/generate-data
  • GET /api/partner-sandbox/statistics
  • DELETE /api/partner-sandbox/cleanup

7. Webhook simulator (/api/partner/webhooks/simulator) — live​

Requiere clave sandbox sk_test_ (misma restricción de API de producción que §6).

  • POST /api/partner/webhooks/simulator/simulate
  • POST /api/partner/webhooks/simulator/simulate-batch
  • POST /api/partner/webhooks/simulator/test-endpoint
  • GET /api/partner/webhooks/simulator/history
Límites del simulator

delay máximo 10 segundos, lote máximo 20 eventos, limit del historial máximo 500. El envío solo acepta HTTPS público y no sigue redirecciones.

8. Supply cenotes (/api/partner-portal/cenotes) — solo partners de supply​

Tipos elegibles: tour_operator y hotel_partner (activos + verificados). Tipos solo-demanda (OTA, travel agency, etc.) reciben 403.

Requiere JWT + roles partner (partner_admin / partner_manager) y permisos:

MethodPathPermission
GET/api/partner-portal/cenotespartner.view_cenotes
POST/api/partner-portal/cenotespartner.manage_cenotes
GET/api/partner-portal/cenotes/:idpartner.view_cenotes
PATCH/api/partner-portal/cenotes/:idpartner.manage_cenotes
POST/api/partner-portal/cenotes/:id/imagespartner.manage_cenotes
POST/api/partner-portal/cenotes/:id/request-publishpartner.request_publish_cenote
Flujo

draft → request-publish → pending_review → admin publish (active) o reject-publish (vuelve a draft). Admin puede suspend / reactivate. El partner solo edita y adjunta imágenes en draft. El attach exige un archivo subido por el mismo usuario (uploaded_by).

Checklist antes de request-publish / publish admin: nombre ES, pricing (agePricing o paquetes), ≥1 imagen activa.

Métricas de venues propios: GET /api/partner-reports/owned-venues.

Notas​

  • Estas rutas no son la integración pública con API key
  • La mayoría exige JWT de partner y un permiso
  • Los montos de reportes y reservas van en centavos
  • POST /api/partner-settings/api-keys/regenerate devuelve apiKey una vez. La auth es el JWT del partner. No envíes x-api-secret.