### Getting Started with the API

Source: https://developer.xentral.com/reference

Instructions on how to get started with the Xentral API using the OpenAPI specification.

```APIDOC
## Getting started with the API

To get started right away with the API, you can use the Xentral OpenAPI spec: https://github.com/xentral/api-spec-public
```

--------------------------------

### Create Product Part - Node.js Example

Source: https://developer.xentral.com/reference/product-parts

This Node.js example shows how to create a new part for a product using the 'axios' library. It includes setting up the request URL, headers, and sending a POST request with a JSON body. Ensure 'axios' is installed (`npm install axios`).

```javascript
const axios = require('axios');

const createProductPart = async (xentralId, productId, partData) => {
  const url = `https://${xentralId}.xentral.biz/api/v1/products/${productId}/parts`;
  try {
    const response = await axios.post(url, partData, {
      headers: {
        'accept': 'application/json',
        'content-type': 'application/json'
      }
    });
    return response.data;
  } catch (error) {
    console.error('Error creating product part:', error.response ? error.response.data : error.message);
    throw error;
  }
};

// Example Usage:
// createProductPart('your_xentral_id', 'product_id', { name: 'New Part', sku: 'NP123' })
//   .then(data => console.log('Part created:', data))
//   .catch(err => console.error('Failed to create part'));
```

--------------------------------

### Exploring the API with Postman

Source: https://developer.xentral.com/reference

Step-by-step guide on how to import the Xentral API specification into Postman and start making requests.

```APIDOC
## Exploring the API with Postman

If you haven't installed Postman yet, you can download it from Postman's official website. Follow the installation instructions specific to your operating system.

### Importing the Xentral API specification

1. Launch Postman and create a new workspace or select an existing one.
2. Click on the `Import` button, typically found at the top-left corner.
3. Choose the `Link` tab.
4. In the URL field, paste the following URL: https://raw.githubusercontent.com/xentral/api-spec-public/main/openapi/xentral-api.openapi-3.0.0.json
5. Click Import to load our Xentral API specification into Postman.

### Configuring the Xentral API Collection

Once the API specification is imported, Postman will create a new collection named 'Xentral API'. You can now explore the various endpoints and methods available in our API.

### Making API requests

With the Xentral API collection loaded, you can start making API requests:

1. Select an endpoint from the 'Xentral API' collection.
2. Click on the `Send` button to execute the request.
3. Review the response in the 'Response' section below.

That's it! You're now ready to use our Xentral API with Postman. For more details on working with OpenAPI specifications in Postman, refer to Postman's official documentation. Happy coding!
```

--------------------------------

### Create Product Part - Python Example

Source: https://developer.xentral.com/reference/product-parts

This Python example uses the 'requests' library to create a new product part. It constructs the API endpoint URL, sets the necessary headers, and sends a POST request with the part data as JSON. Ensure 'requests' is installed (`pip install requests`).

```python
import requests
import json

def create_product_part(xentral_id: str, product_id: str, part_data: dict) -> dict:
    url = f"https://{xentral_id}.xentral.biz/api/v1/products/{product_id}/parts"
    headers = {
        'accept': 'application/json',
        'content-type': 'application/json'
    }
    try:
        response = requests.post(url, headers=headers, data=json.dumps(part_data))
        response.raise_for_status()  # Raise an exception for bad status codes
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error creating product part: {e}")
        return {}

# Example Usage:
# xentral_id = 'your_xentral_id'
# product_id = 'your_product_id'
# part_info = {'name': 'New Python Part', 'sku': 'PYN012'}
# created_part = create_product_part(xentral_id, product_id, part_info)
# print(created_part)
```

--------------------------------

### Get list of documentation (Node.js)

Source: https://developer.xentral.com/reference/documentation

Example Node.js code using the 'axios' library to make a GET request to the documentation API. It handles the response and logs the data. Ensure 'axios' is installed (`npm install axios`).

```javascript
const axios = require('axios');

const getDocumentation = async () => {
  try {
    const response = await axios.get('https://{xentralId}.xentral.biz/api/v1/analytics/documentation', {
      headers: {
        'accept': 'application/json'
      }
    });
    console.log(response.data);
  } catch (error) {
    console.error('Error fetching documentation:', error);
  }
};

getDocumentation();
```

--------------------------------

### Get list of documentation (Python)

Source: https://developer.xentral.com/reference/documentation

Example Python code using the 'requests' library to send a GET request to the documentation API. It prints the JSON response or an error message. Ensure 'requests' is installed (`pip install requests`).

```python
import requests

url = "https://{xentralId}.xentral.biz/api/v1/analytics/documentation"
headers = {
    "accept": "application/json"
}

try:
    response = requests.get(url, headers=headers)
    response.raise_for_status()  # Raise an exception for bad status codes
    print(response.json())
except requests.exceptions.RequestException as e:
    print(f"Error fetching documentation: {e}")
