{
  "openapi": "3.1.1",
  "info": {
    "title": "HPH Integrations direct company-item mapping",
    "version": "v1",
    "description": "HPH Integrations public API v1. Available to the Customer Testing group; not available in Production."
  },
  "paths": {
    "/v1/catalog/items/mapping": {
      "put": {
        "operationId": "SetCompanyItemMapping",
        "summary": "Set the desired HPH mapping for one existing company item.",
        "x-runtime-status": "testing-available",
        "x-required-permission": "item-mapping.direct-map",
        "x-idempotency-key-required": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/SetMappingRequest" },
              "example": {
                "company_item_id": "COMPANY-1001",
                "hph_item_code": "012NI0044",
                "expected_mapping_revision": 3,
                "reason": "Corrected parent association"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The desired mapping is current.",
            "headers": {
              "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SetMappingResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Problem" },
          "401": { "$ref": "#/components/responses/Problem" },
          "403": { "$ref": "#/components/responses/Problem" },
          "404": { "$ref": "#/components/responses/Problem" },
          "409": { "$ref": "#/components/responses/Problem" },
          "422": { "$ref": "#/components/responses/Problem" },
          "429": { "$ref": "#/components/responses/Problem" },
          "503": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/v1/catalog/items/mapping/restorations": {
      "post": {
        "operationId": "RestorePreviousCompanyItemMapping",
        "summary": "Restore the immediately preceding immutable mapping snapshot.",
        "x-runtime-status": "testing-available",
        "x-required-permission": "item-mapping.direct-map",
        "x-idempotency-key-required": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/RestoreMappingRequest" },
              "example": {
                "company_item_id": "COMPANY-1001",
                "restore_from_revision": 3,
                "expected_mapping_revision": 4
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The previous complete snapshot was appended as the new current revision.",
            "headers": {
              "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }
            },
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/RestoreMappedResponse" },
                    { "$ref": "#/components/schemas/RestoreEmptyResponse" }
                  ]
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Problem" },
          "401": { "$ref": "#/components/responses/Problem" },
          "403": { "$ref": "#/components/responses/Problem" },
          "404": { "$ref": "#/components/responses/Problem" },
          "409": { "$ref": "#/components/responses/Problem" },
          "422": { "$ref": "#/components/responses/Problem" },
          "429": { "$ref": "#/components/responses/Problem" },
          "503": { "$ref": "#/components/responses/Problem" }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Problem": {
        "description": "A stable minimized public problem.",
        "content": {
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/ExternalProblem" }
          }
        }
      }
    },
    "schemas": {
      "SetMappingRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["company_item_id", "hph_item_code"],
        "properties": {
          "company_item_id": { "type": "string", "minLength": 1, "maxLength": 255 },
          "hph_item_code": { "$ref": "#/components/schemas/HphItemCode" },
          "expected_mapping_revision": {
            "type": ["integer", "null"],
            "format": "int64",
            "minimum": 0
          },
          "reason": {
            "type": ["string", "null"],
            "maxLength": 512,
            "description": "Required when the desired code replaces a different current parent."
          }
        }
      },
      "RestoreMappingRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["company_item_id", "restore_from_revision", "expected_mapping_revision"],
        "properties": {
          "company_item_id": { "type": "string", "minLength": 1, "maxLength": 255 },
          "restore_from_revision": { "type": "integer", "format": "int64", "minimum": 1 },
          "expected_mapping_revision": { "type": "integer", "format": "int64", "minimum": 2 }
        },
        "description": "restore_from_revision must equal expected_mapping_revision minus one."
      },
      "SetMappingResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "operation_reference", "item_skey", "company_item_id", "transition",
          "mapping_status", "mapping_revision", "hph_item_code", "reused", "validation",
          "available_actions"
        ],
        "properties": {
          "operation_reference": { "$ref": "#/components/schemas/OperationReference" },
          "item_skey": { "$ref": "#/components/schemas/ItemSkey" },
          "company_item_id": { "type": "string", "minLength": 1, "maxLength": 255 },
          "transition": {
            "type": "string",
            "enum": ["initial_mapping", "already_current", "replaced"]
          },
          "mapping_status": { "type": "string", "const": "active" },
          "previous_mapping": { "$ref": "#/components/schemas/PreviousMapping" },
          "mapping_revision": { "type": "integer", "format": "int64", "minimum": 1 },
          "hph_item_code": { "$ref": "#/components/schemas/HphItemCode" },
          "reused": { "type": "boolean" },
          "validation": { "$ref": "#/components/schemas/MappingValidation" },
          "available_actions": { "$ref": "#/components/schemas/AvailableActions" }
        },
        "examples": [
          {
            "operation_reference": "directmap_0123456789abcdef0123456789abcdef",
            "item_skey": "11111111-1111-4111-8111-111111111111",
            "company_item_id": "COMPANY-1001",
            "transition": "initial_mapping",
            "mapping_status": "active",
            "mapping_revision": 1,
            "hph_item_code": "012NI0044",
            "reused": false,
            "validation": { "outcome": "mapped", "warnings": [] },
            "available_actions": []
          },
          {
            "operation_reference": "directmap_1123456789abcdef0123456789abcdef",
            "item_skey": "11111111-1111-4111-8111-111111111111",
            "company_item_id": "COMPANY-1001",
            "transition": "replaced",
            "mapping_status": "active",
            "previous_mapping": { "mapping_revision": 3, "hph_item_code": "012NI0032" },
            "mapping_revision": 4,
            "hph_item_code": "012NI0044",
            "reused": false,
            "validation": {
              "outcome": "mapped_with_warnings",
              "warnings": [
                {
                  "code": "HPH_ITEM_MANUFACTURER_PRICING_DISCONTINUED",
                  "title": "Manufacturer availability is discontinued",
                  "description": "The HPH item remains eligible for mapping, but its Manufacturer availability status is discontinued."
                }
              ]
            },
            "available_actions": [
              {
                "action": "restore_previous_mapping",
                "title": "Restore previous mapping",
                "description": "Appends the immediately preceding immutable snapshot as a new current mapping revision.",
                "operation_id": "RestorePreviousCompanyItemMapping",
                "method": "POST",
                "href": "/v1/catalog/items/mapping/restorations",
                "request_body_required": true,
                "idempotency_key_required": true,
                "confirmation_required": true
              }
            ]
          }
        ]
      },
      "RestoreMappedResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "operation_reference", "item_skey", "company_item_id", "transition", "mapping_status",
          "restored_from_revision", "mapping_revision", "hph_item_code", "reused",
          "validation", "available_actions"
        ],
        "properties": {
          "operation_reference": { "$ref": "#/components/schemas/OperationReference" },
          "item_skey": { "$ref": "#/components/schemas/ItemSkey" },
          "company_item_id": { "type": "string", "minLength": 1, "maxLength": 255 },
          "transition": { "type": "string", "const": "mapping_restored" },
          "mapping_status": { "type": "string", "const": "active" },
          "restored_from_revision": { "type": "integer", "format": "int64", "minimum": 1 },
          "mapping_revision": { "type": "integer", "format": "int64", "minimum": 2 },
          "hph_item_code": { "$ref": "#/components/schemas/HphItemCode" },
          "reused": { "type": "boolean" },
          "validation": { "$ref": "#/components/schemas/MappingValidation" },
          "available_actions": { "$ref": "#/components/schemas/AvailableActions" }
        }
      },
      "RestoreEmptyResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "operation_reference", "item_skey", "company_item_id", "transition", "mapping_status",
          "restored_from_revision", "mapping_revision", "reused", "available_actions"
        ],
        "properties": {
          "operation_reference": { "$ref": "#/components/schemas/OperationReference" },
          "item_skey": { "$ref": "#/components/schemas/ItemSkey" },
          "company_item_id": { "type": "string", "minLength": 1, "maxLength": 255 },
          "transition": { "type": "string", "const": "empty_mapping_restored" },
          "mapping_status": { "type": "string", "const": "unmapped" },
          "restored_from_revision": { "type": "integer", "format": "int64", "minimum": 1 },
          "mapping_revision": { "type": "integer", "format": "int64", "minimum": 2 },
          "reused": { "type": "boolean" },
          "available_actions": { "$ref": "#/components/schemas/AvailableActions" }
        }
      },
      "PreviousMapping": {
        "type": "object",
        "additionalProperties": false,
        "required": ["mapping_revision", "hph_item_code"],
        "properties": {
          "mapping_revision": { "type": "integer", "format": "int64", "minimum": 1 },
          "hph_item_code": { "$ref": "#/components/schemas/HphItemCode" }
        }
      },
      "MappingValidation": {
        "type": "object",
        "additionalProperties": false,
        "required": ["outcome", "warnings"],
        "properties": {
          "outcome": { "type": "string", "enum": ["mapped", "mapped_with_warnings"] },
          "warnings": {
            "type": "array",
            "maxItems": 2,
            "items": { "$ref": "#/components/schemas/MappingWarning" }
          }
        }
      },
      "MappingWarning": {
        "type": "object",
        "additionalProperties": false,
        "required": ["code", "title", "description"],
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "HPH_ITEM_MANUFACTURER_PRICE_ON_APPLICATION",
              "HPH_ITEM_MANUFACTURER_PRICING_DISCONTINUED"
            ]
          },
          "title": { "type": "string", "minLength": 1, "maxLength": 256 },
          "description": { "type": "string", "minLength": 1, "maxLength": 1024 }
        }
      },
      "AvailableActions": {
        "type": "array",
        "maxItems": 4,
        "items": { "$ref": "#/components/schemas/AvailableAction" }
      },
      "AvailableAction": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "action", "title", "description", "operation_id", "method", "href",
          "request_body_required", "idempotency_key_required", "confirmation_required"
        ],
        "properties": {
          "action": {
            "type": "string",
            "enum": ["get_current_mapping", "set_mapping", "restore_previous_mapping", "get_mapping_history"]
          },
          "title": { "type": "string", "minLength": 1, "maxLength": 256 },
          "description": { "type": "string", "minLength": 1, "maxLength": 1024 },
          "operation_id": { "type": "string", "minLength": 1, "maxLength": 128 },
          "method": { "type": "string", "enum": ["GET", "PUT", "POST"] },
          "href": { "type": "string", "pattern": "^/v1/" },
          "request_body_required": { "type": "boolean" },
          "idempotency_key_required": { "type": "boolean" },
          "confirmation_required": { "type": "boolean" }
        }
      },
      "ExternalProblem": { "type": "object", "additionalProperties": false, "required": ["type", "title", "status", "code", "correlation_id", "retryable", "errors"], "description": "Problem details as sent on the wire (application/problem+json). Field names are snake_case, like every other request and response body.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "correlation_id": { "type": "string" }, "retryable": { "type": "boolean" }, "errors": { "type": ["object", "null"], "additionalProperties": { "type": "array", "items": { "type": "string" } } } } },
      "OperationReference": { "type": "string", "minLength": 1, "maxLength": 128 },
      "ItemSkey": {
        "type": "string",
        "format": "uuid",
        "description": "The owning Company's catalog-item identity (item_skey)."
      },
      "HphItemCode": {
        "type": "string",
        "minLength": 9,
        "maxLength": 10,
        "pattern": "^(?:[0-9]{3}[A-Z]{2}|010C |210C |275C1)[0-9]{4}[A-Z]?$"
      }
    }
  }
}