_Version: 1.0_

> This document is the LLM-friendly export of the API. It is regenerated on every request from the live OpenAPI spec. Use it as context when asking an AI assistant for help.

# fature.al Partner API

This is the API a third party uses to run one venue's Wolt orders through fature.al: pull the order
lifecycle from the feed, relay accept, reject and ready back to Wolt, and read the fiscal invoice
fature.al issued for each order.

It is separate from the main API because the token means something narrower here. Everything else
(the bearer token, the `X-Client-Id` and `X-Client-Secret` pair, the response envelope) works the
same way, and the main documentation at [`/docs/api`](/docs/api) covers it.

## Servers

| Environment | URL |
|-------------|-----|
| **Live** | `https://fature.al/api/partner/v1` |
| **Sandbox/Demo** | `https://demo.fature.al/api/partner/v1` |

## One token, one venue

The bearer token resolves to a single Wolt venue, and every endpoint is pinned to it. An order id
that belongs to another venue answers 404, not 403, so a wrong id and a foreign id are
indistinguishable by design.

Call `GET /ping` first: it returns the company, branch and venue the token is bound to, which is how
you confirm the credentials and discover what you are operating on.

## The event feed is the spine

Poll `GET /events` with the last `next_cursor` you received. The feed is append-only, so nothing is
lost across your downtime, and delivery is at-least-once, so treat `(order_id, type)` as idempotent.
Each event carries a compact snapshot of the order at that moment, which is usually enough to avoid
a second call.

## Every write needs an Idempotency-Key

The eight action endpoints require an `Idempotency-Key` header. A request without one is refused
with **400**.

- A retry with the same key replays the first result instead of relaying a second action to Wolt,
  and the replay carries an `Idempotent-Replayed: true` header. Keys are kept for 24 hours.
- A second call with the same key while the first is still in flight is refused with **409**.
- Only successful results are stored, so a transient failure is safe to retry with the same key.

## Errors

Failures use the same envelope as the rest of the API plus a stable `code`:

```json
{"status": false, "message": "No such order for this venue.", "code": "order_not_found"}
```

Branch on `code`, not on `message`, which is localised.

| Code | Status | Meaning |
|------|--------|---------|
| `unauthenticated` | 401 | The token is missing or invalid |
| `wolt_not_enabled` | 403 | The company does not have the Wolt add-on |
| `forbidden` | 403 | The token has no Wolt right |
| `no_venue` | 403 | The token resolves to no single active venue |
| `order_not_found` | 404 | No such order for this venue |
| `invalid_transition` | 409 | The action is not valid for the order's current status. Nothing was relayed to Wolt |
| `idempotency_key_required` | 400 | The Idempotency-Key header is missing |
| `idempotency_in_progress` | 409 | A call with the same key is still running |
| `invalid_data` | 422 | The body did not validate |
| `action_failed` | 422 | The action failed on our side and was not completed |
| `wolt_upstream_error` | 502 | Wolt refused or did not answer. Safe to retry with the same key |

## Rate limits

Reads carry the poll loop, so they are the more generous bucket; writes relay to Wolt, so they are
tighter. Both are per token.

| | Limit |
|---|-------|
| Reads (`GET`) | 180/minute |
| Writes (`POST`) | 60/minute |

Over the limit the response is **429** with a `Retry-After` header saying how many seconds to wait.

## Servers

- `https://fature.al/api/partner/v1` - Live
- `https://demo.fature.al/api/partner/v1` - Sandbox

## Endpoints

### GET /wolt/events

**Summary:** Event feed

The spine of the integration. Poll this endpoint with the last next_cursor
you received to get the venue's order lifecycle events in order. The feed is
append-only, so nothing is missed across your downtime; delivery is
at-least-once, so treat (order_id, type) as idempotent. Each event carries a
compact snapshot of the order at that moment in `order`.

**Tags:** Wolt Partner API

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `since` | query | no | The cursor to resume from; pass the previous next_cursor. Defaults to 0, the start of retention. |
| `limit` | query | no | Max events to return, 1-200. |
| `types` | query | no | Comma-separated event types to include, e.g. order.received,order.ready. |

