API Keys & Integration

You are working in this website backend. Integrate NavYour delivery creation into the existing checkout/order-confirmation flow.

CRITICAL GOAL:
When ONE NEW customer order is successfully confirmed in this website, create exactly ONE NavYour delivery order from the backend, store the returned tracking details on that same local order, and make retries safe.

DO NOT CREATE BULK SYNC:
- Do not fetch all orders from the database and send them to NavYour.
- Do not send old/historical orders.
- Do not run NavYour sync on server startup.
- Do not run NavYour sync from an order list page, admin dashboard, GET endpoint, seed script, or cron unless explicitly asked later.
- Do not create a general “sync all confirmed orders” job.
- This integration must run only for the single local order that was just created/confirmed.
- If a one-time backfill is ever needed, it must be a separate explicit script with date filters and already-synced checks. Do not implement backfill now.

TEST MODE FIRST:
First use the NavYour Test API key only.
Do not switch to Live until a test order appears in:
NavYour Business Portal -> API Keys -> Test Orders.

NavYour API:
- Base URL env: NAVYOUR_API_BASE_URL
- API key env: NAVYOUR_API_KEY
- Endpoint: POST {NAVYOUR_API_BASE_URL}/integration/orders
- Auth header: Authorization: Bearer {NAVYOUR_API_KEY}
- Idempotency header: Idempotency-Key: use this website's immutable local order id/reference
- Content-Type: application/json

Required env example:
NAVYOUR_API_BASE_URL=https://api.navyour.in/v1
NAVYOUR_API_KEY=sk_test_nv_xxxxx

Security rules:
- Store NAVYOUR_API_KEY only in backend/server environment variables.
- Never expose the key in frontend JavaScript, HTML, mobile app code, logs, analytics, error trackers, GitHub, or API responses.
- Do not call NavYour from the browser.
- Only this website backend may call NavYour.
- Redact Authorization and NAVYOUR_API_KEY from logs.
- Never log full customer sensitive data unnecessarily.

Database changes/checks:
Add or reuse these fields on the local orders table:
- navyourOrderId nullable string
- navyourTrackingCode nullable string
- navyourTrackingUrl nullable string
- navyourDeliveryStatus nullable string
- navyourSyncStatus: not_started | creating | created | failed
- navyourSyncError nullable text
- navyourLastSyncAttemptAt nullable datetime

Duplicate prevention:
- Add a database-level unique guard if using a separate NavYour sync/integration table.
- The same local order must not be able to create multiple NavYour deliveries.
- Before calling NavYour, check:
  - if navyourOrderId exists, return existing NavYour details
  - if navyourTrackingCode exists, return existing NavYour details
  - if navyourSyncStatus is "created", return existing NavYour details
  - if navyourSyncStatus is "creating", do not start a second request; return/throw a safe “sync already in progress” result
- Set navyourSyncStatus = "creating" and navyourLastSyncAttemptAt before making the NavYour API request.
- Use a transaction or row lock if this backend supports it, so parallel requests cannot create duplicate delivery orders.

When to call NavYour:
- Call only after this website has successfully saved and confirmed the local order.
- Never create a NavYour delivery before local order confirmation.
- Never create a NavYour delivery before online payment confirmation if this website requires payment first.
- For COD orders, call after COD order is confirmed.
- For prepaid orders, call only after payment is successful/captured.
- The call must happen for the current local order only.

Never hardcode sample order data:
- Do not use ORDER-1001 in production logic.
- Do not reuse the same orderReference for multiple orders.
- Do not send static customer/product/address data.
- All payload fields must come from the actual current local order.

Payload requirements:
Send a complete JSON payload with:
- orderReference: this website's stable unique local order id/reference
- orderSource: "business_website"
- customer.name
- customer.phone
- customer.email if available
- delivery full address and address fields
- pickup store/business address and contact fields
- package description/items/totalItems/weightKg/fragile/specialInstructions
- payment.paymentType
- payment.orderValuePaise
- payment.deliveryFeePaise
- payment.codAmountPaise
- payment.prepaidAmountPaise
- payment.currency: "INR"
- notes.customerNote and notes.internalNote when available

