API CargoRomania pentru integrări
REST JSON pentru TMS-uri, ERP-uri și dispozitive GPS: publici marfă și camioane automat, primești oferte, statusuri, ETA, documente și facturi. Bază: https://www.cargoromania.ro/api/v1.
Autentificare
Creează un token din Profil → API (sau POST /auth/token cu email + parolă). Trimite-l în antet: Authorization: Bearer <token>. Tokenurile pot avea scopes: cargo:read cargo:write offers transports tracking documents invoices alerts webhooks fleet (fără scopes = toate).
curl -X POST https://www.cargoromania.ro/api/v1/auth/token \
-H 'Content-Type: application/json' \
-d '{"email":"[email protected]","password":"…","label":"TMS"}'
# → {"ok":true,"token":"…","expires_in_days":365,"company":{…}} Limite: 600 cereri / minut / token (răspuns 429 + Retry-After). Răspunsurile au forma {"ok":true,…} sau {"ok":false,"error":"…"}. Datele sunt în format ISO (YYYY-MM-DD), monedele EUR/RON, greutățile în kg.
Marfă
| Metodă | Endpoint | Descriere | Scope |
|---|---|---|---|
| GET | /cargo | Listă publică de marfă (filtre: from, to, truck_type, date, page, limit) | |
| GET | /cargo/{id} | Detalii marfă | |
| POST | /cargo | Publică marfă (client) | cargo:write |
| POST | /cargo/{id}/stops | Multi-stop: înlocuiește opririle (listă ordonată load/unload) | cargo:write |
| POST | /cargo/{id}/cancel | Anulează marfa | cargo:write |
| GET | /cargo/{id}/pricing | AI Pricing: preț recomandat, mediu, combustibil, taxe, cost transportator, marjă | cargo:read |
| GET | /cargo/{id}/matches | BEST MATCH: transportatori recomandați cu scor și motive (proprietar) / scorul tău (transportator) | cargo:read |
| POST | /ai/parse | Text liber → câmpuri structurate + transportatori potriviți |
curl -X POST https://www.cargoromania.ro/api/v1/cargo -H 'Authorization: Bearer …' -H 'Content-Type: application/json' -d '{
"from_city":"București","to_city":"Milano","to_country":"IT","load_date":"2026-09-18",
"weight_kg":18000,"pallets":33,"truck_type":"prelata","cargo_type":"general",
"pricing_mode":"fixed","price":1850,"currency":"EUR","description":"Marfă paletizată"
}'
# → {"ok":true,"cargo":{"id":123,"ref":"CR-100123","distance_km":1646,…}} POST /cargo/123/stops
{"stops":[
{"type":"load","city":"București","date":"2026-09-03","time_window":"08:00-12:00","pallets":20},
{"type":"load","city":"Sibiu","pallets":13},
{"type":"unload","city":"Budapesta","country":"HU","pallets":10},
{"type":"unload","city":"Milano","country":"IT"}
]}
Oferte, licitație și negociere
| Metodă | Endpoint | Descriere | Scope |
|---|---|---|---|
| POST | /cargo/{id}/offers | Trimite ofertă (transportator): price, message, truck_id, available_from | offers |
| GET | /cargo/{id}/offers | Ofertele primite (client) | offers |
| GET | /offers | Ofertele mele (transportator) | offers |
| POST | /offers/{id}/accept | Acceptă oferta → creează cursa | offers |
| POST | /offers/{id}/reject | Respinge (client) / retrage (transportator) | offers |
| POST | /offers/{id}/counter | Contraofertă (ambele părți): price, message | offers |
| GET | /offers/{id}/negotiation | Firul de negociere | offers |
| POST | /negotiations/{id}/accept | Acceptă o propunere → cursa se creează la acel preț | offers |
Transporturi, comandă și documente
| Metodă | Endpoint | Descriere | Scope |
|---|---|---|---|
| GET | /transports | Cursele mele (?active=1 include poziția, km rămași, ETA) | transports |
| GET | /transports/{id} | Detalii cursă + snapshot tracking + documente | transports |
| POST | /transports/{id}/assign | Alocă camion/șofer: truck_id, driver_id | transports |
| POST | /transports/{id}/status | Schimbă statusul: truck_assigned, arrived_load, loading, in_transit, arrived_unload, delivered, pod_uploaded (transportator) · pod_validated, completed, cancelled (client) | transports |
| GET | /transports/{id}/order.pdf | Comanda de transport (PDF) | transports |
| POST | /transports/{id}/sign | Semnează electronic comanda (partea curentă) | transports |
| GET | /transports/{id}/documents | Documentele cursei | documents |
| POST | /transports/{id}/documents | Încarcă document (multipart: file, type=cmr|pod|aviz|invoice|photo_loading|photo_unloading|other) | documents |
| GET | /documents/{id} | Descarcă fișierul | documents |
| POST | /transports/{id}/pod/validate | Clientul validează POD → se poate factura | transports |
GPS tracking
| Metodă | Endpoint | Descriere | Scope |
|---|---|---|---|
| POST | /tracking/position | Poziție de la dispozitiv/telematică: token (al camionului), lat, lng, speed, heading — fără Bearer | |
| POST | /transports/{id}/position | Poziție pentru o cursă (transportator) | tracking |
| GET | /transports/{id}/tracking | Traseu, poziție curentă, km rămași, ETA, etape, opriri | tracking |
| GET | /map | Harta globală: camioane disponibile, curse goale, marfă, camioane în tranzit | tracking |
Tokenul GPS al fiecărui camion se găsește în Camioane. Integrare telematică (Teltonika, Ruptela, orice tracker cu HTTP POST): trimite la fiecare 30–60 s.
curl -X POST https://www.cargoromania.ro/api/v1/tracking/position -H 'Content-Type: application/json' \
-d '{"token":"<gps_token camion>","lat":45.7489,"lng":21.2087,"speed":78,"heading":270}'
# → {"ok":true,"transport":{"ref":"TR-100001","km_remaining":989,"eta_at":"2026-09-03 22:00:31"}}
Flotă, curse goale și backhaul
| Metodă | Endpoint | Descriere | Scope |
|---|---|---|---|
| GET | /trucks | Camioanele mele | fleet |
| POST | /trucks | Adaugă camion (plate, type, capacity_kg, pallets, current_city, available_from, route_to_city…) | fleet |
| POST | /trucks/{id} | Actualizează camion (poziție, disponibilitate, rută preferată) | fleet |
| GET | /recommended | Marfă recomandată pentru flota mea (scor + motive) | cargo:read |
| GET | /empty-trucks | Camioane disponibile publice (?mine=1 doar ale mele) | |
| POST | /empty-trucks | Anunță o cursă goală: from_city, to_city/to_country, available_from, truck_type, capacity_kg, radius_km | fleet |
| GET | /empty-trucks/{id}/matches | Marfa compatibilă cu cursa goală | cargo:read |
| GET | /backhaul?transport={id} | Curse retur directe + lanțuri de 2–3 segmente cu km goi minimi | cargo:read |
Facturi și alerte
| Metodă | Endpoint | Descriere | Scope |
|---|---|---|---|
| POST | /transports/{id}/invoice | Emite factura de transport (transportator → client) din POD validat | invoices |
| GET | /invoices | Facturile mele (emise și primite) | invoices |
| GET | /invoices/{id} | Detalii factură (linii, TVA, total, status) | invoices |
| GET | /invoices/{id}.pdf | PDF factură | invoices |
| POST | /invoices/{id}/paid | Marchează plătită (emitent): method, ref | invoices |
| GET | /alerts | Alertele mele de marfă | alerts |
| POST | /alerts | Creează alertă: name, params{from,to_country,truck_type,weight_min…}, channels[inapp,email,sms,whatsapp] | alerts |
| POST | /alerts/{id}/delete | Șterge alerta | alerts |
| GET | /notifications | Notificări + număr necitite | |
| GET | /realtime/poll?since={id} | Polling incremental pentru notificări/mesaje noi |
Import în masă
| Metodă | Endpoint | Descriere | Scope |
|---|---|---|---|
| POST | /imports | Multipart file=CSV/XLSX (+review=1 pentru ciorne) → job asincron | cargo:write |
| GET | /imports/{id} | Starea importului și rezultatul pe rânduri | cargo:read |
| POST | /imports/email | Text liber (email, mesaj) → marfă ciornă; publish=1 publică direct | cargo:write |
Webhooks
Primești evenimente în timp real la URL-ul tău HTTPS. Creezi din POST /webhooks (url, events) sau din Profil → API; secretul se afișează o singură dată.
| Eveniment | Când |
|---|---|
cargo.published | o marfă a fost publicată (a ta) / apare marfă potrivită (transportator) |
offer.created · offer.accepted · negotiation.countered | ofertare și negociere |
transport.status | orice schimbare de status a cursei (include status, ETA, km rămași) |
tracking.position | poziție GPS nouă pe cursele tale (max 1/min) |
document.uploaded | CMR/POD/foto încărcate |
invoice.issued · invoice.paid | facturare |
Fiecare livrare are antetul X-Signature: sha256=<HMAC-SHA256(body, secret)> și X-Event. Verificare:
// PHP
$sig = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
if (!hash_equals($sig, $_SERVER['HTTP_X_SIGNATURE'] ?? '')) { http_response_code(401); exit; }
// Node
const sig = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex'); Răspunde cu 2xx în maximum 10 s; altfel reîncercăm de 3 ori (1, 5, 30 min). După 20 de eșecuri consecutive webhook-ul se dezactivează.
Aplicația șoferului
| Metodă | Endpoint | Descriere | Scope |
|---|---|---|---|
| POST | /driver/login | Telefon + PIN → token de șofer (fără Bearer) | |
| GET | /driver/trip | Cursa curentă, opriri, următoarele evenimente permise | transports |
| POST | /driver/trip/{id}/event | event: arrived_load | loaded | departed | arrived_unload | unloaded (+lat, lng) | transports |
| POST | /driver/position | Poziție din telefon: lat, lng, speed, heading | tracking |
Coduri de eroare
401 token lipsă/invalid · 402 limită de plan · 403 fără acces / scope lipsă · 404 inexistent · 409 duplicat · 422 validare · 429 rate limit · 501 funcție neactivată încă.
Întrebări sau integrări dedicate (ERP, telematică): contact.