# Atribuir operador ao turno (https://docs.pulsarml.com/pt/v1/api-reference/shifts/post-shifts-shift_id-operator)

Atribui um operador a um turno pelo seu ID (o que é devolvido por `GET /v1/shifts`), mesmo em turnos que já terminaram. Sem `start`, o operador assume a máquina desde o início do turno.

**Como as atribuições de operador se somam.** Cada turno mantém uma cronologia de quem operou a máquina. Uma atribuição significa "a partir de `start`, este operador opera a máquina": dura até ao fim do turno, ou até à atribuição seguinte.

* **Primeira atribuição.** Se o turno ainda não tiver ninguém atribuído, o operador cobre o **turno completo**, desde o seu primeiro minuto, mesmo quando `start` é posterior.
* **Atribuições posteriores.** Cada uma divide a cronologia em `start`: quem tinha a máquina mantém-na até `start`, e o novo operador assume-a de `start` até ao fim do turno.
* **A ordem importa.** Envie as atribuições por ordem cronológica. Um `start` anterior à última mudança do turno é rejeitado com `400`, por isso depois não é possível inserir um operador a meio. Um `start` igual à última mudança substitui o operador que assumiu a máquina nesse momento.
* **As repetições são seguras.** Enviar a mesma atribuição outra vez não altera nada.
* `start` é arredondado para baixo ao minuto.

Por exemplo, para um turno `Morning` das 06:00 às 14:00 ainda sem ninguém atribuído:

| Pedido | Cronologia depois dele |
| --- | --- |
| operador 1063 a partir das 10:00 | 1063 06:00–14:00 (a primeira atribuição cobre o turno completo) |
| operador 2071 a partir das 10:00 | 1063 06:00–10:00, 2071 10:00–14:00 |
| operador 3300 a partir das 12:00 | 1063 06:00–10:00, 2071 10:00–12:00, 3300 12:00–14:00 |
| operador 4410 a partir das 08:00 | Rejeitado com `400`: 08:00 é antes da última mudança, às 12:00 |

Para registar um turno que teve vários operadores, envie o primeiro a partir do início do turno e depois os restantes pela ordem em que assumiram a máquina.

As métricas de operador do turno são recalculadas em segundo plano, por isso os relatórios podem demorar um momento a mostrar a alteração.

Erros:

* `400`: nenhum turno corresponde, ou `start` está fora do turno, no futuro, ou antes da última mudança de operador do turno.
* `403`: o turno tem produção marcada como revista, o que o bloqueia.
* `404`: o operador não existe na sua empresa.

## `POST /v1/shifts/{shift_id}/operator`

Base URLs:
- `https://draco.prod.pulsarml.com` — Produção
- `https://draco.dev.pulsarml.com` — Desenvolvimento (sandbox)

Authentication: send your API key in the `x-api-key` header.

### Path parameters

- `shift_id` (integer, required) — O ID do turno.

### Request body (`application/json`, required)

Type: object (`AssignOperatorToShiftRequestV1`)

- `operatorId` (integer, required, e.g. `1063`) — O ID do operador, tal como devolvido por `/v1/operators`.
- `start` (string (date-time), optional, nullable, e.g. `"2026-10-12T10:00:00Z"`) — Quando o operador assume a máquina, dentro do turno e não no futuro. Por predefinição, é o início do turno. Uma hora sem desvio UTC é interpretada como UTC.

### Responses

#### 200 — O turno ao qual o operador foi atribuído

Type: object (`ShiftOperatorAssignmentDtoV1`)

- `shiftId` (integer, required, e.g. `48213`) — O turno ao qual o operador foi atribuído.
- `machineId` (integer, required, e.g. `12`) — A máquina a que o turno pertence.
- `operatorId` (integer, required, e.g. `1063`) — O operador que foi atribuído.
- `start` (string (date-time), required, e.g. `"2026-10-12T10:00:00Z"`) — Quando o operador assumiu a máquina. Mantém-na até ao fim do turno, ou até uma atribuição posterior.

#### 422 — Erro de validação

Type: object (`HTTPValidationError`)

- `detail` (array of object, optional)
  - `loc` (array of string | integer, required)
  - `msg` (string, required)
  - `type` (string, required)
  - `input` (any, optional)
  - `ctx` (object, optional)

### Example request

```bash
curl -X POST 'https://draco.prod.pulsarml.com/v1/shifts/<shift_id>/operator' \
  -H 'x-api-key: <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "operatorId": 1063,
    "start": "2026-10-12T10:00:00Z"
  }'
```