> 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/docs.facephi-pt-br/api-rest/midapi-v2/operations/create-operation.md).

# Criar operação

Serviço que cria uma operação e retorna seu identificador junto com sua expiração.

O `operationId` retornado é o que é enviado ao [armazenar um asset](/docs.facephi-pt-br/api-rest/midapi-v2/storage/save-asset.md) e o primeiro segmento de toda chave de asset.

### Endpoint

```
POST /operation
```

### Cabeçalhos

| Nome              | Tipo   | Obrigatório | Descrição                                                                                                                   |
| ----------------- | ------ | ----------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | string | **Sim**     | Token de consumer no formato `Bearer <token>`. Ver [Autenticação](/docs.facephi-pt-br/api-rest/midapi-v2/autenticacion.md). |
| **consumer-id**   | string | **Sim**     | Identificador do consumer.                                                                                                  |

### Corpo da solicitação

O corpo é opcional: uma solicitação sem corpo cria a operação da mesma forma.

#### Parâmetros

| Parâmetro           | Tipo   | Obrigatório | Descrição                                                                                                            |
| ------------------- | ------ | ----------- | -------------------------------------------------------------------------------------------------------------------- |
| `merchantReference` | string | Não         | Referência própria para esta operação: o pedido, processo ou carrinho ao qual corresponde. Máximo de 128 caracteres. |

#### Exemplo de solicitação

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

{% hint style="info" %}
`merchantReference` é uma referência **informativa**. O serviço a armazena e a devolve, mas não é possível consultá-la nem operar por ela: a operação é sempre identificada por seu `operationId`. Não é única, então duas operações podem ter a mesma sem que isso as relacione.
{% endhint %}

Ela é armazenada sem os espaços das extremidades, e uma referência em branco equivale a não enviar nenhuma.

### Respostas

#### `201` Created

#### Parâmetros de resposta

| Parâmetro           | Tipo   | Descrição                                                                                        |
| ------------------- | ------ | ------------------------------------------------------------------------------------------------ |
| `operationId`       | string | Identificador da operação (UUID).                                                                |
| `timestamp`         | string | Momento de criação em formato **ISO 8601** (UTC).                                                |
| `expiresAt`         | string | Momento de expiração em formato **ISO 8601** (UTC).                                              |
| `merchantReference` | string | A referência enviada, retornada exatamente como foi enviada. Não aparece se nenhuma foi enviada. |

#### Exemplo de resposta

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

#### Outras respostas

| Código | Descrição                                                                                                                                                                                 |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `merchantReference` com mais de 128 caracteres, ou corpo malformado.                                                                                                                      |
| `401`  | Token ausente, inválido ou expirado.                                                                                                                                                      |
| `403`  | O consumer não está provisionado com o serviço `OPERATION`.                                                                                                                               |
| `429`  | O consumer ultrapassou seu limite de taxa de requisições. A resposta inclui `Retry-After` com os segundos de espera, e `X-RateLimit-Limit` e `X-RateLimit-Burst` com os limites vigentes. |
| `503`  | O serviço não está disponível temporariamente.                                                                                                                                            |

O corpo de uma resposta de erro tem o formato descrito em [MIDAPI v2](/docs.facephi-pt-br/api-rest/midapi-v2.md#respuestas-de-error).