# Rating API: an adapted working reference This reference preserves the useful protocol and authoring explanations from the earlier documentation, corrected against the Go implementation used for the walkthroughs. It is not an archival copy of every predecessor guide or a complete OpenAPI specification. Product-specific names and private deployment details are anonymized. The engine is not included in this source pack. ## Credentials and transport Use JSON:API media type `application/vnd.api+json` for Accept and Content-Type, and `Authorization: Bearer `. Set the private installation's version header to `2026-03-22`. The header name is deliberately supplied through VERSION_HEADER, not published under a fictitious wire name. The examples distinguish authoring credentials, read credentials and runtime credentials bound to a division. A token suitable for authoring is not necessarily admitted to rating. The first journey captures HTTP 403 ACTOR_UNAUTHORIZED from the unbound authoring token. `POST /api/access-tokens` receives: ```json { "data": { "type": "access-token", "attributes": { "token_type": "sk", "name": "Disposable walkthrough token", "abilities": ["*"], "division_id": "", "rate_limit_per_minute": 600 } } } ``` The response's `data.attributes.plain_text_token` supplies the runtime bearer. Never publish it. The sample runner uses it in memory and redacts token and secret string fields from saved exchanges. Token issuance is a real mutation; the disposable installation owns cleanup and revocation. ## Definition authoring Create a division using resource type `division` and attributes division_code and state (`active` in these examples). Its HTTP 201 response gives `data.id`. Then use these endpoints under `/api/divisions/{id}/shipping-method-definition`: | Endpoint | Method | Purpose | | --- | --- | --- | | /validate | POST | Validate a complete definition document | | /plan | POST | Inspect the intended application | | /apply | POST | Apply the document and its lifecycle instructions | | /export | GET | Inspect the authored result using read credentials | The definition body has resource type `shipping-method-definition-document`. Its attributes include `schema_version: 1`, `document_type: shipping-method-config`, `division_id`, `config` and `meta` (an object, not an empty array). The downloadable definition files contain that full envelope. config connects carriers/releases/services, option schemas, currency metadata, pricing and pricing_catalog, governance, rulesets, option relationships, computed formulas, runtime policy, request-context routing and verification. Some documents include both a convenience pricing section and explicit artifact catalogs. Do not delete one representation from a working example without checking the writer's interpretation and all profile references. The authoring schema includes these pricing families: - Rates, contract schedules, surcharges, adjustments and accessorials. - Geography, zones, lanes, route distances, distance bands and service-point topology. - Chargeable and freight weight, package/shipment breaks, pallet space and classification, unit-load classification, multi-unit aggregation, load transitions and handling. - Goods classifications, offers, availability and constraints. - Minimum charges, precedence, override resolution and seasonal calendars. Lifecycle instructions can connect validation, scenario cases, review, approval, publication and effective dates. Supporting contracts, policies and computed facts have their own identities. A structurally valid document is not a blanket guarantee that every imaginable combination is commercially complete or ready to publish. Plan and apply return HTTP 200 in the successful examples, and their `data.attributes.succeeded` flag is true. Check both. Give each command its own request/idempotency metadata even when it uses the same definition body. The runner's short namespace avoids overflowing nested persisted operation keys; it is not a request to shorten meaningful artifact identities blindly. Individual-resource authoring APIs also exist in the implementation. This pack chooses the definition-document route and does not pretend to include an independently executed granular authoring tutorial. ## Evaluation request POST `/api/rating/evaluate`, resource type rating-evaluation: ```text meta request_id idempotency_key data.attributes division_id contract_version operation_code timezone context scope request channel customer shipment origin destination packages[] items[] package_item_allocations[] (where used) legs[] parties ``` context and shipment are direct attributes. There is no payload wrapper. The HTTP API version and rating contract_version are different selections. Examples use operation_code rate_quote; their published models define the matching request/response contracts and runtime configuration. Packages carry identity, type, measurements and units. Items carry their own identity, quantity, value and optional goods data. Allocations connect item quantities to package IDs. Legs have ordered identities, endpoints and package membership. Repeated addresses and party roles must remain coherent with the shipment you intend to describe. A package count alone cannot represent those relationships. Amounts returned in the examples are decimal strings with currency_code. Some authoring values use amount.currency instead; preserve the documented shape at each boundary rather than applying a global field rename. ## Read the result Evaluation returns data.attributes.shipping_options, not options. Each option includes carrier/service identities, canonical and presentation keys, price_components, total_price, transit, eligibility_trace and legs. A component records kind, code, scope, optional scope_reference, amount and calculation_basis. The basis can identify artifact and row versions and the amount/groups selected for a percentage. Package-scoped components reference package_id. Don't infer identity from response-array position or assume a single rule code can have only one component instance. The walkthroughs inspect `_group_code` as an implementation-exposed diagnostic alongside scope and percentage bases. It is useful for these versioned examples, not a promise that this underscored field is a stable general-purpose accounting API. A production consumer needs its actual supported contract. HTTP 200 can contain no shipping options when every candidate is ineligible. That is different from malformed input or denied admission. Treat an empty option set as no offer, not zero cost or a reason to silently reuse an old quote. ## Operation identity and simulation The first journey repeats an identical evaluation and checks meta.idempotency.replayed=true. Reusing the same identity after changing the weight returns 409 REQUEST_ID_CONFLICT. An uncertain network outcome should be retried as the same operation; a different quote needs a different identity. The example checks API behavior, not direct database reconciliation of every decision record. POST `/api/rating/simulate` uses type rating-simulation and its own request shape. The candidate example supplies requested_at and decision_instant_at and an identical shipment in a separately applied candidate division. That demonstrates an isolated candidate result, not live promotion or a general promise to evaluate arbitrary unpublished drafts. The reference is intentionally tied to the bodies and observed behavior in this pack. Future changes to the private engine need fresh execution against its selected contract; renaming a header or copying an old guide is not a compatibility check.