v1.0
POST /api/orders
{ success: true }
Sendwise Orders

Sendwise Orders

API Documentatie

API Version 1.0

API Overzicht

De Sendwise Orders API stelt je in staat om orders te importeren vanuit je eigen systeem. Verstuur eenvoudig ordergegevens via een HTTP POST request en wij zorgen voor de rest.

Veilig & betrouwbaar

API key authenticatie

Order items ondersteuning

Stuur producten mee met je order

API Endpoint

POST
https://app.sendwise.nl/api/orders
Let op: Alle requests moeten via HTTPS worden verstuurd met Content-Type: application/json header.

Authenticatie

Authenticatie gebeurt via de Authorization header met een Bearer token. Dit is volgens REST best practices en zorgt voor optimale beveiliging.

Authorization Header

Stuur je API key mee in de Authorization header als Bearer token.

Authorization: Bearer your_20_character_api_key
Belangrijk: Bewaar je API key veilig en deel deze nooit publiekelijk. De API key geeft volledige toegang tot het aanmaken van orders in jouw account. Gebruik omgevingsvariabelen en deel keys nooit in code repositories.

Request Parameters

VerplichtVerplichte velden

VeldTypeBeschrijving
weightnumberGewicht van de zending in kg (moet > 0 zijn)
receiver_namestringNaam van de ontvanger
receiver_streetstringStraatnaam
receiver_house_numberstringHuisnummer
receiver_postal_codestringPostcode
receiver_citystringPlaatsnaam
receiver_countrystringISO 3166-1 alpha-2 landcode (bijv. NL, BE, DE)
receiver_emailstringE-mailadres ontvanger

OptioneelOptionele velden

VeldTypeBeschrijving
reference_numberstringJouw order referentienummer
receiver_companystringBedrijfsnaam
receiver_house_number_suffixstringHuisnummer toevoeging (bijv. A, bis)
receiver_address_2stringAdresregel 2 (bijv. verdieping)
receiver_phonestringTelefoonnummer ontvanger
itemsarrayArray met order items (zie hieronder)

Order Items (optioneel)

Je kunt optioneel een lijst met order items meesturen. Elk item moet de volgende structuur hebben:

VeldTypeVerplichtBeschrijving
article_namestringNaam van het artikel
quantitynumberAantal (positief geheel getal)
pricenumberPrijs per stuk (in Euro)
article_numberstringArtikelnummer
skustringSKU code

Veldspecificaties & Limieten

Alle velden hebben specifieke validatieregels, lengtelimieten en formats. Controleer deze voordat je een request verstuurt om onnodige errors te voorkomen.

VeldTypeMin/MaxFormat/ValidatieVoorbeeld
reference_numberstring1-50 charsUniek per integratieORDER-2024-001
weightnumber0.001-1000Kilogram, max 3 decimalen1.5
receiver_namestring1-100 charsUTF-8, accenten toegestaanJan Jansen
receiver_companystring0-100 charsUTF-8Jansen BV
receiver_streetstring1-100 charsUTF-8, geen huisnummerKerkstraat
receiver_house_numberstring1-10 charsNumeriek of alfanumeriek12
receiver_house_number_suffixstring0-10 charsToevoeging (A, bis, etc)A
receiver_address_2string0-100 charsVerdieping, app. nummerVerdieping 2
receiver_postal_codestring1-20 charsLand-specifiek (zie tabel)1234AB
receiver_citystring1-100 charsUTF-8Amsterdam
receiver_countrystringexact 2ISO 3166-1 alpha-2 (uppercase, wordt genormaliseerd)NL
receiver_phonestring8-20 charsInternationaal formaat +31...+31612345678
receiver_emailstring5-254 charsRFC 5321 email formatjan@example.com
items[].article_numberstring0-50 charsOptioneelSKU-001
items[].article_namestring1-200 charsVerplichtProduct Naam
items[].skustring0-50 charsOptioneelSKU-001
items[].quantityinteger1-10000Positief geheel getal2
items[].pricedecimal0.00-999999.99Max 2 decimalen (€ Euro)29.99
Let op: Velden gemarkeerd met blauwe kleur zijn verplicht. Emoji's en speciale Unicode karakters worden geaccepteerd maar kunnen problemen veroorzaken bij sommige verzenders.

Ondersteunde Landen

De API ondersteunt verzending naar alle EU landen. Hieronder vind je de volledige lijst van ondersteunde landen.

LandCode
🇳🇱 NederlandNL
🇧🇪 BelgiëBE
🇩🇪 DuitslandDE
🇫🇷 FrankrijkFR
🇮🇹 ItaliëIT
🇪🇸 SpanjeES

Voorbeeld Request

