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[] (JSON de display). Enviar defaultRate / intentar cambiar seller_profiles.commissionRate se rechaza (403 error.partner.commission_rate_admin_only si llega al servicio). Los cambios de tasa de payout van por APIs admin de partners.

webhookUrl en configuración API

PATCH /api/partner-settings/api con webhookUrl debe ser HTTPS público. URLs privadas/metadata se rechazan (misma política SSRF + DNS fijado que los webhooks del portal).

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 un partner_user pendiente (isActive=false). No envía email automáticamente (emailDelivery=pending_manual). Roles de sistema distintos de client se rechazan. Las cuentas placeholder nuevas permanecen con rol de sistema client hasta aceptar.

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

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 ADMIN (@Roles(ADMIN)); distinto del endpoint de prueba del partner arriba

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á live cuando existe el schema partners_sandbox (migración v23.0.62+). Requiere una API key sandbox sk_test_. Estas claves no son válidas en rutas de producción /api/partner/* (sandbox_key_not_allowed_on_production_api). Los conteos de generate están limitados (máx. 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 ≤ 10s, batch ≤ 20 eventos, history limit ≤ 500 (validado + clamp en servidor). Los POST salientes usan el mismo guard SSRF y DNS fijado (el DNS se resuelve después de cualquier delay).

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:

Method	Path	Permission
GET	/api/partner-portal/cenotes	partner.view_cenotes
POST	/api/partner-portal/cenotes	partner.manage_cenotes
GET	/api/partner-portal/cenotes/:id	partner.view_cenotes
PATCH	/api/partner-portal/cenotes/:id	partner.manage_cenotes
POST	/api/partner-portal/cenotes/:id/images	partner.manage_cenotes
POST	/api/partner-portal/cenotes/:id/request-publish	partner.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.

Notes

• estas rutas no forman parte de la capa pública de integración con API key
• la mayoría requiere JWT + contexto partner o permisos adicionales
• reports y estadísticas de reservas exponen montos en cents a nivel de contrato API
• POST /api/partner-settings/api-keys/regenerate revela apiKey una sola vez (auth JWT + roles/permisos partner; no hay x-api-secret funcional); deactivate+insert corre en transacción DB
• Verificado contra partner-supply-cenotes (2026-08-04)