FOFR NetSpedice – API – import objednávek

Import dat do systému Netspedice přes webovou službu

Na adrese: http://objednavky.fofrcz.cz:4434 (nebo https://objednavky.fofrcz.cz:4433) naleznete webovou službu pro automatický příjem dat. Pro webovou službu je povolen import pouze souborů typu XML.

Metoda příjem dat

Pro úspěšné odeslání je potřeba v odesílací funkci „PrijemDat_v2“ vyplnit následující parametry:

• id_firma
  • Vaše ID pro přihlášení do objednávkového systému (vpravo nahoře číslo za křížkem po přihlášení do objednávek).
• kod_pobocky
  • Další závorka za id – dvouznakový řetězec
• uzivatel_fofr
  • Jméno uživatele použitého pro přihlášení do systému
• xml_data
  • xml data
• odeslat_automaticky
  • zadejte ‚T‘ pouze pokud by jste chtěli data nahrát do rozhraní a okamžitě je odesílat na pobočku bez zásahu uživatele, jinak zadejte ‚F‘

Nově metoda příjem dat provádí i automatickou kontrolu a opravu zdrojového XML.
Dále automaticky blokuje vytváření duplicitních zásilek, informace o zablokování je uvedena v elementu <CHYBA_PREPRAVY> a v elementu <SHIPMENT_NUM> se navrátí číslo již existující zásilky.
V případě úspěšné validace a platného přihlášení do systému nahraje zdrojové přepravy, zboží a přílohy do databáze.
Vrací hlášení v podobě XML formátu včetně chyb, pokud se vyskytne v průběhu validace či v průběhu nahrávání do databáze.

Pokud data chcete pouze otestovat, bez toho, aby se hned odeslala, nastavte id_firma na hodnotu 999999 a kod_pobocky na CB. Funkce pouze otestuje správnost dat a navrátí hlášení v xml formátu.

Příklad navrácené zprávy:

<?xml version="1.0"?>
<RESULT>
  <CHYBA_VALIDACE>XML je validni</CHYBA_VALIDACE>
  <PREPRAVA>
    <CISLO>1</CISLO>
    <SHIPMENT_ROK>2021</SHIPMENT_ROK>
    <SHIPMENT_NUM>7011409419</SHIPMENT_NUM>
    <PREPRAVA_ID>8773902</PREPRAVA_ID>
    <CENTRE_ORIGIN>UL</CENTRE_ORIGIN>
    <CENTRE_FROM>BL</CENTRE_FROM>
    <CENTRE_TO>ZR</CENTRE_TO>
    <CENA_BEZ_DPH>130,66</CENA_BEZ_DPH>
  </PREPRAVA>
</RESULT>

V navrácené zprávě se mohou vyskytnout následující chybové elementy:

• <CHYBA_VALIDACE>
  • Obsahuje buď potvrzení, že XML je validní nebo konkrétní validační chybu.
• <CHYBA_VYPOCTU>
  • Chyba vzniklá při výpočtu ceny přepravy/ přeprava s požadovaným číslem již existuje.
• <CHYBA_PREPRAVY>
  • Chyba vzniklá při výpočtu ceny přepravy.
  • Zásilka je duplicitní a proto nebude vytvořena.
• <CHYBA_DATUM>
  • Slouží pouze jako upozornění na změnu/doplnění datumu.

Pokud máte problémy s validací vašich souborů, je zde možnost kontaktovat it@transforwarding.cz ohledně opravy namespace, pořadí elementů a některých hodnot.

V současnosti je povolený zdroj pouze XML soubor.

Log změn

// 19.04.2023 přidán nepovinný element <SKUPINA_OBJEDNAVEK> do vstupního XML
// 29.10.2024 přidán nepovinný element <FAKTURACNI_CENA_OBJEDNATEL> do vstupního XML
// 28.11.2024 přidána blokace duplicitních zásilek v rámci dne
// 28.03.2025 přidány nepovinné elementy <ODESILATEL_NUTNE_AUTO_S_CELEM>, <PRIJEMCE_NUTNE_AUTO_S_CELEM> a <NESTOHOVATELNE> do vstupního XML
// 09.04.2025 přidán nepovinný element <TYP_OBJEDNAVKY> do vstupního XML

