Neutralni REST API za transportne naloge

1.Autentikacija

Ako vaš alat ne može pozvati putanju na vlastitoj domeni, upotrijebite funkcijski URL iz odjeljka 9 s istim tijelom i poljem route.

2.Predaja naloga — POST /external/loads

curl -X POST https://viaillyrica.com/api/v1/external/loads \
  -H "Content-Type: application/json" \
  -H "X-API-Key: vil_..." \
  -d '{
    "external_id": "TM-4711",
    "pickup_location": "Zagreb",
    "pickup_country": "HR",
    "pickup_date": "2026-11-03",
    "pickup_time": "08:00",
    "delivery_location": "Vukovar",
    "delivery_country": "HR",
    "delivery_date": "2026-11-03",
    "delivery_time": "14:00",
    "cargo_type": "Paletizirana roba",
    "weight_kg": 12000,
    "pallet_count": 18,
    "volume_m3": 24,
    "loading_meters": 12.5,
    "price": 400,
    "price_currency": "EUR",
    "vehicle_type_required": "kamion",
    "notes": "Utovar do 12h"
  }'

Odgovor 201 (novi nalog) ili 200 (već zaprimljen):

{
  "ok": true,
  "id": "0f3c...-uuid",
  "status": "KREIRANO",
  "duplicate": false,
  "billing_info": {
    "pricing_model": "PERCENTAGE_TIER_1",
    "applied_rate_percent": 2.85,
    "cargo_price": 400,
    "fee_amount": 11.4,
    "total_charged_amount": 411.4,
    "currency": "EUR",
    "payment_method": "STRIPE_CONNECT_ESCROW",
    "payment_status": "AWAITING_PAYMENT",
    "stripe_checkout_url": "https://checkout.stripe.com/c/pay/cs_live_...",
    "stripe_payment_intent_client_secret": null,
    "notes": "Provizija od 2.85% za vrijednost vožnje do 2000 EUR. Plaćanje se dovršava na stripe_checkout_url; sredstva se drže u escrow-u do potvrde isporuke."
  },
  "load": {
    "id": "0f3c...-uuid",
    "title": "TM-4711 · Zagreb → Vukovar",
    "pickup_location": "Zagreb",
    "delivery_location": "Vukovar",
    "weight_tons": 12,
    "status": "otvoren"
  }
}

Nalog je odmah otvoren za uparivanje s prijevoznicima. Uz nalog se lokacije automatski geokodiraju i računa se udaljenost kad su adrese prepoznate.

Provizija u odgovoru (billing_info)

Uz svaki zaprimljeni nalog vraćamo i obračunatu proviziju servisa, pa je vaš ERP može knjižiti bez ručnog izračuna: pricing_model, applied_rate_percent, cargo_price, fee_amount i total_charged_amount (cijena prijevoza i provizija preračunate u EUR).

Prag od 2.000 EUR primjenjuje se na protuvrijednost u eurima. Ako nalog stigne u RSD, BAM ili drugoj valuti, osnovica se preračunava po tečaju na dan zaprimanja naloga, a provizija se iskazuje u EUR. Ako cijena nije poslana, polja provizije vraćaju se kao null uz objašnjenje u polju notes.

Plaćanje i escrow

Uz nalog vraćamo i pripremljeno plaćanje: stripe_checkout_url vodi na sigurnu Stripe stranicu na kojoj naručitelj autorizira ukupan iznos (prijevoz + provizija). Sredstva se drže u escrow-u, a puštaju se prijevozniku tek nakon potvrde isporuke. Za automatizirane klijente vraćamo i Stripe Customer ID tvrtke, pa se uplata može izvršiti i bez klika. Ako se koristi bankovni virman, umjesto poveznice vraćamo IBAN i poziv na broj.

3.Polja naloga

Prihvaćene su i inačice naziva: origin / pickup / utovar, destination / delivery / istovar, weight (tone), volume (m³), id (external_id), cargo, equipment. Ako se vaša polja razlikuju od ovih, mapiranje se postavlja jednom na našoj strani — bez izmjene vašeg sustava.

Poštanski broj. U polja pickup_location i delivery_location slobodno pošaljite format [poštanski broj] [grad], npr. 10000 Zagreb. SAP TM razlikuje lokacije preko poštanskog broja jer u regiji više mjesta dijeli isti naziv. Opcionalna polja pickup_zip i delivery_zip planiramo u sljedećoj inačici; do tada poštanski broj šaljite unutar naziva mjesta.

4.Vrijednosti za vehicle_type_required

Vrijednosti pišite hrvatski. Sustav ih sam normalizira (kamion, šleper, cerada, hladnjača, kombi…), pa je dovoljno poslati ono što piše u vašem nalogu.

5.Provjera statusa — GET /external/loads/{id}/status

Umjesto {id} prihvaćamo naš UUID, naš broj objave (VI-000123) ili vaš external_id.

curl https://viaillyrica.com/api/v1/external/loads/TM-4711/status \
  -H "X-API-Key: vil_..."

