Spendint API - POST /sn_spend_intg/spendint/orderack

  • Release version: Washingtondc
  • Updated February 1, 2024
  • 4 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Spendint API - POST /snspendintg/spendint/orderack

    The Spendint API allows users to update order information when shopping from third-party catalogs. Upon checkout, a purchase line is created to facilitate approvals and generate purchase orders within ServiceNow, which are then stored in Outbound Order and Outbound Order Line tables. Suppliers can access these tables to query pending orders.

    Show full answer Show less

    Key Features

    • Integration with ERP: Purchase orders and lines are submitted to ERP systems if applicable, remaining in a Pending Submission state until confirmed by the third-party integration or ERP.
    • Status Tracking: Suppliers can monitor order acknowledgment requests through the Table REST API, identifying any failures via the Order Acknowledgment Error table.
    • Request Flexibility: Supports asynchronous and synchronous modes for processing requests.
    • Detailed Request and Response Structure: The API accepts a well-defined structure for requests, including customer details, order numbers, status codes, and sales order lines.

    Key Outcomes

    By utilizing this API, ServiceNow customers can streamline procurement processes, ensure timely updates on order statuses, and facilitate communication between systems. Successful integration enhances order management efficiency and provides clarity on order confirmations and errors, leading to improved operational workflows.

    Updates order information for when a user shops for a product from a third-party catalog. When the user checks out, a purchase line is created so that approvals or other tasks for the purchase can be completed.

    When a purchase order is generated in the ServiceNow database, the order is pushed into the following tables:
    • Outbound Order: Contains the order header.
    • Outbound Order Line: Contains the order lines.

    Suppliers need to query these tables and fetch the orders that are pending against them. Suppliers should create a scoped app for Flow Designer actions for integrating with the ServiceNow database.

    Query the tables with the following parameters:
    • sysparm_query=supplier_id=<supplier_id>^purchase_order.status=20 for header
    • sysparm_query=purchase_order.supplier_id=<supplier_id>^purchase_order.status=20 for header
    When a purchase line is converted to a purchase order line, the following processes are run:
    1. The purchase order and purchase order line are submitted to the Enterprise Resource Planning (ERP), if applicable.
    2. The purchase order and purchase order line are transferred through integration to the third party with the customer ID, supplier ID, purchase order number, order date, purchase order amount, purchase order amount currency, and purchase order lines.
    3. The purchase order and purchase order line remain in the Pending Submission state until confirmation messages are received by both the third-party catalog integration and the ERP. After confirmation is received, the state is updated to Ordered. If there is no ERP integration involved, a confirmation message is required only from the third-party integration.

    Status tables

    To know the status of the order acknowledgment request, make a REST call into the ServiceNow database using the Table REST API. The response from the API lists the records where the order acknowledgment request failed. For an order acknowledgment response, query the Order Acknowledgment Error table with the following parameter:

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

    The details on the customer ID, supplier ID, error type, unique import set ID, and state can be found in the Outbound Status table, which is the parent error table.

    URL format

    /api/sn_spend_intg/spendint/orderack

    Supported request parameters

    Table 1. Path parameters
    Name Description
    None
    Table 2. Query parameters
    Name Description
    mode Support for asynchronous and synchronous modes for third-party integration.

    Data type: String

    Valid values:
    • async: Asynchronous mode.
    • sync: Synchronous mode.

    Default: async
    Table 3. Request body parameters (XML or JSON)
    Name Description
    customer_id Required. Identifier for the customer.

    Data type: String

    Maximum length: 100
    order_number Required. Purchase order number provided by the customer for this order.

    Data type: String

    Maximum length: 40
    sales_order_lines List of objects that define the sales order lines with unique updates for the purchases in this order.

    Data type: Array

    "sales_order_lines":[
  {
    "estimated_arrival_date": "String",
    "line_number": "String",
    "sales_order_line_number": "String"
  }
]
    sales_order_lines.estimated_arrival_date Estimated arrival date of the order.

    Data type: String

    Maximum length: 40

    Format: YYYY-MM-DD
    sales_order_lines.line_number Required. Purchase order line number that was generated by the customer for a particular purchase.

    Data type: String

    Maximum length: 40
    sales_order_lines.sales_order_line_number Sales order line number that was generated by the supplier. This number is required only for revisions to this purchase.

    Data type: String

    Maximum length: 40
    sales_order_number Number or value that is generated by the supplier for this order.

    Data type: String

    Maximum length: 40
    status_code Required. Status of the submitted order that confirms if the order was successfully placed.

    Data type: String

    Valid values:
    • confirmed: Order placed successfully.
    • rejected: Order not placed.
    status_message Message that is attached to a status code. For example, the message could be that the order was successfully placed and is on back order.

    Data type: String

    Maximum length: 1000
    supplier_id Required. Identifier for the reseller or supplier that the customer can place orders with.

    Data type: String

    Maximum length: 100
    third_party_import_id Identifier that enables a third party to pass a string value to uniquely identify a set of imported data.

    Data type: String

    Maximum length: 100

    Headers

    The following request and response headers apply to this HTTP action only or apply to this action in a distinct way.

    Table 4. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: application/json
    Note:
    Only the application/json data format is supported for Procurement Integration Framework.
    Table 5. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action.

    Table 6. Status codes
    Status code Description
    success Successful. The request was successfully processed.
    failure Unsuccessful. The request was processed with errors.

    Response body parameters (JSON)

    These response body parameters are received when queried in synchronous mode.
    Name Description
    error_response_body Description of the errors, listed by the sales order number, sales order line number, and the error message.

    Data type: Array
    error_response_body.error_message Detailed error message.

    Data type: String
    status_code Response status such as "success" or "failure."

    Data type: String

    cURL request

    curl "https://instance.service-now.com/api/sn_spend_intg/spendint/orderack" \
--request POST \
--header "Accept:application/json" \
--user 'username':'password'
{"root":[{
  "customer_id": "ACME CORP",
  "supplier_id": "SUP-123456",
  "third_party_import_id": "undefined",
  "order_number": "PO08903323",
  "sales_order_number": "SO03323212",
  "status_code": "CONFIRMED",
  "status_message": "BACKORDERED",
  "sales_order_lines":[
    {
      "line_number": "POL6789876",
      "sales_order_line_number": "SOL5678909",
      "estimated_arrival_date": "YYYY-MM-DD"
    }
  ]
}
]}

    Possible responses:

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

// Error response:
{
    "result": {
        "response": [
            {
                "customer_id": "ACME CORP",
                "supplier_id": "SUP-123456",
                "third_party_import_id": "undefined",
                "status_code": "failure",
                "error_response_body": [
                    {
                        "sales_order_number": "SO03323212",
                        "sales_order_line_number": "SOL5678909",
                        "error_message": "Field Value empty/Formatting issue Purchase order number\nField Value empty/Formatting issue Purchase order line number\n"
                    }
                ]
            }
        ]
    }
}