The following explains how POS specific Third Party Codes / Interfaces can be applied to item data.
Note that in the Fetch API when you post new POS specific properties they are referred to as Third Party Codes, but when you get those POS specific properties as they are assigned to items they are referred to as Interfaces. For the Yellow Dog user, they are known as Interfaces.
When a third party pulls items from our API it is standard practice for them to have a minimum of one third party code that they post to our API’s ThirdPartyCodes endpoint as part of installation for their integration.
- This is generally a true/false option named using their company's / POS's name followed by "_Publish", which would designate to your code whether the item should be pulled into your system or not.
- For example if your POS's name is Acme, you would name yours "Acme_Publish".
- If true, you would pull that item into your system.
- If false or blank/null, you would NOT pull that item into your system.
Think about what other item specific properties your POS needs to know about that may not be present in a standard field that could be interpreted the same way for all customers. For each POS specific property that you need to know about, you can define a third party code / interface requirement, which is like an annotation for the items.
For example, your POS may need to flag an alcohol purchase so that the terminal operator knows that they need to ask the patron to present their ID. Some clients encode this into their level data but they don't all do it the same way. You can solve this by defining "Contains Alcohol" as a third party code / interface requirement, again, prepending with your company/POS name, "Acme_Contains Alcohol".
Other commonly used third party code / interface examples are [YourCompany/POSName]_Category ("Acme_Category") and [YourCompany/POSName]_TaxGroup ("Acme_TaxGroup"), but it is up to you to determine what is needed for your integration.
Note that these third party codes / interfaces will be set by the Level in Yellow Dog and inherited by the items assigned to that level. So even though you will be getting the interface from the item in the API, third party codes / interfaces are not normally assigned directly to the item in Yellow Dog's UI.
Although some interfaces may be location specific in your system, your code should look to a designated Primary Store for [YourCompany/POSName]_Publish and other non-location specific interfaces. This simplifies things in your code but also simplifies things for the customer, who will be trained to make all items they want published to your system available to the designated Primary Store for the integration and then will only have to set the interfaces on that store, as opposed to all stores the item is available to.
Think of each third party code / interface requirement that you encounter as a drop down menu that can select from two or more options. You will need a name for each third party code / interface requirement and for each option it contains. You must also decide which of these options should serve as a default when no option has been selected.
After the POS determines its item third party code / interface requirements, it uses the POST /interfaces/thirdPartyCodes endpoint to define them at installation time in the Yellow Dog database for a specific client. The client then works with the Yellow Dog implementation team to map categories of Item data (Levels) to the appropriate POS defined options for each third party code / interface requirement.
The POS decides which of its third party code / interface requirements must bear an explicit value for an item to be usable and which can can infer a default value when not specified. When the integration goes live, the POS periodically checks for updates to item data. It ignores any items that don't meet explicit requirements and applies default values where optional third party code / interface are unspecified.
See the POST /interfaces/thirdPartyCodes endpoint documentation for more information about defining POS specific annotations.