Global Stocks – JSON API Documentation
All endpoints except /api/docs require HTTP Basic Authentication.
Two login pairs are supported: primary (username/password) and optional second (username2/password2 in config).
Example usage: curl -u "username:password" "https://api.globalstocks.eu/api/product-catalog"
Example JSON responses (auth required): https://www.api.globalstocks.eu/api/docs/examples
| Method | Path | Description | |
|---|---|---|---|
| GET | /api/docs | API documentation (this page). | Try it → |
| GET | /api/pages-content | PagesContent – pagestranslation (id, parent_id, lang, title, content). | Try it → |
| GET | /api/category-list | CategoryList – stockcategorylist (id, parent_id, title, route, language, level). | Try it → |
| GET | /api/site-pages | SitePages – sitepagesconfig (id, route, title, type, lang). | Try it → |
| GET | /api/domain-configuration | DomainConfiguration – domainconfiguration. | Try it → |
| GET | /api/product-catalog | Product list (default limit 30, totalCount in meta) or single item by id. Filters: region, category. | Try it → |
| GET | /api/product-catalog-search | Search title/description. Filters: region, category. All matches by default; optional pagination. | Try it → |
| GET | /api/product-count | Total count. Optional by=category or by=region for grouped breakdown. | Try it → |
| GET | /api/product-files | Documents and pictures for one product. Returns files[] and images[]. Query: id (required). | Try it → |
| GET | /api/banner-config | BannerConfig – bannerconfig. | Try it → |
| GET | /api/seasonal-offer | Static franchise seasonal offer (HTML header + content). Visible 2026-06-01 to 2026-06-30 (active flag). | Try it → |
| POST | /api/subscribers | Create a newsletter subscriber (subscribers_new). JSON body; HTML in any field is rejected. | |
| POST | /api/messages | Submit a site contact message (messages_new). type must be mainContactForm or stockContactForm; HTML rejected. |
Filter values region and category use route slugs from product data (regionRoute, categoryRoute), not display titles. Paginated list/search responses put meta before data.
| Endpoint | Purpose |
|---|---|
/api/product-catalog | List or fetch one product (includes embedded files / images). |
/api/product-catalog-search | Text search with optional region/category filters. |
/api/product-count | Aggregate counts (total, by category, or by region). |
/api/product-files | Documents and pictures for one product id (files[] + images[]). |
Asset paths (config.ini [paths]): stockDataRoot = portal root containing public/data/…; stockDataDirectRoot = flat layout with {id}/files and {id}/pictures. JSON paths always use public/data/{id}/…. Reload PHP after config changes.
GET /api/product-catalogReturns products ordered by id DESC. Each list row includes files and images path arrays.
| Parameter | Required | Description |
|---|---|---|
id | No | Return a single product by id. When set, pagination, filters, and meta are omitted. |
limit | No | Page size. Default 30. |
offset | No | Pagination offset. Default 0. |
region | No | Filter by regionRoute (exact match). |
category | No | Filter by categoryRoute (exact match). |
List meta: limit, offset, region, category, count, totalCount. To load only asset paths without product fields, use /api/product-files?id=.
GET /api/product-catalog-searchSubstring search in title and description (LIKE %query%). By default returns all matching products. Pass limit and/or offset to paginate.
| Parameter | Required | Description |
|---|---|---|
query | Yes | Search term matched against title and description. |
region | No | Filter by regionRoute (exact match). |
category | No | Filter by categoryRoute (exact match). |
limit | No | Page size. Only used when paginating; default is all matches. |
offset | No | Pagination offset. Only used when paginating. |
Meta fields: query, region, category, limit, offset, count (items in current response), totalCount (all matches for the current filters).
GET /api/product-countReturns aggregate product counts. Use the optional by parameter to choose grouping.
| Parameter | Required | Description |
|---|---|---|
by | No | category – group by category with by_region nested in each category. region – group by region with by_category nested in each region. Omit for total count only. |
Default response: data.count only (no category or region breakdown).
by=category: data.count, data.by_category[] with category, categoryRoute, count, by_region[].
by=region: data.count, data.by_region[] with region, regionRoute, count, by_category[].
GET /api/product-filesReturns documents and pictures for one product in a single response. This is the only dedicated assets endpoint (no separate pictures route).
| Parameter | Required | Description |
|---|---|---|
id | Yes | Product id. |
Response: data.id, data.files[] (documents from public/data/{id}/files/), data.images[] (pictures from public/data/{id}/pictures/, or stub images when empty).
Example: curl -u "username:password" "https://api.globalstocks.eu/api/product-files?id=12345"
Static franchise promotion content (no database). Use the active flag together with showFrom / showTo to decide whether to display the modal on the portal.
GET /api/seasonal-offerReturns the current seasonal franchise offer. No query parameters.
| Field | Description |
|---|---|
data.seasonal_offer.header | Modal title (plain text). |
data.seasonal_offer.content | Modal body as HTML (<p>, links, <br/>). |
data.seasonal_offer.showFrom | First date the offer may be shown (YYYY-MM-DD). Currently 2026-06-01. |
data.seasonal_offer.showTo | Last date the offer may be shown (YYYY-MM-DD). Currently 2026-06-30. |
data.seasonal_offer.active | true when today's date is between showFrom and showTo (inclusive); otherwise false. |
Display logic: show the modal when active is true. Content is always returned; clients may ignore it when active is false.
Example: curl -u "username:password" "https://api.globalstocks.eu/api/seasonal-offer"
POST endpoints for newsletter sign-ups and contact-form submissions. Send Content-Type: application/json. All string fields are checked for HTML — if tags or encoded markup are detected, the API returns 400 with an error (nothing is stored).
POST /api/subscribersInserts a row into subscribers_new. dateCreated is set automatically.
| JSON field | Required | Description |
|---|---|---|
subscriberFormType | Yes | Form identifier (plain text, no HTML). |
subscribersEmail | Yes | Subscriber email address. |
subscribersDomain | Yes | Originating site domain (plain text, no HTML). |
Success (201): { "success": true, "data": { "subscriber": { "id": 123 } } }
Example: curl -u "username:password" -H "Content-Type: application/json" -d '{"subscriberFormType":"footer","subscribersEmail":"user@example.com","subscribersDomain":"globalstocks.eu"}' "https://api.globalstocks.eu/api/subscribers"
POST /api/messagesInserts a row into messages_new. created_at is set automatically.
| JSON field | Required | Description |
|---|---|---|
name | Yes | Sender name (plain text, no HTML). |
type | Yes | Contact form type. Must be exactly mainContactForm or stockContactForm — use mainContactForm for the main site contact form and stockContactForm for the stock portal contact form. |
subject | Yes | Message subject (plain text, no HTML). |
email | Yes | Sender email address. |
comments | Yes | Message body (plain text, no HTML). |
type values: mainContactForm · stockContactForm — any other value returns 400.
HTML rejected: { "success": false, "error": "HTML is not allowed in comments" }
Success (201): { "success": true, "data": { "message": { "id": 456 } } }
Example: curl -u "username:password" -H "Content-Type: application/json" -d '{"name":"Jane Doe","type":"mainContactForm","subject":"Inquiry","email":"jane@example.com","comments":"Hello"}' "https://api.globalstocks.eu/api/messages"