1. Vendor Integration Guide
  2. Vendor Integration Overview

1 Vendor Integration Overview

Overview: A vendor can receive and confirm shipment of drop ship purchase orders by:

  • using the screens in the Vendor Portal for all activities, or

  • using the vendor integration between Oracle Retail Order Broker and the vendor’s system.

A vendor can also use a combination of these options; for example, the vendor can receive purchase orders through the vendor integration, and also use the Vendor Portal screens to confirm shipments and update purchase orders.

Included in the vendor integration: The vendor integration includes:

  • sending batches of new purchase orders to the vendor’s system when the vendor’s system requests them

  • enabling the vendor’s system to acknowledge receipt of a batch of purchase orders

  • confirming shipments of purchase orders, including the carrier (ship via) used, tracking number, weight, shipment date, and freight charges

Not included in the vendor integration: The vendor integration does not include:

  • modifying purchase orders, such as changing expected ship dates or putting a line on hold

  • accepting or rejecting address changes or cancellation requests from the retailer

  • receiving cost changes from the retailer

  • generating invoices and submitting them to the retailer

Each of these options is available in the Vendor Portal if the vendor user has authority.

Mapping to the vendor’s system: The vendor can use the messages described in this guide to map to the vendor’s system, or contact an Oracle representative for information on creating unique maps.

JSON messages: The vendor integration uses the JSON (JavaScript Object Notation) format for its messages. See the messages in this guide for examples.

Process Overview

The typical vendor integration process:

  • Creation: Purchase orders are created in Oracle Retail Order Broker (the status is New Order and no batch numbers are assigned yet).

  • Get Purchase Orders:

    • The vendor system requests new orders with the getDSOrders Request Message to Oracle Retail Order Broker.

    • The getDSOrders Response Message from Oracle Retail Order Broker includes the new purchase orders. At this time:

      • a batch number is assigned to the purchase orders included in the response

      • the pack slip PDF, pack slip CSV, and pullsheet are generated, if specified for the vendor.

  • Acknowledgement Required?

    • Not required: If the vendor is not configured to require an acknowledgment, the status of the purchase orders in the response message changes automatically to In Process.

    • Required: Otherwise, if the vendor is configured to require acknowledgment, the status of the purchase orders remains New Order until the vendor system acknowledges receipt of the batch:

      Note:

      If acknowledgment is required and has not yet been received, the purchase orders are not included in the summary table at the Get Purchase Orders screen. Also, if an address change or cancellation request arrives during this interval, the change or cancellation applies automatically.

  • Confirm shipment: Optionally, as an alternative to using the shipment screens available in the Vendor Portal:


Order Broker Vendor Middleware Flowchart

Required Information and Setup

Required Information

Information required for the integration and used in the messages includes:

  • vendor code (vendorCd): The code, rather than the name, of the integrated vendor. Included in all requests to Oracle Retail Order Broker. Displayed at the Vendors screen in Oracle Retail Order Broker and at the Vendor Configuration screen in the Vendor Portal.

  • carrier code (carrierCd): The code, rather than the name, of the carrier shipping a purchase order. Displayed at the Carriers screen in Oracle Retail Order Broker and at the Carriers tab of the Vendor Configuration screen in the Vendor Portal.

  • destination: The name of the Oracle Retail Order Broker database. Must match the Account value specified at the Tenant - Admin screen; however, not case-sensitive. Normally set to locate.

  • version: Must be 4.5 or higher.

  • default vendor system (vendorSystemCd): the code identifying the default vendor system for the organization (the Vendor Default flag is selected at the System screen in Oracle Retail Order Broker). Note: Not the code identifying the system that originates the drop ship orders.

For more information: See:

  • Setting Up Data for the Supplier Direct Fulfillment Module in the Oracle Retail Order Broker online help

  • Additional Configuration Options in the Oracle Retail Order Broker Operations Guide

Integrated Vendor Configuration

