Kết nối một hệ thống với Orbitify
Một hệ thống khác (ERP, hệ thống bảo trì, hệ thống điều khiển của tòa nhà, gateway tại hiện trường) làm việc với một công ty trong Orbitify qua một kết nối: một tài khoản riêng có vai trò, như một người. Mọi thứ một kết nối được làm đều được mô tả ở đây, tạo ra từ mã nguồn, nên luôn được cập nhật.
Bắt đầu
- Hãy thực hành trong công ty thử nghiệm trước. Quản trị viên của công ty tạo nó trong Cài đặt > Hệ thống kết nối: một bản sao các loại, trường, quy trình, vai trò và nhóm của công ty, và cả vị trí và tài sản nếu chọn, không có công việc thật.
- Kết nối hệ thống ở đó (Kết nối một hệ thống), cấp các vai trò nó cần và tạo một khóa. Một khóa chỉ dùng được trong công ty nơi nó được tạo.
- Gửi khóa trong Authorization: Bearer, và một Idempotency-Key với mỗi thay đổi: một thay đổi gửi lại với cùng khóa đó được trả lời như lần đầu và không bao giờ thực hiện hai lần.
- Khi đã chạy tốt, hãy kết nối nó trong công ty thật với một khóa riêng.
curl -X POST "https://dashboard.orbitify.ai/api/ops/actions/request.raise" \
-H "Authorization: Bearer $KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"dryRun": true, "params": {"summary": "Pump P-1 is leaking", "classKey": "fault", "assetId": "erp:P-100"}}'Mọi thay đổi là một thao tác
- Mọi thay đổi là một thao tác, POST /ops/actions/<action>, được kiểm tra như của một người: vai trò, gói dịch vụ, phê duyệt và quy tắc của quy trình. Nó được lưu trong lịch sử với tên của kết nối và người đã kết nối nó.
- Gửi dryRun: true để xem nó sẽ làm gì; không có gì được lưu.
- Một lời từ chối nói lý do bằng lời (message), theo ngôn ngữ của Accept-Language.
- Id có thể là của chúng tôi hoặc của hệ thống kia, viết là system:id (erp:WO-55120). Một lệnh tạo gửi kèm outsideId chỉ được tạo một lần: gửi lại thì nó trả lời bằng bản ghi đã tạo trước đó.
Đọc dữ liệu
- GET /ops/registry cho biết các loại, trường và các bước của từng quy trình của công ty: các khóa mà một thao tác nhận.
- Một yêu cầu, lệnh công việc hoặc tài sản: GET /ops/requests/<id>, /ops/work-orders/<id>, /ops/assets/<id>. Một kết nối chỉ đọc được những gì vai trò của nó được xem.
- GET /ops/test-company cho biết khóa có đang dùng trong một công ty thử nghiệm hay không (testOf).
Chỉ số từ một hệ thống
Tối đa 1.000 chỉ số mỗi lần gọi, POST /ops/readings/batch, mỗi chỉ số khớp với đúng một tài sản theo id của chúng tôi, số, mã, số sê-ri hoặc system:id. Khóa chỉ dành cho chỉ số chỉ mở được đường này.
Dữ liệu trực tiếp từ hiện trường
Gateway tại hiện trường hoặc một tệp nhật ký xu hướng gửi bằng khóa dữ liệu trực tiếp, tạo trên trang của nguồn trong Cài đặt > Nguồn dữ liệu trực tiếp, chỉ mở POST /ops/live/ingest. Tối đa 5.000 chỉ số mỗi lần gọi, dạng JSON, JSON của Telegraf hoặc CSV. Một chỉ số của một tag tại một thời điểm đã lưu chỉ được lưu một lần, nên có thể gửi lại bộ đệm; không cần Idempotency-Key. Không có gì ghi ngược lại vào hệ thống điều khiển.
curl -X POST "https://dashboard.orbitify.ai/api/ops/live/ingest" \
-H "Authorization: Bearer $LIVE_KEY" -H "Content-Type: application/json" \
-d '{"readings": [{"tag": "INV-03.Temp_Bearing", "at": "2026-10-23T14:02:00Z", "value": 71.5}]}'Nhận biết những gì xảy ra
- Những gì xảy ra được gửi đến các địa chỉ https mà kết nối lắng nghe, ký theo Standard Webhooks 1.0, và được giữ 30 ngày trong danh sách sự kiện, GET /ops/events, cũ nhất trước, phân trang theo seq.
- Kiểm tra webhook-signature: HMAC-SHA256 của "webhook-id.webhook-timestamp.body" với các byte của khóa bí mật. Các thư viện của chính tiêu chuẩn làm việc này.
- Một sự kiện cho biết cái gì thay đổi và cần xem ở đâu, không bao giờ kèm bản ghi: hãy đọc bản ghi để lấy giá trị. Thứ tự không được đảm bảo: bỏ qua sự kiện có phiên bản cũ hơn phiên bản đã thấy.
- Một lần gửi thất bại được thử lại trong khoảng ba ngày; 410 sẽ tắt địa chỉ đó.
Giới hạn và an toàn
- 120 lần gọi mỗi phút cho mỗi khóa và 600 cho mỗi công ty; vượt quá thì trả về 429 kèm Retry-After.
- Một kết nối đột nhiên thay đổi nhiều hơn hẳn bình thường sẽ bị tạm dừng cho đến khi quản trị viên cho chạy lại.
- Khóa hết hạn sau một năm nếu không gia hạn, và mỗi kết nối được người phụ trách xem lại sáu tháng một lần.
Phiên bản và thay đổi
- Phiên bản của API này là 2026-10-24, ngày nó ra mắt. API chỉ tăng thêm: hành động, trường, giá trị và sự kiện mới được thêm vào; không có gì mà hệ thống kết nối đang dùng bị gỡ bỏ hay thay đổi. Hãy bỏ qua các trường và giá trị bạn không biết.
- Gửi Orbitify-Version: 2026-10-24 để cố định phiên bản; câu trả lời cho biết phiên bản đã dùng. Phiên bản mới chỉ ra đời khi có thay đổi không thể làm mà không gây hỏng, và phiên bản trước vẫn hoạt động ít nhất 6 tháng.
- Một hành động sắp ngừng sẽ trả lời kèm tiêu đề Deprecation và Sunset cùng đường dẫn tới thứ thay thế. Người phụ trách mỗi kết nối còn dùng nó sẽ nhận email khi có thông báo, 30 ngày trước và 7 ngày trước khi nó ngừng.
- Sự kiện cũng chỉ tăng thêm: một sự kiện cần đổi nội dung sẽ trở thành một loại sự kiện mới, còn loại cũ vẫn giữ nguyên.
curl "https://dashboard.orbitify.ai/api/ops/registry" \
-H "Authorization: Bearer $KEY" \
-H "Orbitify-Version: 2026-10-24"Nhật ký thay đổi API
Kết nối các hệ thống khác của bạn
Cài đặt giờ có mục Hệ thống kết nối. Mỗi hệ thống bạn kết nối có tài khoản riêng với các vai trò bạn chọn, khóa có hiệu lực một năm, và nhật ký mọi thứ nó đã thay đổi. Hệ thống của bạn có thể tạo và cập nhật bản ghi theo cùng các quy tắc như con người, và nhận biết thay đổi qua webhook có chữ ký hoặc một luồng sự kiện. Một công tắc an toàn tạm dừng kết nối nào bỗng thay đổi nhiều hơn hẳn bình thường, và báo cho quản trị viên của bạn.
Trang công khai dành cho lập trình viên
Lập trình viên xây dựng tích hợp giờ có thể đọc trang dành cho lập trình viên mà không cần đăng nhập. Trang liệt kê mọi thao tác, mọi dữ liệu đọc được và mọi sự kiện kèm ví dụ, và có liên kết tới mô tả API để họ tải vào công cụ của mình. Trang được tạo từ chính nền tảng đang chạy, nên luôn được cập nhật.
Phiên bản theo ngày cho API kết nối
Gửi tiêu đề Orbitify-Version, như Orbitify-Version: 2026-10-24, để nêu phiên bản mà tích hợp của bạn được viết cho; mọi câu trả lời đều cho biết phiên bản đã dùng. API chỉ thay đổi bằng cách thêm vào. Một thay đổi không thể làm bằng cách thêm sẽ thành phiên bản mới, được báo trước ít nhất 6 tháng trước khi phiên bản cũ kết thúc, và một lệnh gọi tới thao tác sắp bị bỏ sẽ trả về tiêu đề Deprecation và Sunset cùng liên kết hướng dẫn việc cần làm.
Mã tham chiếu
Số thao tác hiển thị: 32. Phiên bản 2026-10-24
Requests
POST/api/ops/actions/request.assignPass request to a team
Give a request to a team, the people who will sort it or do the work. To give work to a person, make a work order for the request and assign that (work_order.create, work_order.assign).
| Tên | Kiểu | Nó là gì |
|---|---|---|
expectedVersion | integer | |
teamId | id: của chúng tôi hoặc system:id |
{
"target": "bms:ALM-88213",
"params": {
"teamId": "3f1c2a9e-0000-4000-8000-000000000001"
}
}POST/api/ops/actions/request.raiseRaise request
Raise a request (a ticket, a call-out, a fault report): report a fault, a need or a finding at a location or on an asset. Use it when someone reports something wrong or needed; it is not yet work for anyone (make a work order for that). Routing rules choose the team, time targets start and the right people are told, as for a person. It needs a summary, the kind of request and where it is: a location, an asset at one, or both (people in the app are refused with neither; a connected system may still leave both out). Raising it for someone else (reportedById) needs the right to raise requests for someone else (a connected system needs only to raise requests). Coming from another system, send outsideId with that system's ticket id so a repeat makes nothing twice.
| Tên | Kiểu | Nó là gì |
|---|---|---|
classKey* | string | The kind of request, a key from GET /api/ops/registry (classes of kind request), never a work order's kind such as corrective |
summary* | string | Its title: what is wrong or needed, in one short line |
assetId | id: của chúng tôi hoặc system:id | The asset it is about (or system:id); its location is taken when locationId is left out |
attrs | object | Values for the kind's own fields, by field key (GET /api/ops/registry) |
details | string | Its description: what was seen, since when, anything that helps the team; optional |
detectionMethod | string | How it was found, such as an alarm or an inspection |
entityId | id: của chúng tôi hoặc system:id | a legal entity in the company's group; null: its place's, or the one above |
findingIds | array | |
impact | string | ONE (one asset or room), SEVERAL or SITE (the whole site): with the company's grid, the severity is worked out from it and the severity said (its urgency) |
incidentTypeId | id: của chúng tôi hoặc system:id | |
internal | boolean | |
locationId | id: của chúng tôi hoặc system:id | Where: a location id (or system:id). Give a location, an asset at one, or both (needed in the app; a connected system may leave both out) |
photos | array | of {url, name, contentType, sizeBytes}: photos, videos or PDFs of the fault, uploaded first (POST /api/ops/uploads |
punchListId | id: của chúng tôi hoặc system:id | a punch list it is an item of: its place, team and kind unless given here |
reportedById | id: của chúng tôi hoặc system:id | who reported it, when someone raises it for them: a person who called or wrote; needs the right to raise requests for someone else |
reportedVia | string | APP | PHONE | CHAT | EMAIL | ON_SITE (how it came in; APP when left out)Một trong: APP, PHONE, CHAT, EMAIL, ON_SITE |
severity | string | How bad it is; the company's own words for each are in GET /api/ops/settingsMột trong: MINOR, MODERATE, MAJOR, CRITICAL |
teamId | id: của chúng tôi hoặc system:id | A team to give it to; left out, the company's routing rules choose |
outsideId | string | The other system's id for it, system:id; it is then made once |
{
"params": {
"summary": "Water leaking under the plant room door",
"details": "A puddle by the door since this morning; it seems to come from the pipe above the ceiling.",
"classKey": "leak",
"locationId": "9e8d7c6b-0000-4000-8000-000000000014",
"severity": "MODERATE"
}
}POST/api/ops/actions/request.transitionChange request status
Move a request to another step of its flow: start it, put it on hold, mark it fixed, confirm it, close or cancel it. The steps it may go to next are on its read (GET /api/ops/requests/{id}, next) and GET /api/ops/requests/{id}/checks says what each would need. The flow's rules hold: required fields, who may make the move, approvals.
| Tên | Kiểu | Nó là gì |
|---|---|---|
to* | string | The key of the step to move to, one of the request's next steps |
attrs | object | |
expectedVersion | integer | |
note | string | Why, kept with the move |
{
"target": "bms:ALM-88213",
"params": {
"to": "closed",
"note": "Alarm cleared at the source"
}
}POST/api/ops/actions/request.updateEdit request
Change what a request says: its summary (title), description (details), severity, kind, location, asset or fields. Use it to correct or add to a request; a new severity, kind or place matches its time target again. Not its step (request.transition) nor its team (request.assign). A closed or cancelled request stays as it was.
| Tên | Kiểu | Nó là gì |
|---|---|---|
assetId | id: của chúng tôi hoặc system:id | null takes the asset off |
attrs | object | fields to change; null removes one |
classKey | string | |
details | string | its description; empty takes it off |
entityId | id: của chúng tôi hoặc system:id | a legal entity in the company's group; null: its place's, or the one above |
expectedVersion | integer | The version you read; the change is refused when someone changed it since |
impact | string | ONE | SEVERAL | SITEMột trong: ONE, SEVERAL, SITE |
locationId | id: của chúng tôi hoặc system:id | |
severity | string | MINOR | MODERATE | MAJOR | CRITICAL (its urgency, with the company's grid)Một trong: MINOR, MODERATE, MAJOR, CRITICAL |
summary | string | its title |
{
"target": "bms:ALM-88213",
"params": {
"severity": "CRITICAL"
}
}Work orders
POST/api/ops/actions/cost.addAdd a cost to a work order
Add a cost to a work order (the target): parts, a purchase, a subcontractor, travel, other; in any currency, at the latest rate kept. Parts from the store are charged by issuing them (part.issue), not here.
| Tên | Kiểu | Nó là gì |
|---|---|---|
amount* | number | |
description* | string | |
kind* | string | PART | PURCHASE | SUBCONTRACT | TRAVEL | OTHERMột trong: PART, PURCHASE, SUBCONTRACT, TRAVEL, OTHER |
currency | string | Its currency (ISO 4217); the company's when left out |
incurredOn | string (date) | |
rate | number | Its rate to the company's currency; the latest kept when left out |
vendorId | id: của chúng tôi hoặc system:id |
{
"target": "erp:WO-55120",
"params": {
"kind": "SUBCONTRACT",
"description": "Crane hire, half a day",
"amount": 450,
"currency": "EUR"
}
}POST/api/ops/actions/message.addWrite a message
Add a message to a request or a work order (the target): words and files (photos, videos, PDFs uploaded first) the people on it read. Shared messages are seen by the client's people too; a note for the company only is shared false. Use it to tell the people on the work something, or to answer a question on it.
| Tên | Kiểu | Nó là gì |
|---|---|---|
body | string | |
files | array | of {url, name, contentType, sizeBytes}: photos, videos or PDFs uploaded first |
objectKind | string | request | work_order (request when left out)Một trong: request, work_order |
shared | boolean | seen by the client's people; on for a request, off for a work order when left out |
{
"target": "bms:ALM-88213",
"params": {
"objectKind": "request",
"body": "The alarm came back at 14:02"
}
}POST/api/ops/actions/time.logLog time on a work order
Log time worked on a work order (the target) for a person who is on it: how long and on which day. Logging someone else's time needs the right to assign the work.
| Tên | Kiểu | Nó là gì |
|---|---|---|
personId* | id: của chúng tôi hoặc system:id | |
time* | string | How long: 1h30, 90m, 1.5h or 0:45 |
note | string | |
workedOn | string (date) | The day it was worked; today when left out |
{
"target": "erp:WO-55120",
"params": {
"time": "1h30",
"workedOn": "2026-11-03",
"personId": "5b2d7c1e-0000-4000-8000-000000000002"
}
}POST/api/ops/actions/work_order.assignAssign work order
Give a work order to a team, a person, or both, and set who else is on it (crewIds, the whole list). Use it to dispatch work to a technician. The certificates the work needs are checked for each person.
| Tên | Kiểu | Nó là gì |
|---|---|---|
assigneeId | id: của chúng tôi hoặc system:id | |
crewIds | array | everyone else on the work order besides its person: the whole list; [] for nobody |
deadline | string (date) | |
expectedVersion | integer | |
note | string | a few words more on the reason |
reason | string | when assigneeId is not suggestedId: KNOWS_THE_SITE | AVAILABLE_SOONER | CLIENT_ASKED | TRAINING | SHARING_WORK | OTHERMột trong: when, AVAILABLE_SOONER, CLIENT_ASKED, TRAINING, SHARING_WORK, OTHER |
suggestedId | id: của chúng tôi hoặc system:id | who "Who could do it" put first, when the screen showed it |
teamId | id: của chúng tôi hoặc system:id |
{
"target": "erp:WO-55120",
"params": {
"assigneeId": "5b2d7c1e-0000-4000-8000-000000000002"
}
}POST/api/ops/actions/work_order.createCreate work order
Make a work order (a job): work for someone to do at a location or on assets, optionally answering requests, with the tasks of its kind and a checklist. Use it when a request needs work, or to plan corrective or preventive work directly. Approval rules, certificates and permits hold as for a person. Needs a title; give the kind, where, the requests it answers, a priority and a due date when known. Coming from another system, send outsideId with that system's order number so a repeat makes nothing twice.
| Tên | Kiểu | Nó là gì |
|---|---|---|
title* | string | What is to be done, in one line |
assetId | id: của chúng tôi hoặc system:id | |
assetIds | array | the assets it is about, in order: a round of several |
assigneeId | id: của chúng tôi hoặc system:id | |
attrs | object | |
checklistId | id: của chúng tôi hoặc system:id | a checklist whose tasks it also gets, after its kind's (V331 |
classKey | string | The kind of work, a key from GET /api/ops/registry (classes of kind work_order) |
deadline | string (date) | When it is due: a day (2026-11-03) or a time |
description | string | |
entityId | id: của chúng tôi hoặc system:id | a legal entity in the company's group; null: its place's, or the one above |
estimatedHours | number | the hours the work should take (V317 |
locationId | id: của chúng tôi hoặc system:id | |
move | boolean | Take requests already on another open work order off it; left out, people in the app are refused and a connected system moves it |
parentId | id: của chúng tôi hoặc system:id | |
priority | string | Left out with requests: their worst severity sets it, as the company's settings map themMột trong: ROUTINE, PLANNED, URGENT, EMERGENCY |
projectId | id: của chúng tôi hoặc system:id | |
requestIds | array | Requests it answers (ids or system:id); they follow it and close when it is done |
tasks | array | Tasks to add after its kind's: each {title, kind: CHECK|READING|TEXT|CHOICE|PHOTO, required, unit} |
teamId | id: của chúng tôi hoặc system:id | |
outsideId | string | The other system's id for it, system:id; it is then made once |
{
"params": {
"title": "Fix the leak under the plant room door",
"classKey": "corrective",
"requestIds": [
"8d4f6b2a-0000-4000-8000-000000000011"
],
"priority": "URGENT",
"deadline": "2026-11-04"
}
}POST/api/ops/actions/work_order.record_tasksRecord several tasks of a work order
Record several tasks of a work order at once, each by its id or its title: done or not, a reading's value, a note. Use it when a technician reports a few things together. All or nothing.
| Tên | Kiểu | Nó là gì |
|---|---|---|
tasks* | array | of {taskId or title, done, value, note, readAt} |
{
"target": "erp:WO-55120",
"params": {
"tasks": [
{
"title": "Suction pressure",
"value": 4.2
},
{
"title": "Discharge pressure",
"value": 15.8
},
{
"title": "Belt tension checked",
"done": true
}
]
}
}POST/api/ops/actions/work_order.schedulePlan a work order on the schedule
Put a work order on the schedule (a start and hours), or take it off; optionally give it to a person. Use it to plan who does what on which day; GET /api/ops/schedule shows the board. Warns for a client that agrees visits first, a day fuller than the person works, or a due date before the day.
| Tên | Kiểu | Nó là gì |
|---|---|---|
assigneeId | id: của chúng tôi hoặc system:id | give it to this person (leave out to keep its person |
hours | string | how long it takes, in hours (empty: not said) |
start | string | when it starts: 2026-10-09T09:00 (in timeZone), a day (2026-10-09: when the person's day starts), or empty to take it off the schedule |
timeZone | string | the zone start is written in, such as Europe/London (else the person's own, else UTC) |
{
"target": "erp:WO-55120",
"params": {
"start": "2026-11-04T08:00",
"hours": 2,
"timeZone": "Europe/London"
}
}POST/api/ops/actions/work_order.transitionChange work order status
Move a work order to another step of its flow: send it out, start, put on hold, finish, close or cancel it. The steps it may go to next are on its read (GET /api/ops/work-orders/{id}, next) and GET /api/ops/work-orders/{id}/checks says what each would need. Required tasks, failure reports, permits, agreed visits, certificates and approvals hold as for a person.
| Tên | Kiểu | Nó là gì |
|---|---|---|
to* | string | |
attrs | object | |
expectedVersion | integer | |
whatWasDone | string | what was done, kept as a shared message on the work order and on each request it finishes |
{
"target": "erp:WO-55120",
"params": {
"to": "completed"
}
}POST/api/ops/actions/work_order.updateEdit work order
Change what a work order says: title, description, priority, deadline, kind, location, fields, estimated hours. Not its step (work_order.transition), people (work_order.assign) or schedule (work_order.schedule).
| Tên | Kiểu | Nó là gì |
|---|---|---|
attrs | object | fields to change; null removes one |
classKey | string | |
deadline | string (date) | YYYY-MM-DD) or time; null takes it off |
description | string | |
entityId | id: của chúng tôi hoặc system:id | a legal entity in the company's group; null: its place's, or the one above |
estimatedHours | number | the hours the work should take; null takes it off (V317 |
expectedVersion | integer | The version you read; the change is refused when someone changed it since |
locationId | id: của chúng tôi hoặc system:id | |
priority | string | ROUTINE | PLANNED | URGENT | EMERGENCYMột trong: ROUTINE, PLANNED, URGENT, EMERGENCY |
title | string |
{
"target": "erp:WO-55120",
"params": {
"deadline": "2026-12-05"
}
}Tasks
POST/api/ops/actions/task.recordRecord a task
Record one task of a work order (the task is the target): done or not, its answer or reading, a note. Out of range readings are marked. For several tasks at once, work_order.record_tasks.
| Tên | Kiểu | Nó là gì |
|---|---|---|
done | boolean | |
note | string | |
photos | array | |
readAt | string (date-time) | a reading was taken: 2026-10-16T09:30 (UTC unless it says its offset); empty: now |
removePhotoIds | array | |
value | number | string |
{
"targetId": "7a0e5f3c-0000-4000-8000-000000000003",
"params": {
"value": 61.5,
"done": true
}
}Assets and readings
POST/api/ops/actions/asset.createAdd asset
Add an asset (a piece of equipment, infrastructure, a vehicle or a tool) to the register at a location or inside another asset. Use it when something new is installed or found that is not on the register; asset.register also records its warranty, value, spare parts and maintenance plan in one go. A serial number another asset has is refused. Coming from another system, send outsideId with that system's asset id so a repeat makes nothing twice.
| Tên | Kiểu | Nó là gì |
|---|---|---|
name* | string | |
attrs | object | |
builtOn | string (date) | when it was built |
classKey | string | The kind of asset, a key from GET /api/ops/registry (classes of kind asset) |
code | string | |
defaultWorkKindKey | string | the kind of work a work order about it is when nobody says |
groupId | id: của chúng tôi hoặc system:id | its asset group (V317 |
installedOn | string (date) | |
investedOn | string (date) | when it was paid for |
locationId | id: của chúng tôi hoặc system:id | |
manufacturer | string | |
model | string | |
ownerEntityId | id: của chúng tôi hoặc system:id | a legal entity in the company's group; null: its place's |
parentAssetId | id: của chúng tôi hoặc system:id | |
projectId | id: của chúng tôi hoặc system:id | |
serialNumber | string | |
yearlyCost | number | what keeping it costs a year |
yearlyCostCurrency | string | default: the company's |
outsideId | string | The other system's id for it, system:id; it is then made once |
{
"params": {
"name": "Chilled water pump 3",
"classKey": "pump",
"locationId": "9e8d7c6b-0000-4000-8000-000000000014",
"manufacturer": "Northside Pumps",
"model": "NB 65-200",
"serialNumber": "SN-77811"
}
}POST/api/ops/actions/asset.moveMove asset
Move an asset to another location or inside another asset; its history keeps where it was and why (moved, removed, returned, swapped under warranty). To put a spare in an asset's place, asset.replace.
| Tên | Kiểu | Nó là gì |
|---|---|---|
expectedVersion | integer | |
locationId | id: của chúng tôi hoặc system:id | |
note | string | |
parentAssetId | id: của chúng tôi hoặc system:id | |
reason | string | MOVED | REMOVED | RETURNED | WARRANTY_SWAP (why, for its history)Một trong: MOVED, REMOVED, RETURNED, WARRANTY_SWAP |
{
"target": "erp:EQ-1042",
"params": {
"locationId": "erp:WORKSHOP",
"reason": "REMOVED",
"note": "Sent for repair"
}
}POST/api/ops/actions/asset.updateEdit asset
Change what an asset's record says: name, code, kind, make, model, serial number, dates, fields, group. Not where it is (asset.move) nor who looks after it (asset.set_care).
| Tên | Kiểu | Nó là gì |
|---|---|---|
attrs | object | |
builtOn | string (date) | |
classKey | string | |
code | string | |
defaultWorkKindKey | string | |
expectedVersion | integer | |
groupId | id: của chúng tôi hoặc system:id | its asset group (V317); null: none |
installedOn | string (date) | |
investedOn | string (date) | |
manufacturer | string | |
model | string | |
name | string | |
ownerEntityId | id: của chúng tôi hoặc system:id | a legal entity in the company's group; null: its place's |
serialNumber | string | |
yearlyCost | number | |
yearlyCostCurrency | string |
{
"target": "erp:EQ-1042",
"params": {
"serialNumber": "SN-77810-B"
}
}POST/api/ops/actions/reading.recordRecord a reading of an asset
Record one reading on an asset with no work order (a meter, a counter, a gauge, a measurement): what was read, its value and unit, when. Maintenance by meter and condition rules count it. For many at once, reading.record_batch; on a work order, record its reading task instead (task.record).
| Tên | Kiểu | Nó là gì |
|---|---|---|
assetId* | id: của chúng tôi hoặc system:id | the asset read (or the target |
title* | string | what was read, such as Running hours (as a reading task names it |
value* | number | |
note | string | |
readAt | string (date-time) | it was read: 2026-10-16T09:30 (UTC unless it says its offset); empty: now |
unit | string | its unit, such as h (empty: none |
{
"params": {
"assetId": "bms:AHU-3",
"title": "Running hours",
"value": 18234,
"unit": "h",
"readAt": "2026-11-03T06:00Z"
}
}POST/api/ops/readings/batchSend readings
Record up to 1,000 readings at once. Each is matched to exactly one asset by our id, its number, its code, its serial or system:id; a reading that matches none, or more than one, is refused alone with why, and the rest are kept. readAt is required and never in the future; a unit must match the readings before it. A key made for readings only opens this and nothing else.
| Tên | Kiểu | Nó là gì |
|---|---|---|
readings* | array | |
dryRun | boolean |
{
"readings": [
{
"asset": "AST-00128",
"title": "Energy",
"value": 50213.4,
"unit": "kWh",
"readAt": "2026-11-03T06:00Z"
},
{
"asset": "bms:AHU-3",
"title": "Running hours",
"value": 18240,
"unit": "h",
"readAt": "2026-11-03T06:00Z"
}
]
}Live data from sites
POST/api/ops/live/ingestSend a site's live readings
Up to 5,000 readings a call, 4 MB at most, with a key of purpose LIVE (made on the source's page in Settings > Live data sources), which opens this and nothing else. A reading of a tag at a time already kept is kept once, so a buffer may be sent again after an outage; no Idempotency-Key. Also accepted: a bare array of readings, Telegraf's JSON ({"metrics": [...]}, each field the tag <device>.<field>) and CSV (text/csv, lines of tag,at,value[,quality], a header line allowed).
| Tên | Kiểu | Nó là gì |
|---|---|---|
readings* | array |
{
"readings": [
{
"tag": "INV-03.Temp_Bearing",
"at": "2026-10-23T14:02:00Z",
"value": 71.5
},
{
"tag": "INV-03.Power",
"at": "2026-10-23T14:02:00Z",
"value": 412,
"quality": "good"
}
]
}Locations
POST/api/ops/actions/location.createCreate location
Add a location (a building, a floor, a room, an area, a site) inside another, with its kind, code and fields; optionally its pin or outline on the map. Coming from another system, send outsideId with that system's id so a repeat makes nothing twice.
| Tên | Kiểu | Nó là gì |
|---|---|---|
name* | string | |
attrs | object | |
classKey | string | |
clientCode | string | |
code | string | |
entityId | id: của chúng tôi hoặc system:id | a legal entity in the company's group; null: its place's, or the one above |
outline | object | GeoJSON polygon |
parentId | id: của chúng tôi hoặc system:id | The location it is inside (or system:id); a project's own location at the top |
point | array | [longitude, latitude] |
projectId | id: của chúng tôi hoặc system:id | |
outsideId | string | The other system's id for it, system:id; it is then made once |
{
"params": {
"name": "Plant room 2",
"code": "PR-2",
"parentId": "erp:BLOCK-B",
"outsideId": "erp:LOC-2201"
}
}POST/api/ops/actions/location.updateUpdate location
Change what a location's record says: name, code, kind, fields. A project's own location is renamed with the project. Its client is set by location.set_client; a project's stage and settings by workspace.configure.
| Tên | Kiểu | Nó là gì |
|---|---|---|
attrs | object | |
classKey | string | |
code | string | |
costCentreId | id: của chúng tôi hoặc system:id | |
entityId | id: của chúng tôi hoặc system:id | a legal entity in the company's group; null: its place's, or the one above |
name | string | |
status | string |
{
"target": "erp:LOC-2201",
"params": {
"code": "B-PR-2"
}
}Parts, suppliers and stock
POST/api/ops/actions/part.saveSave a part
Add a spare part or a service to the catalogue, or change one (the target): code, name, unit, usual price, default supplier, whether it is tracked one by one by serial number. Codes are unique. Use it before parts are stocked, reserved or bought.
| Tên | Kiểu | Nó là gì |
|---|---|---|
code* | string | |
name* | string | |
active | boolean | |
defaultPrice | number | |
defaultVendorId | id: của chúng tôi hoặc system:id | |
description | string | |
kind | string | PART (kept in stores) | SERVICE (bought or charged, never stocked)Một trong: PART, SERVICE |
priceCurrency | string | |
tracked | boolean | tracked one by one, each with its serial number (repaired and used again |
unit | string | |
outsideId | string | Another system's id for what this makes, written system:id; sent again, it answers with the record made before |
{
"params": {
"code": "FLT-600",
"name": "Bag filter 600x600",
"unit": "each",
"defaultPrice": 32.5,
"priceCurrency": "EUR"
}
}POST/api/ops/actions/purchase_order.receiveReceive what came of a purchase order
Receive what came on an issued purchase order (the target): some lines, everything, or what was wrong with it (damaged, wrong item, short, refused). Parts go into stock at the order's price; anything else for a work order becomes its cost. Whoever issued the order is told of problems.
| Tên | Kiểu | Nó là gì |
|---|---|---|
all | boolean | |
lines | array | of {lineId, quantity, serials: for a part tracked one by one, each one's serial number} |
note | string | |
problems | array | of {lineId, kind: DAMAGED, WRONG_ITEM, SHORT, REFUSED or OTHER, quantity, note} |
receivedOn | string (date) | |
storeId | id: của chúng tôi hoặc system:id |
{
"target": "erp:PO-7781",
"params": {
"all": true,
"receivedOn": "2026-11-03"
}
}POST/api/ops/actions/stock.receiveReceive parts into a storeroom
Receive parts into a store (by id or code), at a cost, without a purchase order (for an order, purchase_order.receive). The average cost follows. A part tracked one by one names each serial received.
| Tên | Kiểu | Nó là gì |
|---|---|---|
quantity* | number | |
currency | string | |
note | string | |
partCode | string | |
partId | id: của chúng tôi hoặc system:id | |
rate | number | |
serials | array | a part tracked one by one, the serial number of each one received |
spotCode | string | |
spotId | id: của chúng tôi hoặc system:id | |
storeCode | string | |
storeId | id: của chúng tôi hoặc system:id | |
unitCost | number | |
vendorId | id: của chúng tôi hoặc system:id |
{
"params": {
"storeCode": "MAIN",
"partCode": "FLT-600",
"quantity": 10,
"unitCost": 31.8,
"currency": "EUR"
}
}POST/api/ops/actions/vendor.saveSave a vendor
Add a supplier, or change one (the target): names, contacts, currency, payment terms, tax number, bank details.
| Tên | Kiểu | Nó là gì |
|---|---|---|
name* | string | |
active | boolean | |
address | string | |
bankAccountName | string | whose account it is |
bankAccountNumber | string | |
bankBranch | string | |
bankName | string | |
code | string | |
contactEmail | string | |
contactName | string | |
contactPhone | string | |
currency | string | |
legalName | string | as on its invoices |
localName | string | the legal name in the local language |
paymentTermsDays | integer | |
swiftCode | string | 8 or 11 letters and digits |
taxNumber | string | |
outsideId | string | Another system's id for what this makes, written system:id; sent again, it answers with the record made before |
{
"params": {
"name": "Northside Filters",
"code": "NSF",
"currency": "EUR",
"paymentTermsDays": 30
}
}Events
GET/api/ops/eventsEvents, oldest first
What happened, oldest first, only about records the connection may read. Keep `next` and send it as `after` next time; while `more` is true, ask again at once. Events are kept 30 days.
| Tên | Kiểu | Nó là gì |
|---|---|---|
after | integer (int64) | The seq of the last event read; 0 for the first |
types | string | Kinds to keep, comma-separated (request.raised,work_order.transitioned); all when left out |
limit | integer | query |
Reads
GET/api/ops/registryKinds, fields and flows
The company's kinds of location, asset, request and work order (their keys are classKey), their fields (attrs) and the steps of each flow (the keys a move goes to). Reads are under the connection's own rights: what its roles may see.
GET/api/ops/requests/{id}One request
A request with its step and `next`: the steps it may move to now. Reads are under the connection's own rights: what its roles may see.
| Tên | Kiểu | Nó là gì |
|---|---|---|
id* | string (uuid) | path |
GET/api/ops/work-orders/{id}One work order
A work order with its step, tasks and `next`. Reads are under the connection's own rights: what its roles may see.
| Tên | Kiểu | Nó là gì |
|---|---|---|
id* | string (uuid) | path |
GET/api/ops/assets/{id}One asset
An asset with its location and fields. Reads are under the connection's own rights: what its roles may see.
| Tên | Kiểu | Nó là gì |
|---|---|---|
id* | string (uuid) | path |
GET/api/ops/test-companyWhether this is a test company
testOf: the company this is a test of (id and name); null in a real company. Reads are under the connection's own rights: what its roles may see.
Sự kiện gửi đến các địa chỉ của nó (webhook)
request.raisedrequest.transitionedrequest.assignedrequest.updatedrequest.mergedwork_order.createdwork_order.transitionedwork_order.assignedwork_order.scheduledwork_order.updatedasset.createdasset.updatedasset.movedasset.disposedreading.recordedlocation.createdlocation.updatedreading.batch_recordedstock.receivedstock.movedpurchase_order.issuedpurchase_order.receivedapproval.requestedapproval.approvedapproval.refusedimport.doneconnector.ping