```

--------------------------------

### Product Creation Example

Source: https://developer.xentral.com/reference/productcreatev2

An example JSON object demonstrating the structure for creating a new product. This includes basic information, pricing details, and custom fields.

```json
{
  "name": "Test Product Beverage",
  "number": "123456",
  "description": "This is a very long description for the Test Product Beverage.",
  "shortDescription": "This is a short description.",
  "project": {
    "id": "7"
  },
  "customsTariffNumber": "12345678",
  "ean": "1234567890",
  "internalComment": "Attention: Only available for customers over the age of 18.",
  "minimumOrderQuantity": 100,
  "minimumStorageQuantity": 30,
  "allowPurchaseFromAllSuppliers": false,
  "hidePriceOnDocuments": false,
  "hasBatches": true,
  "serialNumbersMode": "disabled",
  "hasBestBeforeDate": true,
  "hasBillOfMaterials": false,
  "isAssembledJustInTime": false,
  "isProductionProduct": false,
  "isExternallyProduced": false,
  "isDisabled": false,
  "countryOfOrigin": "DE",
  "regionOfOrigin": "01",
  "salesTax": "standard",
  "isStockItem": true,
  "manufacturer": {
    "name": "Beverage Manufacturer",
    "number": "BM#1",
    "link": "https://example.com"
  },
  "ageRating": "18",
  "freeFields": [
    {
      "id": "8",
      "value": "FF8"
    },
    {
      "id": "16",
      "value": "FF16"
    },
    {
      "id": "32",
      "value": "FF32"
    }
  ]
}
```

--------------------------------

### Example: List Sales Prices for a Product

Source: https://developer.xentral.com/reference/productlistsalesprices-1

Provides a JSON example demonstrating how sales prices for a given product are listed. It includes details such as product ID, customer information, validity periods, amounts, and currency. This example helps developers understand the expected response format for sales price queries.

```json
{
  "data": [
    {
      "id": "2",
      "customer": {
        "id": "7",
        "name": "Thilo Altmann-Meyer"
      },
      "customerGroup": null,
      "validFrom": "2024-04-01",
      "expiresAt": "2024-04-30",
      "amount": 1,
      "price": {
        "amount": "0.16000000",
        "currency": "EUR"
      }
    },
    {
      "id": "17",
      "customer": null,
      "customerGroup": null,
      "validFrom": null,
      "expiresAt": "2024-12-12",
      "amount": 10,
      "price": {
        "amount": "3.00000000",
        "currency": "CHF"
      }
    },
    {
      "id": "16",
      "customer": null,
      "customerGroup": null,
      "validFrom": "2025-01-01",
      "expiresAt": null,
      "amount": 10,
      "price": {
        "amount": "3.00000000",
        "currency": "CHF"
      }
    }
  ],
  "extra": {
    "page": {
      "number": 1,
      "size": 10
    }
  }
}
```

--------------------------------

### GET /xentral/carriers

Source: https://developer.xentral.com/docs/setting-up-a-carrier

Registers available carriers and their shipping products with Xentral. This endpoint is called by Xentral during the setup process to validate the connection and retrieve carrier capabilities.

```APIDOC
## GET /xentral/carriers

### Description
This endpoint is used by Xentral to discover available shipping carriers and their services. It allows Xentral to automatically create shipping methods based on the response.

### Method
GET

### Endpoint
/xentral/carriers

### Parameters
#### Query Parameters
- **Accept-Language** (string) - Optional - Specifies the preferred language for the response. Example: `en-US`

### Request Headers
- **Accept**: `application/json`
- **Authorization**: `Bearer [token]` or `Basic [Base64 encoded user+pass]` or `Bearer [oAuth Token]`

### Request Example
```curl
curl --request GET \
     --url [https://your-carrier-service.com]/xentral/carriers \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer [token]' \
		 --header 'Accept-Language: en-US'
```

### Response
#### Success Response (200)
- **carriers** (array) - List of available carriers.
  - **name** (string) - The display name of the carrier.
  - **id** (string) - A unique identifier for the carrier.
  - **products** (array) - List of shipping products offered by the carrier.
    - **id** (string) - A unique identifier for the shipping product.
    - **name** (string) - The display name of the shipping product.
    - **description** (string) - A brief description of the shipping product.
    - **label** (object) - Defines label properties.
      - **type** (array of strings) - Supported label formats (e.g., `pdf`, `zpl`).
      - **size** (array of strings) - Supported label sizes (e.g., `A4`).
      - **orientation** (array of strings) - Supported label orientations (e.g., `portrait`).
    - **insurance** (object) - Defines insurance options.
      - **available** (boolean) - Indicates if insurance is available.
    - **shipmentType** (array of strings) - Supported shipment types (e.g., `outbound`, `return`).

