API
Delivio Integrations-API
Legen Sie Aufträge aus Ihrem eigenen System an, lesen Sie deren Status, stornieren Sie sie.
Authentifizierung
Erstellen Sie den Schlüssel auf der Kundenseite im Panel. Ein Schlüssel gehört zu genau einem Kunden; für welchen Kunden der Auftrag ist, ergibt sich aus dem Schlüssel, nicht aus dem Body.
Authorization: Bearer dlv_live_xxxxxxxxxxxx_…
Auftrag anlegen
Adresse und Betrag genügen. Koordinaten mitzusenden macht Kurierzuordnung und ETA genauer.
curl -X POST https://delivio.talivio.com/api/v1/integration/orders \
-H "Authorization: Bearer $DELIVIO_KEY" \
-H "Idempotency-Key: siparis-1042" \
-H "Content-Type: application/json" \
-d '{
"address": "Moda Cad. 12/3",
"customer_name": "Ada",
"customer_phone": "+90 555 000 00 00",
"total": 24000,
"is_prepaid": true
}'
Beträge sind GANZZAHLEN in der kleinsten Einheit (24000 = 240,00). Fließkommazahlen werden abgelehnt.
Senden Sie einen Idempotency-Key: Wird dieselbe Anfrage nach einem Verbindungsabbruch wiederholt, entsteht kein zweiter Auftrag.
{
"data": { "id": 1042, "code": "S-1042", "status": 15, "…": "…" },
"tracking_url": "https://delivio.talivio.com/t/…"
}
Status lesen und stornieren
curl https://delivio.talivio.com/api/v1/integration/orders/1042 -H "Authorization: Bearer $DELIVIO_KEY" curl -X POST https://delivio.talivio.com/api/v1/integration/orders/1042/cancel \ -H "Authorization: Bearer $DELIVIO_KEY" \ -d 'reason=Müşteri vazgeçti'
Sobald ein Kurier den Auftrag übernommen hat, ist die Stornierung per API geschlossen (409): Eine Kassenanfrage kann einen bereits fahrenden Kurier nicht zurückholen — stornieren Sie aus dem Panel.
Fehler
| HTTP | code | Bedeutung |
|---|---|---|
| 401 | invalid_key | Der Schlüssel ist ungültig oder widerrufen. |
| 402 | api_not_in_plan | Der API-Zugang ist nicht im Tarif enthalten. |
| 404 | — | Der Auftrag gehört nicht zum Kunden dieses Schlüssels. |
| 409 | already_assigned | Ein Kurier hat ihn übernommen; stornieren Sie aus dem Panel. |
| 422 | — | Die Feldprüfung ist fehlgeschlagen oder der Auftragsstatus lässt es nicht zu. |
| 429 | — | Ratenlimit: 120 Anfragen pro Minute. |
Webhooks
Legen Sie Ihren Endpunkt auf der Kundenseite im Panel fest. Wir senden einen POST, wenn ein Auftrag angenommen, abgeholt, geliefert und storniert wird.
POST /sizin-ucunuz
X-Delivio-Event: order.delivered
X-Delivio-Signature: t=1755680000,v1=9f2c…
{
"event": "order.delivered",
"sent_at": "2026-08-20T12:00:00+00:00",
"order": { "id": 1042, "code": "S-1042", "status": 20, "…": "…" }
}
Jede Anfrage trägt `X-Delivio-Signature: t=<unix>,v1=<hmac>`. Zum Prüfen berechnen Sie `hmac_sha256(ihr_geheimnis, "<t>." + roher_body)` und vergleichen mit `v1`; verwerfen Sie sie, wenn `t` älter als 5 Minuten ist (Replay).
// PHP
[$t, $v1] = sscanf($_SERVER['HTTP_X_DELIVIO_SIGNATURE'], 't=%d,v1=%s');
$expected = hash_hmac('sha256', $t.'.'.file_get_contents('php://input'), $secret);
if (! hash_equals($expected, $v1) || abs(time() - $t) > 300) {
http_response_code(400);
exit;
}
Antwortet Ihr Endpunkt nicht mit 2xx, versuchen wir es nach 10 s, 1 Min., 5 Min. und 30 Min. erneut. Nach 20 Fehlern in Folge wird der Endpunkt deaktiviert und das Panel nennt den Grund.