Calling Norce Commerce Connect
Norce Commerce Connect is a comprehensive integration framework for integrations between Norce and other systems. Norce Commerce connect handles integrations and normalization of data such as products, prices, customers (people and organisations) and inventory from suppliers, content providers and ERP/PIM/CRM systems.
Norce Commerce connect also handles order and transactional integrations between Norce and ERP systems.
API References
You can find the reference documentation here.
Code examples
See our Postman collection with connect examples here:
Read about how to use the postman examples.
There is also some older code examples (for .net standard)
How to call connect
Communication protocols
It is required to use REST in all integrations with Norce Commerce Connect.
Authentication and authorization
Norce Commerce Connect uses OAuth2 for authentication. The credentials is created in the Admin UI, see Accessing API's with OAuth2 accounts for more information.
HTTPS is required for all calls to and from the API.
Status codes
The Norce Commerce Connect's REST API uses the standard HTTP status codes.
Using asynchronous REST Calls
Norce Commerce Connect must receive some incoming rest calls asynchronously. This means that incoming calls is received, stored and processed later by workers. A job id is returned to the caller, for later check on the job status.
In the api, the following methods are asynchronous and requires the special header to control the behaviour of the API, see below:
| Documentation | Method | Description |
|---|---|---|
| Guide | ImportCompetitorSkus | Imports product data to the competitor entities, use this to import data to the product catalog from price comparison solutions. |
| Guide | ImportOnhands | Imports availability data to the product entities. |
| Guide | ImportPriceLists | Import price list entities. Use this to import campaigns and other price lists, like company agreements or contracts. |
| Guide | ImportProducts | Imports product content. Use this to import whole product catalogs. Only one price is allowed per product. Use ImportSkuPriceList to add more prices. To import availability data use ImportOnhands. |
| - | ImportRelations | Imports relations between products or variants. Use this to import relations only for the whole product catalog. |
| Guide | ImportSkuPriceLists | Imports price data to product entities. Use this to import prices, in a separate feed than the rest of the product data. |
| Guide | ImportCustomers | Insert or update customer information as well as connect or disconnect to account and/or companies. |
| Guide | ImportCompanies | Insert or update company information as well as connect or disconnect customers to the company. |
| Guide | ImportProducts | Imports supplier product catalogs. |
Special headers
The X-Storm-connect-Header must be specified for all incoming (asynchronous) calls to the Connect API. This contains the specific header object for the call. This object controls which fields that is updateable and other behaviors of the call.
X-Stormconnect-Header : {Header object}Note
The reason for this design is to improve performance, by only updating fields that have changed. To be able to do this, Norce Commerce Connect needs to know which fields to pay attention to and which fields to ignore. In addition to mandatory fields that must be set in the message body, the header must contain a list of message body fields, whose values Norce Commerce Connect should process.
Fields in the message body that are NOT defined in the message header list will be ignored by Norce Commerce Connect during the Import.
Jobs
All asynchronous calls to Norce Commerce Connect returns a job id if the call is successful. This can be tracked in the Admin UI here, as well as through the API calls - list job, get job, etc.
Use this JobId to track the progress of your import. Call Job.Get or wait on the JobCompletedEvent that you can subscribe to in the Admin UI, read about Norce Commerce Event here.
Restart a Job
If you need to rerun a job call the Job.Restart method. This takes the payload from your earlier method call and will rerun the job from the same data.
A job can only be restarted for so long the payload is stored in the Cache (about two weeks after the initial import).
Also, a job can only be restarted after it has finished its earlier run.
Using Norce Commerce Connect for data imports
The asynchronous methods are designed for updating many items as the same time and should not be used for one at a time updates. This will result in long lead times since there are large overheads in this kind of processes. Make sure to implement your integration as described below.
These asynchronous calls are specifically designed to work for high throughput of data that should update Norce Commerce. Design your integration so that it accumulate many changes and call Norce Commerce Connect every 60 minutes (or any time span, depending on your needs) with a list of items for update.
Note
Because of Norce Commerce Connect’s design, it is not advisable to handle your updates one at a time, This might cause Norce Commerce Connect’s queue to quickly grow and might result in much longer lead times than it would be, if you hade fewer calls with many changed items.
Special functionality
Client libraries
For .net platforms, Norce provides some client libraries as a nuget package. This contains the contracts and a REST helper class. See the example articles for more information in this.
Synchronous notifications
Most outgoing messages from Norce uses the Norce Commerce Event solution, giving an asynchronous publish-subscribe pattern. But for one scenario a more synchronous outgoing call is needed, since Norce has a specific workflow before and after the call to the external systems.
- Currently there are only some few scenarios using synchronous notifications.
- Read more on these here: Implementing an order receiver service and Shopping integrations and Shopping integrations
Common practices
Limitation
Norce Commerce Connect has a rate limit on 60 request/minute per customer.
Using system accounts
All calls to Norce Commerce Connect can have an AccountId in its request. This can be left out, but our best practice is to use it. This account is a specific system account that you can create in the Admin UI, here or use one from the list below.
Use different system accounts for all identifiable source system the client has. This makes it possible to track what system (or user) updated which data.
Common system accounts
| AccountId | Account name |
|---|---|
| Generic system names | |
| 10000 | ERP |
| 10001 | POS |
| 10002 | PIM |
| 10003 | Storefront |
| 10005 | CRM |
| 10006 | Marketplace |
| 10007 | Shipping service |
| 10008 | Translation service |
| Specific systems | |
| 10009 | Visma Business |
| 10010 | Visma.net |
| 10011 | Business central |
| 10013 | CDON marketplace |
| 10014 | Voyado |
| 1134976 | Visma |
| 1231903 | inRiver |
| 1233237 | M3 |
| 1408480 | Stibo |
| 10015 | Norce [Jetshop] |
| 10016 | Norce Feed |
| Additional system names | |
| 10017 | Legacy system |
| 10018 | old ERP |
| 10019 | old Commerce |
| 10020 | Store |
| 10021 | Integration |
| 10022 | Supplier 1 |
| 10023 | Supplier 2 |
| 10024 | Supplier 3 |
| 10025 | Bespoke |
Use "full" feeds at regular intervals
All imports in Norce Commerce Connect has the possibility to be marked as fullfile. When this flag is set true, Norce Commerce will deactivate all items that is missing in the feed. This "resets" the specific item catalogs.
The recommended practice is to update Norce Commerce Connect using change feeds (fullfile = false) as often as needed and at regular intervals (daily, weekly or monthly) send in the full catalog (fullfile = true). This creates a "self-repairing" process, where the full feed will find and fix any data irregularities.
Read about this here.
Postman examples
- You find some good examples on Norce Commerce Connect calls here .