Files
typo3-13/docs/cms-api.md
T
frommeandClaude Opus 5.5 5455973dba feat: Kalender-Code replaces the product's calendar hotel
Every hotel field now has one job. The hotel's code and aliases are
import codes only (dates, lookups); a new Kalender-Code (calendar_code)
decides the availability a record shows and may be shared by a house's
summer and winter records. The product's "Unterkunft für
Belegungskalender" is replaced by the checkbox "Kalender anzeigen"
(show_calendar): a product page shows the calendar of the hotel it
displays, the season still decides which one.

- Price calendar, price tables, Belegungskalender, iCal feeds and
  /api/calendar-hotels read the Kalender-Code. A feed without one answers
  404 instead of an empty calendar.
- The upgrade wizard epProductsCalendarCode fills both fields from
  calendar_hotel, preserving today's calendars; the deploy runs it between
  the schema update and the switch. calendar_hotel stays in the database,
  so the previous release keeps working. ep:calendar-codes lists the
  product pages whose calendar differs from it.
- HotelCodeResolver is the one lookup of import codes (date import,
  /api/hotel, Travelinfo); a code on several records resolves to the
  record whose own code it is, then the lowest uid, with a warning.
  Saving a code that is already another visible record's import code is
  refused with a message naming that record.
- /api/product without hotel attaches the product's only visible
  Unterkunft (422 otherwise) and adds board_description,
  additional_services and calendar_hotel_code.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-11-16 17:18:00 +01:00

137 lines
6.8 KiB
Markdown