Příklady datových souborů

Metoda stav zásilky

Pro úspěšné odeslání je potřeba v odesílací funkci „StavZasilky“ vyplnit následující parametry:

• id_firma
  • Vaše ID pro přihlášení do objednávkového systému (vpravo nahoře číslo za křížkem po přihlášení do objednávek).
• kod_pobocky
  • Další závorka za id – dvouznakový řetězec
• uzivatel_fofr
  • Jméno uživatele použitého pro přihlášení do systému
• rok
  • Rok odeslání zásilky
• shipment_num
  • číslo zásilky
• code_objednatel
  • kód objednatele

Je třeba vždy správně vyplnit rok a číslo zásilky nebo kód objednatele. Funkce vrací zprávu o stavu zásilky v xml formátu. Číselník stavů naleznete zde.

Příklad navrácené zprávy:

<?xml version="1.0"?>
<RESULT>
  <SHIPMENT_ROK>2020</SHIPMENT_ROK>
  <SHIPMENT_NUM>3318220477</SHIPMENT_NUM>
  <PREPRAVA_ID>5868542</PREPRAVA_ID>
  <CENTRE_ORIGIN>CB</CENTRE_ORIGIN>
  <CENTRE_FROM>CB</CENTRE_FROM>
  <CENTRE_TO>BR</CENTRE_TO>
  <STATUT_NETSPEDICE>POŘÍZENÁ - EXPORTOVANÁ</STATUT_NETSPEDICE>
  <DATUM_PORIZENI_NETSPEDICE>2020-05-28T07:22:13+02:00</DATUM_PORIZENI_NETSPEDICE>
  <DATUM_EXPORT_NETSPEDICE>2020-05-28T10:49:24+02:00</DATUM_EXPORT_NETSPEDICE>
  <CENA_BEZ_DPH>347</CENA_BEZ_DPH>
  <STAV_ZASILKY_ID>6</STAV_ZASILKY_ID>
  <STAV_ZASILKY_POPIS>doručená</STAV_ZASILKY_POPIS>
  <STAV_ZASILKY_DATUM>2020-05-29T15:14:49+02:00</STAV_ZASILKY_DATUM>
  <URL_TRACK_TRACE>https://objednavky.fofrcz.cz/sleduj-fofr/2020/3318220477</URL_TRACK_TRACE>
</RESULT>

Metoda Přeprava Info

Slouží k získání informací o přepravě a to zejména pro výpočet ceny přepravy, případně vrátí chybové hlášení.

Pro úspěšné odeslání je potřeba v odesílací funkci „PrepravaInfo“ vyplnit následující parametry:

• id_firma
  • Vaše ID pro přihlášení do objednávkového systému (vpravo nahoře číslo za křížkem po přihlášení do objednávek).
• kod_pobocky
  • Další závorka za id – dvouznakový řetězec
• uzivatel_fofr
  • Jméno uživatele použitého pro přihlášení do systému
• xml_data
  • xml data

Pokud chcete použít tuto metodu pouze pro výpočet ceny přepravy bez vyplnění adresy odesílatele, příjemce a ostatních informací o přepravě, musíte uvést v XML elementech všechny údaje, na kterých je závislý výpočet ceny za přepravu. Jsou to minimálně PSČ odesílatele a příjemce – pro určení kilometrické vzdálenosti a středisek FOFRu odkud a kam bude zásilka převážená. Dále popis všech jednotlivých manipulačních kusů zboží zásilky pro přepravu (hmotnost a případně objem nebo rozměry).
Když chcete u příjemce vybírat dobírku, je nutné uvést i hodnotu pro výpočet doběrečného XML element <DOBIRKA> a <DOBRKA_MENA>.
Jestliže máte požadavek na odesílání placených SMS zpráv příjemcům zboží, je to také nutné uvést v datech XML element <PRIJEMCE_SMS_PLACENA>.
Všechny další elementy, které jsou v popisu uvedené jako povinné, je nutné vyplnit nějakou hodnotou, např. <ODESILATEL_FIRMA> X </ODESILATEL_FIRMA>.

