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

6.8 KiB

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.
{
  "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.
{
  "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.

  • 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.
[
  {"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).

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.