#### Response Example
```json
{
  "carriers": [
    {
      "name": "Post Swiss",
      "id": "post-ch",
      "products": [
        {
          "id": "post-ch-express",
          "name": "Express",
          "description": "The express shipping method of Post Swiss",
          "label": {
            "type": [
              "pdf",
							"zpl"
            ],
            "size": [
              "A4"
            ],
            "orientation": [
              "portrait"
            ]
          },
          "insurance": {
            "available": true
          },
          "shipmentType": [
            "outbound",
            "return"
          ]
        }
      ]
    }
  ]
}
```

### Error Handling
- **401 Unauthorized**: Authentication failed.
- **406 Not Acceptable**: The `Accept` header is not `application/json`.
- **500 Internal Server Error**: An error occurred on the server.
```

--------------------------------

### Create Product Media (cURL)

Source: https://developer.xentral.com/reference/product-media-1

Example of creating product media using cURL. This demonstrates the POST request method, URL, and necessary headers for content type and acceptance.

```shell
curl --request POST \
     --url https://xentral.xentral.biz/api/v1/productMedia \
     --header 'accept: text/html' \
     --header 'content-type: application/json'
```

--------------------------------

### Retrieve Delivery Shipment Details in Node.js

Source: https://developer.xentral.com/reference/delivery-note

Example of fetching delivery shipment details using Node.js with the 'axios' library. This code makes a GET request to the xentral API and logs the response data. Ensure 'axios' is installed (`npm install axios`).

```javascript
const axios = require('axios');

const getDeliveryDetails = async (deliveryId) => {
    try {
        const response = await axios.get(`https://{xentralId}.xentral.biz/api/v1/deliveries/${deliveryId}`, {
            headers: {
                'accept': 'application/json'
            }
        });
        console.log(response.data);
        return response.data;
    } catch (error) {
        console.error('Error fetching delivery details:', error);
    }
};

// Example usage:
// getDeliveryDetails('DEL-12345');
```

--------------------------------

### POST /v1/products

Source: https://developer.xentral.com/reference/shippingmethodview

Creates a new product in the system.

```APIDOC
## POST /v1/products

### Description
Creates a new product in the system.

### Method
POST

### Endpoint
/v1/products

### Parameters
#### Request Body
- **name** (string) - Required - The name of the product.
- **sku** (string) - Required - The Stock Keeping Unit for the product.
- **price** (number) - Required - The price of the product.
- **description** (string) - Optional - A detailed description of the product.

### Request Example
```json
{
  "name": "New Gadget",
  "sku": "NG-007",
  "price": 99.99,
  "description": "A brand new, innovative gadget."
}
```

### Response
#### Success Response (201)
- **id** (integer) - The unique identifier for the newly created product.
- **name** (string) - The name of the product.
- **sku** (string) - The Stock Keeping Unit for the product.
- **price** (number) - The price of the product.
- **description** (string) - A detailed description of the product.

#### Response Example (201)
```json
{
  "id": 10,
  "name": "New Gadget",
  "sku": "NG-007",
  "price": 99.99,
  "description": "A brand new, innovative gadget."
}
```

#### Error Response (400)
- **error** (object) - Details about the error.
  - **type** (string) - The type of error, e.g., "https://api.xentral.biz/problems/generic-validation".
  - **title** (string) - A short description of the error.
  - **messages** (object) - An object where keys are field names and values are arrays of validation error messages.

#### Response Example (400)
```json
{
  "error": {
    "type": "https://api.xentral.biz/problems/generic-validation",
    "title": "Validation failed",
    "messages": {
      "name": [
        "Product name cannot be empty."
      ],
      "sku": [
        "SKU is already in use."
      ]
    }
  }
}
```
```

--------------------------------

### OAuth 2.0 Client Credentials Authentication Request Example

Source: https://developer.xentral.com/docs/setting-up-a-carrier

Example cURL request demonstrating OAuth 2.0 Client Credentials authentication for the /xentral/carriers endpoint. This involves an initial token request followed by a GET request using 'Authorization: Bearer [oAuth Token]'.

```curl
curl --request GET \
     --url [Service URL]/xentral/carriers \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer [oAuth Token]' \
		 --header 'Accept-Language: en-US'
```

--------------------------------

### Fetch Delivery Shipment Details in Python

Source: https://developer.xentral.com/reference/delivery-note

Python example using the 'requests' library to fetch delivery shipment details. This code sends a GET request to the xentral API and prints the JSON response. Make sure to install the library (`pip install requests`).

```python
import requests

def get_delivery_details(delivery_id, xentral_id):
    url = f"https://{xentral_id}.xentral.biz/api/v1/deliveries/{delivery_id}"
    headers = {
        'accept': 'application/json'
    }
    try:
        response = requests.get(url, headers=headers)
        response.raise_for_status()  # Raise an exception for bad status codes
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error fetching delivery details: {e}")
        return None

