> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laportenard.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Orders

> API endpoints for creating and managing orders.

All order endpoints require [authentication](/api-reference/authentication).

## Create or update order

<Card>
  **POST** `/pos-api/v1/orders/create`
</Card>

Creates a new order or updates an existing one. Order creation is **idempotent** — sending the same `pos_reference` returns the existing order.

### Key fields

| Field           | Type    | Description                              |
| --------------- | ------- | ---------------------------------------- |
| `pos_reference` | string  | Unique order reference (idempotency key) |
| `table_id`      | integer | Floor plan table ID                      |
| `lines`         | array   | Order line items                         |
| `fiscal_type`   | string  | NCF fiscal type for Dominican tax        |

<Note>
  The `pos_reference` field is the idempotency key. Duplicate submissions with the same reference are safe and return the existing order.
</Note>

## Reserve NCF

<Card>
  **POST** `/pos-api/v1/orders/reserve-ncf`
</Card>

Reserves a fiscal number (NCF) for the order. Required for Dominican tax compliance before finalizing.

## Hub batch sync

<Card>
  **POST** `/pos-api/v1/hub/batch-sync`
</Card>

Used by the sync hub to forward completed orders upstream to Odoo. Accepts an array of order snapshots.

## Hub order finalization

<Card>
  **POST** `/pos-api/v1/hub/finalize`
</Card>

Called by the sync hub when a terminal completes payment. Receives a full order snapshot (lines, totals, payment lines) and runs the complete Odoo fiscal pipeline (`create_from_ui`) inside a database savepoint.

### Behaviors

| Behavior                 | Detail                                                                                                                      |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| **Savepoint**            | `create_from_ui` runs inside `self.env.cr.savepoint()` — any failure rolls back atomically, preventing phantom draft orders |
| **Default partner**      | When no customer is provided, falls back to `config.default_partner_id`                                                     |
| **Payment verification** | After creation, verifies `statement_ids` are present; raises if empty                                                       |
| **Idempotency**          | Same `pos_reference` returns the existing paid order                                                                        |
| **Fiscal pipeline**      | Full NCF/DGII processing (same as direct API orders)                                                                        |

### Response

```json theme={null}
{
  "status": "ok",
  "pos_reference": "NU/CFG1/S42/1709123456789-3f7a",
  "order_id": 9585,
  "created": true,
  "line_id_map": { "client-line-1": 12345 },
  "fiscal": {
    "reference": "B0200000160",
    "fiscal_type_code": "B02"
  }
}
```

### Audit

Each hub finalization is logged as a `hub_finalize` event in the `nu_restaurant_pos.order_audit` model.