Partner API Overview

This overview reflects the real controller structure currently implemented in LosCenotes API.

Base URL

https://service-gateway.loscenotes.com/api

All routes shown in this documentation already include the global /api prefix.

Partner endpoint families

Family	Base path	Auth	Endpoints
Public Partner API	/api/partner	X-API-Key (seed-test-data @Public, solo dev/test)	7
Partner Registration	/api/partners	Public + throttling	2
Partner Portal	/api/partner-portal	JWT partner user	26
Admin Partners	/api/admin/partners	JWT admin	11
Settings	/api/partner-settings	JWT partner user	10
Users	/api/partners/users	JWT + permissions	9
Reports	/api/partner-reports	JWT partner user	7
Reservations	/api/partner-reservations	JWT partner user	6
Webhooks	/api/partners/webhooks	JWT + permissions (test); ADMIN for trigger	2
Sandbox	/api/partner-sandbox	Sandbox sk_test_ key	3
Webhook Simulator	/api/partner/webhooks/simulator	Sandbox sk_test_ key	4

Total current partner endpoints: 87

Sandbox en vivo

El schema partners_sandbox está disponible. Portal sandbox generate/reset/status, /api/partner-sandbox/* (generate-data, statistics, cleanup) y el webhook simulator están en vivo cuando el schema existe.

• Portal (/api/partner-portal/sandbox/*, incluyendo POST /api/partner-portal/sandbox/reset): soft-fail — HTTP 200 con payload explicando indisponibilidad si falta el schema. El reset existe solo en esta ruta del portal (no bajo /api/partner-sandbox).
• /api/partner-sandbox/* (sin ruta reset):
  • POST generate-data: hard-fail — HTTP 400 partners.sandbox_schema_not_available si falta el schema
  • GET statistics: soft-degrade — devuelve ceros si falta el schema
  • DELETE cleanup: soft-degrade — success con deletedRecords: 0 si falta el schema

Production API key rule

Usa sk_live_* para /api/partner/* y otras rutas partner de producción. Las claves sk_test_ / sandbox solo se permiten en /api/partner-sandbox/* y /api/partner/webhooks/simulator/*. En cualquier otro sitio devuelven Forbidden error.partner.sandbox_key_not_allowed_on_production_api.

Credential SSOT (short)

• Auth: X-API-Key → partner_api_keys (no x-api-secret)
• JSONB api_configuration: metadata + apiEnabled only
• Remint: regenerate once-reveal only (enableApi does not mint)

Response architecture

Partner endpoints follow the standard LosCenotes wrapper:

{
  "success": true,
  "message": "partners.portal.dashboard_retrieved",
  "data": {},
  "pagination": {
    "total": 25,
    "perPage": 15,
    "currentPage": 1,
    "lastPage": 2
  },
  "currency": {
    "code": "MXN",
    "symbol": "$"
  }
}

Notes

• pagination only appears on list endpoints
• currency only appears on pricing-related endpoints
• some endpoints return plain metadata objects in data, others return arrays or detail objects
• la familia /api/partner está mayormente protegida por API key; POST /api/partner/seed-test-data es @Public pero solo se permite cuando config.environment es development o test — en producción devuelve Forbidden error.partner.seed_not_allowed_in_production (no es un helper de producción para partners)

Error shape

Error responses can include validation details like these:

{
  "success": false,
  "message": "validation.invalid_input",
  "statusCode": 400,
  "timestamp": "2026-03-10T18:00:00.000Z",
  "path": "/api/partner/reservations",
  "errors": {
    "messages": ["guestEmail must be an email"],
    "fields": {
      "guestEmail": ["guestEmail must be an email"]
    }
  }
}

Navigation by use case

External integrations

• Public Partner API quick reference
• Pricing
• Checkout
• Discounts and coupons

New partner onboarding

• Partner registration
• Authentication
• Quickstart

Portal and operations

• Partner portal APIs
• Admin APIs
• Management features

Shared platform APIs

Not every integration endpoint lives under src/partners. Partners also commonly use shared modules:

• /api/pricing/*
• /api/payment-methods*
• /api/checkout/*
• /api/public/discount-rules/*
• /api/coupons/*
• /api/cenotes/*

Those are documented in the shared platform section of this docs site.

---

Verified against controllers on 2026-07-21 (partners-finish-plan WU4).