Spendint API - POST /sn_spend_intg/spendint/catalog

  • 릴리스 버전: Zurich
  • 업데이트 날짜 2025년 07월 31일
  • 소요 시간: 13분

    • 공급자가 공급자 제품, 모델 제품, 계약 및 가격 책정 기록을 만들기 위해 여러 카탈로그를 게시할 수 있도록 해 줍니다.

    카탈로그 API 통합의 외부 공급업체 카탈로그에서 데이터를 수신하면 다음을 수행할 수 있습니다.
    1. 새 외부 공급업체 범주를 만들고 이러한 범주를 모델 범주에 매핑합니다.
      • 사용 가능한 경우 UNSPSC(United Nations Standard Products and Services Code)와 범주 이름을 사용합니다.
      • UNSPSC를 사용할 수 없는 경우에는 범주 이름만 사용합니다.
    2. 외부 공급업체 범주를 모델 범주에 매핑한 후 제조업체 부품 번호(MPN)를 사용하여 기존 제품 모델(사용 가능한 경우)을 찾습니다.
      1. MPN에 대한 제품 모델이 있는 경우 제품 모델을 변경 내용으로 업데이트한 다음 제품 모델과 관련된 공급자 제품을 생성하거나 업데이트합니다.
      2. MPN에 대한 제품 모델이 없는 경우 다음을 수행합니다.
        1. 제품 모델 클래스는 일반적으로 제품의 외부 공급업체 범주에서 참조하는 모델 범주에서 사용할 수 있습니다. 이 제품 모델 클래스를 사용하여 하드웨어, 소프트웨어, 소모품 등 제품 모델을 생성해야 하는 제품 모델 테이블을 가져옵니다. 사용할 수 있는 제품 모델 클래스가 없는 경우 기본 제품 모델 테이블에서 제품 모델을 생성합니다.
        2. 올바른 제품 모델 클래스가 식별되면 다음과 같이 올바른 클래스에 새 제품 모델을 생성합니다.
          • 제조업체, 게시자 또는 제공자는 제품 모델의 제조업체에 매핑해야 합니다.
          • API의 제품 이름은 제품 모델의 이름에 매핑해야 합니다.
          • API의 MPN은 모델 번호를 업데이트해야 합니다.
          • API의 제품 설명은 제품 모델에 대한 설명을 업데이트해야 합니다.
          • 모델 범주는 외부 공급업체 범주 기록에서 참조한 제품 범주로 업데이트해야 합니다.
          • 제품 범주는 외부 공급업체 범주 기록에서 참조한 제품 범주로 업데이트해야 합니다.
          • API의 대체 제품에 값이 있는 경우 현재 제품 모델과 다른 제품 모델 간에 대체 제품 기록을 생성합니다.
          • API의 호환 제품에 값이 있는 경우 현재 제품 모델과 다른 제품 모델 간에 호환 제품 기록을 생성합니다.
          • API의 제품 속성은 제품 모델의 제품 속성 관련 목록에서 생성되거나 업데이트되어야 합니다.
    3. 제품 모델을 사용할 수 있는 경우 공급자 부품 번호를 사용하여 제품 모델과 관련된 공급자 제품을 생성하거나 업데이트합니다.

    외부 공급업체 매핑

    다음 테이블을 사용하여 외부 공급업체 범주, 모델, 단위 매핑을 수행합니다.
    • 외부 공급업체 범주: ShoppingHub 관리자가 내부 기존 모델 범주와 매핑할 수 있도록 모든 외부 공급업체 범주 기록을 저장합니다.
    • 외부 공급업체 모델 매핑: 제품 모델과 외부 공급업체 모델 범주 간의 모든 매핑 정보를 저장합니다.
    • 외부 공급업체 단위: ShoppingHub 관리자가 공급자 제품 단위와 매핑할 수 있도록 모든 외부 공급업체 단위 기록을 저장합니다.
    • 외부 공급업체 단위 매핑: 제품 모델과 외부 공급업체 단위 간의 모든 매핑 정보를 저장합니다.
    주:
    외부 공급업체 통합 제품은 외부 공급업체 범주와 외부 공급업체 단위가 모두 적절하게 매핑되면 자동으로 게시됩니다.

    공급자 제품 판매 날짜

    공급자 제품은 판매 종료 날짜가 되면 중단되고 더 이상 카탈로그에 게시되지 않습니다. 공급자 제품 양식의 판매 시작 날짜 및 판매 종료 날짜 필드는 카탈로그 API에서 외부 공급업체 통합을 통해 채워집니다.

    상태 테이블

    대량 제품 임포트 요청의 상태를 확인하려면 테이블 REST API를 사용하여 ServiceNow 데이터베이스에 대한 REST 호출을 수행합니다. API 응답에는 대량 임포트 요청이 실패한 기록이 나열됩니다. 대량 제품 임포트 응답의 경우 다음 매개변수를 사용하여 카탈로그 오류 테이블을 쿼리합니다.

    sysparm_query=outbound_error.supplier_id=<supplier_id>^outbound_error.state=20

    고객 ID, 공급자 ID, 오류 유형, 고유 임포트 세트 ID, 상태에 대한 상세 정보는 상위 오류 테이블인 아웃바운드 상태 테이블에서 확인할 수 있습니다.

    URL 형식

    /api/sn_spend_intg/spendint/catalog

    지원되는 요청 매개변수

    표 1. 경로 매개변수
    이름 설명
    없음
    표 2. 쿼리 매개변수
    이름 설명
    모드 외부 공급업체 통합을 위한 비동기 및 동기 모드를 지원합니다.

    데이터 유형: 문자열

    유효한 값은 다음과 같습니다.
    • async: 비동기 모드입니다.
    • sync: 동기 모드입니다.

    기본값: async
    표 3. 요청 본문 매개변수(XML 또는 JSON)
    이름 설명
    customer_id 고객의 식별자입니다.

    데이터 유형: 문자열

    최대 길이: 100
    catalog_id 고객이 구매할 수 있는 카탈로그 컨텐츠의 식별자입니다.

    데이터 유형: 문자열

    최대 길이: 100
    제품 생성하거나 업데이트할 제품을 정의하는 객체 목록입니다. 각 트랜잭션은 제품 한도가 1,000개입니다.

    데이터 유형: 배열

    "products": [
  {
    "available_units": "String",
    "available_for_country": [Array],
    "bundled_components": [Array],
    "contract_agreement": {Object},
    "delivery_time": "String",
    "images": [Array],
    "manufacturer": "String",
    "mpn": "String",
    "parent_bundle": "String",
    "product_attributes": {Object},
    "product_category_name": "String",
    "product_description": "String",
    "product_name": "String",
    "sku": "String",
    "unit": "String",
    "unspsc": "String",
  }
]
    products.available_units 재고로 보관되는 제품에 필요합니다. 이 값은 이 제품에 사용할 수 있는 단위 수량을 나타냅니다.

    데이터 유형: 문자열

    최대 길이: 40
    products.available_for_country 공급자 제품을 구입할 수 있는 국가 코드 목록입니다. 제공된 국가가 없으면 어느 국가에서나 사용자가 제품을 구매할 수 있습니다.

    데이터 유형: 배열

    "available_for_country": ["US","IN","GB"]
    products.bundled_components 제품 번들을 카탈로그 페이로드의 일부로 보내는 시나리오에만 유효하며 상위 번들 페이로드에만 적용됩니다. 이 값에는 하위 번들 구성요소에 대한 참조가 포함됩니다. MPN 목록과 하위 번들 구성요소에 대한 수량이 여기에 유지됩니다.
    주:
    동일한 하위 번들 구성요소를 번들 내에 두 번 이상 추가할 수 있으므로 입력한 수량으로 인해 동일한 하위 번들 구성요소 간의 차이가 발생합니다.
    하위 번들 구성요소와 해당 상세 정보(MPN 및 수량)는 동일한 공급자에 매핑되어야 합니다.

    데이터 유형: 배열

    "bundled_components": [
  {
    "mpn": "String",
    "quantity": "String"
  }
]
    products.contract_agreement 제품 계약에 대한 상세 정보입니다.
    주:
    하위 번들 구성요소에는 필요하지 않습니다.

    데이터 유형: 객체

    "contract_agreement": {
  "contract_end_date": "String",
  "contract_number": "String",
  "contract_start_date": "String",
  "negotiated_currency ": "String",
  "negotiated_price": "String"
}
    products.contract_agreement.contract_end_date 계약 조건이 종료되는 날짜입니다.

    데이터 유형: 문자열

    최대 길이: 40

    형식: YYYY-MM-DD
    products.contract_agreement.contract_number 필수입니다. 제품과 관련된 활성 계약의 번호입니다.

    데이터 유형: 문자열

    최대 길이: 100
    products.contract_agreement.contract_start_date 계약 조건이 시작되는 날짜입니다.

    데이터 유형: 문자열

    최대 길이: 40

    형식: YYYY-MM-DD
    products.contract_agreement.negotiated_currency 필수입니다. 협상된 가격의 통화입니다.

    데이터 유형: 문자열

    최대 길이: 40
    products.contract_agreement.negotiated_price 필수입니다. 공급자 또는 리셀러와 계약을 통해 협상한 제품의 단가입니다.

    데이터 유형: 문자열

    최대 길이: 40
    products.delivery_time 제품을 고객에게 배송하는 데 걸리는 예상 일 수입니다. 이 값은 일 수를 나타내며 정수여야 합니다.

    데이터 유형: 문자열

    최대 길이: 40
    products.images 공급자 제품에 대한 이미지 URL을 지정하는 문자열 목록입니다.

    데이터 유형: 배열
    products.manufacturer 필수입니다. 제품을 제조, 게시 또는 제공하는 회사입니다. 제품의 공급자 또는 리셀러가 아닙니다.

    데이터 유형: 문자열

    최대 길이: 100
    products.mpn 필수입니다. 제조업체, 게시자 또는 제공자가 제공하는 제품의 식별자입니다.
    주:
    SKU 값을 사용할 수 있는 경우 리셀러 상위 번들에는 필요하지 않습니다.

    데이터 유형: 문자열

    최대 길이: 100
    products.parent_bundle 제품 번들을 카탈로그 페이로드의 일부로 보내는 시나리오에만 유효하며 하위 번들 구성요소 페이로드에만 적용됩니다. 하위 번들 구성요소의 경우 상위 번들 구성요소에 대한 참조가 여기에 유지됩니다. 상위 MPN 및 SKU 값도 여기서 설정됩니다.

    데이터 유형: 문자열

    최대 길이: 100
    products.product_attributes 제품 속성을 정의하는 키-값 쌍의 목록입니다(예: "색": "스페이스 그레이"). 제품에 여러 속성이 허용됩니다. 그러나 가격 책정이나 재고 가용성에 영향을 미치는 속성만 API를 통해 제공되어야 합니다.

    데이터 유형: 객체
    products.product_category_name 필수입니다. unspsc 속성을 설정하지 않을 경우 입력하는 이름입니다. 이 이름은 제품이 속한 범주입니다. 이 범주 이름은 제품 쇼핑을 위한 상거래 시나리오에서 사용할 수 있습니다. 예를 들어, 파워 스트립 제품은 사무 기기 범주에 속할 수 있습니다.

    데이터 유형: 문자열

    최대 길이: 100
    products.product_description 상거래 경험에서 소비자에게 표시되는 제품에 대한 전체 설명입니다.
    주:
    공급자는 특히 하위 번들 구성요소가 있는 제품 번들 카탈로그 항목에 대해 여기서 최대한 설명하는 것이 좋습니다.

    데이터 유형: 문자열

    최대 길이: 65000
    products.product_name 필수입니다. 제품의 이름입니다.

    데이터 유형: 문자열

    최대 길이: 1000
    products.sku 필수입니다. 해당 공급자가 판매한 제품을 고유하게 식별하는 공급자가 생성한 번호입니다.

    데이터 유형: 문자열

    최대 길이: 100
    products.unit 필수입니다. 공급자가 해당 제품을 판매하는 단위 또는 요금입니다. 예를 들어, 개(piece), 시간 등이 있습니다.

    데이터 유형: 문자열

    최대 길이: 40
    products.unspsc 필수입니다. product_category_name 속성을 설정하지 않을 경우 입력하는 식별자입니다. 이 식별자는 제품이 속한 범주의 UNSPSC입니다. 예를 들어 UNSPSC 코드 43210000은 제품 범주 컴퓨터의 식별자입니다.

    데이터 유형: 문자열

    최대 길이: 100
    supplier_id 필수입니다. 고객이 주문할 수 있는 리셀러 또는 공급자의 식별자입니다.

    데이터 유형: 문자열

    최대 길이: 100
    third_party_import_id 외부 공급업체가 문자열 값을 전달하여 임포트한 데이터 세트를 고유하게 식별할 수 있는 식별자입니다.

    데이터 유형: 문자열

    최대 길이: 100

    헤더

    다음 요청 및 응답 헤더는 이 HTTP 작업에만 적용되거나 이 작업에 고유한 방식으로 적용됩니다.

    표 4. 요청 헤더
    헤더 설명
    수용 응답 본문의 데이터 형식입니다. 지원되는 유형은 application/json 또는 application/xml입니다.

    기본값: application/json
    주:
    Procurement Integration Framework에는 application/json 데이터 형식만 지원됩니다.
    표 5. 응답 헤더
    헤더 설명
    없음

    상태 코드

    다음 상태 코드는 이 HTTP 작업에 적용됩니다.

    표 6. 상태 코드
    상태 코드 설명
    성공 성공입니다. 요청이 성공적으로 처리되었습니다.
    실패 실패했습니다. 요청이 오류와 함께 처리되었습니다.

    응답 본문 매개변수(JSON)

    이러한 응답 본문 매개변수는 동기 모드에서 쿼리될 때 수신됩니다.
    이름 설명
    error_response_body sku, mpn 및 오류 메시지로 나열된 오류에 대한 설명입니다.

    데이터 유형: 배열
    error_response_body.error_message 자세한 오류 메시지입니다.

    데이터 유형: 문자열
    status_code "성공" 또는 "실패"와 같은 응답 상태입니다.

    데이터 유형: 문자열

    cURL 요청

    curl "https://instance.service-now.com/api/sn_spend_intg/spendint/catalog" \
