# Order Source Certification `certify.py` is a black-box self-test. It talks to your **staging** FleetBridge environment over plain HTTP, the same way your own integration will, and checks that the responses match this package's documented contract. You don't need FleetBridge source code, repo access, or any internal tooling — just your staging Base URL and staging API key. Use it to: - Verify your staging credentials and network path are working before you write any integration code. - Re-run after you build your integration, as a smoke test against the real contract (not just against your own mocks). - Produce a `results.json` you can attach when requesting production activation. ## Requirements - Python 3.8 or later. No packages to install — `certify.py` uses only the Python standard library. ## Steps 1. Copy `config.example.json` to `config.json` and fill in: - `baseUrl` — your staging Base URL, no trailing slash. - `apiKey` — a **staging** Order Source API key (`key_` + 64 lowercase hex characters). Never put a production key in this file. - `externalBranchId` — a branch reference your Order Source is already configured to use in staging. - `webhookTestSupported` — set to `true` only if you have already registered a staging webhook endpoint for this Order Source and want the optional `/api/v1/webhooks/test` check exercised. 2. Run: ``` python3 certify.py config.json ``` 3. Read the console output. Each line is one check: `PASS`, `FAIL`, or `WARN` (a non-required check that did not run or did not apply). The script exits with a non-zero status if any **required** check failed. 4. A full machine-readable report is written to `results.json` in the same directory (override the path with `--out`). ## What it checks - Authentication is rejected with no key, and accepted with a valid key (Section 2 of `ORDER_SOURCE_INTEGRATION_API.md`). - Create Order succeeds with a minimal valid payload (Section 7). - Idempotency: replaying the exact same `Idempotency-Key` and body returns the same order, not a duplicate (Section 13). - Reads: Get by platform id, get by your own external id, get status, get tracking history — including the empty-array (not error) case when no shipment exists yet (Sections 8, 12). - Update: a partial PATCH is accepted (Section 11). - Cancel: a first cancel succeeds, and a repeated cancel on the same order stays idempotent rather than erroring (Section 12). - Validation: an invalid Create (missing a required field) is rejected with `400` and a structured `errorCode` (Section 16). - Isolation: an unknown order reference returns `404`, never a different Order Source's data. - Optionally, if you already have a staging webhook endpoint registered, triggers `/api/v1/webhooks/test` and confirms it is accepted. ## What it intentionally does not check - Rate limiting (`429`) — deliberately not triggered by this script; hammering your own staging environment to provoke a `429` is not a meaningful correctness signal and risks tripping shared infrastructure limits. - Actual webhook delivery and signature verification — that depends on your own callback endpoint being reachable from FleetBridge. Verify signature handling using the code samples in `../webhook-signing/` against the `webhook.test` payload your endpoint receives after step 14, or against captured real event payloads. - Scheduled order dispatch timing — `certify.py` only verifies a scheduled Create is accepted; it does not wait for a future dispatch to occur. ## Interpreting a FAIL Every failed check's `detail` field states exactly what was expected versus what was observed. Cross-reference the check `name` with the matching section in `ORDER_SOURCE_INTEGRATION_API.md` (mirrored in `index.html`) before assuming the failure is on FleetBridge's side — most first-run failures turn out to be a misconfigured `baseUrl`, an expired or revoked staging key, or an `externalBranchId` that isn't provisioned for your Order Source yet. Still failing after you've double-checked your config? Contact FleetBridge through your onboarding channel with the generated `results.json` attached.