# REST `alya/v1` reference

Auth public: `wp_rest` nonce + IP buckets (`verify_public_nonce_and_limit`). Staff: capabilities. API key never in browser.

## Hotels (public unless noted)

| Method | Endpoint | Limit (code) | External |
|--------|----------|--------------|----------|
| GET | `/search` | 40/600s | LiteAPI hotels search |
| GET | `/places` | 30/600s | places |
| GET | `/place-details` | 20/600s | place details |
| GET | `/hotel-details` | nonce | hotel |
| POST | `/rates` | 20/600s | hotels/rates |
| POST | `/prebook` | nonce | rates/prebook |
| POST | `/book` | 10/600s | rates/book |
| GET | `/booking/{id}` | nonce | bookings |
| POST | `/cancel` | **staff** `verify_cancel_permission` | cancel |
| GET | `/config` | public | no secrets |
| GET | `/reviews` | nonce | reviews |
| GET | `/facilities` `/hotel-types` `/chains` `/countries` `/currencies` `/languages` `/cities` | nonce | data |

## Flights

`/flights/airports` 30/600, `/search` 10/600, `/verify` 15/600, `/prebook` **8/600**, `/book`, `/sync`, cancel-quote/cancel, itinerary, confirmation, ops (staff).

## Webhooks

`POST /webhooks/nuitee`, `/flights/nuitee-webhook`, `/flights/stripe-webhook`.

## Cockpit (logged-in caps)

`/pricing/margin`, `/pricing/rules`, `/customers`, `/team`, `/notifications*`, `/cache/*`, `/hotels/sync`, `/destinations/sync`, `/documents/issue`, `/emails/send`, `/crm/import`, `/helpdesk/*`, `/ops/health|snapshot|uptime`.

Errors: WP_Error JSON. Rate limit → 429 + Retry-After. Circuit open → 429.

---

## How to read this table

Never invent request/response JSON. Fields below are **confirmed from route registration and permission callbacks**. Full payload shapes: see PHP services (`NuiteeClient`, `Flight*Service`). Live `/book` was **not** called this audit.

### Convention

| Column | Meaning |
|--------|---------|
| Auth | `nonce` = `wp_rest`; `staff` = capability; `public` = `__return_true` |
| DB | Local effects when the handler succeeds |
| Front | Primary JS caller |

### Hotels (detail)

| Endpoint | Method | Auth | Nonce/limit | Capability | External | DB | Front |
|----------|--------|------|-------------|------------|----------|-----|------|
| `/search` | GET | nonce | 40/600 | — | LiteAPI hotels | cache possible | `alya-hotel.js` |
| `/places` | GET | nonce | 30/600 | — | places | — | search autocomplete |
| `/place-details` | GET | nonce | 20/600 | — | place details | — | search |
| `/hotel-details` | GET | nonce | nonce | — | hotel | hotel cache | fiche |
| `/rates` | POST | nonce | 20/600 | — | hotels/rates + margin | — | fiche/checkout |
| `/prebook` | POST | nonce | nonce | — | rates/prebook | CPT/index prebook | checkout |
| `/book` | POST | nonce | 10/600 | — | rates/book | CPT confirmed | checkout **not called this audit** |
| `/booking/{id}` | GET | nonce | nonce | — | bookings GET | — | confirmation |
| `/cancel` | POST | staff | — | `verify_cancel_permission` | cancel | status log | staff |
| `/config` | GET | public | none | — | none | none | all widgets |

Request/response bodies: **not invented**. See `Routes.php` callbacks.

### Flights (detail)

Search 10/600, verify 15/600, prebook **8/600**, airports 30/600. Ops routes: `verify_staff_permission`. Cancel B2C: public nonce + session.

Frontend: `alya-flights.js`. Live search this pass failed on nonce before LiteAPI.

### Errors

429 + Retry-After. Circuit open 429. NuiteeException mapped to WP_Error. Flight “Session de page expirée” is the front copy for a stale nonce. `VERIFIED LIVE`