Supplier record contract

Prepare source-derived product, capacity and service records for the integration preview.

Contract version: 0.1.0. Release status · JSON schema · Preview OpenAPI.

Validation envelope

POST /api/v1/supplier/validate accepts a strict JSON object with schemaVersion, source and records. Unknown fields are rejected, including caller-supplied company IDs or approval flags. The API key determines the company.

source contains a stable id, a system name and mode (api or sdk). records contains one to 50 records. The full request must fit in 256 KiB. Required nullable fields must be present as null when unknown.

Record fields

Field	Type / rule
sourceRecordId	Stable source identifier; unique within a batch
sourceVersion	Source revision/change token or deterministic record digest
kind	product, capacity or service
title	Source-derived description, up to 500 characters
manufacturer, manufacturerPartNumber	Strings or null
unit	Source unit, up to 40 characters
condition	new, used, refurbished or unknown
availability	Quantity, window, location and lead time, as described below
pricing	Public-price context and quantity tiers, or null
sourceUpdatedAt	ISO 8601 timestamp with zone, or null
observedAt, expiresAt	ISO 8601 timestamps with zone
status	active or withdrawn

Identifiers start with an alphanumeric character and may contain letters, numbers, ., _, :, / and -, up to 160 characters. An MPN is not automatically the same as a supplier listing ID.

Availability

• quantity: unsigned decimal string or null.
• window: { "start": "…", "end": "…" } or null; required for capacity, with end after start.
• location: string or null.
• leadTimeDays: whole number from 0 to 3650, or null.

Pricing

When a price is known, provide currency (three uppercase letters), country (two uppercase letters), audience: "public", taxBasis (net, gross or unknown), taxRate (decimal proportion or null), positive minimumOrderQuantity, positive orderMultiple and one to 50 tiers.

Each tier has a positive minimumQuantity and nonnegative unitPrice. Decimal strings support up to 12 integer digits and eight fractional digits. Tier thresholds must be unique and ascending. A zero price is allowed only when the source actually says zero. Currency/country syntax validation is not proof that a market context is valid.

Freshness

Expiry must follow observation by at most 24 hours. An observation more than 60 seconds in the future is rejected. Expired observations are rejected. A known source modification time cannot follow observation. Never freshen cached source data by replacing its timestamps.

The JSON schema covers structural constraints. Cross-field rules, freshness and tier ordering are also enforced by the server.

Successful validation

{
  "valid": true,
  "schemaVersion": "0.1.0",
  "recordsValidated": 1,
  "persisted": false,
  "admitted": false
}

No data is saved to a catalogue and no source URL is fetched. Validation cannot prove source access, source truth, continuous synchronization or permission to share. A synthetic example passing validation is not an integrated supplier.

Supplier-hosted interface: proposed

For a later pull integration, we propose that your service expose a provider manifest, cursor-paginated catalogue, read-only availability checks and health endpoint. These paths would be on your service, not the Middleman API:

Proposed path	Purpose
GET /v1/provider	Schema version, capabilities, supported markets and units
GET /v1/catalog?cursor=…	Stable identities and source-derived records
POST /v1/availability/check	Read current price/stock/capacity for identified records
GET /v1/health	Source connection and last successful refresh

This transport and its authentication/admission process are not yet released. Do not deploy an unauthenticated endpoint or send us credentials on the assumption that it will be polled. Prepare the record mapping first; confirm transport details before production work.