--request POST \
--header "Accept:application/json" \
--user 'username':'password'
{"root": [{
  "customer_id": "AB-1234323",
  "catalog_id": "ACME CORP-12347898",
  "supplier_id": "SUP-123456",
  "third_party_import_id": "DELL1234567",
  "products": [
    {
      "product_name": "Apple MacBook Pro 13 Core i7",
      "mpn": "Z0WQ-20004301931",
      "sku": "55788741",
      "manufacturer": "Apple",
      "product_category_name": "Computer",
      "parent_bundle": "920-0045362002",
      "bundled_components": {
        "mpn": "Z0WQ-20004301931",
        "quantity": "4",
       },
      "unspsc": "43211500",
      "product_description": "Apple MacBook Pro 13 Core i7 2.8GHz 16GB 512GB - Touch Bar - Space Gray",
      "product_attributes": {
        "Color": "Space Grey",
        "RAM": "16GB",
        "Screen Size": "13inch"
      },
      "images": ["http://test123.image1.png", "http://test123.image2.jpeg"],
      "unit": "Each",
      "available_units": "4",
      "available_for_country": ["US","IN","GB"],
      "delivery_time": "4",
      "contract_agreement": {
        "contract_number": "34567892",
        "contract_start_date": "YYYY-MM-DD",
        "contract_end_date": "YYYY-MM-DD",
        "negotiated_price": "456",
        "negotiated_currency ": "USD"
      }
    }
  ]
}
]}

    가능한 응답:

    // Success response:
{
    "result": {
        "response": "success"
    }
}

// Error response:
{
    "result": {
        "response": [
            {
                "customer_id": "AB-1234323",
                "supplier_id": "SUP-123456",
                "third_party_import_id": "DELL1234567",
                "status_code": "failure",
                "error_response_body": [
                    {
                        "sku": "55788741",
                        "mpn": "Z0WQ-20004301931",
                        "error_message": "Field Value empty/Formatting issue Negotiated currency \n"
                    }
                ]
            }
        ]
    }
}