POST https://app.sendwise.nl/api/orders
Authorization: Bearer your_20_character_api_key
Content-Type: application/json

{
  "reference_number": "ORDER-2024-001",
  "weight": 1.5,
  "receiver_name": "Jan Jansen",
  "receiver_company": "Jansen BV",
  "receiver_street": "Kerkstraat",
  "receiver_house_number": "12",
  "receiver_house_number_suffix": "A",
  "receiver_address_2": "Verdieping 2",
  "receiver_postal_code": "1234AB",
  "receiver_city": "Amsterdam",
  "receiver_country": "NL",
  "receiver_phone": "+31612345678",
  "receiver_email": "jan@example.com",
  "items": [
    {
      "article_number": "SKU-001",
      "article_name": "Product Naam",
      "sku": "SKU-001",
      "quantity": 2,
      "price": 29.99
    }
  ]
}

Response Voorbeelden

Succesvolle response (201 Created)

{
  "success": true,
  "order_id": 12345,
  "message": "Order created successfully",
  "request_id": "req_1234567890",
  "items_count": 1
}

Fout response (400 Bad Request)

{
  "success": false,
  "error": "Missing required field: receiver_name",
  "code": "MISSING_FIELD",
  "request_id": "req_1234567890"
}

HTTP Status Codes & Error Codes

HTTP StatusError CodeBeschrijving
201-Order succesvol aangemaakt
400INVALID_CONTENT_TYPEContent-Type moet application/json zijn
400MISSING_FIELDEen verplicht veld ontbreekt
400INVALID_API_KEY_FORMATAPI key moet exact 20 karakters zijn
400INVALID_WEIGHTGewicht moet een positief getal zijn
400INVALID_COUNTRY_CODEOngeldige ISO 3166-1 alpha-2 landcode
400INVALID_EMAILOngeldig e-mailadres formaat
400INVALID_PHONEOngeldig telefoonnummer formaat
400INVALID_POSTAL_CODEOngeldige postcode voor het land
400INVALID_ITEMSOngeldige items array
400INVALID_ITEMEen of meer order items zijn ongeldig
401INVALID_API_KEYAPI key is ongeldig of integratie niet gevonden
409DUPLICATE_ORDEROrder met dit referentienummer bestaat al
413REQUEST_TOO_LARGERequest is te groot (max 1MB)
429RATE_LIMIT_EXCEEDEDRate limit overschreden (max 2000/dag)
500DATABASE_ERRORDatabase fout bij opslaan
500INTERNAL_ERRORInterne server fout

Uitgebreide Foutvoorbeelden

Hieronder vind je concrete voorbeelden van veelvoorkomende fouten met de volledige request en response. Dit helpt je om foutafhandeling correct te implementeren.

400 - MISSING_FIELD

Een verplicht veld ontbreekt in de request.

REQUEST
POST https://app.sendwise.nl/api/orders Authorization: Bearer aBcD1234EfGh5678IjKl { "weight": 1.5, "receiver_name": "Jan Jansen", // receiver_street ontbreekt! "receiver_house_number": "12", "receiver_postal_code": "1234AB", "receiver_city": "Amsterdam", "receiver_country": "NL", "receiver_email": "jan@example.com" }
RESPONSE (400)
{ "success": false, "error": "Missing required field: receiver_street", "code": "MISSING_FIELD", "request_id": "req_1234567890" }

400 - INVALID_ITEM

Een order item heeft ongeldige waarden.

REQUEST
POST https://app.sendwise.nl/api/orders Authorization: Bearer aBcD1234EfGh5678IjKl { "weight": 1.5, "receiver_name": "Jan Jansen", ... "items": [ { "article_name": "Product A", "quantity": 0, // Moet >= 1 zijn! "price": 29.99 } ] }
RESPONSE (400)
{ "success": false, "error": "Item 1: quantity must be a positive integer", "code": "INVALID_ITEM", "request_id": "req_1234567890" }

400 - INVALID_POSTAL_CODE

Postcode voldoet niet aan het land-specifieke format.

REQUEST
POST https://app.sendwise.nl/api/orders Authorization: Bearer aBcD1234EfGh5678IjKl { "receiver_country": "DE", "receiver_postal_code": "ABC123", // DE vereist 12345 ... }
RESPONSE (400)
{ "success": false, "error": "Invalid postal code format for DE", "code": "INVALID_POSTAL_CODE", "request_id": "req_1234567890" }

401 - INVALID_API_KEY

De API key is ongeldig of de integratie is niet actief.

REQUEST
POST https://app.sendwise.nl/api/orders Authorization: Bearer wrongkey12345678901 // Verkeerde key! { ... }
RESPONSE (401)
{ "success": false, "error": "Invalid API key or integration not found", "code": "INVALID_API_KEY", "request_id": "req_1234567890" }

