# Organizaciones y recursos
URL: https://docs.fluenta.io/docs/organizations

Cómo se encadenan las llamadas, de tu usuario a tus organizaciones y de una organización a sus módulos, puestos y operarios.



Aquí verás qué recursos tiene la API, de qué llamada sale cada id y cómo
trabajar con una cuenta que pertenece a varias organizaciones.

## El recorrido [#el-recorrido]

```text
usuario (tu token)
└── organizaciones
    ├── módulos
    │   └── puestos
    └── operarios
```

Un token es personal: actúa como tu usuario y llega a todas las
organizaciones a las que perteneces. No hay organización por defecto: cada
ruta nombra la suya en la ruta, como `organizationId`.

## De dónde sale cada id [#de-dónde-sale-cada-id]

| Recurso      | Qué es                                             | Su id sale de                                                                                                             | Se usa como                                       |
| ------------ | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| Organización | Una planta, un taller o la cuenta de una marca     | `GET /me` → `organizations[].id`, `GET /organizations` → `items[].id`                                                     | `organizationId` en la ruta                       |
| Módulo       | Una línea de producción                            | `GET …/modules` → `[].id`, `GET …/floor` → `modules[].id`                                                                 | `moduleId` en la ruta o como filtro               |
| Puesto       | Una estación numerada de un módulo                 | `GET …/modules/{moduleId}/stations` → `[].id`, `GET …/stations` → `items[].id`, `GET …/floor` → `modules[].stations[].id` | `stationId` en la ruta, `operationId` como filtro |
| Operario     | La persona que registra su producción en un puesto | `GET …/operators` → `[].id`, el campo `operator.id` de un puesto                                                          | `operatorId` en la ruta o como filtro             |

El id de un puesto tiene dos nombres. En la ruta es `stationId`. En los
filtros de los reportes es `operationId`, y en sus filas viene en
`operation.id`. Es el mismo número.

Cada operario trae en `station` el puesto donde está sentado, o `null` si no
está en ninguno. Cada puesto trae en `operator` al operario sentado, o `null`
si está vacío.

## Un ejemplo encadenado [#un-ejemplo-encadenado]

```bash
# 1. Tus organizaciones → organizationId
curl https://api.fluenta.io/v1/external/organizations \
  -H "Authorization: Bearer $FLUENTA_TOKEN"

# 2. Los módulos de la organización 42 → moduleId
curl https://api.fluenta.io/v1/external/organizations/42/modules \
  -H "Authorization: Bearer $FLUENTA_TOKEN"

# 3. Los puestos del módulo 7 → stationId
curl https://api.fluenta.io/v1/external/organizations/42/modules/7/stations \
  -H "Authorization: Bearer $FLUENTA_TOKEN"

# 4. El puesto 311, como lo lee el tablero ahora
curl https://api.fluenta.io/v1/external/organizations/42/stations/311 \
  -H "Authorization: Bearer $FLUENTA_TOKEN"

# 5. La eficiencia de ese puesto en un rango: el mismo id, como operationId
curl "https://api.fluenta.io/v1/external/organizations/42/analytics/efficiency?from=2026-11-03&to=2026-11-07&operationId=311" \
  -H "Authorization: Bearer $FLUENTA_TOKEN"
```

Los pasos 1 a 4 responden en todos los planes. El paso 5 sigue el plan: mira
[Planes](/docs/plans).

`GET …/floor` responde los módulos con sus puestos en una sola llamada. Úsala
cuando necesites toda la planta, no para leer un solo puesto: cuenta contra un
límite de uso más bajo.

## Cuentas con varias organizaciones [#cuentas-con-varias-organizaciones]

Una persona puede pertenecer a varias organizaciones: una marca y sus
talleres, o alguien que trabaja para dos plantas. El mismo token llega a
todas.

* `GET /me` trae las primeras 50, por nombre, y el total en
  `organizationsTotal`.
* `GET /organizations` las pagina de a 50 con `page` y las busca por nombre
  con `search`.
* Cada organización responde según su propio plan. `connectorEnabled` dice si
  esa organización responde a tu credencial.
* Cada organización tiene su propio límite de uso, y hay uno más para el
  token entre todas: mira [Límites de uso](/docs/rate-limits).
* Cada organización tiene su propio reloj. Los días y las horas de sus
  respuestas van en su zona horaria: `timezone` y `today` en
  `GET /organizations/{organizationId}`.
* Tu rol y tus permisos en una organización están en
  `GET /organizations/{organizationId}/access`.

Para recorrer una marca y sus talleres, lista las organizaciones y repite las
mismas llamadas con cada `organizationId`.

## Lo que no es tuyo responde 404 [#lo-que-no-es-tuyo-responde-404]

Una organización a la que no perteneces responde igual que una que no existe:

```json
{
  "statusCode": 404,
  "code": "ORGANIZATION_NOT_FOUND",
  "message": "Organización no encontrada"
}
```

Nunca responde 403. Lo mismo pasa dentro de una organización: un módulo, un
puesto o un operario de otra organización responde 404 con
`MODULE_NOT_FOUND`, `OPERATION_NOT_FOUND` u `OPERATOR_NOT_FOUND`, igual que un
id que no existe.

Usa siempre ids que salieron de una respuesta de la API. No los construyas ni
los adivines. [Errores](/docs/errors) tiene el resto de los códigos.