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

# Crear orden (v2)

> Crea una orden en Fire desde la caja, el kiosco o un integrador de agregadores, con la misma estructura de orden que ya envían hoy.

Crea una orden en Fire. Lo usan la **caja**, el **kiosco** y los **integradores de agregadores**
para enviar sus ventas directamente a Fire, **sin cambiar el cuerpo** que ya arman hoy: solo
cambian la URL, la credencial y la forma de leer la respuesta.

Esta es la **versión 2**: recibe la estructura de órdenes de caja y kiosco y la de agregadores. Si
tu sistema ya envía las órdenes en formato Fire, usa [Crear orden (v1)](https://docs.fire.rest/es/api-reference/create-order.md).
Las dos versiones están vigentes y terminan en el mismo lugar: mismas validaciones, misma respuesta.

Fire reconoce de qué tipo de orden se trata por el `channel.uid` del cuerpo:

* Si el canal es de un agregador (iFood, 99Food, Keeta, Rappi), el cuerpo es el de
  [Inyectar orden](https://docs.fire.rest/es/api-reference/orders.md) (camelCase, con precios y totales).
* Cualquier otro canal (caja, kiosco) usa la estructura de caja y kiosco que se describe abajo
  (snake\_case, solo con el precio unitario: Fire calcula los totales).

Una vez creada, la orden sigue el mismo ciclo que cualquier orden de Fire: impuestos, día de
negocio, documento fiscal y [eventos](https://docs.fire.rest/es/events/overview.md).

## Autenticación

**x-api-key** `string` *required*

Tu API key de Fire con scope `orders:write`. También se acepta `Authorization: Bearer <api_key>`.
La key **debe estar asociada a un vendor**: la cuenta de la orden sale de ese vendor. Una key
sin vendor se rechaza con `403`. No hace falta enviar el header `account`; si llega, se ignora.

## Identidad del cliente (caja y kiosco)

Envía **exactamente uno** de estos dos headers. Si no envías ninguno, o envías los dos, la orden
se rechaza con `400` `VALIDATION_ERROR`. Las órdenes de agregadores no los usan.

**anonymous\_customer\_uid** `string`

Identificador de la sesión anónima del equipo (caja o kiosco). Es el caso habitual.

**customer\_uid** `string`

Identificador de un cliente registrado.

## Cuerpo — caja y kiosco

**order\_code** `string` *required*

Código único de la orden en tu sistema. Si ya existe una orden con ese código para tu vendor,
la respuesta es `409`.

**vendor\_uid** `string` *required*

Vendor de la orden (p. ej. `11.6.1350`).

**catalog\_uid** `string` *required*

Catálogo del canal de venta.

**status** `string`

`COMPLETED` si la venta ya está cerrada; `OPEN` si queda pendiente de cobro. Una orden que no
llega `COMPLETED` + `SUCCEEDED` queda pendiente de pago.

**payment\_status** `string`

`SUCCEEDED` si ya está cobrada.

**channel** `object` *required*

Canal de venta. Su `uid` decide cómo se interpreta el cuerpo.

**channel**

**uid** `string` *required*

UID del canal en Fire.

**code** `string` *required*

Código del canal (p. ej. `POS`, `KIOSK`).

**service** `object` *required*

Servicio de la venta.

**service**

**uid** `string` *required*

UID del servicio en Fire.

**code** `string` *required*

Código del servicio (p. ej. `Dine-In`, `Takeaway`).

**store** `object` *required*

Tienda de la venta.

**store**

**uid** `string` *required*

UID de la tienda.

**code** `string` *required*

Código de la tienda.

**name** `string` *required*

Nombre de la tienda.

**vendor\_uid** `string` *required*

Vendor de la tienda.

**vendor\_name** `string` *required*

Nombre del vendor.

**fulfillment** `object` *required*

Forma de entrega y catálogo.

**fulfillment**

**method** `string` *required*

`POS` o `KIOSK`.

**catalog\_uid** `string` *required*

Catálogo. Debe estar habilitado para tu cuenta.

**details** `object`

Datos de la entrega, p. ej. `buzzer_name` (nombre para llamar al cliente).

**device** `object`

Equipo que registró la venta: `uid`, `name`, `metadata`.

**operator** `object`

Cajero u operador: `uid`, `name`, `session` (`uid`, `start_timestamp`, `end_timestamp`).
`null` en el kiosco.

**customer** `object`

Datos del cliente: `uid`, `name`, `last_name`, `phone` (obligatorios si envías el objeto),
`email`, `gov_id_type`, `gov_id_number`.

**billing** `object`

Datos de facturación: `gov_id_type`, `gov_id_number`, `business_name`.

**metadata** `object`

Datos adicionales de la venta, p. ej. `display_code` (número para llamar la orden) y los datos
del kiosco o de la caja.

**order\_lines** `object[]` *required*

Productos de la orden.

**order\_lines\[]**

**hash** `string` *required*

Identificador de la línea dentro de la orden.

**item\_id** `string` *required*

UID del producto en el catálogo.

**item\_description** `string` *required*

Nombre del producto.

**item\_type** `string` *required*

Tipo de ítem (p. ej. `PRODUCT`).

**quantity** `string` *required*

Cantidad, como texto (`"1"`).

**selected\_currency** `string` *required*

Moneda (p. ej. `BRL`).

**vendor\_uid** `string` *required*

Vendor.

**store\_uid** `string` *required*

Tienda.

**fulfillment** `object` *required*

`method` y `catalog_uid`, como en la orden.

**price** `object` *required*

Solo el precio unitario: `unit_price[]` con `currency_code`, `gross_price`, `net_price`,
`taxes`, `taxes_value`, `discount_value`, `subtotal_before_taxes` y `discounts`. Los montos
van como texto (`"14.9"`). Fire calcula el total de la línea y de la orden.

**modifier\_groups** `object[]` *required*

Grupos de modificadores (`uid`, `description`, `selected_modifiers[]`). Cada modificador
tiene la misma forma que una línea. `[]` si no hay.

**additional\_info** `object`

Códigos del producto, p. ej. `code`, `external_code`, `ncm`.

**payment\_methods** `object[]` *required*

Pagos de la orden.

**payment\_methods\[]**

**uid** `string` *required*

UID del medio de pago.

**method** `string` *required*

Medio de pago (p. ej. `CASH`, `CREDIT`, `DEBIT`).

**currency\_code** `string` *required*

Moneda.

**total** `string` *required*

Monto pagado, como texto.

**details** `object`

Detalle de la transacción: `processor`, `transaction_status` (`APPROVED`, `PENDING`),
`transaction_type`, `transaction_id`, `tid`, `authorization_code`, `total_bill`,
`customer_cash_amount`, `change_amount`, `card`, `acquirer`, `transaction_date`. Un pago
`PENDING` deja la orden abierta, pendiente de cobro.

**metadata** `object`

Datos del autorizador del pago.

## Cuerpo — agregadores

El mismo cuerpo de [Inyectar orden](https://docs.fire.rest/es/api-reference/orders.md), sin cambios. Fire lo identifica
como orden de agregador por `channel.uid` y la registra cerrada y pagada.

## Respuesta

**success** `boolean`

`true` cuando la orden se creó.

**data** `object`

**data**

**id** `string`

ID de la orden en Fire. Úsalo para consultarla, actualizarla o anularla.

**external\_order\_id** `string`

El `order_code` que enviaste.

**status** `string`

`COMPLETED` u `OPEN`.

**payment\_status** `string`

`SUCCEEDED` o `PENDING`.

**business\_day\_date** `string`

Día de negocio de la tienda, `YYYY-MM-DD`.

**created\_at** `string`

Fecha de creación en Fire (ISO 8601).

## Errores

| HTTP | `error` / `code` | Cuándo |
| - | - | - |
| `400` | `VALIDATION_ERROR` | Falta el código de la orden, el cuerpo no se puede leer (caja y kiosco: `details[]` detalla cada problema; agregadores: el mensaje dice qué falta), los headers de cliente faltan o vienen los dos, o el canal no está habilitado para tu vendor |
| `400` | `BUSINESS_ERROR` | Tienda inactiva, día de negocio cerrado, o la orden no cumple una regla de validación activada para tu vendor (`ORDER_INVARIANT_VIOLATION`) |
| `404` | `NOT_FOUND` | La tienda no existe |
| `401` | `UNAUTHORIZED` | API key inválida, vencida o revocada |
| `403` | `FORBIDDEN` | API key sin scope `orders:write` o no asociada a un vendor |
| `409` | `CONFLICT` / `DUPLICATE_ORDER` | La orden ya existía para tu vendor. `data` trae `id`, `externalOrderId` y `status` de la existente |

> [!NOTE]
>
> Toda petición queda registrada en Fire con su cuerpo y el motivo del rechazo, también las
> rechazadas. Si reintentas una orden que ya se creó, la respuesta es `409` y no se duplica.

```bash Caja o kiosco theme={null}
curl -X POST https://app.fire.rest/api/v2/external/orders \
  -H "x-api-key: $FIRE_API_KEY" \
  -H "anonymous_customer_uid: device-session-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "order_code": "BR-K000-05-1793063248",
    "vendor_uid": "11.6.1350",
    "catalog_uid": "5",
    "status": "COMPLETED",
    "payment_status": "SUCCEEDED",
    "channel": { "uid": "c784d4ba-23c7-4929-b2f0-1a1960d9cdc2", "code": "KIOSK" },
    "service": { "uid": "726c4892-48b9-45da-b066-2a8e83d2cb78", "code": "Dine-In" },
    "store": { "uid": "11.6.1350.50", "code": "K000", "name": "Tienda demo", "vendor_uid": "11.6.1350", "vendor_name": "Vendor demo" },
    "fulfillment": { "method": "KIOSK", "catalog_uid": "5", "details": { "buzzer_name": "Cliente" } },
    "customer": { "uid": "device-session-0001", "name": "CONSUMIDOR", "last_name": "FINAL", "phone": "" },
    "metadata": { "display_code": "48K" },
    "order_lines": [{
      "hash": "hash_0",
      "item_id": "7abdd4e5-d685-43ff-ba79-5e8b2f700b5b",
      "item_description": "12 Tiras de Frango",
      "item_type": "PRODUCT",
      "quantity": "1",
      "selected_currency": "BRL",
      "vendor_uid": "11.6.1350",
      "store_uid": "11.6.1350.50",
      "fulfillment": { "method": "KIOSK", "catalog_uid": "5" },
      "price": { "unit_price": [{ "currency_code": "BRL", "gross_price": "64.9", "net_price": "64.9", "taxes": [], "taxes_value": "0", "discount_value": "0", "subtotal_before_taxes": "64.9", "discounts": [] }] },
      "modifier_groups": []
    }],
    "payment_methods": [{
      "uid": "80242d0c-3bdd-4e8a-8ec2-eb250230b4e9",
      "method": "CREDIT",
      "currency_code": "BRL",
      "total": "64.9",
      "details": { "processor": "Tarjeta", "transaction_status": "APPROVED", "transaction_type": "CREDIT", "transaction_id": "BR-K000-05-1793063248", "tid": "TF000000", "authorization_code": "0000000000000", "total_bill": "64.9", "currency_code": "BRL", "exact_payment": false, "customer_cash_amount": "0", "mid": "", "voucher": "", "reference_number": "", "card": null, "acquirer": null, "transaction_date": { "date": "2026-10-26T22:08:00-03:00", "time_zone_name": "America/Sao_Paulo", "time_zone_type": "3" } }
    }]
  }'
```

```bash Agregador theme={null}
curl -X POST https://app.fire.rest/api/v2/external/orders \
  -H "x-api-key: $FIRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d @ifood-order.json   # mismo cuerpo que en "Inyectar orden"
```

```json 201 theme={null}
{
  "success": true,
  "data": {
    "id": "6f1c2b9e-3a1d-4c55-9b7e-0d2f6a7c8e10",
    "external_order_id": "BR-K000-05-1793063248",
    "status": "COMPLETED",
    "payment_status": "SUCCEEDED",
    "business_day_date": "2026-10-26",
    "created_at": "2026-10-27T01:08:00.405Z"
  }
}
```

```json 409 theme={null}
{
  "success": false,
  "error": "CONFLICT",
  "code": "DUPLICATE_ORDER",
  "message": "Order with external id BR-K000-05-1793063248 already exists for this vendor.",
  "data": { "id": "6f1c2b9e-3a1d-4c55-9b7e-0d2f6a7c8e10", "externalOrderId": "BR-K000-05-1793063248", "status": "COMPLETED" }
}
```

```json 400 theme={null}
{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Datos de entrada inválidos",
  "details": [{ "code": "custom", "path": [], "message": "customer_uid or anonymous_customer_uid is required" }]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.