**Responses:**

- `200`
- `401`
- `403` - The company has no Wolt add-on, the token has no Wolt right, or it resolves to no single active venue.
- `429` - Rate limit reached: 180 reads a minute per token. Retry after the number of seconds in the Retry-After header.

---

### GET /wolt/orders

**Summary:** List orders

The venue's orders, newest first. Page backwards with ?cursor=<next_cursor>.

**Tags:** Wolt Partner API

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `cursor` | query | no | Return orders older than this id; pass the previous next_cursor. |
| `limit` | query | no | Page size, 1-100. |
| `status` | query | no | Filter by raw Wolt status (e.g. received, acknowledged, ready, delivered). |
| `from` | query | no | Only orders received on/after this date (YYYY-MM-DD). |
| `to` | query | no | Only orders received on/before this date (YYYY-MM-DD). |

**Responses:**

- `200`
- `401`
- `403` - The company has no Wolt add-on, the token has no Wolt right, or it resolves to no single active venue.
- `429` - Rate limit reached: 180 reads a minute per token. Retry after the number of seconds in the Retry-After header.

---

### GET /wolt/orders/{id}

**Summary:** Get an order

The authoritative snapshot of one order: header, parties, lines, totals and
fiscal linkage.

**Tags:** Wolt Partner API

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The order's Fatureal id, from the feed or the order list. |

**Responses:**

- `200`
- `401`
- `403` - The company has no Wolt add-on, the token has no Wolt right, or it resolves to no single active venue.
- `404` - No such order for this venue.
- `429` - Rate limit reached: 180 reads a minute per token. Retry after the number of seconds in the Retry-After header.

---

### POST /wolt/orders/{id}/accept

**Summary:** Accept an order

Relays acceptance to Wolt. On a marketplace order, pickup_minutes tells Wolt
when it will be ready so a courier is dispatched to match; on a self-delivery
order it is the total delivery time committed to the customer.

**Tags:** Wolt Partner API

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The order's Fatureal id, from the feed or the order list. |
| `Idempotency-Key` | header | yes | Your own unique key for this action. A retry with the same key replays the first result instead of relaying a second action to Wolt, and the replay carries an Idempotent-Replayed: true header. Kept for 24 hours. |

**Request body content types:** application/json

**Responses:**

- `200`
- `401`
- `400` - The Idempotency-Key header is missing.
- `403` - The company has no Wolt add-on, the token has no Wolt right, or it resolves to no single active venue.
- `404` - No such order for this venue.
- `409` - The order's current status does not allow this action, or a call with the same Idempotency-Key is still in flight. Nothing was relayed to Wolt.
- `422` - pickup_minutes is outside 5-180, or the action failed on our side and was not completed.
- `502` - Wolt refused or did not answer. Safe to retry with the same Idempotency-Key.
- `429` - Rate limit reached: 60 writes a minute per token. Retry after the number of seconds in the Retry-After header.

---

### POST /wolt/orders/{id}/confirm-preorder

**Summary:** Confirm a pre-order

Confirms a customer-scheduled pre-order. It is parked until Wolt releases it
into production near its due time, after which it can be marked ready.

**Tags:** Wolt Partner API

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The order's Fatureal id, from the feed or the order list. |
| `Idempotency-Key` | header | yes | Your own unique key for this action. A retry with the same key replays the first result instead of relaying a second action to Wolt, and the replay carries an Idempotent-Replayed: true header. Kept for 24 hours. |

**Responses:**

- `200`
- `401`
- `400` - The Idempotency-Key header is missing.
- `403` - The company has no Wolt add-on, the token has no Wolt right, or it resolves to no single active venue.
- `404` - No such order for this venue.
- `409` - The order's current status does not allow this action, or a call with the same Idempotency-Key is still in flight. Nothing was relayed to Wolt.
- `422` - The action failed on our side and was not completed.
- `502` - Wolt refused or did not answer. Safe to retry with the same Idempotency-Key.
- `429` - Rate limit reached: 60 writes a minute per token. Retry after the number of seconds in the Retry-After header.

