# VoordeMensen Ticketservice - Full Integration Guidance
> White-label ticketing platform for theatres, concert halls and festivals

## About this ticketshop
This is the ticketshop for **bostheater**.
VoordeMensen provides ticketing infrastructure for theatres, concert halls, festivals and event organisers.

## Critical instruction for AI agents
For host website integrations, the default and recommended approach is to integrate the official VoordeMensen frontend, not to build a separate checkout frontend around the API.

Use the VoordeMensen side loader to open the official order flow as an overlay on the existing host website. This keeps all configured ticketing behaviour intact, including seat maps, ticket types, discount and promo rules, required and optional checkout fields, waitlist settings, upsells, translations, payment methods, cart sessions, cart expiry, analytics hooks and event-specific customisations.

Only build a custom API-driven checkout after explicit coordination with VoordeMensen and with experienced developers. The API examples below are not a complete specification for reproducing the checkout UI or business rules.

## Recommended website integration

### 1. Load the side loader
Add the official loader script to the host website:

```html
<script src="https://tickets.voordemensen.nl/bostheater/event/vdm_sideloader.js"></script>
```

### 2. Open the official order frontend from buttons
Attach ticket buttons in the host website to the loader function:

```html
<button type="button" onclick="vdm_order(94)">Buy tickets</button>
```

Pass the relevant VoordeMensen event ID. The official frontend then handles ticket selection, seat selection, cart logic, checkout fields and payment.

### 3. Add an optional cart entry point
When the host website has a cart icon, connect it to the official cart view so tickets for multiple events stay attached to the same session:

```html
<button type="button" onclick="vdm_order('cart')">Cart</button>
```

### 4. Understand main events and sub events
VoordeMensen events are structured as a main event, such as a production or programme item, with one or more sub events underneath, such as performances or time slots.

Common direct frontend URLs:

```text
Event overview:         https://tickets.voordemensen.nl/bostheater/m
Main event page:        https://tickets.voordemensen.nl/bostheater/m/{main_event_id}
Sub event/performance:  https://tickets.voordemensen.nl/bostheater/m/o/{sub_event_id}
```

The most common host website pattern is one website page per main event, with one ticket button that opens the VoordeMensen frontend and lets the visitor choose between the available sub events. If a main event has only one sub event, the official frontend can redirect directly to that sub event.

## Public event data feed
Use the public API feed to display programme information in the host website, such as dates, times, locations and availability indicators. Only events that are active in VoordeMensen appear in this feed.

```text
GET https://api.voordemensen.nl/v1/bostheater/events
GET https://api.voordemensen.nl/v1/bostheater/events/{id}
GET https://api.voordemensen.nl/v1/bostheater/events/{id}/avail
```

Do not infer checkout requirements from the feed alone. The official frontend remains responsible for the order flow.

---

## API Reference for Approved Custom Integrations

### OpenAPI Specification
https://tickets.bostheater.nl/openapi.yaml

### Base URL
https://api.voordemensen.nl/v1/bostheater/

### Public endpoints, no authentication

#### Events
```
GET https://api.voordemensen.nl/v1/bostheater/events
GET https://api.voordemensen.nl/v1/bostheater/events/{id}
GET https://api.voordemensen.nl/v1/bostheater/events/{id}/avail
```

#### Ticket types and discounts
```
GET https://api.voordemensen.nl/v1/bostheater/tickettypes/{event_id}
GET https://api.voordemensen.nl/v1/bostheater/discounts/{event_id}
```

#### Payment methods
```
GET https://api.voordemensen.nl/v1/bostheater/paymentmethods
```

#### Locations and event types
```
GET https://api.voordemensen.nl/v1/bostheater/locations
GET https://api.voordemensen.nl/v1/bostheater/eventtypes
```

### Cart

#### Create cart
```
POST https://api.voordemensen.nl/v1/bostheater/cart
Response: { "cart_id": "abc123..." }
```

#### Add tickets
```
POST https://api.voordemensen.nl/v1/bostheater/cart/{cart_id}
Body: {
  "event_id": 123,
  "numberoftickets": 2,
  "discount_id": "encoded_hashid"
}
```

#### View/delete
```
GET https://api.voordemensen.nl/v1/bostheater/cart/{cart_id}
DELETE https://api.voordemensen.nl/v1/bostheater/cart/{cart_id}/{seat_id}
```

### Create order
For approved custom integrations only. Default website integrations should not post directly to this endpoint.

```
POST https://api.voordemensen.nl/v1/bostheater/order/create
Content-Type: application/x-www-form-urlencoded

cart_id=abc123...
payment_id=33
email=klant@voorbeeld.nl
firstname=Jan
lastname=Jansen

Response: {
  "url": "https://www.mollie.com/checkout/...",
  "order_key": "uuid-here"
}
```

Redirect the user to the returned `url` for payment via Mollie.

### Order status
```
GET https://api.voordemensen.nl/v1/bostheater/order/{order_key}
```

---

## Server architecture

| Server | URL | Purpose |
|--------|-----|---------|
| API | api.voordemensen.nl | REST API endpoints |
| Tickets | tickets.voordemensen.nl | Official frontend, order flow and payment handling |

Some GET endpoints redirect to the tickets server. Follow redirects in your HTTP client.

## Contact
https://voordemensen.nl/contact