# Panda Parcel courier integration setup

## Current delivery
A common shipping interface, five separate server-only disabled adapters, authenticated readiness checks, private request history and sandbox-only database constraints are implemented. Existing simulated parcel functionality is preserved. No live-provider HTTP transport, signature algorithm or callback has been invented.

**None of the five couriers is connected or sandbox-certified.** Readiness checks save a blocked record; they do not call couriers. Schema foundations exist for future sandbox shipments and deduplicated callback events. No existing browser parcels are uploaded. ZTO remains a preview-only option outside this integration request.

Lovable Cloud powers accounts and secure storage. Sign-in methods: email/password (confirmation required), Google and Lovable. Password recovery is available. Account creation is not courier authorization.

## Provider requirements and sources
- **SF:** https://open.sf-express.com/Api — selected mainland specifications show POST form-encoded UTF-8 requests and fields `partnerID`, `requestID`, `serviceCode`, `timestamp`, `msgData`, plus `msgDigest` or `accessToken`. Obtain the authorized service contract, exact authentication/signature examples and timestamp tolerance, sandbox credentials, required fields, response schema, quotas and callback rules. Do not use international SF contracts for mainland SF.
- **STO:** https://open.sto.cn/ — registration, interface application and joint testing described. Obtain authorized interface documentation, credentials, sandbox endpoint, signing, encoding, rate limits and callback contract.
- **YTO:** https://open.yto.net.cn/ — official registration platform. Obtain approved catalogue, sandbox and complete authentication, request/response, idempotency, error and callback specifications.
- **Yunda:** https://open.yundaex.com/ — reviewed catalogue at https://yundaex.apifox.cn/ describes waybill creation/cancellation and tracking subscription, UTF-8 form requests and `app-key`, `sign`, `req-time` (milliseconds). Confirm that catalogue/version directly with Yunda. Obtain full signing recipe, customer account grant, non-billable sandbox behavior and limits. Rate inquiry and callback verification are unverified.
- **JD Logistics:** https://www.jingdonglogistics.com/ — request the applicable partner/developer documentation directly. JD Retail https://open.jd.com/ is not evidence of logistics permissions. All shipping protocol details remain unverified.

No provider-approved SDK was verified. Use a provider's official HTTP examples or a verified runtime-compatible SDK after approval. Translate documentation explanations while keeping parameter names unchanged.

## Safe activation sequence
1. Obtain business agreements and approved API operations; confirm pickup/service reachability independently of the address directory.
2. Supply official account-specific documentation and signing test vectors. Include exact sandbox hosts, API version, headers, timestamp units/window, form/JSON encoding, required fields, error codes, quotas and idempotency guarantees.
3. Confirm the sandbox cannot create real pickups or charges, including label/waybill operations.
4. Ask for secure credential forms after documentation establishes the actual credential names. No credentials are currently requested or stored for couriers. Available workspace connections were checked; none were present.
5. Implement only verified operations inside the corresponding server-only adapter. Keep unknown capabilities disabled. Validate exact signature/encoding against provider examples. Use backend secrets, never `VITE_` variables, browser storage, source files or chat.
6. Add narrow authenticated server functions and owner-scoped result reads. Current authenticated insert permission allows blocked readiness records only; no user can mark a provider request successful or write labels/tracking events. Extend verified processing deliberately, not by opening access policies.
7. Before shipment dispatch, atomically reserve an owner/request key and immutable request fingerprint in durable storage. Same key with different input must fail. Timeout after create means uncertain, not failed: reconcile through an approved provider lookup before resubmitting. No automatic create retries without documented provider idempotency.
8. Implement callback routes under `/api/public/` only once verification and acknowledgment rules are known. Verify signature and timestamp/replay rules before private writes, enforce size limits, deduplicate events, and never expose parcel data publicly. No callback endpoint is active now.
9. Use bounded documented read retries with jitter, `Retry-After` where specified, request timeouts and at most five concurrent courier calls. No retry transport is active while protocols remain unknown.
10. Run opt-in sandbox tests: read-only first, then explicitly non-billable sandbox shipment tests. Confirm results read back through the signed-in app. Record actual results, never substitute mocks for sandbox certification.
11. Seek separate explicit production approval. No production dispatch or payments are implemented or authorized.

## Logs and privacy
Logs allow only courier, operation, normalized result, UUID correlation ID and duration. Raw provider bodies, tokens, signatures, addresses, names, phone numbers, pickup codes and label URLs must never be logged. Original Chinese tracking messages may be retained in private normalized results, not operational logs.

## Environment template
Download `courier-environment.example`. It contains no credentials or guessed provider secret names. It describes the disabled boundary; setting a flag does not enable a courier. Lovable Cloud injects its managed configuration. Store future private credentials through secure forms; do not create a committed secret-bearing `.env` file.

## Tests
Run `bunx vitest run` for the existing regression suite and adapter safety tests. See `courier-test-results.md` for this delivery's verified outcomes and unexecuted contract/sandbox checks.