Spendint API - POST /sn_spend_intg/spendint/orderack

  • Release version: Xanadu
  • Updated August 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 endpointPOST /snspendintg/spendint/orderackenables ServiceNow customers to update order information for purchases made from third-party catalogs. When users check out, purchase lines are created to manage approvals and related tasks. Upon generating purchase orders in ServiceNow, the orders are stored inOutbound Order(order headers) andOutbound Order Line(order details) tables. Suppliers can query these tables to retrieve pending orders based on supplier ID and purchase order status.

    Show full answer Show less

    This API supports integration workflows that communicate order acknowledgments from third-party suppliers back into ServiceNow, allowing synchronization of order states between ServiceNow, third-party catalogs, and optionally Enterprise Resource Planning (ERP) systems.

    Key Features

    • Order Status Updates: The API accepts order acknowledgment data including customer ID, supplier ID, purchase order number, status, and detailed sales order lines with estimated arrival dates.
    • Integration with ERP and Third Parties: Purchase orders and lines are submitted to ERP and third-party systems, remaining in pending submission state until confirmation messages are received.
    • Order Status Tracking: Customers can track order acknowledgment failures and errors by querying the Order Acknowledgment Error and Outbound Status tables through the Table REST API.
    • Supports Asynchronous and Synchronous Modes: The mode query parameter enables integration in either asynchronous (default) or synchronous modes based on third-party needs.
    • Request and Response Handling: The API expects JSON request bodies containing order details and returns JSON responses indicating success or detailed errors mapped to sales order numbers and lines.

    Practical Use for ServiceNow Customers

    • Create scoped apps or Workflow Studio actions to automate fetching pending orders from outbound tables and posting order acknowledgment updates back via this API.
    • Use the API to keep purchase order statuses synchronized with third-party suppliers, improving visibility and accuracy of order fulfillment.
    • Leverage error status queries to proactively manage and resolve order acknowledgment issues.
    • Configure request bodies carefully with required fields such as customerid, supplierid, ordernumber, statuscode, and detailed sales order lines to ensure accurate processing.
    • Handle the response codes to confirm successful updates or troubleshoot errors with detailed messages returned per line item.

    Expected Outcomes

    • Effective synchronization of purchase order acknowledgments between ServiceNow and third-party catalogs or ERP systems.
    • Improved procurement process automation through real-time order status updates.
    • Enhanced supplier collaboration by enabling suppliers to query and update orders directly via ServiceNow tables and the API.
    • Clear visibility into order acknowledgment errors facilitating prompt resolution.

    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 Workflow Studio 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"
                    }
                ]
            }
        ]
    }
}