In addition to the steps described under Setting Up Data for the Supplier Direct Fulfillment Module in the Oracle Retail Order Broker online help:

  • Oracle Retail Order Broker: When logged into Oracle Retail Order Broker as a retailer user, use the Create Vendor or Edit Vendor screen, Preferences tab:

    • Integration folder:

      • Select Enable Integration to display the Get Purchase Orders screen rather than the Select Purchase Orders screen in the Vendor Portal

      • Select Require Acknowledgement if the vendor needs to send the setDSAcknowledge request message for each batch of purchase orders

      • Select the Vendor Client Id to use when authenticating inbound messages through OAuth. Only client IDs that have been assigned Vendor web service access and have not been assigned to another vendor are available for selection. Note that before you can select the Vendor Client Id for the vendor, it needs to be created and assigned the Vendor web service access. See Web service authentication configuration, below, for more information on OAuth configuration and authentication for integrated vendors.

    • Pack Slip folder:

      • Use the Generate Format setting to specify whether to generate PDF pack slip, pack slip CSV, or both (Note: This setting is used only if the PDF Form Type setting is not set to None).

      • Use the PDF Form Type setting to specify whether to generate the pack slip PDF in graphical format, non-graphical format, or not to generate the PDF pack slip.

      • Use the Print Batch Pullsheet setting to specify whether to generate a PDF batch pullsheet along with the pack slip or pack slip CSV.

    • Invoices folder: Use these settings to control access to invoice generation options through the Vendor Portal screens. See the Oracle Retail Order Broker online help for more information.

    • Emails folder: Use these settings to control when to generate email notifications to the vendor and the email address(es) to use. See the Oracle Retail Order Broker online help for more information.

  • Configuration options in the Vendor Portal: Optionally, when logged into the Vendor Portal as a vendor user, use the Vendor Configuration screen, Preferences tab:

    • Pack Slip folder

      • Use the Generate Format setting to specify whether to generate PDF pack slip, pack slip CSV, or both (Note: This setting is used only if the PDF Form Type setting is not set to None).

      • Use the PDF Form Type setting to specify whether to generate the pack slip PDF in graphical format, non-graphical format, or not to generate the PDF pack slip.

      • Use the Print Batch Pullsheet setting to specify whether to generate a PDF batch pullsheet along with the pack slip or pack slip CSV.

    • Emails folder: Use these settings to control when to generate email notifications to the vendor and the email address(es) to use.

For more information: See the Oracle Retail Order Broker online help (New Vendor or Edit Vendor screens) or the Vendor Portal online help (Vendor Configuration screen).

Web service authentication configuration: OAuth web service authentication is required to authenticate the getDSOrders, setDSAcknowledge, and setDSConfirm messages from an integrated vendor.

For each integrated vendor, generate a new vendor-specific IDCS or OCI IAM client ID through the Manage External Application Access screen, with theApplication Type set to External. Then assign the Vendor web service access to each vendor client ID. You can assign this access through the Manage External Application screen. You can then assign the client ID to a single vendor, as described above.

About OAuth: With OAuth, each web service request must contain an OAuth "bearer" token in the Authorization header. The vendor-specific client ID and secret are used to request a token from IDCS (Oracle Identity Cloud Service) or OCI IAM (Oracle Cloud Infrastructure Identity and Access Management). The customer-specific IDCS or OCI IAM URL, in the format of http://idcs-DOMAIN.com/oauth2/v1/token, is used to get the token.

If authentication fails, Order Broker returns error code 3003: Invalid vendor code.

Logging

If the Vendor Portal Request/Response field at the Event Logging screen is set to Everything or Errors, Oracle Retail Order Broker logs the JSON messages.

All personally identifiable information for customers, vendors, or locations is removed in log files. Personally identifiable information includes names, address, email addresses, phone numbers, customer numbers, and tender accounts.

The personally identifiable information is replaced in the log with the text *** Removed by Logger ***. For example, the email address might appear in the log file as <email>*** Removed by Logger ***</email>.