# Classificar paragens (https://docs.pulsarml.com/pt/v1/api-reference/stops/put-stops-classifications)

**Scope necessário:** `stop_classifications.update`. Relacionados: `reports.read` para encontrar as paragens a classificar com `POST /v1/reports/stops`; `stop_catalogs.read` para listar as causas e os componentes que cada máquina aceita com `GET /v1/stops/classification-options`.

Classifica paragens: define a sua causa geral, causa específica, componente e descrição. O corpo é um **array** JSON de até 1000 linhas, cada uma com a sua própria classificação.

**Como identificar uma paragem.** Uma paragem é identificada pela sua máquina e pela hora em que começou, não por um id: os ids de paragem podem mudar quando um turno é recalculado. Obtenha `machine.id` e `stop.startTime` de `POST /v1/reports/stops`. As paragens abertas, ainda em curso, também podem ser classificadas.

**Como escolher uma classificação.** Cada máquina aceita apenas as causas da sua árvore de perdas e os seus próprios componentes, listados por `GET /v1/stops/classification-options`. Uma linha define pelo menos um `generalCauseId` ou uma `description`; `specificCauseId` requer um `generalCauseId`.

**Uma linha substitui a classificação da paragem.** O que uma linha omite é apagado: enviar apenas `generalCauseId` remove a causa específica, o componente e a descrição da paragem. Enviar as mesmas linhas novamente não tem efeitos, por isso um pedido cujo tempo limite se esgotou pode ser repetido tal como está. Uma causa definida por um operador no Pulsar também é substituída.

Cada linha é devolvida com um `status`, e só as linhas `classified` alteraram alguma coisa:

* `classified`: a paragem tem agora esta classificação.
* `stopNotFound`: a máquina `machineId` não tem nenhuma paragem que tenha começado em `startTime`, ou não é uma das suas máquinas.
* `duplicateStop`: outra linha do mesmo pedido indica a mesma paragem, por isso nenhuma das duas foi aplicada.
* `generalCauseNotAvailable`: a causa geral não está na árvore de perdas da máquina.
* `specificCauseNotAvailable`: a causa específica não fica abaixo da causa geral nesta máquina.
* `componentNotAvailable`: o componente não está atribuído à máquina.

O esquema também lista `missingClassification` e `missingGeneralCause`. Este endpoint rejeita essas linhas com `422` antes de chegarem ao Pulsar, por isso não as irá receber.

As linhas do resultado repetem as suas linhas pela ordem do pedido, com `startTime` normalizado para UTC; faça-as corresponder pela posição em vez de comparar os textos de `startTime`.

As linhas `classified` de um pedido são guardadas em conjunto. As métricas que dependem das causas das paragens são recalculadas em segundo plano, por isso os relatórios podem demorar um momento a mostrar a alteração.

## `PUT /v1/stops/classifications`

Base URLs:
- `https://draco.prod.pulsarml.com` — Produção
- `https://draco.stage.pulsarml.com` — Sandbox (staging)

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

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

Type: array of object

- `machineId` (integer, required, e.g. `12`) — A máquina da paragem: `machine.id` em `POST /v1/reports/stops`.
- `startTime` (string (date-time), required, e.g. `"2026-10-12T10:00:00Z"`) — Quando a paragem começou, exatamente como `stop.startTime` em `POST /v1/reports/stops`. Juntamente com `machineId`, identifica a paragem. É necessária uma data e hora completas; uma sem desvio UTC é lida como UTC.
- `generalCauseId` (string (uuid), optional, nullable, e.g. `"d56aece5-a92a-462e-b275-919e15446bba"`) — Uma das causas gerais da máquina, de `GET /v1/stops/classification-options`.
- `specificCauseId` (string (uuid), optional, nullable, e.g. `"f89b5866-2d26-45a1-8cfc-8295557594d8"`) — Uma das causas específicas de `generalCauseId` na máquina. Requer `generalCauseId`.
- `componentId` (string (uuid), optional, nullable, e.g. `"3e8e81cf-7521-4ef9-b6c9-40074aa764c5"`) — Um dos componentes da máquina, de `GET /v1/stops/classification-options`.
- `description` (string, optional, nullable, min length 1, max length 255, pattern `\S`, e.g. `"Bearing seized on the main motor"`) — Uma nota de texto livre, não vazia. Obrigatória quando não há `generalCauseId`.

### Responses

#### 200 — Um resultado por linha, pela ordem do pedido

Type: array of object

- `machineId` (integer, required, e.g. `12`) — A máquina da paragem: `machine.id` em `POST /v1/reports/stops`.
- `startTime` (string (date-time), required, e.g. `"2026-10-12T10:00:00Z"`) — Quando a paragem começou, exatamente como `stop.startTime` em `POST /v1/reports/stops`. Juntamente com `machineId`, identifica a paragem. É necessária uma data e hora completas; uma sem desvio UTC é lida como UTC.
- `generalCauseId` (string (uuid), optional, nullable, e.g. `"d56aece5-a92a-462e-b275-919e15446bba"`) — Uma das causas gerais da máquina, de `GET /v1/stops/classification-options`.
- `specificCauseId` (string (uuid), optional, nullable, e.g. `"f89b5866-2d26-45a1-8cfc-8295557594d8"`) — Uma das causas específicas de `generalCauseId` na máquina. Requer `generalCauseId`.
- `componentId` (string (uuid), optional, nullable, e.g. `"3e8e81cf-7521-4ef9-b6c9-40074aa764c5"`) — Um dos componentes da máquina, de `GET /v1/stops/classification-options`.
- `description` (string, optional, nullable, min length 1, max length 255, pattern `\S`, e.g. `"Bearing seized on the main motor"`) — Uma nota de texto livre, não vazia. Obrigatória quando não há `generalCauseId`.
- `status` ("classified" | "stopNotFound" | "duplicateStop" | "missingClassification" | "missingGeneralCause" | "generalCauseNotAvailable" | "specificCauseNotAvailable" | "componentNotAvailable", required, e.g. `"classified"`) — O que aconteceu a esta linha. Só as linhas `classified` alteraram uma paragem; consulte a descrição do endpoint para as restantes.

#### 401 — * `unauthenticated`: as credenciais estão em falta, são inválidas ou expiraram.

#### 403 — * `missing_scope`: as credenciais são válidas, mas não têm o scope que este endpoint requer.

#### 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)

#### 429 — * `rate_limited`: a chave de API excedeu o seu limite de pedidos. Tente novamente após `Retry-After` segundos.

### Example request

```bash
curl -X PUT 'https://draco.prod.pulsarml.com/v1/stops/classifications' \
  -H 'x-api-key: <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "machineId": 12,
      "startTime": "2026-10-12T10:00:00Z",
      "generalCauseId": "d56aece5-a92a-462e-b275-919e15446bba",
      "specificCauseId": "f89b5866-2d26-45a1-8cfc-8295557594d8",
      "componentId": "3e8e81cf-7521-4ef9-b6c9-40074aa764c5",
      "description": "Bearing seized on the main motor"
    }
  ]'
```