Apply a scan event

Módulo Assets

POST/asset-units/scansassetUnits.applyScan

Applies one scanned custody move in one transaction (app.apply_asset_scan): resolves the code to a unit or lot, writes the custody entry or lot movement under the device's event id, and moves the unit's state. Replaying an event id returns `duplicate` and changes nothing. A unit someone else moved meanwhile is refused (422, asset_scan_state_conflict); a code no item carries is refused with NO_ANSWER. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.

Requiere la capacidad assets.custody.write.
Alcances de OAuth: assets.
Envía el encabezado Idempotency-Key. Una repetición con la misma clave devuelve la respuesta original.
Estados de error: 400, 401, 409, 422, 429. Los errores son detalles de problema RFC 9457.

Cuerpo de la solicitud: AssetScanEvent

assetUnits.applyScan: AssetScanEvent
Campo	Tipo	Obligatorio	Descripción
event_id	string (uuid)	Sí	UUID the device minted when the scan happened and keeps in its offline queue. It becomes the custody entry or lot movement id, so replaying the event at any later time changes nothing.
code	string	Sí	The scanned asset tag, external identifier (serial, GTIN) or lot label (LOT:<lot id>).Restricciones: length 1 to 200
action	"check-out" \| "check-in" \| "transfer"	Sí	check-out hands the item to one custodian (the unit becomes Deployed); check-in returns it to a venue (the unit becomes Available); transfer passes a deployed unit to another custodian.
custodian_membership_id	string (uuid) \| null	No	Identifier of the member who takes the item.
custodian_engagement_id	string (uuid) \| null	No	Identifier of the external engagement that takes the item; never together with a member.
venue_id	string (uuid) \| null	No	Identifier of the venue the item returns to; the unit's home venue by default.
project_id	string (uuid) \| null	No	Identifier of the project the item is out for.
note	string \| null	No	Hand-over note.Restricciones: length 0 to 1000
quantity	number \| null	No	Lots only: how many move.

{
  "event_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e70",
  "code": "NWL-RAD-014",
  "action": "check-out",
  "custodian_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "custodian_engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "note": "Stage left radio.",
  "quantity": 12
}

Respuesta 200: AssetScanResult

assetUnits.applyScan: AssetScanResult
Campo	Tipo	Obligatorio	Descripción
outcome	"applied" \| "duplicate"	Sí	applied for a new event; duplicate when the event id was already applied.
subject_kind	"unit" \| "lot"	Sí	What the code named.
subject_id	string (uuid)	Sí	The asset unit or lot moved.
ledger_id	string (uuid)	Sí	The custody entry or lot movement, equal to the event id.
asset_state	"Proposed" \| "Received" \| "Available" \| "Reserved" \| "Deployed" \| "In Maintenance" \| "Damaged" \| "Lost" \| "Retired" \| null	Sí	Units: the state after the move.
on_hand	number \| null	Sí	Lots: the quantity on hand after the move.

{
  "outcome": "applied",
  "subject_kind": "unit",
  "subject_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "ledger_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "asset_state": "Available",
  "on_hand": 72
}

Ejemplos de código

curl -X POST "$XOS_BASE_URL/asset-units/scans" \
  -H "Authorization: Bearer $XOS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e70","code":"NWL-RAD-014","action":"check-out","custodian_membership_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","custodian_engagement_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","venue_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","project_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","note":"Stage left radio.","quantity":12}'

const { data } = await xos.assetUnits.applyScan({
    "event_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e70",
    "code": "NWL-RAD-014",
    "action": "check-out",
    "custodian_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
    "custodian_engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
    "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
    "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
    "note": "Stage left radio.",
    "quantity": 12
  });

response = xos.asset_units.apply_scan({"event_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e70", "code": "NWL-RAD-014", "action": "check-out", "custodian_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "custodian_engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "note": "Stage left radio.", "quantity": 12})

xos asset-units apply-scan --data '{"event_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e70","code":"NWL-RAD-014","action":"check-out","custodian_membership_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","custodian_engagement_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","venue_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","project_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","note":"Stage left radio.","quantity":12}'