# Clasificar paros (https://docs.pulsarml.com/es/v1/api-reference/stops/put-stops-classifications)

**Scope requerido:** `stop_classifications.update`. Relacionados: `reports.read` para encontrar los paros que hay que clasificar con `POST /v1/reports/stops`; `stop_catalogs.read` para listar las causas y los componentes que acepta cada máquina con `GET /v1/stops/classification-options`.

Clasifica paros: define su causa general, causa específica, componente y descripción. El cuerpo es un **arreglo** JSON de hasta 1,000 filas, cada una con su propia clasificación.

**Cómo identificar un paro.** Un paro se identifica por su máquina y la hora en que empezó, no por un id: los ids de paro pueden cambiar cuando se recalcula un turno. Toma `machine.id` y `stop.startTime` de `POST /v1/reports/stops`. También se pueden clasificar los paros abiertos, que siguen en curso.

**Cómo elegir una clasificación.** Cada máquina acepta solo las causas de su árbol de pérdidas y sus propios componentes, que lista `GET /v1/stops/classification-options`. Una fila define al menos un `generalCauseId` o una `description`; `specificCauseId` necesita un `generalCauseId`.

**Una fila reemplaza la clasificación del paro.** Lo que una fila no incluye se borra: enviar solo `generalCauseId` quita la causa específica, el componente y la descripción del paro. Enviar las mismas filas otra vez no causa problemas, así que una solicitud que agotó el tiempo de espera se puede reintentar tal cual. Una causa que un operador puso en Pulsar también se sobrescribe.

Cada fila regresa con un `status`, y solo las filas `classified` cambiaron algo:

* `classified`: el paro ahora tiene esta clasificación.
* `stopNotFound`: la máquina `machineId` no tiene ningún paro que haya empezado en `startTime`, o no es una de tus máquinas.
* `duplicateStop`: otra fila de la misma solicitud indica el mismo paro, así que no se aplicó ninguna de las dos.
* `generalCauseNotAvailable`: la causa general no está en el árbol de pérdidas de la máquina.
* `specificCauseNotAvailable`: la causa específica no va debajo de la causa general en esta máquina.
* `componentNotAvailable`: el componente no está asignado a la máquina.

El esquema también lista `missingClassification` y `missingGeneralCause`. Este endpoint rechaza esas filas con `422` antes de que lleguen a Pulsar, así que no las vas a recibir.

Las filas del resultado repiten tus filas en el orden de la solicitud, con `startTime` normalizado a UTC; relaciónalas por posición en lugar de comparar los textos de `startTime`.

Las filas `classified` de una solicitud se guardan juntas. Las métricas que dependen de las causas de los paros se recalculan en segundo plano, así que los reportes pueden tardar un momento en mostrar el cambio.

## `PUT /v1/stops/classifications`

Base URLs:
- `https://draco.prod.pulsarml.com` — Producción
- `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`) — La máquina del paro: `machine.id` en `POST /v1/reports/stops`.
- `startTime` (string (date-time), required, e.g. `"2026-10-12T10:00:00Z"`) — Cuándo empezó el paro, exactamente como `stop.startTime` en `POST /v1/reports/stops`. Junto con `machineId` identifica el paro. Se requiere una fecha y hora completas; una sin desfase UTC se lee como UTC.
- `generalCauseId` (string (uuid), optional, nullable, e.g. `"d56aece5-a92a-462e-b275-919e15446bba"`) — Una de las causas generales de la máquina, de `GET /v1/stops/classification-options`.
- `specificCauseId` (string (uuid), optional, nullable, e.g. `"f89b5866-2d26-45a1-8cfc-8295557594d8"`) — Una de las causas específicas de `generalCauseId` en la máquina. Necesita `generalCauseId`.
- `componentId` (string (uuid), optional, nullable, e.g. `"3e8e81cf-7521-4ef9-b6c9-40074aa764c5"`) — Uno de los componentes de la 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"`) — Una nota de texto libre, no vacía. Obligatoria cuando no hay `generalCauseId`.

### Responses

#### 200 — Un resultado por fila, en el orden de la solicitud

Type: array of object

- `machineId` (integer, required, e.g. `12`) — La máquina del paro: `machine.id` en `POST /v1/reports/stops`.
- `startTime` (string (date-time), required, e.g. `"2026-10-12T10:00:00Z"`) — Cuándo empezó el paro, exactamente como `stop.startTime` en `POST /v1/reports/stops`. Junto con `machineId` identifica el paro. Se requiere una fecha y hora completas; una sin desfase UTC se lee como UTC.
- `generalCauseId` (string (uuid), optional, nullable, e.g. `"d56aece5-a92a-462e-b275-919e15446bba"`) — Una de las causas generales de la máquina, de `GET /v1/stops/classification-options`.
- `specificCauseId` (string (uuid), optional, nullable, e.g. `"f89b5866-2d26-45a1-8cfc-8295557594d8"`) — Una de las causas específicas de `generalCauseId` en la máquina. Necesita `generalCauseId`.
- `componentId` (string (uuid), optional, nullable, e.g. `"3e8e81cf-7521-4ef9-b6c9-40074aa764c5"`) — Uno de los componentes de la 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"`) — Una nota de texto libre, no vacía. Obligatoria cuando no hay `generalCauseId`.
- `status` ("classified" | "stopNotFound" | "duplicateStop" | "missingClassification" | "missingGeneralCause" | "generalCauseNotAvailable" | "specificCauseNotAvailable" | "componentNotAvailable", required, e.g. `"classified"`) — Qué pasó con esta fila. Solo las filas `classified` cambiaron un paro; consulta la descripción del endpoint para las demás.

#### 401 — * `unauthenticated`: Las credenciales faltan, no son válidas o expiraron.

#### 403 — * `missing_scope`: Las credenciales son válidas, pero no tienen el scope que requiere este endpoint.

#### 422 — Error de validación

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`: La API key superó su límite de solicitudes. Reintenta después de `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"
    }
  ]'
```