Chuyển tới nội dung
Orbitify
Lập trình viên

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.

Địa chỉ để gọi

https://dashboard.orbitify.ai/apiTải mô tả API

Bắt đầu

  1. 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.
  2. 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.
  3. 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.
  4. 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

Mới

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.

Trong gói có Hệ thống kết nốiLiên kết
Mới

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.

Trong gói có Hệ thống kết nốiLiên kết
Mới

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.

Trong gói có Hệ thống kết nốiLiên kết
Mọi thay đổi của Orbitify

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ênKiểuNó là gì
expectedVersioninteger
teamIdid: 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ênKiểuNó là gì
classKey*stringThe kind of request, a key from GET /api/ops/registry (classes of kind request), never a work order's kind such as corrective
summary*stringIts title: what is wrong or needed, in one short line
assetIdid: của chúng tôi hoặc system:idThe asset it is about (or system:id); its location is taken when locationId is left out
attrsobjectValues for the kind's own fields, by field key (GET /api/ops/registry)
detailsstringIts description: what was seen, since when, anything that helps the team; optional
detectionMethodstringHow it was found, such as an alarm or an inspection
entityIdid: của chúng tôi hoặc system:ida legal entity in the company's group; null: its place's, or the one above
findingIdsarray
impactstringONE (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)
incidentTypeIdid: của chúng tôi hoặc system:id
internalboolean
locationIdid: của chúng tôi hoặc system:idWhere: 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)
photosarrayof {url, name, contentType, sizeBytes}: photos, videos or PDFs of the fault, uploaded first (POST /api/ops/uploads
punchListIdid: của chúng tôi hoặc system:ida punch list it is an item of: its place, team and kind unless given here
reportedByIdid: của chúng tôi hoặc system:idwho reported it, when someone raises it for them: a person who called or wrote; needs the right to raise requests for someone else
reportedViastringAPP | PHONE | CHAT | EMAIL | ON_SITE (how it came in; APP when left out)Một trong: APP, PHONE, CHAT, EMAIL, ON_SITE
severitystringHow bad it is; the company's own words for each are in GET /api/ops/settingsMột trong: MINOR, MODERATE, MAJOR, CRITICAL
teamIdid: của chúng tôi hoặc system:idA team to give it to; left out, the company's routing rules choose
outsideIdstringThe 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ênKiểuNó là gì
to*stringThe key of the step to move to, one of the request's next steps
attrsobject
expectedVersioninteger
notestringWhy, 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ênKiểuNó là gì
assetIdid: của chúng tôi hoặc system:idnull takes the asset off
attrsobjectfields to change; null removes one
classKeystring
detailsstringits description; empty takes it off
entityIdid: của chúng tôi hoặc system:ida legal entity in the company's group; null: its place's, or the one above
expectedVersionintegerThe version you read; the change is refused when someone changed it since
impactstringONE | SEVERAL | SITEMột trong: ONE, SEVERAL, SITE
locationIdid: của chúng tôi hoặc system:id
severitystringMINOR | MODERATE | MAJOR | CRITICAL (its urgency, with the company's grid)Một trong: MINOR, MODERATE, MAJOR, CRITICAL
summarystringits 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ênKiểuNó là gì
amount*number
description*string
kind*stringPART | PURCHASE | SUBCONTRACT | TRAVEL | OTHERMột trong: PART, PURCHASE, SUBCONTRACT, TRAVEL, OTHER
currencystringIts currency (ISO 4217); the company's when left out
incurredOnstring (date)
ratenumberIts rate to the company's currency; the latest kept when left out
vendorIdid: 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ênKiểuNó là gì
bodystring
filesarrayof {url, name, contentType, sizeBytes}: photos, videos or PDFs uploaded first
objectKindstringrequest | work_order (request when left out)Một trong: request, work_order
sharedbooleanseen 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ênKiểuNó là gì
personId*id: của chúng tôi hoặc system:id
time*stringHow long: 1h30, 90m, 1.5h or 0:45
notestring
workedOnstring (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ênKiểuNó là gì
assigneeIdid: của chúng tôi hoặc system:id
crewIdsarrayeveryone else on the work order besides its person: the whole list; [] for nobody
deadlinestring (date)
expectedVersioninteger
notestringa few words more on the reason
reasonstringwhen 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
suggestedIdid: của chúng tôi hoặc system:idwho "Who could do it" put first, when the screen showed it
teamIdid: 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ênKiểuNó là gì
title*stringWhat is to be done, in one line
assetIdid: của chúng tôi hoặc system:id
assetIdsarraythe assets it is about, in order: a round of several
assigneeIdid: của chúng tôi hoặc system:id
attrsobject
checklistIdid: của chúng tôi hoặc system:ida checklist whose tasks it also gets, after its kind's (V331
classKeystringThe kind of work, a key from GET /api/ops/registry (classes of kind work_order)
deadlinestring (date)When it is due: a day (2026-11-03) or a time
descriptionstring
entityIdid: của chúng tôi hoặc system:ida legal entity in the company's group; null: its place's, or the one above
estimatedHoursnumberthe hours the work should take (V317
locationIdid: của chúng tôi hoặc system:id
movebooleanTake requests already on another open work order off it; left out, people in the app are refused and a connected system moves it
parentIdid: của chúng tôi hoặc system:id
prioritystringLeft out with requests: their worst severity sets it, as the company's settings map themMột trong: ROUTINE, PLANNED, URGENT, EMERGENCY
projectIdid: của chúng tôi hoặc system:id
requestIdsarrayRequests it answers (ids or system:id); they follow it and close when it is done
tasksarrayTasks to add after its kind's: each {title, kind: CHECK|READING|TEXT|CHOICE|PHOTO, required, unit}
teamIdid: của chúng tôi hoặc system:id
outsideIdstringThe 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ênKiểuNó là gì
tasks*arrayof {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ênKiểuNó là gì
assigneeIdid: của chúng tôi hoặc system:idgive it to this person (leave out to keep its person
hoursstringhow long it takes, in hours (empty: not said)
startstringwhen 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
timeZonestringthe 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ênKiểuNó là gì
to*string
attrsobject
expectedVersioninteger
whatWasDonestringwhat 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ênKiểuNó là gì
attrsobjectfields to change; null removes one
classKeystring
deadlinestring (date)YYYY-MM-DD) or time; null takes it off
descriptionstring
entityIdid: của chúng tôi hoặc system:ida legal entity in the company's group; null: its place's, or the one above
estimatedHoursnumberthe hours the work should take; null takes it off (V317
expectedVersionintegerThe version you read; the change is refused when someone changed it since
locationIdid: của chúng tôi hoặc system:id
prioritystringROUTINE | PLANNED | URGENT | EMERGENCYMột trong: ROUTINE, PLANNED, URGENT, EMERGENCY
titlestring
{
  "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ênKiểuNó là gì
doneboolean
notestring
photosarray
readAtstring (date-time)a reading was taken: 2026-10-16T09:30 (UTC unless it says its offset); empty: now
removePhotoIdsarray
valuenumber | 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ênKiểuNó là gì
name*string
attrsobject
builtOnstring (date)when it was built
classKeystringThe kind of asset, a key from GET /api/ops/registry (classes of kind asset)
codestring
defaultWorkKindKeystringthe kind of work a work order about it is when nobody says
groupIdid: của chúng tôi hoặc system:idits asset group (V317
installedOnstring (date)
investedOnstring (date)when it was paid for
locationIdid: của chúng tôi hoặc system:id
manufacturerstring
modelstring
ownerEntityIdid: của chúng tôi hoặc system:ida legal entity in the company's group; null: its place's
parentAssetIdid: của chúng tôi hoặc system:id
projectIdid: của chúng tôi hoặc system:id
serialNumberstring
yearlyCostnumberwhat keeping it costs a year
yearlyCostCurrencystringdefault: the company's
outsideIdstringThe 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ênKiểuNó là gì
expectedVersioninteger
locationIdid: của chúng tôi hoặc system:id
notestring
parentAssetIdid: của chúng tôi hoặc system:id
reasonstringMOVED | 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ênKiểuNó là gì
attrsobject
builtOnstring (date)
classKeystring
codestring
defaultWorkKindKeystring
expectedVersioninteger
groupIdid: của chúng tôi hoặc system:idits asset group (V317); null: none
installedOnstring (date)
investedOnstring (date)
manufacturerstring
modelstring
namestring
ownerEntityIdid: của chúng tôi hoặc system:ida legal entity in the company's group; null: its place's
serialNumberstring
yearlyCostnumber
yearlyCostCurrencystring
{
  "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ênKiểuNó là gì
assetId*id: của chúng tôi hoặc system:idthe asset read (or the target
title*stringwhat was read, such as Running hours (as a reading task names it
value*number
notestring
readAtstring (date-time)it was read: 2026-10-16T09:30 (UTC unless it says its offset); empty: now
unitstringits 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ênKiểuNó là gì
readings*array
dryRunboolean
{
  "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ênKiểuNó 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ênKiểuNó là gì
name*string
attrsobject
classKeystring
clientCodestring
codestring
entityIdid: của chúng tôi hoặc system:ida legal entity in the company's group; null: its place's, or the one above
outlineobjectGeoJSON polygon
parentIdid: của chúng tôi hoặc system:idThe location it is inside (or system:id); a project's own location at the top
pointarray[longitude, latitude]
projectIdid: của chúng tôi hoặc system:id
outsideIdstringThe 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ênKiểuNó là gì
attrsobject
classKeystring
codestring
costCentreIdid: của chúng tôi hoặc system:id
entityIdid: của chúng tôi hoặc system:ida legal entity in the company's group; null: its place's, or the one above
namestring
statusstring
{
  "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ênKiểuNó là gì
code*string
name*string
activeboolean
defaultPricenumber
defaultVendorIdid: của chúng tôi hoặc system:id
descriptionstring
kindstringPART (kept in stores) | SERVICE (bought or charged, never stocked)Một trong: PART, SERVICE
priceCurrencystring
trackedbooleantracked one by one, each with its serial number (repaired and used again
unitstring
outsideIdstringAnother 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ênKiểuNó là gì
allboolean
linesarrayof {lineId, quantity, serials: for a part tracked one by one, each one's serial number}
notestring
problemsarrayof {lineId, kind: DAMAGED, WRONG_ITEM, SHORT, REFUSED or OTHER, quantity, note}
receivedOnstring (date)
storeIdid: 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ênKiểuNó là gì
quantity*number
currencystring
notestring
partCodestring
partIdid: của chúng tôi hoặc system:id
ratenumber
serialsarraya part tracked one by one, the serial number of each one received
spotCodestring
spotIdid: của chúng tôi hoặc system:id
storeCodestring
storeIdid: của chúng tôi hoặc system:id
unitCostnumber
vendorIdid: 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ênKiểuNó là gì
name*string
activeboolean
addressstring
bankAccountNamestringwhose account it is
bankAccountNumberstring
bankBranchstring
bankNamestring
codestring
contactEmailstring
contactNamestring
contactPhonestring
currencystring
legalNamestringas on its invoices
localNamestringthe legal name in the local language
paymentTermsDaysinteger
swiftCodestring8 or 11 letters and digits
taxNumberstring
outsideIdstringAnother 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ênKiểuNó là gì
afterinteger (int64)The seq of the last event read; 0 for the first
typesstringKinds to keep, comma-separated (request.raised,work_order.transitioned); all when left out
limitintegerquery

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ênKiểuNó 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ênKiểuNó 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ênKiểuNó 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.raised
  • request.transitioned
  • request.assigned
  • request.updated
  • request.merged
  • work_order.created
  • work_order.transitioned
  • work_order.assigned
  • work_order.scheduled
  • work_order.updated
  • asset.created
  • asset.updated
  • asset.moved
  • asset.disposed
  • reading.recorded
  • location.created
  • location.updated
  • reading.batch_recorded
  • stock.received
  • stock.moved
  • purchase_order.issued
  • purchase_order.received
  • approval.requested
  • approval.approved
  • approval.refused
  • import.done
  • connector.ping