# Creates Third Party Codes

##### About Third-Party Interface Codes
Third-Party Interface Codes serve multiple use cases, as described below.
The primary use case is to define POS specific annotations known as Third Party Codes / Interfaces that can be added to item data.
<details id="tpcodes-and-enums">
<summary> Third-party interface codes and enumerated types explained </summary>
Use the `POST /interfaces/thirdpartycodes` endpoint to define codes specific to your system to serve as
enumerated values that can be assigned in Yellow Dog. Each one is associated with a
specified enumerated type. The developer defines the following properties:
- The interface code will belong to an enumerated type specified by the "type" property.
- A "code" property defines the enumerated value that this interface code will represent.
- A "description" property allows a human-friendly name to be attached to each interface code in Yellow Dog's UI.
- The interface code is scoped to a store specified by the "store.id" property.

If a new interface code is defined with a "type" name that has not yet been used in
the scope of the specified store, a new enumerated type will be created.
Interface codes are simply enumerated values that get grouped into enumerated types
where the "type" and "store.id" properties match.
</details>
<details id="tpcode-item-annotation">
<summary> Annotating items with third-party interface codes </summary>
A software developer integrating a POS or other system with a Yellow Dog inventory
database may find it necessary to annotate inventory items with their own
third-party interface codes. For example, they may want to be able to associate
particular items with specific menus on a POS terminal or tax categories.
They will also need to a way to know which items are relevant to the integration and
which items should be ignored.
The use of third-party interface codes to perform this annotation is a multi-step process:
- First, the developer designs enumerated types name-spaced to their integration for the annotations they care about.
- Second, they use the `POST /interfaces/thirdpartycodes` endpoint to define corresponding "type" and "code" properties.
- Third, instructions are provided to customers regarding when and how to annotate items with the specific third-party codes.
- Fourth, customers or support staff use drop down menus in the "Interfaces" tab associated with groups of items in `YDInv.exe` to apply one annotation per type.

Note that name-spacing need only be applied to the "type" property.
If the name of the integrated product is "ACME" and the purpose of the enumerated type
is a tax category, an appropriately name-spaced "type" property would be
"ACME_TaxCategory" with an underscore character separating the name-space from the
purpose name.
The instructions for annotating items will usually not expect items to be individually
annotated with third-party interface codes. The codes will most often be applied to a
level category, such as alcoholic beverages, so that all items belonging to that category
will inherit a specified interface code. Default codes can also be specified for all items
in a store and be overridden by individually assigning a code to an item.
</details>
<details id="tpcode-negated-annotation">
<summary> Defining a none-of-the-above value </summary>
When designing a list of enumerated values for a third-party code type that will be
used to annotate items, it is important to ask whether all possible cases have been
covered. It is often the case that some kind of none-of-the-above value needs to be
included to support items where the category itself is not relevant. Consider
***Example A***, which is used to specify a tax category. In addition to county and
state tax categories, an untaxed category is defined as a catch-all for items where
taxation is not relevant.
In YDInv.exe, there is an inherent option to leave a third-party code type as "not set",
meaning that none of the available values is chosen for that enumerated type. This
cannot be relied upon to serve as a none-of-the-above value because it does not provide
a way to override a default setting inherited from a level category or store. In order
to support a none-of-the-above selection, there has to be an explicit value that
represents it. This is true even if it is interpreted as having the same effect as
leaving the third-party code type "not set".
</details>
<details id="tpcode-item-map">
<summary> Populating items into POS item map with the special "ItemNumber" type </summary>
For sales-only integrations that are not pulling item data from Yellow Dog's API, Yellow Dog
populates sold items that have an ItemNumber in the sales data into the POS Item Map so that
the client can map those sold items to recipes. This is often used by F&B sites, or in cases
where the integration doesn't provide SKU in the sales data for direct item matching.
If the POS system integrating with Yellow Dog wants to allow the client to map unsold items
in the POS Item Map as well, they can post a special third-party interface code type called "ItemNumber".
This feature is helpful for larger sites with many stores where all items would need to be sold in
all stores in order to map sales via sold items. Posting ItemNumbers allows the client to map all
POS items to recipes in Yellow Dog stores even if they haven't been sold there yet. That means that
those POS items will match to the mapped Yellow Dog recipes automatically once they have been sold.
The ItemNumber third party code type serves as an enumerated type whose values are
POS specific item numbers to be populated into the `YDInv.exe` POS item map, which is
scoped to a specific store.
When using the `POST /interfaces/thirdpartycodes` endpoint to add POS items to an
item map, the usual interface code properties are specified and have the following
effects:
- "type" -- must be "ItemNumber".
- "code" -- specifies a number that the POS uses to uniquely identify the item on its side
- "description" -- will become the description field for the item
- "store.id" -- applies to the POS item map for the specified store
</details>