---

### POST /wolt/orders/{id}/courier-at-customer

**Summary:** Self-delivery step 2: the courier reached the customer

**Tags:** Wolt Partner API

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The order's Fatureal id, from the feed or the order list. |
| `Idempotency-Key` | header | yes | Your own unique key for this action. A retry with the same key replays the first result instead of relaying a second action to Wolt, and the replay carries an Idempotent-Replayed: true header. Kept for 24 hours. |

**Responses:**

- `200`
- `401`
- `400` - The Idempotency-Key header is missing.
- `403` - The company has no Wolt add-on, the token has no Wolt right, or it resolves to no single active venue.
- `404` - No such order for this venue.
- `409` - The order's current status does not allow this action, or a call with the same Idempotency-Key is still in flight. Nothing was relayed to Wolt.
- `422` - The action failed on our side and was not completed.
- `502` - Wolt refused or did not answer. Safe to retry with the same Idempotency-Key.
- `429` - Rate limit reached: 60 writes a minute per token. Retry after the number of seconds in the Retry-After header.

---

### POST /wolt/orders/{id}/delivered

**Summary:** Close the order: customer pickup (takeaway) once ready, or self-delivery drop-off complete

**Tags:** Wolt Partner API

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The order's Fatureal id, from the feed or the order list. |
| `Idempotency-Key` | header | yes | Your own unique key for this action. A retry with the same key replays the first result instead of relaying a second action to Wolt, and the replay carries an Idempotent-Replayed: true header. Kept for 24 hours. |

**Responses:**

- `200`
- `401`
- `400` - The Idempotency-Key header is missing.
- `403` - The company has no Wolt add-on, the token has no Wolt right, or it resolves to no single active venue.
- `404` - No such order for this venue.
- `409` - The order's current status does not allow this action, or a call with the same Idempotency-Key is still in flight. Nothing was relayed to Wolt.
- `422` - The action failed on our side and was not completed.
- `502` - Wolt refused or did not answer. Safe to retry with the same Idempotency-Key.
- `429` - Rate limit reached: 60 writes a minute per token. Retry after the number of seconds in the Retry-After header.

---

### GET /wolt/orders/{id}/invoice

**Summary:** Get the order's fiscal invoice

Returns the fiscal invoice issued for the order (identifiers IIC/FIC/EIC,
verification via pdf_url, client, amounts and lines). The invoice object is
identical to the one from GET /api/v1/invoice/{id}/details. It is null while
the order has not been fiscalised yet; poll fiscal_state (pending, deferred,
fiscalised, failed) or watch the order.fiscalized feed event.

**Tags:** Wolt Partner API

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The order's Fatureal id, from the feed or the order list. |

**Responses:**

- `200`
- `401`
- `403` - The company has no Wolt add-on, the token has no Wolt right, or it resolves to no single active venue.
- `404` - No such order for this venue.
- `429` - Rate limit reached: 180 reads a minute per token. Retry after the number of seconds in the Retry-After header.

---

### POST /wolt/orders/{id}/pickup-completed

**Summary:** Self-delivery step 1: the venue's own courier collected the order

**Tags:** Wolt Partner API

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The order's Fatureal id, from the feed or the order list. |
| `Idempotency-Key` | header | yes | Your own unique key for this action. A retry with the same key replays the first result instead of relaying a second action to Wolt, and the replay carries an Idempotent-Replayed: true header. Kept for 24 hours. |

**Responses:**

- `200`
- `401`
- `400` - The Idempotency-Key header is missing.
- `403` - The company has no Wolt add-on, the token has no Wolt right, or it resolves to no single active venue.
- `404` - No such order for this venue.
- `409` - The order's current status does not allow this action, or a call with the same Idempotency-Key is still in flight. Nothing was relayed to Wolt.
- `422` - The action failed on our side and was not completed.
- `502` - Wolt refused or did not answer. Safe to retry with the same Idempotency-Key.
- `429` - Rate limit reached: 60 writes a minute per token. Retry after the number of seconds in the Retry-After header.

