Create an ERP field-mapping (new version)

POST 
/api/v1/erp-mappings

Required scope: mapping:write. Stores a { erp_column -> field_id } alias map for the calling company under source, as a new monotonic version. Every field_id VALUE is validated against the company's active FormTemplate catalog: an unknown field_id returns 422 UNKNOWN_FIELDS (the whole request is rejected, nothing stored) with details.unknownFieldIds listing ONLY the unresolved field_ids, never the erp_column keys. companyId comes from the key, never the body. Idempotent via Idempotency-Key.

Request

Responses

201

The created mapping version.

400

400 — INVALID_JSON, VALIDATION_ERROR, 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).

422

UNKNOWN_FIELDS — a mapping value is not in the company's active field catalog; details.unknownFieldIds lists the unresolved field_ids (never the erp_column keys). Nothing is stored.

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).