
API Documentatie
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.
API key authenticatie
Stuur producten mee met je order
https://app.sendwise.nl/api/ordersAuthenticatie gebeurt via de Authorization header met een Bearer token. Dit is volgens REST best practices en zorgt voor optimale beveiliging.
Stuur je API key mee in de Authorization header als Bearer token.
Authorization: Bearer your_20_character_api_key| Veld | Type | Beschrijving |
|---|---|---|
| weight | number | Gewicht van de zending in kg (moet > 0 zijn) |
| receiver_name | string | Naam van de ontvanger |
| receiver_street | string | Straatnaam |
| receiver_house_number | string | Huisnummer |
| receiver_postal_code | string | Postcode |
| receiver_city | string | Plaatsnaam |
| receiver_country | string | ISO 3166-1 alpha-2 landcode (bijv. NL, BE, DE) |
| receiver_email | string | E-mailadres ontvanger |
| Veld | Type | Beschrijving |
|---|---|---|
| reference_number | string | Jouw order referentienummer |
| receiver_company | string | Bedrijfsnaam |
| receiver_house_number_suffix | string | Huisnummer toevoeging (bijv. A, bis) |
| receiver_address_2 | string | Adresregel 2 (bijv. verdieping) |
| receiver_phone | string | Telefoonnummer ontvanger |
| items | array | Array met order items (zie hieronder) |
Je kunt optioneel een lijst met order items meesturen. Elk item moet de volgende structuur hebben:
| Veld | Type | Verplicht | Beschrijving |
|---|---|---|---|
| article_name | string | Naam van het artikel | |
| quantity | number | Aantal (positief geheel getal) | |
| price | number | Prijs per stuk (in Euro) | |
| article_number | string | Artikelnummer | |
| sku | string | SKU code |
Alle velden hebben specifieke validatieregels, lengtelimieten en formats. Controleer deze voordat je een request verstuurt om onnodige errors te voorkomen.
| Veld | Type | Min/Max | Format/Validatie | Voorbeeld |
|---|---|---|---|---|
| reference_number | string | 1-50 chars | Uniek per integratie | ORDER-2024-001 |
| weight | number | 0.001-1000 | Kilogram, max 3 decimalen | 1.5 |
| receiver_name | string | 1-100 chars | UTF-8, accenten toegestaan | Jan Jansen |
| receiver_company | string | 0-100 chars | UTF-8 | Jansen BV |
| receiver_street | string | 1-100 chars | UTF-8, geen huisnummer | Kerkstraat |
| receiver_house_number | string | 1-10 chars | Numeriek of alfanumeriek | 12 |
| receiver_house_number_suffix | string | 0-10 chars | Toevoeging (A, bis, etc) | A |
| receiver_address_2 | string | 0-100 chars | Verdieping, app. nummer | Verdieping 2 |
| receiver_postal_code | string | 1-20 chars | Land-specifiek (zie tabel) | 1234AB |
| receiver_city | string | 1-100 chars | UTF-8 | Amsterdam |
| receiver_country | string | exact 2 | ISO 3166-1 alpha-2 (uppercase, wordt genormaliseerd) | NL |
| receiver_phone | string | 8-20 chars | Internationaal formaat +31... | +31612345678 |
| receiver_email | string | 5-254 chars | RFC 5321 email format | jan@example.com |
| items[].article_number | string | 0-50 chars | Optioneel | SKU-001 |
| items[].article_name | string | 1-200 chars | Verplicht | Product Naam |
| items[].sku | string | 0-50 chars | Optioneel | SKU-001 |
| items[].quantity | integer | 1-10000 | Positief geheel getal | 2 |
| items[].price | decimal | 0.00-999999.99 | Max 2 decimalen (€ Euro) | 29.99 |
De API ondersteunt verzending naar alle EU landen. Hieronder vind je de volledige lijst van ondersteunde landen.
| Land | Code |
|---|---|
| 🇳🇱 Nederland | NL |
| 🇧🇪 België | BE |
| 🇩🇪 Duitsland | DE |
| 🇫🇷 Frankrijk | FR |
| 🇮🇹 Italië | IT |
| 🇪🇸 Spanje | ES |
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
}
]
}{
"success": true,
"order_id": 12345,
"message": "Order created successfully",
"request_id": "req_1234567890",
"items_count": 1
}{
"success": false,
"error": "Missing required field: receiver_name",
"code": "MISSING_FIELD",
"request_id": "req_1234567890"
}| HTTP Status | Error Code | Beschrijving |
|---|---|---|
| 201 | - | Order succesvol aangemaakt |
| 400 | INVALID_CONTENT_TYPE | Content-Type moet application/json zijn |
| 400 | MISSING_FIELD | Een verplicht veld ontbreekt |
| 400 | INVALID_API_KEY_FORMAT | API key moet exact 20 karakters zijn |
| 400 | INVALID_WEIGHT | Gewicht moet een positief getal zijn |
| 400 | INVALID_COUNTRY_CODE | Ongeldige ISO 3166-1 alpha-2 landcode |
| 400 | INVALID_EMAIL | Ongeldig e-mailadres formaat |
| 400 | INVALID_PHONE | Ongeldig telefoonnummer formaat |
| 400 | INVALID_POSTAL_CODE | Ongeldige postcode voor het land |
| 400 | INVALID_ITEMS | Ongeldige items array |
| 400 | INVALID_ITEM | Een of meer order items zijn ongeldig |
| 401 | INVALID_API_KEY | API key is ongeldig of integratie niet gevonden |
| 409 | DUPLICATE_ORDER | Order met dit referentienummer bestaat al |
| 413 | REQUEST_TOO_LARGE | Request is te groot (max 1MB) |
| 429 | RATE_LIMIT_EXCEEDED | Rate limit overschreden (max 2000/dag) |
| 500 | DATABASE_ERROR | Database fout bij opslaan |
| 500 | INTERNAL_ERROR | Interne server fout |
Hieronder vind je concrete voorbeelden van veelvoorkomende fouten met de volledige request en response. Dit helpt je om foutafhandeling correct te implementeren.
Een verplicht veld ontbreekt in de 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"
}{
"success": false,
"error": "Missing required field: receiver_street",
"code": "MISSING_FIELD",
"request_id": "req_1234567890"
}Een order item heeft ongeldige waarden.
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
}
]
}{
"success": false,
"error": "Item 1: quantity must be a positive integer",
"code": "INVALID_ITEM",
"request_id": "req_1234567890"
}Postcode voldoet niet aan het land-specifieke format.
POST https://app.sendwise.nl/api/orders
Authorization: Bearer aBcD1234EfGh5678IjKl
{
"receiver_country": "DE",
"receiver_postal_code": "ABC123", // DE vereist 12345
...
}{
"success": false,
"error": "Invalid postal code format for DE",
"code": "INVALID_POSTAL_CODE",
"request_id": "req_1234567890"
}De API key is ongeldig of de integratie is niet actief.
POST https://app.sendwise.nl/api/orders
Authorization: Bearer wrongkey12345678901 // Verkeerde key!
{
...
}{
"success": false,
"error": "Invalid API key or integration not found",
"code": "INVALID_API_KEY",
"request_id": "req_1234567890"
}Een order met dit reference_number bestaat al voor deze integratie.
POST https://app.sendwise.nl/api/orders
Authorization: Bearer aBcD1234EfGh5678IjKl
{
"reference_number": "ORDER-2024-001", // Al gebruikt!
...
}{
"success": false,
"error": "Order with this reference number already exists for this integration",
"code": "DUPLICATE_ORDER",
"request_id": "req_1234567890"
}Je hebt het dagelijkse request limiet overschreden.
{
"success": false,
"error": "Rate limit exceeded. Maximum 2000 requests per day. Current count: 2001",
"code": "RATE_LIMIT_EXCEEDED",
"request_id": "req_1234567890"
}X-RateLimit-Limit: 2000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1704067200
X-RateLimit-Window: 86400request_id die je kunt gebruiken voor debugging en support requests. Bewaar deze ID's in je logs voor troubleshooting.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
$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);
?>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())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);
});Controleer velden zoals email, telefoonnummer en postcode voordat je een request stuurt om onnodige API calls te voorkomen.
Geef elke order een uniek referentienummer om duplicaten te voorkomen. Als je geen reference_number meegeeft, wordt er automatisch een gegenereerd.
Verwerk alle mogelijke HTTP status codes en error codes correct in je applicatie. Log errors voor debugging.
Sla de API key op in environment variables, niet in je source code. Deel de key nooit publiekelijk.
Alle API calls moeten via HTTPS gebeuren om de veiligheid van je gegevens te waarborgen.
Heb je vragen of loop je tegen problemen aan? Neem contact op met ons support team.
© 2025 Sendwise Orders API Documentation - Versie 1.0