Vzor XML v minimální podobě naleznete zde.

Funkce vrací zprávu v XML formátu.

Příklad navrácené zprávy:

<FOFR>
  <RESPONSE>
    <PREPRAVA_CISLO>1</PREPRAVA_CISLO>
    <CENTER_FROM>OV</CENTER_FROM>
    <CENTER_TO>PZ</CENTER_TO>
    <PRICE_WITH_VAT>488,36</PRICE_WITH_VAT>
    <PRICE_WITHOUT_VAT>403,6</PRICE_WITHOUT_VAT>
    <GOODS_TOTAL_WEIGHT>30</GOODS_TOTAL_WEIGHT>
    <GOODS_TOTAL_VOLUME>0,01</GOODS_TOTAL_VOLUME>
    <GOODS_TOTAL_COLLI>2</GOODS_TOTAL_COLLI>
    <DISTANCE_KM>395</DISTANCE_KM>
    <SELECTED_MODUL>B</SELECTED_MODUL>
  </RESPONSE>
</FOFR>

V případě chyby výpočtu se vrací XML v následující podobě:

<FOFR>
  <CHYBA_VYPOCTU>Přeprava nemohla být vytvořena z důvodu: X</CHYBA_VYPOCTU>
</FOFR>

A v případě chyby validace, XML vypadá následovně:

<FOFR>
  <CHYBA_VALIDACE>XML není validní, chyba X</CHYBA_VALIDACE>
</FOFR>

Metoda Přeprava Polepky

Slouží k navrácení polepek zadané přepravy ve formátu base64. Formát polepky je daný podle nastavení v profilu uživatele NetSpedice. Tisk na A4 (7×2,5×2), pás termo 90x40mm

Pro úspěšné odeslání je potřeba v odesílací funkci „PrepravaPolepky“ vyplnit následující parametry:

• id_firma
  • Vaše ID pro přihlášení do objednávkového systému (vpravo nahoře číslo za křížkem po přihlášení do objednávek).
• kod_pobocky
  • Další závorka za id – dvouznakový řetězec
• uzivatel_fofr
  • Jméno uživatele použitého pro přihlášení do systému
• shipment_num
  • Jedno nebo více čísel zásilek, oddělených čárkami
• pozice_polepky
  • Řetězec číselné pozice první polepky na stránce v případě tisknu na A4, kde systém sleduje pozici poslední tisknuté polepky a nabízí další volnou podle počtu polepek.
  • Nepovinný parametr

Funkce vrací zprávu ve formátu xml. V případě chybějících nebo prázdných parametrů funkce vrátí xml s tagem CHYBA, v případě správného nastavení vrátí v tagu RESPONSE base64 podobu pdf.

Příklad navrácené zprávy:

<?xml version="1.0"?>
<RESULT>
  <RESPONSE>...... Base 64 encoded pdf ........</RESPONSE>
</RESULT>

<?xml version="1.0"?>
<RESULT>
  <PREPRAVA_ID>000001</PREPRAVA_ID>
  <STATUS>Přeprava smazána</STATUS>
</RESULT>

<?xml version="1.0"?>
<RESULT>
  <STATUS>OK</STATUS>
</RESULT>

Metoda příjem dat – zastaralé

Podpora metody bude ukončena 31.12. 2025. Po tomto datu nebude možné odeslat touto metodou data.

Pro úspěšné odeslání je potřeba v odesílací funkci „PrijemDat“ vyplnit následující parametry:

• id_firma
  • Vaše ID pro přihlášení do objednávkového systému (vpravo nahoře číslo za křížkem po přihlášení do objednávek).
• kod_pobocky
  • Další závorka za id – dvouznakový řetězec
• uzivatel_fofr
  • Jméno uživatele použitého pro přihlášení do systému
• xml_data
  • xml data
• odeslat_automaticky
  • zadejte ‚T‘ pouze pokud by jste chtěli data nahrát do rozhraní a okamžitě je odesílat na pobočku bez zásahu uživatele, jinak zadejte ‚F‘