Migrating from Web Services v1

Both versions will be available in parallel during a limited transition period.

Major Security and Data Protection Objectives

  • OAuth-based authorization using LOOK4 ID v2
  • Authentication is mandatory for everything except for (a reduced version of) catalog data and downloading public catalogs
  • HTTPS only

More Reasons to Switch

  • Offering JSON representations in parallel to XML for everything that is not a standardized SPECTARIS document (like orders, catalogs etc.), making it easier to integrate into browser applications.
  • Use terms from standardized SPECTARIS documents consistently also across web service parameters and additional web-service related document types.
  • Improved performance, availability, and scalability.
  • New functionalities and improvements will only be available in v2.
  • HTTP/2 and IPv6 available.

Breaking Changes in Existing Web Services

  • OAuth authentication (see LOOK4 ID section for details). For every HTTP request, please include a valid OAuth access token (bearer token) in the Authorization header like this:

    Authorization: Bearer <your current access token>

  • New base URLs for testing and production environments, see Environments.

  • Replace the following web service URLs:

    • GET /CatalogService/GetCatalogInfos.ashx becomes /catalogs
    • The URL for downloading catalogs changes to /catalogs/supplierID/catalogID and can be taken directly from the catalog info response. The catalog version doesn’t need to be provided anymore; you will always get the currently activated catalog version.

  • Authentication is now mandatory for everything except for (a reduced version of) catalog data and downloading public catalogs.

  • We now use supplierID consistently across all calls to identify a supplier (company). If you currently use companyID or vatID somewhere, please replace it with supplierID. This value matches the supplierID attribute in the SPECTARIS catalogs.

  • We now use the terms Supplier (Suppliers) instead of Company (Companies), respectively, to be consistent with elements and attributes in SPECTARIS documents.

  • We now use catalogID consistently across all calls to identify a supplier’s catalog. If you currently use catalogResourceKey or resourceKey somewhere, please replace it with catalogID. This value matches the catalogID attribute in the SPECTARIS catalog format.

  • We now use versionID consistently across all calls to identity the version of a supplier’s catalog. If you currently use RevisionNumber or Revision somewhere, please replace it with versionID. This value matches the versionID attribute in the SPECTARIS catalog format. To match the new name, also RevisionDateTime was renamed to versionTimestamp.

Catalog Infos

  • For the XML representation of catalog infos, we now consistently use camelCasing for attribute names and PascalCasing for element names. This is also consistent with Spectaris XSD schemas.
  • For suppliers, the name1 and name2 attributes were replaced by a single name attribute.
  • The RevisionComment catalog attribute was removed. The content was often not meaningful or even confusing for users.
  • For the XML representation of catalog infos, we have removed all non-container elements in <CatalogInfo>. They are now represented as attributes to this tag (in camelCasing). This includes the following: catalogID, catalogName, catalogLanguage, versionID, versionTimestamp, validStartDate and validEndDate.
  • For the catalog infos request, the ProductGroups and ProductGroup elements have been renamed to ArticleTypes and ArticleType, to make it clear that this information is based on the ArticleType feature in the catalog itself.

Catalog Downloads

  • The download URL pattern has changed. However, you don’t need to assembly the URL yourself anymore, you can simply use the _downloadCatalogUrl attribute from the Catalog Infos response to download a catalog.
  • You don’t need to specify a revision or version anymore. Always the currently activated catalog will be provided.

Barcode List Downloads

  • The download URL pattern has changed. However, you don’t need to assembly the URL yourself anymore, you can simply use the _downloadBarcodeListUrl attribute from the Catalog Infos response. Absence of this attribute in Catalog Infos indicates that no barcode list is available for this catalog.
  • You will now get a single SPECTARIS BarcodeList XML document instead of a ZIP archive with sometimes multiple XML documents that had to be merged.

Placing Orders

  • The URL changed to v2/orders.

  • All order requests must be authenticated. The clientID attribute in the order document must be authorized for the provided access token.

  • There is a new optional URL parameter available, atomic. If set to true, the entire order will be rejected, and HTTP 400 will be returned, if any order item is invalid.

    The default behavior is to accept any valid order item, and to return HTTP 200 as long as there is at least one accepted order item.

  • There is a new optional URL parameter available, dryrun. If set to true, an OrderResponse document will be returned, but the order will not be persisted and processed.

    This can be used to validate an order without actually submitting it when successful.

Order Status

  • The URL changed to ​/v2​/orderstatus​/{supplierID}​/{clientID}. As before, you have to append the clientOrderID and/or the clientOrderItemID URL parameter for filtering.
  • The resulting SPECTARIS OrderResponse document now contains more details about the order and its items, if provided by the supplier.

ASN (Advanced Shipping Notes)

  • The URL for retrieving a list of available ASN document changed to /v2/asn/{supplierID}. You can use the same set of URL parameters for filtering as before.

  • The result set is limited to 1000 items. At the root level of the result you will find a new attribute, continuationToken. You can add this value as an URL parameter continuationToken to a subsequent request to this service, and you will only get items that were added later to our data set than the newest item on the previous request.

    You can use this new behavior either for paging through a huge result set. Or, if your application is persisting this token across sessions, you can use it to easily and reliably get all new ASN items that your application hasn’t seen before, without using any of the other filters (like date filters).

  • The URL for retrieving a single ASN document changed to /v2/asn/{supplierID}/{advancedShippingNoteID}.