SAAVI API — Developer Portal

SAAVI API is the buyer-facing API surface for a supplier tenant. Enterprise buyers submit purchase orders, look up status, and receive acknowledgements. Accepted POs are promoted into the downstream supplier system via the SAAVI OrderFlow bridge.

The API is REST/JSON over HTTPS, uses OAuth 2.0 client credentials, and enforces per-request idempotency and correlation. All endpoints are versioned under/api/supplier/v1.

1. Request onboarding via your SAAVI account manager.
2. Buyer profile, tenant map, and adapter configuration are provisioned for you.
3. Receive your client credentials and tenant identifiers.
4. Integrate against the base URL using the examples below.
5. Escalate via the standard SAAVI support path for reason-code triage.

Buyer-facing auth uses OAuth 2.0 client credentials issuing short-lived bearer tokens (RS256, standard iss/aud/scopes/exp/jti). All state-changing calls requireIdempotency-Key and echoX-Correlation-Id.

Internal service-to-service calls use a separate JWT verified server-side. No client-side secrets are ever required.

Two logical environments: sandbox and production. Both are served from https://api.saavi.com.au and selected via theenvironment field on the request payload and the credentials issued to your client.

POST /purchase-orders validates the canonical PO, applies mappings, and submits it downstream via the OrderFlow bridge.

curl -X POST https://api.saavi.com.au/api/supplier/v1/purchase-orders \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Idempotency-Key: <UUID>" \
  -H "X-Correlation-Id: <UUID>" \
  -H "Content-Type: application/json" \
  -d '{"buyerPoNumber":"PO-1001","environment":"production","lines":[{"lineNumber":1,"buyerSku":"SKU-A","quantity":2,"uom":"EA"}]}'

GET /purchase-orders/{supplierPoId} returns the buyer-safe status plus latest ACK id and reason code. Never leaks internal tenant or system details.

Idempotency-Key is required on all writes. Same key + same payload hash returns the stored response. Same key + different payload returns409 idempotency_conflict. TTL 24h.

Buyer-safe reason codes emitted across the surface:

• accepted_for_processing
• pending_mapping_review
• invalid_customer_mapping
• invalid_ship_to_mapping
• invalid_sku_mapping
• invalid_uom_mapping
• duplicate_po
• idempotency_conflict
• tenant_mapping_error
• auth_failed
• missing_scope
• token_expired
• orderflow_rejected
• supplier_system_unavailable
• unknown_processing_error

Register HTTPS endpoints to receive event callbacks for PO lifecycle transitions. Event names, payload shapes, and retry policy are documented below.

• Event & Webhook Contract
• Webhooks & Events reference

Sequence diagrams for onboarding, PO submission, certification, and error/retry flows.

• Integration Timelines & Sequence Diagrams

• OpenAPI 3.1 YAML
• OpenAPI 3.1 JSON
• Swagger UI

• SAAVI API collection (JSON)
• View cURL, TypeScript, idempotency-conflict, status, and error examples

• 1.0.9 — Latest published version. Developer portal, OpenAPI v1, supplier intake, status API, webhooks, and OrderFlow bridge available at https://api.saavi.com.au.