跳到內容

送出機械人維修(beta)

Beta
POST
/v1/robots/maintenance
curl --request POST \
--url https://api.example.yas/v1/robots/maintenance \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "partnerId": "partner", "schemaVersion": "2026-11", "sourceSystem": "partner-export", "robotId": "rbt_example", "maintenanceId": "mnt_1001", "timezone": "Asia/Hong_Kong", "component": "drive", "downtimeStart": "2026-10-15T12:00:00.000Z" }'

Beta。用 server key 建立或取代一筆維修紀錄。請送 partnerId、schemaVersion、sourceSystem、robotId、maintenanceId 與 timezone。這台機械人必須已存在於這個 partnerId。未知的 robotId 是 404。之後用同一個 partnerId、robotId 與 maintenanceId 再送,會蓋掉舊內容。選填欄位不送就會清掉。updatedAt 是 ISO-8601 UTC。

Request Bodyrequired

小節:Request Bodyrequired
Media typeapplication/json
object
partnerId
required

合作夥伴 id。必須與 server key 相符。

string
schemaVersion
required

這次內容的 schema 版本。例子:2026-11。

string
sourceSystem
required

送出這次內容的系統名稱。例子:partner-export。

string
robotId
required

機械人 id。這台機械人必須已經存在。

string
maintenanceId
required

這次維修的 id。同一合作夥伴、機械人與維修 id 再送,會蓋掉舊內容。

string
timezone
required

IANA 時區。例子:Asia/Hong_Kong。

string
taskInstanceId

這次維修相關的任務實例。沒有就可以不送。

string
eventId

這次維修相關的事件 id。沒有就可以不送。

string
complaint

報稱的問題。

string
diagnosis

查出的原因。

string
component

維修的部件。例子:drive。

string
partReplacement

更換的零件。

string
correctiveAction

做了什麼。

string
downtimeStart

停機開始的時間,ISO-8601。

string format: date-time
downtimeEnd

停機結束的時間,ISO-8601。

string format: date-time
labourHours

這次維修的工時。

number
cost

費用金額。請同時送 currency。

number
currency

貨幣代碼。例子:HKD。

string
recurrence

這個故障以前出現過時為 true。

boolean
warranty

這次維修在保養期內時為 true。

boolean
firmwareVersion

送出時的韌體版本。

string
metadata

合作夥伴的額外欄位。照送出的內容保存。

object
key
additional properties
any

Example

{
"partnerId": "partner",
"schemaVersion": "2026-11",
"sourceSystem": "partner-export",
"robotId": "rbt_example",
"maintenanceId": "mnt_1001",
"timezone": "Asia/Hong_Kong",
"component": "drive",
"downtimeStart": "2026-10-15T12:00:00.000Z"
}

維修已保存。之後用同一個維修 id 再送,會蓋掉它。updatedAt 是 ISO-8601 UTC。

Media typeapplication/json
object
robotId
required
string
maintenanceId
required
string
updatedAt
required
string format: date-time

Example

{
"robotId": "rbt_example",
"maintenanceId": "mnt_1001",
"updatedAt": "2026-10-15T13:00:00.000Z"
}
400缺少必填欄位。
Media typeapplication/json
object
error
required

穩定的錯誤代碼。沒有 stack trace。

string

Example

{
"error": "invalid_body"
}
401沒有 server key,或 server key 不正確。
Media typeapplication/json
object
error
required

穩定的錯誤代碼。沒有 stack trace。

string

Example

{
"error": "invalid_credentials"
}
403server key 可以只限車輛、只限機械人,或兩者都可以。超出範圍的呼叫是 403 `forbidden`,而且不會保存。`identity_mismatch` 表示 `partnerId` 與 server key 不符。
Media typeapplication/json
object
error
required

穩定的錯誤代碼。沒有 stack trace。

string

Example

{
"error": "forbidden"
}
404未知的 `robotId`。這次什麼都不會存。
Media typeapplication/json
object
error
required

穩定的錯誤代碼。沒有 stack trace。

string

Example

{
"error": "not_found"
}