details Sales Ingestion API

The Sales Ingestion API allows you to directly import sales data into the Details client databases via JSON/JSONL file transfer. This guide provides detailed instructions on using the API.

API Endpoint https://api.berlin3.com/api/clientID/

Required Parameters

When making API requests, include the following parameters:

• clientID: Unique Client ID
• file: JSON/JSONL file location to upload
• action: The type of action (e.g., add_sales)
• year: Sales Year (yyyy)
• month: Sales Month (mm)
• currency: ISO currency code
• shared_key: Key to identify the statement source
• api_key: Unique Client API Key

Your clientID is in the clients login link.
To find your api_key, log into your Details account and go to Settings > Sharing.
The shared_key(s) can be found in the Import Setups for any Distribution Account and are generated automatically. If you create a new Account, close and re-open it to find the Shared Key.

Data Format

The JSON file should be an array of objects, and the JSONL file should be a list of objects separated by a new line.

Field Descriptions

Import Frequency

Sales Imports are usually performed monthly. However, weekly or daily imports are also possible depending on your needs. For example, one use case involves daily sales imports plus additional credit notes as needed.

Overwriting Previous Imports

New imports do not overwrite previous imports for the same month. Instead, each new import adds to the existing data for that month.

Handling Foreign Currency Sales

Imports are usually for one account (shop, company).
For each account, you can set up multiple import settings for different currencies.
It is important that each import setting (=shared_key) must be in one currency.

Importing Physical Sales

• Quantity: Returns should be represented as negative numbers. A signed INT can include negative values for returns.
• Usage Type: For physical sales, usage_type can be left empty or marked as ‘physical’. The documentation mainly mentions Promo, Downloads, and Streams.
• Import Format: Use appropriate format descriptions like “LP,” “Box,” or “12”. Ideally, use the same format names as those in the details. If an unrecognized format is imported, the user will need to assign a format.
• Channel: For physical sales, the value for the channel field should be “p”.

Test Environment Setup

If you need to test imports, we can set up a test shop (DSP/Platform) for you. Please contact us!

Note that unknown stores are not automatically set up and will be ignored.

Making API Requests

Important Notes

1. POST Requests: Ensure that the POST requests are made with multipart/form-data content type. This is crucial for file uploads.
   
   
2. Trailing Slash: The API endpoint should not have a trailing slash.
   In other words, use https://api.berlin3.com/api/clientID instead of
   https://api.berlin3.com/api/clientID/.

Example Usage with cURL

To make a POST request with file upload, use the following cURL command:

curl -X POST "https://api.berlin3.com/api/<client_id>/" 
-F "api_key=<api_key>" 
-F "shared_key=<shared_key>" 
-F "action=add_sales" 
-F "year=2024" 
-F "month=03" 
-F "currency=EUR" 
-F "description=TestImport" 
-F "file=@path/to/detailsSampleData.json"

Sample JSON File

[
{
"identifier": "DEAK123456",
"identifier_product": "0123454712872",
"artist": "Superaki",
"title": "Paris Moskau (Strom Mix)",
"catalog_no": "Det Rec 002",
"country": "FR",
"shop": "iTunes",
"usage_type": "DL",
"usage_type_description": "Full Price Download",
"qty": 112,
"ppu": 0.53,
"ppd": 0.70,
"sales_date": "2018-11-30",
"import_format": "Track",
"channel": "d",
"mechanical_pu": 0.12345
}
]

API Response

The API returns an object with the following fields:

• success: Always 1 when the call succeeds.
• error: Contains a value if there is an error (e.g., period_already_id, shared_key_unknown, Invalid Request, Auth Failed).

Sample Response

{"success":"1","error":""}