Property REST interface: endpoints and responses
The portal-side property REST endpoints: API key authentication, function right, list, data sheet, image, response structure and error codes.
The portal-side property interface offers three read-only REST endpoints to external systems. It has no table of its own; it reads the property master and the document store through the portal-side models. Its OpenAPI description is supplied to the central API explorer (tag: property).
Endpoints
| Path | Operation | Parameters |
|---|---|---|
GET /masterdata/property | listProperties | since (YYYY-MM-DD HH:MM:SS), page (default 1), limit (default 100, max. 500) |
GET /masterdata/property/{property_id} | getProperty | property ID |
GET /masterdata/property/{property_id}/image/{doc_id} | getPropertyImage | property and document ID |
Process
- Gate on every endpoint: the API key (header
X-Oc-Api-Key) resolves to a user; an invalid key returns "Invalid or missing API key." (UNAUTHORIZED, 401) and writes a warning log line. - Function right of the key's user:
masterdata/property+export; otherwise "Permission denied." (PERMISSION_DENIED, 403). - List:
sincefilters on the modification time, or the creation time if there is none. Response:properties[]with ID, own ID, status and modification date. It does not filter by status. - Data sheet: the export shape (
Dlbtproperty::exportShape()): types, uses, texts per language, address, geo coordinates, figures (net, gross and plot area, rooms, half rooms, year built, floor, building floors), details (without the withdrawn advert fields), rooms, per-level totals, utility meters, stores, media. Media items: ID, role, name, extension, SHA-256; for images also order and download URL. Only documents of companies in the key user's API scope. A missing property: "The property was not found." (NOT_FOUND, 404). - Image: only a document linked to the property, with an image extension and in scope; JPEG, at most 2048 px,
Cache-Control: private, max-age=3600. OtherwiseNOT_FOUND.
Errors use the common REST envelope: success:false, error, error_code, with the HTTP status taken from the code; exceptions return DB_QUERY_ERROR (500).
Permissions
- Base access: the portal-side path with a valid API key.
- Function right:
masterdata/propertyexportfor the key's user. - Content scope: the API scope applies to documents and images (the document's company). The text and figures of the property are passed on without a company scope.
Known limitations
Adapters for listing portals (for example real estate portals or the OpenImmo format) are not in the code; they are a separate task. The admin-side property export returns the same shape without image URLs.