Location Operator
Read the consignment, download its documents, and send your match back to TWIN.
TWIN notifies you when a consignment books a carrier at one of the ports you manage. Using the globalId that notification carries, fetch-consignment.sh reads the consignment and downloads its documents, and send-match.sh confirms back that it matches your records.
This assumes you've already followed Get the scripts — you have a terminal open in the unzipped folder and config.env already has your credentials.
(Optional) Save the consignment's globalId
Every command below can take the globalId as an argument, but if you'd rather not retype it each time, add it to the same config.env you already filled in (Get the scripts) — every script reads it from there:
open -e config.envnano config.envSave and exit: Ctrl+O, Enter, Ctrl+X.
notepad config.envSANDBOX_CONSIGNMENT_GLOBAL_ID=<globalId of the published consignment>Read the consignment and its documents
Still in the same terminal, same folder — if you saved the globalId in the previous step:
bash fetch-consignment.shOr pass the globalId directly as an argument:
bash fetch-consignment.sh <globalId>The script retrieves the full consignment and downloads every attached document — the real files, not just metadata — into downloads/<globalId>/:
Reading as: did:iota:0x...
Consignment: <globalId>
✓ Consignment → downloads/<globalId>/consignment.json
✓ INV-1234 (Commercial Invoice, rev 0) → downloads/<globalId>/INV-1234-rev0.pdf
✓ PL-9 (Packing List, rev 0) → downloads/<globalId>/PL-9-rev0.pdf
Done — 2 document(s) downloaded to downloads/<globalId>/Getting consignmentNotFound instead? It usually does not mean the consignment is missing. A consignment is only readable by you once the organisation that published it has shared it with yours, and that sharing is set up in the TWIN web app — no script here can grant it.
Two things have to be true: the publishing organisation shares its consignments with Location Operators, and one of the ports on the route is a location your organisation manages. If you are publishing from a test freight forwarder account of your own, both are yours to set.
You can still send your match in the meantime — see the next step.
Send the match back
bash location-operator/send-match.shOr, if you didn't save the globalId in config.env, pass it directly:
bash location-operator/send-match.sh <globalId>On success:
Sending as: did:iota:0x...
Consignment: MYREF-001 (<globalId>)
Event: twin:locationOperatorMatch at 2026-07-03T09:00:00Z
✓ twin:locationOperatorMatch sent for consignment <globalId>twin:locationOperatorMatch is the journey event: it joins the consignment's event list and advances its status.
If you could not read the consignment in the previous step, sending the match still works — it is a write, and does not depend on your read access. Pass the consignment's identifier as a second argument; publish-consignment.sh prints it as Consignment: when it runs:
bash location-operator/send-match.sh <globalId> <identifier>Without it the script looks the identifier up by reading the consignment, which is the part that fails.