Cargonity Public API & Webhook Kézikönyv

Kapcsolja össze vállalatirányítási (ERP), CRM vagy TMS fuvarszervező szoftverét a Cargonity intelligens e-mail és fuvarlevél feldolgozó motorjával. Teljes automatizáció a beérkező ajánlatkéréstől a fuvarmegbízás rögzítéséig.

API Kézikönyv Letöltése (.PDF) Postman Kollekció (.JSON) API Kulcs Megtekintése

1. Hitelesítés (Authentication)

A publikus API eléréséhez minden fiók számára egyedi API kulcs (API Key) biztosított, amely a Beállítások oldalon érhető el PRO vagy Enterprise csomag esetén.

A kulcsot minden HTTP kérés fejlécében (Header) kötelező átadni:

X-API-KEY: az_on_titkos_api_kulcsa

Biztonsági figyelmeztetés: Az API kulcs teljes hozzáférést ad a fiókjához. Kizárólag szerveroldali (backend) hívásokban használja, soha ne tegye közzé publikus böngészős kódban!

2. Alapértelmezett Elérési Út (Base URL)

Minden hivatalos végpont az /api előtaggal kezdődik:

https://cargonity.com/api

3. Szállítmányok Kezelése (Shipments)

Szállítmányok listázása és szűrése

GET /api/shipments/

Lekérdezi a feldolgozott és kinyert szállítmányokat. Számos szűrési paraméter áll rendelkezésre:

date_from: Kezdő dátum (pl. 2026-09-01 vagy today / ma)
date_to: Záró dátum (pl. 2026-09-30)
erp_ready: Logikai szűrő (true esetén csak a hiánytalan, ERP átadásra kész rekordokat adja)
needs_attention: Logikai szűrő (true esetén a diszpécseri beavatkozást igénylő rekordok)
status: Közvetlen státusz szűrés (pl. READY_FOR_ERP, NEEDS_ATTENTION, AWAITING_DATA)
from_id: Megadott ID-tól kezdve növekvő sorrendben (hasznos háttér szinkronizációhoz)

Példa JSON válasz:

[
  {
    "id": 12,
    "loading_country": "Magyarország",
    "loading_country_code": "HU",
    "loading_zip": "1117",
    "loading_city": "Budapest",
    "loading_address": "Budafoki út 56",
    "loading_date": "2026-09-15",
    "loading_date_to": "2026-09-16",
    "loading_time_from": "08:00",
    "loading_time_to": "16:00",
    "unloading_country": "Németország",
    "unloading_country_code": "DE",
    "unloading_zip": "80331",
    "unloading_city": "München",
    "unloading_address": "Marienplatz 1",
    "unloading_date": "2026-09-18",
    "unloading_date_to": null,
    "goods_name": "Raklapos áru (Acél lemezek)",
    "pallet_count": 4,
    "weight_kg": 1200.0,
    "dimensions": "80x120x150 cm",
    "is_adr": "no",
    "is_frigo": "no",
    "pallet_exchange": "no",
    "vehicle_type": "tilt",
    "notes": "Élvédő szükséges.",
    "sender_company": "Minta Megbízó Kft.",
    "sender_name": "Kovács János",
    "sender_phone": "+36 30 123 4567",
    "reference_number": "PO-4500123456",
    "position_number": "10",
    "price": 1450.0,
    "currency": "EUR",
    "converted_price": 1450.0,
    "converted_currency": "EUR",
    "status": "READY_FOR_ERP",
    "erp_ready": true,
    "thread_token": "C-12",
    "missing_fields": [],
    "confidence": 0.98,
    "created_at": "2026-09-11T12:00:00Z"
  }
]

Egyedi szállítmány lekérdezése

GET /api/shipments/{shipment_id}

Szállítmány jóváhagyása és átvétele külső ERP-ből

PATCH /api/shipments/{shipment_id}

A külső ERP rendszer ezen a végponton közvetlenül frissítheti a hiányzó mezőket vagy átveheti a megbízást:

{
  "position_number": "PO-987654",
  "status": "READY_FOR_ERP",
  "notes": "ERP-ben automatikusan jóváhagyva."
}

Hiányos megbízás azonnali átadása ERP-be (Force Draft)

POST /api/shipments/{shipment_id}/force-erp-draft

AI árajánlat / válasz e-mail generálása

POST /api/shipments/{shipment_id}/generate-reply

Body: {"action": "counter_offer", "price": 1600.0}

4. Valós Idejű ERP Webhookok (Push Notifications)

A Cargonity valós időben tudja továbbítani az adatokat az Ön ERP végpontjára (amelyet a Beállításokban adhat meg az erp_webhook_url mezőben).

Támogatott események:

shipment_ready: Amikor egy megbízás minden kötelező ERP adata rendelkezésre áll.
shipment_needs_attention: Amikor az AI leállította az automata e-mailes adatbekérést (2 kör után), mert még mindig hiányoznak kötelező adatok.

Példa Webhook Payload (JSON):

{
  "event": "shipment_ready",
  "status": "READY_FOR_ERP",
  "shipment_id": 2309,
  "thread_token": "C-2309",
  "reference_number": "PO-123456",
  "position_number": "10",
  "sender_company": "Megbízó Partner Kft.",
  "sender_name": "Gipszes Jakab",
  "sender_phone": "+3687954752",
  "loading_city": "Székesfehérvár",
  "loading_country_code": "HU",
  "loading_date": "2026-09-22",
  "unloading_city": "Szeged",
  "unloading_country_code": "HU",
  "unloading_date": "2026-09-22",
  "weight_kg": 40000.0,
  "pallet_count": 13,
  "price": 1000.0,
  "currency": "EUR"
}

5. Gyors Integrációs Kódminták

Python (Requests)

import requests

url = "https://cargonity.com/api/shipments/?erp_ready=true"
headers = {
    "X-API-KEY": "a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d6",
    "Accept": "application/json"
}

response = requests.get(url, headers=headers)
if response.status_code == 200:
    for s in response.json():
        print(f"#{s['id']} {s['loading_city']} -> {s['unloading_city']}: {s['weight_kg']} kg ({s['price']} {s['currency']})")

Node.js / JavaScript (Fetch)

const res = await fetch("https://cargonity.com/api/shipments/?erp_ready=true", {
  headers: {
    "X-API-KEY": "a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d6",
    "Accept": "application/json"
  }
});
const shipments = await res.json();
console.log("ERP-re kész szállítmányok:", shipments);