# CMS API
Endpoints TYPO3 serves to other systems: **MyE&P** (hotel and product content, calendar hotels),
the **chatbot** (content feed) and **n8n** (JSON-LD of content elements). They are answered by `EP\EpProducts\Middleware\ApiMiddleware`
before the page resolver, so they do not depend on a page and are never page-cached.
The other side of these contracts is documented in MyE&P's `docs/api-consumer-guide.md`
(`EP/myep`).
## Authentication
All endpoints except `/api/json-ld/` (see there) need the shared key `cmsApiKey` from the `ep_products` extension configuration
(Settings → Extension Configuration → ep_products, tab ContentFeed):
- header `X-Api-Key: <key>` (preferred, query strings end up in access logs), or
- query parameter `?key=<key>`.
A missing or wrong key answers `403 {"message": "Invalid or missing api key"}`. An empty
`cmsApiKey` denies every request. MyE&P sends the key as `APP_CMS_API_KEY`; both sides must be
changed together.
## `GET /api/hotel?hotel=<code>`
Content of one hotel, for MyE&P's group house pages and booking flow.
- `hotel`: an import code of the record: its "Import-Code" or one of its "Weitere Import-Codes"
(matchcode aliases), resolved by `HotelCodeResolver`. In MyE&P this is the accommodation's
**CMS code** (e.g. `DGSGRP`), which can differ from its calendar code.
- `400` without `hotel`, `404 {"message": "Hotel not found"}` for an unknown code.
```json
{
"name": "…", "code": "…",
"description": "…", "features": "…", "room_types": "…",
"additional_information": "…", "address": "…",
"images": {"original": [{"url": "…", "alt": "…", "title": "…"}], "resized": […]},
"icons": […],
"region": {"name": "…", "latitude": …, "longitude": …, "webcam": "…", "ski_area": "…",
"ski_area_extended": "…", "description": "…", "news": "…", "length": …,
"altitude": …, "lifts": …, "images": {…}, "region_maps": [{"url": "…", "alt": "…", "title": "…"}]}
}
```
## `GET /api/product?product=<code>[&hotel=<code>]`
Content of one product with a hotel.
- `product`: the product code (default language). `400` without it, `404 {"message": "Product
not found"}` for an unknown code.
- Without `hotel` (MyE&P's group houses, linked by product code): the product's only visible
Unterkunft. Any other number of visible Unterkünfte answers `422 {"message": "Product <code>
links <n> hotels, expected exactly 1", "hotel_count": <n>}`.
- With `hotel` (MyE&P's booking flow): the record of that import code, as in `/api/hotel`; an
unknown code gives `"hotel": []`.
- `board_description`, `additional_services`: raw RTE values, `""` when empty.
- `calendar_hotel_code`: the Kalender-Code of the hotel when "Kalender anzeigen" is on, else
`null`. MyE&P compares it with its accommodation's calendar code.
```json
{
"product": {"name": "…", "code": "…", "images": {…}, "board_description": "…",
"additional_services": "…", "calendar_hotel_code": "SST"},
"country": {"name": "…"},
"region": {…},
"city": {"name": "…"},
"hotel": {…}
}
```
## `GET /api/calendar-hotels`
The Kalender-Codes of all visible hotel records: the codes whose availability TYPO3 shows (iCal
feeds, availability calendar, price calendar). MyE&P syncs its contingent snapshot for these codes
in addition to its accommodations, so hotels offered only in winter, which have no accommodation in
MyE&P, have availability too. See [calendars.md](calendars.md).
- One entry per code; `name` of the record whose import code it is, else of the first record.
- `products`: visible products with "Kalender anzeigen" that link a record with the code under
Unterkünfte.
- Sorted by code; products by uid. Names have line breaks collapsed.
- `season`: `"s"` (summer), `"w"` (winter) or `null`.
```json
[
{"code": "DKI", "name": "Sportclub Schwendi", "products": [
{"uid": 155, "name": "Sportclub Schwendi", "season": "w"},
{"uid": 362, "name": "Gruppenhaus Schwendi", "season": "s"}
]}
]
```
Every code in this list should be a **BusPro code** with a contingent (see
[calendars.md](calendars.md#hotel-codes)).
## `GET /api/content/manifest` and `GET /api/content/records?type=<type>&uids=<uids>`
The content feed for the chatbot (`EP\EpProducts\ContentFeed\ContentFeedApi`).
- `manifest`: everything the feed publishes (pages of the configured sites and records), with a
modification timestamp per item. Cached for 10 minutes.
- `records`: up to 100 records of one type per request. `type` is one of `product`, `hotel`,
`region`, `country`, `city`, `concept`, `news`; `uids` comma-separated. Uids that are no longer
eligible are left out, not answered with an error (the consumer reads them as deleted).
- `400` for an unknown type, no uids or more than 100 uids; `404` for other paths.
- `503` with `Retry-After: 3600` when the feed is switched off (`contentFeedEnabled = 0`, the kill
switch for when the host is struggling), `503` when `contentFeedSites` is empty. The consumer
keeps what it has on a 503; nothing is deleted on the chatbot side.
Configuration (extension configuration `ep_products`, tab ContentFeed): `contentFeedEnabled`,
`contentFeedSites`, `contentFeedLanguages`, `contentFeedExcludedPages`,
`contentFeedNewsDetailPages`.
## `PUT /api/json-ld/<uid>`
n8n writes the JSON-LD (SEO markup) of a content element (`EP\EpProducts\JsonLd\JsonLdApi`).
n8n is the source of truth: the element's `bodytext` is replaced with the posted object wrapped in
`<script type="application/ld+json">`, whatever the element held before. Only plain html elements
(`CType` `html`) are written, any other type is refused, so a wrong uid cannot replace visible page
content. Other fields (hidden, …) are left alone; each translation is its own uid.
- Key: `jsonLdApiKey` (extension configuration `ep_products`, tab JsonLd), only as header
`X-Api-Key`; `?key=` is not accepted.
- `POST` does the same as `PUT` (n8n's default method).
- Body: the JSON-LD object (or array of objects) itself, e.g.
`{"@context": "https://schema.org", "@type": "Event", …}`. Pretty-printed when stored;
`<` and `>` are escaped as `\u003C`/`\u003E`, so a value cannot close the script element.
- `200 {"uid": 13169, "pid": 24, "changed": true}`; `changed: false` when the stored markup is
already identical (nothing written).
- `400` for invalid JSON or a scalar, `403` for a wrong or missing key, `404` for an unknown or
deleted uid, `405` for other methods, `409` when the element is not of type `html`, `503` when
the backend user `_n8n` is missing, `500` with `errors` when DataHandler refuses the write.
The write goes through DataHandler as the backend user `_n8n` (no password, so no login; group
`n8n` with *Tables (modify)* `tt_content` and *Explicitly allow* `tt_content:CType:html`; page
permissions are bypassed). Every change is in the element's history, where it can be undone, and
clears the page cache.