# Example usage:
# delivery_info = get_delivery_details('DEL-12345', '{xentralId}')
# if delivery_info:
#     print(delivery_info)
```

--------------------------------

### Product Creation Example in JSON

Source: https://developer.xentral.com/reference/productcreate-1

An example JSON object demonstrating the structure for creating a new product. It includes fields for name, identifiers, descriptions, hierarchical relationships (project, category), and inventory management details. This example is useful for understanding the required and optional fields for product creation.

```json
{
  "name": "Test Product Beverage",
  "number": "123456",
  "description": "This is a very long description for the Test Product Beverage.",
  "shortDescription": "This is a short description.",
  "project": {
    "id": "7"
  },
  "category": {
    "id": "1001"
  },
  "customsTariffNumber": "12345678",
  "ean": "1234567890",
  "internalComment": "Attention: Only available for customers over the age of 18.",
  "minimumOrderQuantity": 100,
  "minimumStorageQuantity": 30,
  "allowPurchaseFromAllSuppliers": false,
  "hidePriceOnDocuments": false,
  "hasBatches": true
}
```

--------------------------------

### Example Project Data Structure

Source: https://developer.xentral.com/reference/purchaseordercreate-1

Provides an example structure for project data, including a date and a nested project object. This illustrates the expected format for project-related data.

```json
{
  "date": "2024-01-01",
  "project": {
    "id": "1337"
  }
}
```

--------------------------------

### List Tax Rates in Node.js

Source: https://developer.xentral.com/reference/tax-rate-1

Example of fetching tax rates using Node.js with the 'axios' library. It makes a GET request to the taxRates endpoint and logs the response data. Ensure 'axios' is installed.

```javascript
const axios = require('axios');

const getTaxRates = async (countryCode) => {
  try {
    const response = await axios.get(`https://{xentralId}.xentral.biz/api/v1/taxRates/${countryCode}`, {
      headers: {
        'accept': 'application/json'
      }
    });
    return response.data;
  } catch (error) {
    console.error('Error fetching tax rates:', error);
    return null;
  }
};

// Example usage:
// getTaxRates('US').then(data => console.log(data));
```

--------------------------------

### Get list of documentation (Ruby)

Source: https://developer.xentral.com/reference/documentation

Example Ruby code using the 'net/http' library to make a GET request to the documentation API. It handles the response and prints the body. Error handling is basic.

```ruby
require 'net/http'
require 'uri'

uri = URI.parse("https://{xentralId}.xentral.biz/api/v1/analytics/documentation")

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri.request_uri)
request['accept'] = 'application/json'

response = http.request(request)

puts response.body
```

--------------------------------

### Product Configuration Details

Source: https://developer.xentral.com/reference/productcreate-1

This section details various configuration options available for products, including serial number handling, best before dates, bills of materials, and production types.

```APIDOC
## Product Configuration Details

### Description
Provides details on product configuration parameters, including serial numbers, best before dates, bills of materials, and production types.

### Method
GET

### Endpoint
/websites/developer_xentral/products/configuration

### Parameters
#### Query Parameters
- **serialNumbersMode** (string) - Optional - Specifies the mode for handling serial numbers (e.g., "disabled", "user", "product", "productAndWarehouse").
- **hasBestBeforeDate** (boolean | number | string) - Optional - Indicates if the product has a best before date. Accepts boolean, 0/1, or 'true'/'false' strings.
- **hasBillOfMaterials** (boolean | number | string) - Optional - Indicates if the product has a bill of materials. Accepts boolean, 0/1, or 'true'/'false' strings.
- **isAssembledJustInTime** (boolean | number | string) - Optional - Indicates if the product is assembled just in time. Accepts boolean, 0/1, or 'true'/'false' strings.
- **isProductionProduct** (boolean | number | string) - Optional - Indicates if the product is a production product. Accepts boolean, 0/1, or 'true'/'false' strings.
- **isExternallyProduced** (boolean | number | string) - Optional - Indicates if the product is produced externally. Accepts boolean, 0/1, or 'true'/'false' strings.

### Request Example
```json
{
  "serialNumbersMode": "product",
  "hasBestBeforeDate": true,
  "hasBillOfMaterials": false,
  "isAssembledJustInTime": true,
  "isProductionProduct": false,
  "isExternallyProduced": true
}
```

### Response
#### Success Response (200)
- **serialNumbersMode** (string) - The configured mode for serial number handling.
- **hasBestBeforeDate** (boolean) - True if the product has a best before date.
- **hasBillOfMaterials** (boolean) - True if the product has a bill of materials.
- **isAssembledJustInTime** (boolean) - True if the product is assembled just in time.
- **isProductionProduct** (boolean) - True if the product is a production product.
- **isExternallyProduced** (boolean) - True if the product is produced externally.

