verifyCourierScan(envelope_id, courier_id)

Purpose

Logs the physical scan event when a courier picks up a high-value ticket envelope.
This confirms custody transfer and updates fulfillment status to in_transit.

---

Endpoint

POST /api/verify-scan

---

Authorization

• Required Scope: courier.verify
• Token: Bearer token (Courier-issued or Ops override)

---

Parameters

Name	Type	Required	Description
envelope_id	string	✅	Unique identifier of the ticket envelope
courier_id	string	✅	ID of the courier performing the scan

---

Request Example

{
  "courier_id": "courier_001",
  "gps_lat": 40.7128,
  "gps_lng": -74.0060,
  "scan_type": "pickup"
}

---

Response: Success (200 OK)

{
  "envelope_id": "env-22a94",
  "courier_id": "c9f887d3",
  "scan_timestamp": "2025-06-25T14:05:21Z",
  "geo_lat": 40.7128,
  "geo_long": -74.006,
  "status": "in_transit"
}

---

Error States

HTTP Code	Error Key	Description
404	envelope_not_found	The envelope ID is not registered
401	courier_unauthorized	Courier credentials are invalid
409	already_scanned	The envelope has already been scanned

---

Integration Notes

• This method is typically triggered by the Courier App.
• Geo-coordinates are optional but strongly recommended for audit compliance.
• The response should be logged to the fulfillment tracking ledger.
• Pairs with confirmEnvelopeDelivery() to complete the custody chain.