---

### POST /wolt/orders/{id}/ready

**Summary:** Mark an order ready for handover. Creates the fiscal invoice if it does not exist yet

**Tags:** Wolt Partner API

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The order's Fatureal id, from the feed or the order list. |
| `Idempotency-Key` | header | yes | Your own unique key for this action. A retry with the same key replays the first result instead of relaying a second action to Wolt, and the replay carries an Idempotent-Replayed: true header. Kept for 24 hours. |

**Responses:**

- `200`
- `401`
- `400` - The Idempotency-Key header is missing.
- `403` - The company has no Wolt add-on, the token has no Wolt right, or it resolves to no single active venue.
- `404` - No such order for this venue.
- `409` - The order's current status does not allow this action, or a call with the same Idempotency-Key is still in flight. Nothing was relayed to Wolt.
- `422` - The action failed on our side and was not completed.
- `502` - Wolt refused or did not answer. Safe to retry with the same Idempotency-Key.
- `429` - Rate limit reached: 60 writes a minute per token. Retry after the number of seconds in the Retry-After header.

---

### POST /wolt/orders/{id}/reject

**Summary:** Reject an order

**Tags:** Wolt Partner API

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The order's Fatureal id, from the feed or the order list. |
| `Idempotency-Key` | header | yes | Your own unique key for this action. A retry with the same key replays the first result instead of relaying a second action to Wolt, and the replay carries an Idempotent-Replayed: true header. Kept for 24 hours. |

**Request body content types:** application/json

**Responses:**

- `200`
- `401`
- `422` - The reject code is not one of GENERIC, ITEMS_UNAVAILABLE or VENUE_CLOSING_SOON, or the action failed on our side. A validation failure adds an errors object to the envelope.
- `400` - The Idempotency-Key header is missing.
- `403` - The company has no Wolt add-on, the token has no Wolt right, or it resolves to no single active venue.
- `404` - No such order for this venue.
- `409` - The order's current status does not allow this action, or a call with the same Idempotency-Key is still in flight. Nothing was relayed to Wolt.
- `502` - Wolt refused or did not answer. Safe to retry with the same Idempotency-Key.
- `429` - Rate limit reached: 60 writes a minute per token. Retry after the number of seconds in the Retry-After header.

---

### POST /wolt/orders/{id}/retry-fiscalize

**Summary:** Retry a deferred/failed fiscalisation for this order

**Tags:** Wolt Partner API

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The order's Fatureal id, from the feed or the order list. |
| `Idempotency-Key` | header | yes | Your own unique key for this action. A retry with the same key replays the first result instead of relaying a second action to Wolt, and the replay carries an Idempotent-Replayed: true header. Kept for 24 hours. |

**Responses:**

- `200`
- `401`
- `400` - The Idempotency-Key header is missing.
- `403` - The company has no Wolt add-on, the token has no Wolt right, or it resolves to no single active venue.
- `404` - No such order for this venue.
- `409` - The order's current status does not allow this action, or a call with the same Idempotency-Key is still in flight. Nothing was relayed to Wolt.
- `422` - The action failed on our side and was not completed.
- `502` - Wolt refused or did not answer. Safe to retry with the same Idempotency-Key.
- `429` - Rate limit reached: 60 writes a minute per token. Retry after the number of seconds in the Retry-After header.

---

### GET /wolt/ping

**Summary:** Ping

Verify the token and return the single Wolt venue it is bound to. Call this
first to confirm credentials and discover which company/branch/venue the
token operates on.

**Tags:** Wolt Partner API

**Responses:**

- `200`
- `401`
- `403` - The company has no Wolt add-on, the token has no Wolt right, or it resolves to no single active venue.
- `429` - Rate limit reached: 180 reads a minute per token. Retry after the number of seconds in the Retry-After header.

---

## Full OpenAPI specification

For complete schemas, examples and request/response bodies, fetch the JSON spec:

```
https://demo.fature.al/docs/api.json
```