Batch-ingest category form-data (wizard step 4)

PUT 
/api/v1/products/:id/form-data

Pushes a partial batch of category field values to a product draft and returns a field-level accept or reject for every field.

Required scope: dpp:draft:write. A WRITE (HMAC + Idempotency-Key). The headless equivalent of filling the wizard's field sections: push a partial batch of category field_id -> value pairs and get a fail-closed, FIELD-LEVEL accept/reject. Every provided field is checked against the category schema (type / enum / range / pattern) and unknown fields are REJECTED (422 FIELD_VALIDATION_ERROR, details.fieldErrors[]), never silently dropped — so a mis-mapped ERP column is immediately visible. Required-completeness is NOT enforced here (a partial batch is allowed); it is reported by the publish gate. On success the response echoes the post-write completeness score and a compact readiness summary. lockVersion gives optimistic concurrency (stale -> 409).

FILE FIELDS (type: file): send the id of a document your company already holds, as returned by POST /api/v1/products/{id}/documents. The server stores that document's file in the field. The document must belong to your company and to this key's mode (live or test), must not be Infected, ScanFailed or Rejected (nor Pending while public documents are served Clean-only), and its file type must match the field's accept. Any document id that cannot be used is refused with the same 422 FIELD_VALIDATION_ERROR field error, code FILE_REFERENCE_UNRESOLVED, whatever the reason, and nothing is written. A URL or free text is never accepted in a file field. To clear the matching certificate rule at the publish gate, upload the document under the exact documentName and documentType the field's evidence names in GET /api/v1/categories/{code}/schema (see FileFieldEvidence).

Request

Responses

200

Ingested (fully validated)

400

400 — INVALID_JSON, VALIDATION_ERROR, VALIDATION (the {id} path segment is not a UUID), or IDEMPOTENCY_KEY_REQUIRED.

401

401 — INVALID_SIGNATURE or SIGNING_NOT_CONFIGURED (or bearer auth failure).

403

403 — missing scope (FORBIDDEN_SCOPE) or module (FORBIDDEN_MODULE).

404

404 — not found OR owned by another tenant (NOT_FOUND; IDOR-safe).

409

Optimistic lock conflict (LOCK_CONFLICT) — re-GET and retry.

422

Field-level validation failure (FIELD_VALIDATION_ERROR). details.fieldErrors[] carries {field_id, label, code, message} — field references only, never the submitted values (PII redaction). A file field whose document id cannot be used carries code FILE_REFERENCE_UNRESOLVED.

429

429 — RATE_LIMITED (per-key limit, reads and writes alike; fails closed, so a limiter outage also returns 429). A limiter-down 429 is deliberately indistinguishable from a quota 429. Carries Retry-After (seconds).

Response Headers

Retry-After

Seconds to wait before retrying (429 only).

RateLimit-Limit

Per-minute request ceiling for this key's tier.

RateLimit-Remaining

Requests left in the current window (floored at 0).

RateLimit-Reset

Seconds until the window resets.

503

503 — the API is not enabled on this environment (FEATURE_DISABLED).