Use the reviewed proof of delivery audit contract
Proof of delivery is not one field or button. It combines an authorized final order transition, actual customer handoff, optional image, location validation, optional client PIN field, result parsing, and partial follow-ons.
The current contract is source-api-only. Secure-PIN and trusted-location
claims are blocked until server fixes and negative tests are accepted.
Availability
The final delivery action can appear in eligible customer-phase order states. Project configuration can require a status image or client PIN and can apply location rules. When neither media nor PIN opens a modal, the first action can submit directly and bypass the App's modal location checklist.
Control/modal visibility is not authorization, handoff proof, location proof, or server acceptance.
Prerequisites
- Confirm authenticated Driver ownership and the current order revision.
- Confirm the real customer handoff through organizational policy.
- Treat image, location and PIN as independent candidate inputs.
- Require server-side generation/validation for any security secret.
- Use typed server error/result codes, not localized text parsing.
- Define cleanup and partial-effect receipts for media, location, order and provider follow-ons.
Responsibility boundaries
| Owner | Responsibility |
|---|---|
| Driver App UI | Present requirements, capture candidate inputs, loading and explicit result state |
| Order API | Authorize Driver/order/transition and validate required inputs |
| PIN service | Generate one-time secret server-side, bind to order/session, validate once, expire and audit |
| Location service | Validate finite coordinates, source, freshness, mock policy, target and timestamp |
| Media service | Authorize before upload, validate type/content, store purpose-minimally and clean partials |
| Result parser | Consume typed machine result and preserve unresolved/partial states |
| Follow-on services | History, messages, reports, trails, queue, sockets, notifications, jobs/plugins |
| Dispatcher/security | Reconcile exceptions and review failed/partial proof |
Inputs and result
Candidate inputs may include final transition intent, order revision, image, location, and PIN. None is proof before server authorization and validation.
The accepted result contract must distinguish core order write, media write, location/trail write, PIN validation, and every follow-on. It must return an idempotent result receipt for the current order revision and explicit partial or cleanup state.
Current client result handling includes success, generic error, conditional force form, thrown/non-JSON, deferred and partial branches. Some force routing depends on matching error text fragments; case, localization, punctuation, array/object shape, substring, empty or unrelated values can misclassify.
Security and privacy
- Never derive a secure PIN solely in the client or compare it only locally.
- Never accept a client coordinate as fresh/trusted merely because it was sent with the request.
- Authorize before image upload/location write/order mutation.
- Bind proof to one order, Driver, customer handoff, session, purpose and time.
- Do not expose PINs, derivation, parser strings, order IDs, coordinates, media, tokens, provider payloads or security test cases publicly.
- Generic chat media is not proof of delivery.
Limits and failure states
| State | Required interpretation |
|---|---|
| Final button visible | Client candidate only |
| PIN field complete | Local prerequisite, not server proof |
| Image preview | Local media candidate |
| Location check passes | Local candidate, not server trust |
| Request loading | Unresolved; no retry |
| Force form | Parser-selected recovery candidate, not server guarantee |
| Returned order | Core response only |
| Order disappears/completes | Client view, not complete proof receipt |
| Partial media/trail/provider | Requires explicit reconciliation |
No secure PIN, trusted presence, atomic proof package, rollback, exactly-once completion, safe retry, or deployed success is established.
Troubleshooting
PIN appears valid locally
Do not call it secure proof. Require server-generated, order-bound, expiring, one-time validation and audit.
Image or location succeeds before the order fails
Treat each as a separate effect. Run cleanup/reconciliation; do not assume the order rollback removed media or trail data.
A force form appears unexpectedly
Do not continue from text alone. Require a typed error contract and verify the current order revision with the dispatcher.
The order looks completed but proof is uncertain
Do not repeat. Reconcile core order, image, location, PIN, history, queue and provider receipts independently.
Chat contains a photo or signature
Do not use it as delivery proof. Chat media has separate authorization/storage and recipient contracts.
Related guides: Complete a delivery · Use the order mutation contract · Use the reviewed maps contract · Run governed evidence safely