Conventions

The rules that hold for every route: lists and pages, ids, days and hours on the plant's clock, ranges, efficiency, money and compatible changes.

Every route lives under https://api.fluenta.io/v1/external and answers JSON. This page gathers what holds for all of them.

Lists and pages

A list comes in one of three shapes. Each operation's page says which.

Shape of the answer	Operations	Size
`{ items, page, total }`	`listOrganizations`, `listOrganizationStations`, `searchReferences`, `listActivity`	50 per page
`{ items, page, pageSize, total, from, to, groupBy }`	`getEfficiency`, `getProduction`, `getBilling`	100 per page
JSON array, not paged	`listModules`, `listStations`, `listOperators`, `getProgram`, `listOnHold`, `listCatalogue`	Everything in one answer

page goes in the query, starts at 1, and is 1 when you leave it out.
total counts the rows of every page, not of this page.
getBilling adds currency to its answer.
In listOrganizationStations and in the ranges, a page past the last one answers empty items, not an error.

curl 'https://api.fluenta.io/v1/external/organizations/42/stations?page=2' \
  -H 'Authorization: Bearer fluenta_live_xxxxxxxxxxxxxxxx'

{
  "items": [{ "id": 412, "name": "Pegar cuello", "moduleId": 7 }],
  "page": 2,
  "total": 51
}

The example trims the fields of each «puesto» (a station).

Ids

Every id is an integer: organizationId, moduleId, stationId, operatorId, referenceId, templateId.
An id always comes from an earlier answer. organizationId comes from getMe or listOrganizations; there is no default organization.
An id of another organization answers the same 404 as one that does not exist.
The one exception is listActivity: each row is identified by idx, a UUID.

A «puesto» has two names for the same number: stationId in paths and operationId in answers and filters. The id that listStations answers works in both places.

Days, hours and instants

A day is the plant's day, in its «Zona horaria» (time zone), never in UTC.

Value	Format	Clock
Day: `day`, `from`, `to`	`YYYY-MM-DD`	The plant's: `timezone` in `getOrganization` and `getSettings`
Hour: `hour`, `currentHour`	Integer from 0 to 23	The plant's. 9 is 09:00 to 09:59
Instant: `pausedAt`, `expiresAt`, `firstAt`	ISO 8601	UTC
Dates of an OC (an order lot): `dueDate`, `spliceDate`	ISO 8601. When you write them they carry their offset (`Z` or `±HH:MM`), such as `2026-11-28T00:00:00-05:00`	On a write, the plant's offset; in answers, UTC

getOrganization answers today: the plant's today. Use it when someone says "today".
Where day is optional and you leave it out, the API reads the plant's today.
A date that is not a real day answers 400 INVALID_DAY.
getMyUsage is the exception: it counts by UTC days.

Ranges

A range takes from and to, both included.

Operations	Most days, counting both ends
`getEfficiency`, `getProduction`, `getBilling`, `getOperatorReport`, `getModuleEfficiency`, `getOperatorEfficiency`	92 days
`getPauses` («Pausas», the pauses report)	31 days

A longer range answers 400 RANGE_TOO_LARGE, with the cap in maxDays. from after to answers 400 RANGE_INVALID. A day the plant has not reached yet is not an error: it has no data. For a longer question, split the range into several requests.

Efficiency and money

«Eficiencia» (efficiency) is a percentage, not a 0 to 1 ratio: units × 100 ÷ goal, with 2 decimals. 100 is exactly the goal and it can pass 100. It is null when the goal is 0.
Money is in whole currency units with up to 2 decimals: pesos or euros, never cents.
The currency is the plant's, set by its «país» (country): EUR for a plant in España, COP for every other. It is an ISO 4217 code. It comes in the answer's currency when the answer carries one; otherwise in currency.code of getOrganization.
A money figure can be null, not 0, when nothing was billed. Each field's description says so.

Every figure is the dashboard's figure for the same inputs. Quote it as it comes instead of recomputing it.

Caching

Every answer carries Cache-Control: no-store. Do not keep it in a proxy or a shared cache.

Compatible changes

The API grows by addition under /v1/external: new routes, new optional parameters and new fields in answers. Write your program to ignore the fields it does not know.

An error code keeps its name once published, and the permissions read and program are never renamed. The changelog announces the rest.