Money rules:
- deliveryFeePaise is required and must be greater than 0.
- This website decides deliveryFeePaise and sends it to NavYour.
- In Live mode, NavYour deducts deliveryFeePaise from this business's NavYour wallet.
- Customer payment belongs to this business.
- NavYour wallet pays the NavYour delivery fee.
- For COD, codAmountPaise must be the exact cash amount the driver collects from the customer.
- If this website checkout total includes delivery fee, include that delivery fee inside codAmountPaise.
- For prepaid orders, prepaidAmountPaise is the amount already collected by this website.

Idempotency:
- Idempotency-Key must be stable and unique for this local order.
- Recommended: WEBSITE_NAME + "-" + localOrderId
- Use the same Idempotency-Key on every retry for the same local order.
- Use the same orderReference on every retry for the same local order.
- Treat 409 duplicate/order already exists as recoverable only if NavYour returns or can recover the tracking details.

Failure behavior:
- If NavYour fails, do not delete or cancel the customer order.
- Save navyourSyncStatus = "failed".
- Save a safe error message in navyourSyncError.
- Save navyourLastSyncAttemptAt.
- Allow retry only for that specific failed order using the same orderReference and Idempotency-Key.
- Do not retry in an uncontrolled loop.
- Do not retry all old orders automatically.
- Surface a clear internal error for operations, but do not expose API keys or raw sensitive headers.

Expected success response handling:
Parse JSON response and save:
- data.id or data.navyourOrderId -> navyourOrderId
- data.trackingCode -> navyourTrackingCode
- data.trackingUrl -> navyourTrackingUrl
- data.status -> navyourDeliveryStatus
- navyourSyncStatus = "created"
- clear navyourSyncError

Webhook receiver:
- Create POST /api/navyour/webhook in this website backend.
- Store NAVYOUR_WEBHOOK_SECRET only in backend .env.
- Verify NavYour-Signature with raw body before parsing JSON.
- Signature payload is NavYour-Timestamp + "." + rawBody.
- Update the local order using event.order.orderReference or event.order.trackingCode.
- Return HTTP 200 quickly.
- Do heavy work after response if needed.
- Handle at least:
  - driver.assigned
  - order.picked_up
  - order.out_for_delivery
  - order.delivered
  - order.failed
  - order.cancelled
  - cod.collected
  - cod.handed_over
  - cod.settled
- Never create customer orders from webhook payloads.
- Webhook only updates delivery status after API order creation.

Testing steps:
1. Put the NavYour Test API key in backend .env as NAVYOUR_API_KEY.
2. Set NAVYOUR_API_BASE_URL=https://api.navyour.in/v1.
3. Place exactly one new real test checkout/order through this website flow.
4. Confirm backend sends exactly one POST /integration/orders for that one local order.
5. Confirm the request includes Authorization Bearer and Idempotency-Key.
6. Confirm no old orders were sent.
7. Confirm the order appears in NavYour Business Portal -> API Keys -> Test Orders.
8. Confirm NavYour returns a TEST tracking code.
9. Confirm this website order stores trackingCode and trackingUrl.
10. Trigger retry for the same local order and confirm it does not create a second NavYour delivery.
11. Force a NavYour failure and confirm this website marks only that order as failed.
12. Retry only that failed order and confirm it uses the same Idempotency-Key.
13. Configure NavYour webhook URL and signing secret.
14. Send test webhook and verify signature handling.
15. Confirm webhook events update local order delivery status.

Go-live checklist:
- One new test order appears successfully in NavYour Business Portal.
- No old orders were sent during testing.
- The local order stores NavYour tracking details.
- Duplicate retry has been tested.
- Failure/retry behavior has been tested.
- Webhook endpoint is configured and test webhook succeeded.
- Business profile, subscription, and wallet are ready in NavYour.
- Only then replace the Test API key with the Live API key in backend .env.

Implement this using the existing backend framework, existing order model/service patterns, existing logger, and existing environment config style in this repository.

Add focused tests for:
- payload construction from one current order
- no sync if already created
- creating status guard
- idempotency key generation
- success persistence
- failure persistence
- no bulk old-order sync