> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/api-rest/midapi-v2/operations/create-operation.md).

# Create Operation

Servicio que crea una operación y devuelve su identificador junto con su caducidad.

El `operationId` devuelto es el que se envía al [almacenar un asset](/api-rest/midapi-v2/storage/save-asset.md) y el primer segmento de toda clave de asset.

### Endpoint

```
POST /operation
```

### Headers

| Nombre            | Tipo   | Requerido | Descripción                                                                                               |
| ----------------- | ------ | --------- | --------------------------------------------------------------------------------------------------------- |
| **Authorization** | string | **Sí**    | Token de consumer en formato `Bearer <token>`. Ver [Autenticación](/api-rest/midapi-v2/autenticacion.md). |
| **consumer-id**   | string | **Sí**    | Identificador del consumer.                                                                               |

### Cuerpo de la solicitud

El cuerpo es opcional: una solicitud sin cuerpo crea la operación igualmente.

#### Parámetros

| Parámetro           | Tipo   | Requerido | Descripción                                                                                                       |
| ------------------- | ------ | --------- | ----------------------------------------------------------------------------------------------------------------- |
| `merchantReference` | string | No        | Referencia propia para esta operación: el pedido, expediente o carrito al que corresponde. Máximo 128 caracteres. |

#### Ejemplo de solicitud

```json
{
  "merchantReference": "ORD-4417"
}
```

{% hint style="info" %}
`merchantReference` es una referencia **informativa**. El servicio la almacena y la devuelve, pero no se puede consultar ni operar por ella: la operación se identifica siempre por su `operationId`. No es única, así que dos operaciones pueden llevar la misma sin que eso las relacione.
{% endhint %}

Se almacena sin los espacios de los extremos, y una referencia en blanco equivale a no enviar ninguna.

### Respuestas

#### `201` Created

#### Parámetros de respuesta

| Parámetro           | Tipo   | Descripción                                                              |
| ------------------- | ------ | ------------------------------------------------------------------------ |
| `operationId`       | string | Identificador de la operación (UUID).                                    |
| `timestamp`         | string | Momento de creación en formato **ISO 8601** (UTC).                       |
| `expiresAt`         | string | Momento de caducidad en formato **ISO 8601** (UTC).                      |
| `merchantReference` | string | La referencia enviada, devuelta tal cual. No aparece si no se envió una. |

#### Ejemplo de respuesta

```json
{
  "operationId": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04",
  "timestamp": "2026-06-26T12:00:00Z",
  "expiresAt": "2026-06-26T12:15:00Z",
  "merchantReference": "ORD-4417"
}
```

#### Otras respuestas

| Código | Descripción                                                                                                                                                                                    |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `merchantReference` de más de 128 caracteres, o cuerpo mal formado.                                                                                                                            |
| `401`  | Token ausente, inválido o caducado.                                                                                                                                                            |
| `403`  | El consumer no está aprovisionado con el servicio `OPERATION`.                                                                                                                                 |
| `429`  | El consumer ha superado su límite de tasa de peticiones. La respuesta incluye `Retry-After` con los segundos de espera, y `X-RateLimit-Limit` y `X-RateLimit-Burst` con los umbrales vigentes. |
| `503`  | El servicio no está disponible temporalmente.                                                                                                                                                  |

El cuerpo de una respuesta de error tiene la forma descrita en [Middleware API v2](/api-rest/midapi-v2.md#respuestas-de-error).