API Keys & Integration

Use the Test API key while integrating your website. Test orders appear in this page and do not create real deliveries.

Never place this key in frontend JavaScript, HTML, mobile app public code, or GitHub. Store it only in your backend/server .env.

Live API creates real NavYour delivery orders and may deduct delivery fees from your wallet.

Live orders deduct deliveryFeePaise from your NavYour wallet. Create a live key only after a successful test order.

You are working in this website backend. Integrate NavYour delivery creation after our checkout/order-confirmation flow.

Goal:
When a customer order is confirmed in our system, create one NavYour delivery order from the backend, store the returned tracking details on our order, and make retries safe. First use the NavYour Test API key. 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 our order id or immutable order reference
- Content-Type: application/json

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 our backend may call NavYour.
- Redact Authorization and NAVYOUR_API_KEY from logs.

Database changes/checks:
- Add or reuse fields on our orders table:
  navyourOrderId
  navyourTrackingCode
  navyourTrackingUrl
  navyourDeliveryStatus
  navyourSyncStatus: not_started | creating | created | failed
  navyourSyncError
  navyourLastSyncAttemptAt
- Add a unique guard so the same local order cannot create multiple NavYour deliveries.
- Store the NavYour response payload or minimal audit metadata if this project has an integration-log table.

When to call NavYour:
- Call only after our local order is successfully saved/confirmed.
- Never create a NavYour delivery before payment/order confirmation.
- If the customer order is COD, send paymentType "cod".
- If the customer paid online, send paymentType "prepaid".

Payload requirements:
- Send a complete JSON payload with:
  orderReference: our stable order id/reference
  orderSource: "business_website"
  customer.name, customer.phone, customer.email
  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.
- Our website decides deliveryFeePaise and sends it to NavYour.
- In Live mode, NavYour deducts this deliveryFeePaise from our NavYour wallet.
- Customer payment belongs to our business. NavYour wallet pays the NavYour delivery fee.
- For COD, codAmountPaise must be the exact cash amount the driver collects from the customer.
- If our checkout total includes delivery fee, include that delivery fee inside codAmountPaise.
- For prepaid orders, prepaidAmountPaise is the amount already collected by our website.

Idempotency and duplicate prevention:
- Before calling NavYour, check if the order already has navyourTrackingCode. If yes, return the existing tracking details.
- Send Idempotency-Key with the same stable local order id on every retry.
- Use the same orderReference on every retry.
- Treat 409 duplicate/order already exists as recoverable if NavYour returns or can recover a tracking code.

Failure behavior:
- If NavYour fails, do not delete or cancel the customer order.
- Save navyourSyncStatus = "failed", save the error message, and allow admin/background retry.
- Retry only from backend using the same orderReference and Idempotency-Key.
- Surface a clear internal error for operations, but do not expose API keys or raw sensitive headers.

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

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 our 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, and 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. Keep NAVYOUR_API_BASE_URL pointed to the NavYour API base URL.
3. Place a real test checkout/order through our website flow.
4. Confirm our backend sends POST /integration/orders with Authorization Bearer and Idempotency-Key.
5. Confirm the order appears in NavYour Business Portal -> API Keys -> Test Orders.
6. Confirm NavYour returns a TEST tracking code.
7. Confirm our order stores trackingCode and trackingUrl.
8. Confirm duplicate retry does not create a second NavYour delivery.
9. Confirm failed NavYour calls mark sync failed and can be retried.
10. Configure NavYour webhook URL and signing secret.
11. Send test webhook and verify signature handling.
12. Confirm webhook events update local order delivery status.

Go-live checklist:
- A test order appears successfully in NavYour Business Portal.
- 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, idempotency guard, success persistence, and failure persistence.