<details id="tpcode-store-wild-card">
<summary> Always define the store.id property </summary>
Though Yellow Dog's API will not prevent you from posting third party codes without a store.id,
it is important to always include a valid store.id as part of your third party codes.
This will prevent confusion for the client regarding which store(s) they need to assign the interface codes on
and whether certain codes are only available to specific stores or not. This is especially important for larger
sites that have many stores in a single Yellow Dog database, and may have integrations with multiple POS systems.
</details>
<br/>
##### Examples
For the examples that follow, select the corresponding sample payload from the pull-down
menu in the request pane.
<details id="ex-tpcode-tax-category">
<summary> Example A: Defining tax categories </summary>
***Example A*** defines a new enumerated type called "ACME_TaxCategory".
The "ACME_" prefix applies a name-space to associate this enumerated type with the POS
integration that defines it. Three enumerated values are added to this enumerated type
to represent county, state, and untaxed tax categories.
Note that each of the third-party interface codes created
to represent these enumerated values are scoped to the same store.
It will be the only store that can annotate level data or items with this enumerated type.
It may also be the only store that this ACME POS is configured to use.
</details>
<details id="ex-tpcode-modifier">
<summary> Example B: Defining a modifier flag </summary>
***Example B*** defines a new enumerated type called "ACME_ModifierFlag". As in
***Example A***, the name-space prefix and descriptive name are separated by an
underscore character. Since this is type is a flag, it defines "true" and "false"
enumerated values in the "code" properties. In this case, "true" and "false" are
just name strings with no special function other that their descriptive qualities.
Alternatively, "enabled" and "disabled" would also be reasonable values for an
enumerated type that is serving as a flag.
For reasons described above in the section entitled "Defining a none-of-the-above value",
it is necessary for any boolean flag type to explicitly define values for both the on and
off state such that the off state has the same effect as leaving the value "unset".
</details>
<details id="ex-tpcode-item-map">
<summary> Example C: Adding items to the POS item map </summary>
In ***Example C***, there is no name-space prefix because the special "ItemNumber" type
name is being used to add items to the POS item map of the specified store.
This is the only time that a developer
should specify an interface code type without a name-space prefix.
Note that the section entitled "Defining a none-of-the-above value" does not apply to
the special "ItemNumber" type.
</details>
<br/>

Endpoint: POST /interfaces/thirdPartyCodes
Version: v3.0: 3.30.0
Security: Auth API User Token

## Query parameters:

  - `suppressOutput` (boolean)

## Request fields (application/json-patch+json):

  - `id` (string)
    A unique identifier for the TPCode Record
            
This is autogenerated by Yellow Dog on creation of the record.

  - `type` (string, required)
    The Type of code being entered. This should be titled specifically for the third party integrator in Pascal case.
            
A common way to type specifically is to prepend the Type with the name of the integration.

This will be displayed in the Interfaces tab under the Accounting/Other section as "Integration Name Tax Grouping"

  - `code` (string, required)
    Identifier used by the Integrator to match certain behavior on their side of the integration.

  - `description` (string, required)
    User friendly description that will be displayed to the user as part of a drop down box titled by the `type`

  - `store` (object)

  - `store.id` (string)

## Response 201 fields (application/json):

  - `id` (string)
    A unique identifier for the TPCode Record
            
This is autogenerated by Yellow Dog on creation of the record.

  - `type` (string, required)
    The Type of code being entered. This should be titled specifically for the third party integrator in Pascal case.
            
A common way to type specifically is to prepend the Type with the name of the integration.

This will be displayed in the Interfaces tab under the Accounting/Other section as "Integration Name Tax Grouping"

  - `code` (string, required)
    Identifier used by the Integrator to match certain behavior on their side of the integration.

  - `description` (string, required)
    User friendly description that will be displayed to the user as part of a drop down box titled by the `type`

  - `store` (object)

  - `store.id` (string)

  - `store.code` (string | null)

  - `store.name` (string | null)

## Response 400 fields (application/json):

  - `type` (string | null)

  - `title` (string | null)

  - `status` (integer | null)

  - `detail` (string | null)

  - `instance` (string | null)

## Response 500 fields (application/json):

  - `message` (string | null)

  - `errors` (array | null)

  - `errors.message` (string | null)

  - `errors.extensions` (string | null)