Edge API reference

This reference separates the cloud gateway from the local PLC interfaces. Use the origins supplied for your deployment; do not point a local PLC request at the cloud gateway or vice versa.

Cloud gateway

Base path: /api/edge on your deployment's API origin. Registration uses a single-use registration token. Authentication exchanges apiKey and hardwareId for access/refresh tokens. Access tokens last 15 minutes; refresh tokens have a seven-day lifetime and remain subject to current connector/service authority.

Authorization: Bearer <access-token>
Content-Type: application/json

Method	Path	Purpose / authority
POST	/register	Register with registrationToken, hardwareId, and optional runtime metadata. Returns a pending connector and API key.
POST	/auth	Authenticate approved connector with API key and hardware ID.
POST	/auth/refresh	Refresh with refreshToken.
POST	/heartbeat	Health/configuration and pending actions; integration read authority.
GET	/config	Current configuration; integration read authority.
GET	/sync/workcenters	Assigned work centers and mappings; work-center read authority.
GET	/sync/orders	Released/in-progress assigned orders; production-order read authority.
POST	/events/production	Production reporting; progress-report authority.
POST	/events/status	Work-center status; production-issue reporting authority.
POST	/events/malfunction	Malfunction reporting; production-issue reporting authority.
POST	/print-jobs/:id/status	Report eligible label-print job outcome; label-print authority.

The token binds the connector's organization/site/environment. Assignment checks and current service permissions still apply to every request. Do not add caller-supplied scope to evade that binding.

Order synchronization accepts since in Unix milliseconds, limit (default 100), and an optional subset of assigned work-center business codes. It returns orders, syncTimestamp, and hasMore. These metadata do not by themselves provide a lossless pagination procedure for a large changing order set; validate your deployed synchronization strategy.

Production reporting

The gateway accepts an events array. Its current handler uses quantityProduced as the new total, not an additive quantity:

{
  "events": [{
    "eventId": "example-event-001",
    "orderNumber": "PO-DEMO-001",
    "workCenterId": "<assigned-work-center-reference>",
    "quantityProduced": 12,
    "timestamp": "2026-10-13T08:00:00Z"
  }]
}

Use the identity expected by the specific handler. The current assignment check uses database work-center references, while order synchronization returns business work-center codes; do not interchange them or assume a universal mapping. An implementation must prove that its reporting identity matches the target order.

A 200 response contains per-event success and errors; inspect every result. It does not mean every event succeeded. Reporting can trigger order lifecycle transitions. The current production handler acknowledges quantityScrap without maintaining a scrap ledger; use the supported scrap workflow for operational scrap evidence. The separate local ReportScrap method buffers a scrap event, but the current uplink dispatcher marks that event type successful without transmitting it to a cloud scrap handler. Do not use local scrap acceptance as operational scrap evidence. Event IDs are correlation data, not a guarantee of exactly-once application.

Status events accept operational, idle, or malfunctioning. Malfunction events use workCenterId and action: "start" or action: "end", with optional reasonId, details, and timestamp. An end event must include the malfunctionId returned by the matching start. Inspect per-event responses in both cases.

Print outcome

Report printed or failed, with the relevant message, to the eligible print job. The runtime's TCP write completion means data was sent to the printer, not that a physical label was verified. preview-json can be marked printed by local preview handling without producing paper.

Local REST API

The REST listener is disabled by default. Once provisioned, use https://<edge-host>:3005 with a dedicated machine bearer token on every route. Explicit local work-center/action scope applies. Every write also needs a unique requestId and current Unix-millisecond timestamp; see Security for TLS, provisioning, replay protection and limits.

Method	Path	Purpose
GET	/health	Local process response and timestamp.
GET	/work-centers	Cached assigned work centers.
GET	/work-centers/:id	Cached work center by business code.
GET	/orders	Cached orders; optional workCenterId and status.
GET	/orders/:orderNumber	Cached order.
GET	/orders/:orderNumber/recipe	Cached recipe; optional stationRole.
POST	/report/production	Buffer workCenterId, orderNumber, quantityProduced.
POST	/report/station-progress	Buffer work center/order/station, role, sequence, completed and in-progress quantities.

A local success: true confirms local acceptance, not cloud persistence. The cloud router listed above does not expose a station-progress endpoint; confirm the deployed adapter path before relying on that feature. Recipe routes return only cached recipe content; the current normal cloud order projection does not populate a recipe. An empty recipe object is not evidence that the order has no recipe in Ennea.

Local OPC UA methods

The OPC UA listener is disabled by default. Once provisioned, the endpoint is opc.tcp://<edge-host>:4841/UA/EnneaEdge, with trusted certificates, SignAndEncrypt/Basic256Sha256 and a configured machine username/token. Report methods append requestId: String and timestamp: Double after their existing arguments. Browse the EnneaMES folder for GetNextOrder, GetRecipe, ReportProduction, ReportScrap, and ReportStatus. Method status and output strings must both be checked. For example, a successful method call can still return NO_ORDER or ORDER_NOT_FOUND.

Errors and retry

400 usually indicates invalid input; 401 requires credential/expiry checks; 403 can mean pending/revoked connector, IP restriction, scope, or service permissions; 404 requires identity/assignment checks. Keep the original event identity and reconcile cloud state before replaying reports. Do not infer fixed rate limits from older examples: use deployment limits and explicit server feedback.

See Installation, OPC UA, and Troubleshooting.