Order API (V1) - How to import Orders via JSON

Details Team
  • Updated
Follow

How to import orders via the Order API (V1)

Use this guide to send orders into details via a POST request. This article documents the Order API V1.0 (2023) and keeps the V1 behavior.

Note: The endpoint expects a JSON array of orders in the request body. Identifiers can be provided as UUID, barcode, or catalog_no. Barcodes must be unique.

Where to find the endpoint

Go to SETTINGS / SHARING and open the open api box named [JSON Orders Import].

Endpoint & URL format

Base URL:

https://openapi.berlin3.com:10000/orders/json_import/

Path format (with credentials):

https://api.berlin3.com:10000/api/orders/json_import/<client_id>/<checksum>
Open API – JSON Orders Import

Quick start

  1. Generate or locate your <client_id> and <checksum> in SETTINGS / SHARING.
  2. Build your POST request to the URL format above.
  3. Set header Content-Type: application/json.
  4. Send a JSON array of order objects in the request body.

Request parameters

Parameter Description In Expected Value
client_id Unique client identifier path details client_id
checksum API key path details open api key
params Array of orders body JSON

Payload schema (field overview)

Each order is an object. The table below lists available fields. Mandatory fields must be present in every order.

API Field Name Mandatory / Optional Data Type Expected Value Field Description
order_date Mandatory string YYYY-MM-DD Date of the order.
account_id Mandatory integer min ≥ 1 Internal ID of the account.
contra_account_id Mandatory integer — Internal ID of the contra account.
invoice_project_id Mandatory integer — Internal ID of the invoicing project.
vat_handling Mandatory integer 1, 2, 3 1 = excluding VAT, 2 = including VAT, 3 = no VAT.
vat_territory Mandatory string — Territory for VAT calculation.
vat_rate1 Mandatory number — Primary VAT rate.
vat_rate2 Mandatory number — Secondary VAT rate.
orderlines — array — Line items of the order (see fields below).
shipping_type_id Optional integer — Internal ID of shipping type.
order_value Optional number — Total order value.
uuid / barcode / catalog_no Optional string — Item identifiers. Barcodes must be unique.

cURL example

curl -X POST \
  "https://api.berlin3.com:10000/api/orders/json_import/<client_id>/<checksum>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "order_date": "2015-06-01",
      "account_id": 167,
      "contra_account_id": 2,
      "invoice_project_id": 4,
      "currency": "EUR",
      "order_type": 1,
      "vat_handling": 1,
      "vat_territory": "EU",
      "vat_rate1": 19,
      "vat_rate2": 0,
      "orderlines": [
        {"uuid": "b1862090-469e-4035-a073-9f106d270502", "ppu": 12.50, "order_qty": 1},
        {"uuid": "c796d64c-90c6-493f-a8ea-0f244904069b", "ppu": 10.90, "order_qty": 3}
      ]
    }
  ]'

JSON schema (V1)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "import orders",
  "description": "import orders from json",
  "type": "array",
  "items": {
    "type": "object",
    "required": [
      "order_date",
      "account_id",
      "contra_account_id",
      "invoice_project_id",
      "currency",
      "order_type",
      "vat_handling",
      "vat_territory",
      "vat_rate1",
      "vat_rate2"
    ],
    "properties": { /* full property list as in V1 remains supported */ }
  }
}

For completeness, the original V1 schema property list from your legacy documentation is preserved below.

► Full legacy JSON schema (expanded) 
/* Original V1 JSON Schema from your text */
$SCHEMA_BLOCK_START

Sample JSON payload (from V1)

[{
  "status": "Invoice",
  "user_id": null,
  "currency": "EUR",
  "vat_rate1": null,
  "vat_rate2": null,
  "account_id": 167,
  "order_date": "2015-06-01",
  "order_type": 1,
  "orderlines": [
    {"ppu": 12.50, "uuid": "b1862090-469e-4035-a073-9f106d270502", "barcode": "487328472388", "catalog_no": "Detrec 002 CD", "notes": null, "vat_rate": null, "order_qty": 1, "promo_foc": null, "vat_amount": null},
    {"ppu": 10.90, "uuid": "c796d64c-90c6-493f-a8ea-0f244904069b", "notes": null, "vat_rate": null, "order_qty": 3, "promo_foc": null, "vat_amount": null},
    {"ppu": 11.20, "uuid": "ab96df0f-d94a-44b0-ab63-99340bc778fb", "notes": null, "vat_rate": null, "order_qty": 2, "promo_foc": null, "vat_amount": null}
  ],
  "order_value": 504.50,
  "deliver_city": "Subiaco",
  "deliver_name": "Andrew Sinclair",
  "order_source": "fertig prepaid!",
  "vat_handling": null,
  "deliver_phone": "+61406213638",
  "delivery_text": null,
  "one_stop_flag": null,
  "proforma_text": "Good Company Records\nAndrew Sinclair\n267 Hay St.\nSubiaco - 6008\n",
  "shipping_date": null,
  "shipping_info": null,
  "tracking_data": null,
  "vat_territory": null,
  "internal_notes": "Good Company Records\nAndrew Sinclair\n267 Hay St.\n\n6008 Subiaco\nAUSTRALIA",
  "order_discount": null,
  "shipping_costs": 95.40,
  "weight_kg_edit": 17.800,
  "deliver_company": "Good Company Records",
  "deliver_country": "Australia",
  "order_reference": null,
  "deliver_address1": "267 Hay St.",
  "deliver_address2": null,
  "shipping_type_id": 1,
  "contra_account_id": 2,
  "customs_reference": null,
  "payment_method_id": null,
  "deliver_postalcode": "6008",
  "invoice_project_id": 4,
  "deliver_address_type": null,
  "deliver_street_number": null
}]

Sample response

{"details":"Data is received successfully, for more details please check email.","error":0}

Troubleshooting

  • 400/422: Check required fields and data types (see mandatory list).
  • 401: Invalid <client_id> or <checksum>.
  • 500: Retry later; if persistent, contact support@details.eu.

Related articles