Skip to main content

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​

FamilyBase pathAuthEndpoints
Public Partner API/api/partnerX-API-Key (seed-test-data @Public, dev/test only)7
Partner Registration/api/partnersPublic + throttling2
Partner Portal/api/partner-portalJWT partner user26
Admin Partners/api/admin/partnersJWT admin11
Settings/api/partner-settingsJWT partner user10
Users/api/partners/usersJWT + permissions9
Reports/api/partner-reportsJWT partner user7
Reservations/api/partner-reservationsJWT partner user6
Webhooks/api/partners/webhooksJWT + permissions (test); ADMIN for trigger2
Sandbox/api/partner-sandboxSandbox sk_test_ key3
Webhook Simulator/api/partner/webhooks/simulatorSandbox sk_test_ key4

Total current partner endpoints: 87

Sandbox is live

The partners_sandbox schema is in place. Portal sandbox generate/reset/status, /api/partner-sandbox/* (generate-data, statistics, cleanup), and the webhook simulator are live when the schema exists.

  • Portal (/api/partner-portal/sandbox/*, including POST /api/partner-portal/sandbox/reset): soft-fail — HTTP 200 with a payload explaining unavailability if the schema is missing. Reset exists only on this portal path (not under /api/partner-sandbox).
  • /api/partner-sandbox/* (no reset route):
    • POST generate-data: hard-fail — HTTP 400 partners.sandbox_schema_not_available if the schema is missing
    • GET statistics: soft-degrade — returns zeros when the schema is missing
    • DELETE cleanup: soft-degrade — success with deletedRecords: 0 when the schema is missing
Production API key rule

Use sk_live_* for /api/partner/* and other production partner routes. sk_test_ / sandbox keys are allowed only on /api/partner-sandbox/* and /api/partner/webhooks/simulator/*. Elsewhere they return 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
  • the /api/partner family is mostly API-key protected; POST /api/partner/seed-test-data is @Public but only allowed when config.environment is development or test — production returns Forbidden error.partner.seed_not_allowed_in_production (not a partner production helper)

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"]
    }
  }
}

External integrations​

New partner onboarding​

Portal and operations​

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).