Author: detailsadmin

At DETAILS we try to avoid inefficiencies and work duplication wherever possible.
One of these workflows that saves a lot of time and energy for our clients is that we allow a direct data transfer from one details-client to another – for example for sales, costs or licence information.


To comply with data safety and privacy regulations as per the EU GDPR regulations the automatic exchange of data between two details clients will only work when both parties agree on doing so.
For this reason a secret shared-key needs to be activly and deliberatly exchanged between both parties.
For your safety we log of the process.


To set up the data exchange we need to differentiate between a SENDER and a RECEIVER.

The SENDER is the client which will provide sales, costs or other information (typically the Label-Service or Distributor).

The RECEIVER is the client that will ingest the SENDER’s data into their own database (typically the distributed Label).


For the auto-ingestion to work, the SENDER and RECEIVER need to proceed with the following steps:


(1) SENDER details client :

The SENDER needs to log into their details application, create a secret Shared-Key and transmit it together with it’s own client name to the RECEIVER in a secure way.

The Shared-Key is created in the ROYALTY ACCOUNT / SETUP which is designated to be shared:


The details-client name can be found the SENDER’s login link:
https://app.detailsdetails.eu/CLIENTNAME/




(2) RECEIVER details client :

The Shared-Key and the SENDER’s details-client name now need to be included into the Import-Setting of the RECEIVER, designated to receive the respective data.


NOTE: Exchanged data may be sales OR costs and third party licences.
Each data type needs to be set up in SEPERATE Import setup!


You can find the Import Settings in the DISTRIBUTION ACCOUNTS] / CURRENT STATEMENTS / IMPORT SETUP.

 

If you want to delete a sales import that has already been accounted, you need to cancel the invoice first (but make sure before, the invoice hasn’t been forwarded in the accounting process!)

 

1. ACCOUNTING / INVOICES

• find the invoice connected to the sales import and cancel it via the Pen Symbol on the right.

 

 

 

2. DISTRIBUTION / ACCOUNTS

• Once the invoice is cancelled, the sales import shows up again in the CURRENT STATEMENTS tab of the distribution account.
• You can delete the sales import by clicking the red X.

 

TRY TO AVOID DELETING AND ALWAYS CONSIDER IF THERE IS ANYTHING CONNECTED TO THE DELETED ITEM.

details supports automated ingestion of sales statements from various digital service providers (DSPs), including all DSPs covered by MERLIN and Amazon.

By default, these ingestions are scheduled to run automatically twice per week. However, if an import is missing, outdated, or shows incorrect amounts, you can manually trigger a new ingestion any time.

---

Step-by-step: Manually Trigger a Sales Ingestion

1. Go to Distribution / Imports

Navigate to Distribution / Imports in the left menu. Find the row corresponding to the account and importer you want to re-trigger.

2. Click on the Account Name

Click on the blue account name in the left-hand column. This will take you directly to the selected Distribution Account.

Example: Clicking “Merlin / Soundtrack Your Brand” will take you to that specific account.

3. Go to the Import Setup tab

Once you’re in the account view, open the Import Setup tab.

Look for the active importer you want to trigger. Make sure it has a DSS value this indicates that the importer is connected to an automated ingestion service.

4. Click “Perform”

On the right side of the Import Setup box, click the Perform link.

5. Select the Year and Period

In the modal that opens, select the Year and Period (e.g. M3 for March) for the statement you want to re-import.

6. Click “Run Auto Import”

Click the Run Auto Import button. This will trigger our system to connect to the distributor and request the latest available version of the file for that period.

7. Confirmation

You ll see a confirmation message:

“Your upload is being processed. You will be notified when your process is completed.”

---

What Happens Next

• If the request is successful, the updated file will be processed and matched automatically.
• Once matching is complete, the correct statement amount will be displayed in the Imports overview.

Please Note

Depending on the size of the file and the statement contents, the process can take a few minutes.

During this time:

• You may initially see a 0.00 amount in the tile.
• The actual amount will appear once the file has finished processing.
• Let the system work in the background and check back later.

 

---

If you encounter persistent issues with automated ingestion, feel free to contact label_team@details.eu.

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

API Field Name	Data Type	Expected Value	Description
identifier	Text	ISRC, UPC, SKU, VIDEO ID, etc.	Main Identifier
identifier_product	Text	UPC, SKU, GRiD, etc.	Secondary Identifier
artist	Text		Artist Name
title	Text		Title of Item
catalog_no	Text		Catalog Number
country	Text	ISO2 Country Code	Country
shop	Text	Name of DSP (Platform)	Shop Name
usage_type	Text	“DL” for Audio Download, “DV” for Video Download, “STR” for Audio Stream, “STV” for Video Stream, “PROMO” for Platform Promotion	Digital Sales Type
usage_type_description	Text	“Music Video”, “Music Compilation”, “Ringtone”, etc.	Description of Digital Sales
qty	INT	Signed	Quantity
ppd	DECIMAL	25,15	Published Price to Dealers
ppu	DECIMAL	25,15	Net revenue per unit
sales_date	Date	yyyy-mm-dd	Sales Date (alternatively: End of Sales Month)
import_format	Text	“Bundle”, “Track”, “CD”, “LP”, “T-Shirt”, “Video”, “Box”	Item Format
channel	Text	“d” for digital, “p” for physical, “n” for neighboring rights/performance	Sales Channel
mechanical_pu	DECIMAL	25,15	Cost per unit for mechanicals

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":""}