{
  "id": "0f3c...-uuid",
  "external_id": "TM-4711",
  "status": "U_TRANZITU",
  "load_status": "u_tijeku",
  "transport_status": "u_tijeku",
  "pickup_location": "Zagreb",
  "delivery_location": "Vukovar",
  "pod_file_url": null,
  "updated_at": "2026-11-03T09:41:00.000Z"
}

6.Push događaji — POST /external/webhooks/subscribe

Registrirajte HTTPS URL; šaljemo POST zahtjev pri svakoj promjeni statusa. Zahtijeva partnerski integracijski ključ (isti ključ služi i kao tajna za potpis).

curl -X POST https://viaillyrica.com/api/v1/external/webhooks/subscribe \
  -H "Content-Type: application/json" \
  -H "X-API-Key: vil_..." \
  -d '{
    "url": "https://vase-erp.example.com/hooks/viaillyrica",
    "events": ["UTOVARENO", "U_TRANZITU", "ISPORUCENO"]
  }'

Naš zahtjev prema vama izgleda ovako:

POST https://vase-erp.example.com/hooks/viaillyrica
x-viaillyrica-event: U_TRANZITU
x-viaillyrica-signature: sha256=<hmac_sha256_hex>

{
  "event": "U_TRANZITU",
  "occurred_at": "2026-11-03T09:41:00.000Z",
  "partner_id": "partner-uuid",
  "data": {
    "load_id": "0f3c...-uuid",
    "transport_id": "7a1e...-uuid",
    "external_id": "TM-4711",
    "status": "U_TRANZITU",
    "pickup_location": "Zagreb",
    "delivery_location": "Vukovar",
    "pod": null
  }
}

Potpis provjerite tako da izračunate HMAC-SHA256 nad sirovim tijelom zahtjeva. Događaji: UTOVARENO, U_TRANZITU, ISPORUCENO (zadano) te KREIRANO i OTKAZANO po želji; "*" šalje sve. Očekujemo odgovor 2xx u roku od 10 s; u suprotnom događaj se bilježi kao neuspješan.

Potvrda plaćanja — PLACANJE_OSIGURANO

Kad naručitelj autorizira uplatu, Stripe potvrdu vraća nama, a mi je prosljeđujemo vama. Događaj sadrži iznos prijevoza, proviziju i ukupno autorizirani iznos, pa SAP može nalog odmah prebaciti u status „sredstva rezervirana". Ovaj događaj šalje se uvijek, neovisno o popisu događaja na koji ste pretplaćeni.

POST https://vase-erp.example.com/hooks/viaillyrica
x-viaillyrica-event: PLACANJE_OSIGURANO
x-viaillyrica-signature: sha256=<hmac_sha256_hex>

{
  "event": "PLACANJE_OSIGURANO",
  "occurred_at": "2026-10-31T19:47:00.000Z",
  "partner_id": "partner-uuid",
  "data": {
    "load_id": "0f3c...-uuid",
    "external_id": "TM-4711",
    "status": "KREIRANO",
    "payment": {
      "stripe_intent_id": "pi_3Mtw...",
      "status": "ESCROW_LOCKED",
      "cargo_price": 400,
      "viaillyrica_fee": 11.4,
      "total_authorized": 411.4,
      "currency": "EUR",
      "payment_method_type": "card",
      "authorized_at": "2026-10-31T19:46:58.000Z"
    },
    "notes": "Sredstva su uspješno autorizirana i zaključana u escrow sustavu. Nalog je vidljiv prijevoznicima."
  }
}

7.Grupni uvoz — POST /external/files

CSV, XML, JSON ili PDF (base64). Redak s poljima kao u odjeljku 3 obrađuje se kao nalog. U slučaju greške obavještavamo kontaktni e-mail partnera.

curl -X POST https://viaillyrica.com/api/v1/external/files \
  -H "Content-Type: application/json" \
  -H "X-API-Key: vil_..." \
  -d '{
    "filename": "nalozi-2026-11-03.csv",
    "content": "external_id;pickup_location;delivery_location;weight_kg;pallet_count;price\nTM-4712;Osijek;Sarajevo;8400;12;520"
  }'

{
  "ok": true,
  "format": "csv",
  "created": 1,
  "failed": 0,
  "loads": [{ "id": "0f3c...-uuid", "duplicate": false }],
  "errors": []
}

8.Statusi i greške

Preslikavanje na SAP TM

Naši statusi odgovaraju statusima izvršenja u SAP TM-u (Execution Status / Event Code), pa se mapiranje postavlja u SAP-u bez prilagodbe našeg sustava:

9.Alternativni poziv preko funkcijskog URL-a

Isti ključ i ista polja; ruta se zadaje u tijelu. Pogodno za alate koji ne mogu konfigurirati vlastitu putanju.

curl -X POST https://viaillyrica.base44.app/functions/externalApi \
  -H "Content-Type: application/json" \
  -H "X-API-Key: vil_..." \
  -d '{
    "route": "loads",
    "external_id": "TM-4713",
    "origin": "Zagreb",
    "destination": "Beograd",
    "weight": 22,
    "cargo_type": "Čelik"
  }'

https://viaillyrica.base44.app/functions/externalApi