#### Response Example
```json
{
  "serialNumbersMode": "product",
  "hasBestBeforeDate": true,
  "hasBillOfMaterials": false,
  "isAssembledJustInTime": true,
  "isProductionProduct": false,
  "isExternallyProduced": true
}
```
```

--------------------------------

### Get list of documentation (cURL)

Source: https://developer.xentral.com/reference/documentation

Example cURL request to fetch the list of documentation. It specifies the GET method and the target URL. The 'accept' header is set to 'application/json' to indicate the desired response format.

```shell
curl --request GET \
     --url https://xentral.xentral.biz/api/v1/analytics/documentation \
     --header 'accept: application/json'
```

--------------------------------

### Create Product Media (Ruby)

Source: https://developer.xentral.com/reference/product-media-1

Demonstrates how to create product media using Ruby. This usually involves the 'Net::HTTP' module or a gem like 'httparty' to make the POST request.

```ruby
# Ruby example would go here, likely using Net::HTTP or httparty.
# Example structure:
/*
require 'net/http'
require 'uri'
require 'json'

def create_product_media(xentral_id, payload)
  uri = URI.parse("https://#{xentral_id}.xentral.biz/api/v1/productMedia")
  request = Net::HTTP::Post.new(uri)
  request['content-type'] = 'application/json'
  request.body = payload.to_json

  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
    http.request(request)
  end

  if response.is_a?(Net::HTTPSuccess)
    JSON.parse(response.body)
  else
    puts "Error creating product media: #{response.code} #{response.message}"
    nil
  end
end
*/
```

--------------------------------

### Example Product Media List Response

Source: https://developer.xentral.com/reference/productlistmedia-1

An example JSON response structure for listing product media, containing a 'data' array with individual product media objects.

```json
{
  "examples": {
    "Lists all product media": {
      "value": {
        "data": [
          {
            "id": "5",
            "product": {

```

--------------------------------

### List Parts Example

Source: https://developer.xentral.com/reference/productlistparts-1

This example demonstrates the expected JSON response when listing all parts of a given product. It includes an array of part data and pagination information.

```json
{
  "data": [
    {
      "id": "1301",
      "amount": "2.0000",
      "product": {
        "id": "1102",
        "name": "Fabric",
        "number": "346532"
      }
    }
  ],
  "extra": {
    "page": {
      "number": 1,
      "size": 10
    }
  }
}
```

--------------------------------

### Get Settings API Response (JSON)

Source: https://developer.xentral.com/reference/reporting-settings

This snippet shows an example JSON response for a successful (200) 'Get settings' API request. It details the structure of the returned settings, including delimiter, escapeSpecialCharacters, disableQuotes, and exportFormat.

```JSON
{
  "data": [
    {
      "delimiter": ",",
      "escapeSpecialCharacters": true,
      "disableQuotes": false,
      "exportFormat": "txt"
    }
  ]
}
```

--------------------------------

### Get list of documentation (PHP)

Source: https://developer.xentral.com/reference/documentation

Example PHP code using cURL to make a GET request to the documentation API. It sets the necessary options for the cURL request and outputs the JSON response. Error handling is included.

```php
<?php

$url = 'https://{xentralId}.xentral.biz/api/v1/analytics/documentation';

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'accept: application/json'
));

$response = curl_exec($ch);

if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
} else {
    echo $response;
}

curl_close($ch);
?>
```

--------------------------------

### API Response Example (Products)

Source: https://developer.xentral.com/reference/productidentifyproduct

Provides an example of a successful API response when retrieving a list of products. It includes the 'data' array with product details and the 'extra' object containing pagination information.

```json
{
  "data": [
    {
      "id": "2",
      "name": "Coca Cola"
    },
    {
      "id": "4",
      "name": "beer"
    },
    {
      "id": "5",
      "name": "mate"
    }
  ],
  "extra": {
    "totalCount": 53841,
    "page": {
      "number": 1,
      "size": 3
    }
  }
}
```

--------------------------------

### Get Credit Information API Request (Shell)

Source: https://developer.xentral.com/reference/credit

Example cURL command to retrieve credit information from the xentral API. It specifies the GET request method, the API endpoint URL, and the 'accept' header for JSON response.

```shell
curl --request GET \
     --url https://xentral.xentral.biz/api/v1/analytics/credit \
     --header 'accept: application/json'
```

--------------------------------

### Product Example Data

Source: https://developer.xentral.com/reference/productidentifyproduct

Provides example data for a product in multiple languages.

```APIDOC
## GET /websites/developer_xentral/products/{productId}/example

### Description
Retrieves example data for a product, including multilingual content.

### Method
GET

### Endpoint
/websites/developer_xentral/products/{productId}/example

### Parameters
#### Path Parameters
- **productId** (string) - Required - The unique identifier of the product.

### Response
#### Success Response (200)
- **inCatalog** (boolean) - Indicates if the product is in the catalog.
- **primaryLanguage** (object) - Product details in the primary language.
  - **name** (string) - Product name.
  - **shortDescription** (string) - Short description of the product.
  - **description** (string) - Detailed description of the product.
  - **shopDescription** (string) - Shop description for the product.
  - **metaTitle** (string) - Meta title for SEO purposes.
  - **metaDescription** (string) - Meta description for SEO purposes.
  - **metaKeywords** (string) - Comma-separated keywords for SEO.
  - **catalogName** (string) - Name of the product catalog.
  - **catalogText** (string) - Detailed text content for the product catalog.
- **english** (object) - Product details in English.
  - **name** (string) - Product name.
  - **shortDescription** (string) - Short description of the product.
  - **description** (string) - Detailed description of the product.
  - **shopDescription** (string) - Shop description for the product.
  - **metaTitle** (string) - Meta title for SEO purposes.
  - **metaDescription** (string) - Meta description for SEO purposes.
  - **metaKeywords** (string) - Comma-separated keywords for SEO.
  - **catalogName** (string) - Name of the product catalog.
  - **catalogText** (string) - Detailed text content for the product catalog.

#### Response Example
```json
{
  "inCatalog": true,
  "primaryLanguage": {
    "name": "Produkt eins",
    "shortDescription": "Kurze Beschreibung des Produkts.",
    "description": "Dies ist eine detaillierte Produktbeschreibung.",
    "shopDescription": "Verkaufsbeschreibung für den Shop.",
    "metaTitle": "Produkt SEO-Titel",
    "metaDescription": "Meta-Beschreibung für das Produkt.",
    "metaKeywords": "Produkt, SEO, Keywords",
    "catalogName": "Produktkatalogname",
    "catalogText": "Detaillierter Katalogtext für das Produkt."
  },
  "english": {
    "name": "Product One",
    "shortDescription": "Short description of the product.",
    "description": "This is a detailed product description.",
    "shopDescription": "Shop description for the product.",
    "metaTitle": "Product SEO Title",
    "metaDescription": "Meta description for the product.",
    "metaKeywords": "product, SEO, keywords",
    "catalogName": "Product Catalog Name",
    "catalogText": "Detailed catalog text for the product."
  }
}
```
```

--------------------------------

### Create Product Media (Python)

Source: https://developer.xentral.com/reference/product-media-1

Provides a Python example for creating product media. This typically uses the 'requests' library to send a POST request with JSON payload.

```python
# Python example would go here, likely using the requests library.
# Example structure:
/*
import requests

def create_product_media(xentral_id, payload):
    url = f"https://{xentral_id}.xentral.biz/api/v1/productMedia"
    headers = {
        "content-type": "application/json"
    }
    try:
        response = requests.post(url, json=payload, headers=headers)
        response.raise_for_status()  # Raise an exception for bad status codes
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error creating product media: {e}")
        return None
*/
```

--------------------------------

### GET Storage Locations List (Python)

Source: https://developer.xentral.com/reference/storage-location-1

Example Python script using the 'requests' library to get storage locations. It includes basic error handling and JSON parsing.

```python
import requests

url = "https://{xentralId}.xentral.biz/api/v1/warehouses/{warehouseId}/storageLocations"
headers = {
    'accept': 'application/json'
}

try:
    response = requests.get(url, headers=headers)
    response.raise_for_status()  # Raise an exception for bad status codes (4xx or 5xx)
    data = response.json()
    print(data)
except requests.exceptions.RequestException as e:
    print(f"Error fetching storage locations: {e}")

```

--------------------------------

### GET Storage Locations List (Node.js)

Source: https://developer.xentral.com/reference/storage-location-1

Example Node.js (using fetch) request to retrieve storage locations. This demonstrates how to make the GET request and handle the JSON response.

```javascript
// Node.js example using fetch (requires Node.js v18+ or a polyfill)

const options = {
  method: 'GET',
  headers: {
    'accept': 'application/json'
  }
};

fetch('https://{xentralId}.xentral.biz/api/v1/warehouses/{warehouseId}/storageLocations', options)
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error('Error fetching storage locations:', error);
  });

```

--------------------------------

### Product Information Example (JSON)

Source: https://developer.xentral.com/reference/productview-1

This JSON object demonstrates the structure for a single product, including its ID, name, number, category, stock count, and associated options. It also shows variant information and measurement details.

```json
{
  "id": "1",
  "uuid": "018a2690-647a-7a8b-b100-cfc11ab7d4e8",
  "name": "Screw M10x20",
  "description": null,
  "shortDescription": null,
  "number": "700001",
  "project": {
    "id": "1",
    "name": "Standard project"
  },
  "category": {
    "id": "2",
    "name": "Service"
  },
  "standardSupplier": {
    "id": "7"
  },
  "stockCount": 22,
  "shopPriceDisplay": "0.00",
  "ean": null,
  "manufacturer": {
    "name": null,
    "number": null,
    "url": null
  },
  "customsTariffNumber": null,
  "options": [
    {
      "id": "1",
      "name": "Color",
      "values": [
        {
          "id": "1",
          "name": "blue",
          "sort": 1
        },
        {
          "id": "2",
          "name": "red",
          "sort": 2
        }
      ]
    }
  ],
  "selectedOptions": [],
  "variants": [
    {
      "id": "15",
      "options": [
        {
          "id": "1"
        }
      ]
    },
    {
      "id": "16",
      "options": [
        {
          "id": "2"
        }
      ]
    }
  ],
  "isVariant": false,
  "variantOf": null,
  "mainVariant": {
    "id": "15"
  },
  "thumbnailUrl": null,
  "thumbnailId": null,
  "tags": [],
  "freeFields": [],
  "countryOfOrigin": "DE",
  "regionOfOrigin": "",
  "internalComment": "",
  "isDeleted": false,
  "measurements": {
    "weight": {
      "value": 0,
      "unit": "kg"
    },
    "netWeight": {
      "value": 0,
      "unit": "kg"
    },
    "length": {
      "value": 0,
      "unit": "cm"
    },
    "width": {
      "value": 0,
      "unit": "cm"
    },
    "height": {
      "value": 0,
      "unit": "cm"
    }
  }
}
```

--------------------------------

### Create Product Part - Ruby Example

Source: https://developer.xentral.com/reference/product-parts

This Ruby example demonstrates creating a new product part using the 'net/http' library. It constructs the request, sets headers, and sends a POST request with a JSON payload. The response is then parsed.

```ruby
require 'net/http'
require 'uri'
require 'json'

def create_product_part(xentral_id, product_id, part_data)
  uri = URI.parse("https://#{xentral_id}.xentral.biz/api/v1/products/#{product_id}/parts")
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(uri.request_uri)
  request['Accept'] = 'application/json'
  request['Content-Type'] = 'application/json'
  request.body = part_data.to_json

  response = http.request(request)
  JSON.parse(response.body)
rescue => e
  puts "Error creating product part: #{e.message}"
  nil
end

# Example Usage:
# product_id = 'your_product_id'
# xentral_id = 'your_xentral_id'
# part_info = { name: 'New Ruby Part', sku: 'RNP456' }
# created_part = create_product_part(xentral_id, product_id, part_info)
# puts "Created Part: #{created_part}"
```

--------------------------------

### List Delivery Terms - Ruby Example

Source: https://developer.xentral.com/reference/products-api-copy

Provides an example of listing delivery terms in Ruby. This snippet illustrates making an HTTP GET request to retrieve delivery term data.

```ruby
# Placeholder for Ruby code snippet
```

--------------------------------

### GET Storage Locations List (Ruby)

Source: https://developer.xentral.com/reference/storage-location-1

Example Ruby script using the 'httparty' gem to make a GET request for storage locations. Demonstrates sending headers and processing the response.

```ruby
require 'httparty'

url = "https://{xentralId}.xentral.biz/api/v1/warehouses/{warehouseId}/storageLocations"
headers = {
  'accept' => 'application/json'
}

begin
  response = HTTParty.get(url, headers: headers)
  if response.success?
    puts response.parsed_response
  else
    puts "Error fetching storage locations: HTTP #{response.code} - #{response.message}"
  end
rescue StandardError => e
  puts "An error occurred: #{e.message}"
end

```

--------------------------------

### Standard API Documentation

Source: https://developer.xentral.com/reference

Information about accessing the legacy standard API documentation and Postman collection.

```APIDOC
## Standard API

If you need the (legacy) standard API, you can find the documentation here: https://update.xentral.biz/apidoc/docs211.html, and a postman collection in the same GitHub repository: https://github.com/xentral/api-spec-public
```

--------------------------------

### Basic Authentication Request Example

Source: https://developer.xentral.com/docs/setting-up-a-carrier

Example cURL request demonstrating Basic Authentication for the /xentral/carriers endpoint. This method uses an 'Authorization: Basic [Base64 encoded user+pass]' header for authentication.

```curl
curl --request GET \
     --url [Service URL]/xentral/carriers \
     --header 'Accept: application/json' \
     --header 'Authorization: Basic [Base64 encoded user+pass]' \
		 --header 'Accept-Language: en-US'
```

--------------------------------

### Create Product

Source: https://developer.xentral.com/reference/productcreatev2

This endpoint allows you to create a new product with detailed specifications.

```APIDOC
## POST /websites/developer_xentral/products

### Description
Allows the creation of a new product with detailed specifications, including name, pricing, inventory, and supplier information.

### Method
POST

### Endpoint
/websites/developer_xentral/products

### Parameters
#### Request Body
- **name** (string) - Required - The name of the product.
- **number** (string) - Optional - The product number.
- **description** (string) - Optional - A detailed description of the product.
- **shortDescription** (string) - Optional - A brief description of the product.
- **project** (object) - Optional - Project details for the product.
  - **id** (string) - Required - The identifier for the project.
- **customsTariffNumber** (string) - Optional - The customs tariff number.
- **ean** (string) - Optional - The EAN barcode number.
- **internalComment** (string) - Optional - Internal comments about the product.
- **minimumOrderQuantity** (integer) - Optional - The minimum order quantity.
- **minimumStorageQuantity** (integer) - Optional - The minimum storage quantity.
- **allowPurchaseFromAllSuppliers** (boolean) - Optional - Whether to allow purchase from all suppliers.
- **hidePriceOnDocuments** (boolean) - Optional - Whether to hide the price on documents.
- **hasBatches** (boolean) - Optional - Whether the product uses batches.
- **serialNumbersMode** (string) - Optional - The serial number tracking mode ('disabled', 'per_batch', 'per_item').
- **hasBestBeforeDate** (boolean) - Optional - Whether the product has a best before date.
- **hasBillOfMaterials** (boolean) - Optional - Whether the product has a bill of materials.
- **isAssembledJustInTime** (boolean) - Optional - Whether the product is assembled just in time.
- **isProductionProduct** (boolean) - Optional - Whether the product is a production product.
- **isExternallyProduced** (boolean) - Optional - Whether the product is externally produced.
- **isDisabled** (boolean) - Optional - Whether the product is disabled.
- **countryOfOrigin** (string) - Optional - The country of origin.
- **regionOfOrigin** (string) - Optional - The region of origin.
- **salesTax** (string) - Optional - The sales tax rate ('standard', 'reduced', 'none').
- **isStockItem** (boolean) - Optional - Whether the product is a stock item.
- **manufacturer** (object) - Optional - Manufacturer details.
  - **name** (string) - Required - The manufacturer's name.
  - **number** (string) - Optional - The manufacturer's number.
  - **link** (string) - Optional - A link to the manufacturer's website.
- **ageRating** (string) - Optional - The age rating for the product.
- **freeFields** (array) - Optional - An array of free field values.
  - **id** (string) - Required - The identifier of the free field.
  - **value** (string) - Required - The value of the free field.

### Request Example
```json
{
  "name": "Test Product Beverage",
  "number": "123456",
  "description": "This is a very long description for the Test Product Beverage.",
  "shortDescription": "This is a short description.",
  "project": {
    "id": "7"
  },
  "customsTariffNumber": "12345678",
  "ean": "1234567890",
  "internalComment": "Attention: Only available for customers over the age of 18.",
  "minimumOrderQuantity": 100,
  "minimumStorageQuantity": 30,
  "allowPurchaseFromAllSuppliers": false,
  "hidePriceOnDocuments": false,
  "hasBatches": true,
  "serialNumbersMode": "disabled",
  "hasBestBeforeDate": true,
  "hasBillOfMaterials": false,
  "isAssembledJustInTime": false,
  "isProductionProduct": false,
  "isExternallyProduced": false,
  "isDisabled": false,
  "countryOfOrigin": "DE",
  "regionOfOrigin": "01",
  "salesTax": "standard",
  "isStockItem": true,
  "manufacturer": {
    "name": "Beverage Manufacturer",
    "number": "BM#1",
    "link": "https://example.com"
  },
  "ageRating": "18",
  "freeFields": [
    {
      "id": "8",
      "value": "FF8"
    },
    {
      "id": "16",
      "value": "FF16"
    },
    {
      "id": "32",
      "value": "FF32"
    }
  ]
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created product.
- **name** (string) - The name of the product.
- **number** (string) - The product number.

#### Response Example
```json
{
  "id": "prod_12345",
  "name": "Test Product Beverage",
  "number": "123456"
}
```
```

--------------------------------

### Get Report Usage API Response Example (JSON)

Source: https://developer.xentral.com/reference/report-usage

This JSON object illustrates a successful response (200 OK) from the 'Get report usage' API. It contains an array of 'data' objects, each representing a chargeable request with its ID, endpoint, timestamp, identifier, and the SQL query executed.

```JSON
{
  "data": [
    {
      "id": 1,
      "endpoint": "report/123/export",
      "timestamp": "2024-01-01T00:00:00+00:00",
      "identifier": "My Report",
      "query": "SELECT * FROM table"
    }
  ]
}
```

--------------------------------

### Bearer Token Authentication Request Example

Source: https://developer.xentral.com/docs/setting-up-a-carrier

Example cURL request demonstrating Bearer Token authentication for the /xentral/carriers endpoint. This method uses an 'Authorization: Bearer [Token]' header to authenticate requests.

```curl
curl --request GET \
     --url [Service URL]/xentral/carriers \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer [Token]' \
		 --header 'Accept-Language: en-US'
```