409 - DUPLICATE_ORDER

Een order met dit reference_number bestaat al voor deze integratie.

REQUEST
POST https://app.sendwise.nl/api/orders Authorization: Bearer aBcD1234EfGh5678IjKl { "reference_number": "ORDER-2024-001", // Al gebruikt! ... }
RESPONSE (409)
{ "success": false, "error": "Order with this reference number already exists for this integration", "code": "DUPLICATE_ORDER", "request_id": "req_1234567890" }

429 - RATE_LIMIT_EXCEEDED

Je hebt het dagelijkse request limiet overschreden.

RESPONSE (429)
{ "success": false, "error": "Rate limit exceeded. Maximum 2000 requests per day. Current count: 2001", "code": "RATE_LIMIT_EXCEEDED", "request_id": "req_1234567890" }
RESPONSE HEADERS
X-RateLimit-Limit: 2000 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1704067200 X-RateLimit-Window: 86400
Tip: Alle error responses bevatten een unieke request_id die je kunt gebruiken voor debugging en support requests. Bewaar deze ID's in je logs voor troubleshooting.

Code Voorbeelden

cURL

curl -X POST https://app.sendwise.nl/api/orders \
  -H "Authorization: Bearer your_20_character_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "reference_number": "ORDER-2024-001",
    "weight": 1.5,
    "receiver_name": "Jan Jansen",
    "receiver_street": "Kerkstraat",
    "receiver_house_number": "12",
    "receiver_postal_code": "1234AB",
    "receiver_city": "Amsterdam",
    "receiver_country": "NL",
    "receiver_email": "jan@example.com"
  }'

PHP

<?php
$ch = curl_init('https://app.sendwise.nl/api/orders');

$data = [
    'reference_number' => 'ORDER-2024-001',
    'weight' => 1.5,
    'receiver_name' => 'Jan Jansen',
    'receiver_street' => 'Kerkstraat',
    'receiver_house_number' => '12',
    'receiver_postal_code' => '1234AB',
    'receiver_city' => 'Amsterdam',
    'receiver_country' => 'NL',
    'receiver_email' => 'jan@example.com',
];

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer your_20_character_api_key',
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
?>

Python

import requests

url = 'https://app.sendwise.nl/api/orders'
headers = {
    'Authorization': 'Bearer your_20_character_api_key',
    'Content-Type': 'application/json'
}

data = {
    'reference_number': 'ORDER-2024-001',
    'weight': 1.5,
    'receiver_name': 'Jan Jansen',
    'receiver_street': 'Kerkstraat',
    'receiver_house_number': '12',
    'receiver_postal_code': '1234AB',
    'receiver_city': 'Amsterdam',
    'receiver_country': 'NL',
    'receiver_email': 'jan@example.com',
}

response = requests.post(url, json=data, headers=headers)
print(response.status_code)
print(response.json())

Node.js (axios)

const axios = require('axios');

const url = 'https://app.sendwise.nl/api/orders';
const data = {
  reference_number: 'ORDER-2024-001',
  weight: 1.5,
  receiver_name: 'Jan Jansen',
  receiver_street: 'Kerkstraat',
  receiver_house_number: '12',
  receiver_postal_code: '1234AB',
  receiver_city: 'Amsterdam',
  receiver_country: 'NL',
  receiver_email: 'jan@example.com',
};

axios.post(url, data, {
  headers: {
    'Authorization': 'Bearer your_20_character_api_key',
    'Content-Type': 'application/json'
  }
})
  .then(response => {
    console.log(response.status);
    console.log(response.data);
  })
  .catch(error => {
    console.error(error.response.data);
  });

Best Practices

Valideer input aan jouw kant

Controleer velden zoals email, telefoonnummer en postcode voordat je een request stuurt om onnodige API calls te voorkomen.

Gebruik unieke reference_number

Geef elke order een uniek referentienummer om duplicaten te voorkomen. Als je geen reference_number meegeeft, wordt er automatisch een gegenereerd.

Implementeer error handling

Verwerk alle mogelijke HTTP status codes en error codes correct in je applicatie. Log errors voor debugging.

Bewaar je API key veilig

Sla de API key op in environment variables, niet in je source code. Deel de key nooit publiekelijk.

Gebruik HTTPS

Alle API calls moeten via HTTPS gebeuren om de veiligheid van je gegevens te waarborgen.

Hulp nodig?

Heb je vragen of loop je tegen problemen aan? Neem contact op met ons support team.

© 2025 Sendwise Orders API Documentation - Versie 1.0