Bevezető

A Foxpost 2021. októberében publikálta legújabb, Webapi névre keresztelt API-ját. Jelen dokumentum segítséget nyúlt a legrégebbi, ecomm API-ról történő átálláshoz.

Jellegében a két megoldás hasonló, mindkét kapcsolat szinkron adatátvitelt tesz lehetővé, azaz a küldés pillanatában válaszban megérkezik a hívás sikerességének visszajelzése, illetve a válaszban a szükséges adatok is.

Amennyiben az api összekötéssel kapcsolatban kérdése merülne fel, keressen minket a b2chelpdesk@foxpost.hu email címen.

Az új API-ról

Az új api RestFUL, működési elve szinkron (a hívás azonnali válaszban tér vissza a hívás sikerességével és annak eredményével).

A Webapi Swagger dokumentációja ide kattintva érhető el.

API híváshoz szükséges adatok

Az api használatához legelőször a foxpost.hu oldalon kell üzleti partnerként regisztrálni. Amennyiben ez sikeresen megtörtént, akkor kezdhető el az integráció.

Az API authentikációhoz három adatra van szükség:

  • Basic auth username
  • Basic auth password
  • API-key

Az api hívásához szükséges paraméterek a foxpost.hu oldalra belépve, a Beállítások (https://foxpost.hu/beallitasok) aloldal tetején találhatók.

Amennyiben az API-key mező üres, abban az esetben a "Jelszó generálása" gombra kattintva generálható API kulcs. A kulcs módosítására szintén itt van lehetőség.

Egy fiókhoz csak egy API kulcs generálására van lehetőség, azonban egy kulcsot több helyen is lehet használni.

Hívás és azonosítás

A Webapi API baseUrl-je:

https://webapi.foxpost.hu/api
Basic auth

Az API Basic authentikációval jelentkeztet be, melynek két paramétere az Basic auth username és az Basic auth password. Ezt a két adatot minden hívásnál küldeni kell.

Api kulcs

A másik kötelező paraméter az API-key, melyet minden hívás esetén Header paraméterként szükséges küldeni.

Fejlécek

Az API JSON adatformátummal kommunikál, így vár minden adatot és - néhány eseten kívül - így is adja vissza a választ. Ahol a visszatérési érték nem json, ott ez külön kiemelésre kerül! A kommunikációhoz szükséges fejlécek:

                        
{
    "Accept-Encoding": "Application/json",
    "Content-Type": "Application/json",
    "Api-key": "...",
}
                        
                    
Automata lista
Automata lista adatok

Csomagautomaták folyamatosan frissülő listája az alábbi címen érhető el:

https://cdn.foxpost.hu/apms.json

Új csomagautomata és a régiek megszűnése is ebben a fájlban követhető.

Az állomány fontosabb mezőinek értéke:

Mező neve Leírás
place_id Automata azonosítója. Deprecated, a jövőben az automata azonosítását az operator_id mező fogja átvenni
operator_id Automata azonosítója, új kapcsolat esetén ezt a mezőt szükséges használni!
name Automata neve
address Automata teljes címe
zip Automata irányítószáma
city Automata város
street Város
findme Megtalálhatóság, az adott helyszínen belül hol található az automata.
geolat, leolon GPS koordináták.
Allowed2 Megadja, hogy az adott automatából milyen csomagot lehet küldeni.
Lehetséges értékei: "ALL" - bárki küldhet
"C2C" - csak c2c csomag adható fel
"B2B" - csak B2B csomag adható fel
load Telítettség. Két fajta értéke lehet: normal-loaded vagy overloaded.
isOutdoor Megadja, hogy az automata kültéren helyezkedik-e el. Lehetséges értékek: true, false (bool)
open Nyitvatartási idő napok szerint
fillEmptyList Megadja azokat az időszakokat, amikor az adott automatába elhelyezésre, illetve amikor onnan elszállításra kerülnek a csomagok.
Parcel

Csomagok létrehozása/módosítása/törlése

POST
/api/parcel

Új csomag/csomagok létrehozása.

Egy hívással több csomag is átadható, amennyiben egynél több elemű json kerül átadásra.

Két fajta csomagot különböztetünk meg, egyik típus a csomagautomatába történő szállítás (továbbiakban apm), másik pedig a házhoszállításos csomag (továbbiakban hd). A csomagok beküldése történhet vegyesen is, nem kell külön küldeni a házhozszállításos és az automatás rendeléseket.

Request query

Paraméter név Típus Leírás
isWeb Opcionális
Boolean
Megadja, hogy a csomag megjelenjen-e a Foxpost.hu oldalon a csomagok között.
Engedélyezett értékek: true, false
Alapértelmezett érték: true

Request body

Paraméter név Típus Leírás
[] Kötelező
RequestItem[]
Tetszőleges számú HD vagy API Request Item tömb.

Request Items

Paraméter név Típus Leírás
cod Opcionális Integer Utánvét értéke
Minimális érték: 0
Maximális érték: 150000
Alapértelmezett érték: 0
deliveryNote Opcionális String Futárnak szóló üzenet
Minimális hossz: 0
Maximális hossz: 50
Alapértelmezett érték: null
fragile Opcionális Bool Törékeny
Engedélyezett értékek: true, false
Alapértelmezett érték: false
label Opcionális Bool Foxpost nyomtasson címkét. Csak c2c csomag esetén használatos.
Engedélyezett értékek: true, false
Alapértelmezett érték: false
recipientAddress Kötelező String Szállítási cím (utca, házszám, emelet, ajtó)
Minimális hossz: 1
Maximális hossz: 150
recipientCity Kötelező String Szállítási cím város
Minimális hossz: 1
Maximális hossz: 50
recipientName Kötelező String Címzett neve
Minimális hossz: 1
Maximális hossz: 150
recipientEmail Kötelező String Címzett email címe, formailag helyes email címnek kell lennie!
recipientPhone Kötelező String Címzett telefonszáma +36 formátumban. Csak magyarországi mobiltelefon-számokat fogad el a rendszer!
reguláris kifejezés: ^(\+36|36)(20|30|31|70|50|51)\d{7}$
recipientZip Kötelező Integer Címzett irányítószáma
Minimális érték: 1000
Maximális érték: 9999
refCode Kötelező String Elszámoláshoz használatos csomagoazosító szám. Értéke tetszőleges lehet. Segítségével az elszámolásban könnyen azonosítani tudja a csomagjait.
A referenciakód adatok a FoxPost rendszerében olyan egyedi azonosítók, melyeknek csomagonként (és nem csak az adott üzleti partnertől származó csomagokat tekintve) eltérőnek kell lenniük. Elsősorban annak érdekében, hogy a csomagkövetés szolgáltatásunk (https://foxpost.hu/csomagkovetes) igénybevétele során a vásárlóik a megfelelő információkat kapják. Ezért kérjük, hogy az átadandó kódokat ún. hibrid, legalább 4 betűt és legalább 4 számot tartalmazó azonosítók használatával tegyék egyedivé. A betűk lehetőség szerint utaljanak az adott partnerre. Például: FIRMA987654321 Minimális hossz: 0
Maximális hossz: 30
size Kötelező String A mező értéke a betöltés során kötelező, azonban a rendszer nem veszi figyelembe, így az értéke lehet fixen M. A végleges érték a Foxpost raktári folyamatai során utóla, automatikusan kerül meghatározásra.
Lehetséges értékek: ["L", "M", "S", "XS", "XL"]
uniqueBarcode Opcionális String Az egyedi vonalkód használata csak automatába történő szállítás esetén használható. Ebben az esetben a címkére nem a Foxpost által generált CLFOX kezdetű vonalkód lesz rányomtatva, hanem a webshop által generált vonalkód.
Fontos, hogy a vonalkódnak egyedinek kell lennie, két egyforma vonalkód nem fordulhat elő a Foxpost rendszerében, ezért fontos, hogy a webshop gondoskodjon a vonalkód egyediségéről.
kérjük, hogy az átadandó kódokat ún. hibrid, legalább 4 betűt és legalább 4 számot tartalmazó azonosítók használatával tegyék egyedivé. A betűk lehetőség szerint utaljanak az adott partnerre. Például: FIRMA987654321
Amennyiben olyan vonalkód kerül átadásra, ami már létezik a rendszerben, úgy a csomag létrehozása sikertelen lesz (API feladás esetén DUPLICATED_UNIQUE_BARCODE hibakód).
Minimális hossz: 0
Maximális hossz: 20
voucher Opcionális String Csomaghoz tartozó voucher kód.
Paraméter név Típus Leírás
barcode Opcionális String Vonalkód (egyedi vonalkód használata esetén)
Alapértelmezett érték: null
cod Opcionális Integer Utánvét értéke
Minimális érték: 0
Maximális érték: 150000
Alapértelmezett érték: 0
deliveryNote Opcionális String Futárnak szóló üzenet
Minimális hossz: 0
Maximális hossz: 50
Alapértelmezett érték: null
destination Kötelező String A címzett automata kódja. Értéke a korábbi json fájl operator_id mezője.
recipientEmail Kötelező String Címzett email címe, formailag helyes email címnek kell lennie!
recipientPhone Kötelező String Címzett telefonszáma +36 formátumban. Csak magyarországi mobiltelefon-számokat fogad el a rendszer!
reguláris kifejezés: ^(\+36|36)(20|30|31|70|50|51)\d{7}$
refCode Kötelező String Elszámoláshoz használatos csomagoazosító szám. Értéke tetszőleges lehet. Segítségével az elszámolásban könnyen azonosítani tudja a csomagjait.
A referenciakód adatok a FoxPost rendszerében olyan egyedi azonosítók, melyeknek csomagonként (és nem csak az adott üzleti partnertől származó csomagokat tekintve) eltérőnek kell lenniük. Elsősorban annak érdekében, hogy a csomagkövetés szolgáltatásunk (https://foxpost.hu/csomagkovetes) igénybevétele során a vásárlóik a megfelelő információkat kapják. Ezért kérjük, hogy az átadandó kódokat ún. hibrid, legalább 4 betűt és legalább 4 számot tartalmazó azonosítók használatával tegyék egyedivé. A betűk lehetőség szerint utaljanak az adott partnerre. Például: FIRMA987654321 Minimális hossz: 0
Maximális hossz: 30
size Kötelező String A mező értéke a betöltés során kötelező, azonban a rendszer nem veszi figyelembe, így az értéke lehet fixen M. A végleges érték a Foxpost raktári folyamatai során utóla, automatikusan kerül meghatározásra.
Lehetséges értékek: ["L", "M", "S", "XS", "XL"]
uniqueBarcode Opcionális String Az egyedi vonalkód használata csak automatába történő szállítás esetén használható. Ebben az esetben a címkére nem a Foxpost által generált CLFOX kezdetű vonalkód lesz rányomtatva, hanem a webshop által generált vonalkód.
Fontos, hogy a vonalkódnak egyedinek kell lennie, két egyforma vonalkód nem fordulhat elő a Foxpost rendszerében, ezért fontos, hogy a webshop gondoskodjon a vonalkód egyediségéről.
kérjük, hogy az átadandó kódokat ún. hibrid, legalább 4 betűt és legalább 4 számot tartalmazó azonosítók használatával tegyék egyedivé. A betűk lehetőség szerint utaljanak az adott partnerre. Például: FIRMA987654321
Amennyiben olyan vonalkód kerül átadásra, ami már létezik a rendszerben, úgy a csomag létrehozása sikertelen lesz (API feladás esetén DUPLICATED_UNIQUE_BARCODE hibakód).
Minimális hossz: 0
Maximális hossz: 20
voucher Opcionális String Csomaghoz tartozó voucher kód.

Response

Kód Megnevezés Leírás
201 Sikeres művelet
FIGYELEM! A 201-es sikeres kód nem jelenti azt, hogy a csomagfeladások sikeresek voltak! A visszakapott csomagadatok között (legalább egyben), ha van error kulcs, akkor a feladás sikertelen volt. Amennyiben legalább egy csomagban van hiba, úgy a többi feladása is sikertelen lesz!

Válasz objektum

A válasz objektumban minden egyes rendeléshez visszakapjuk azokat az adatokat, amik mentésre kerültek. Ezek az adatok reprezentálják, hogy a Foxpost rendszerében mi került lementésre. Mindkét rendeléstípus esetén ugyanazokat a kulcsokat kapjuk vissza.

Kulcs Szállítási típus Leírás
recipientName Házhozsszállítás
Csomagautomata
Címzett neve
recipientPhone Házhozsszállítás
Csomagautomata
Címzett telefonszáma
recipientEmail Házhozsszállítás
Csomagautomata
Címzett email címe
size Házhozsszállítás
Csomagautomata
Csomag mérete
recipientCity Házhozsszállítás
Szállítási város
Alapértelmezett: null
recipientZip Házhozsszállítás
Irányítószám
Alapértelmezett: null
recipientAddress Házhozsszállítás
Cím adatok
Alapértelmezett: null
cod Házhozsszállítás
Csomagautomata
Utánvét értéke
Alapértelmezett: 0
deliveryNote Házhozsszállítás
Megjegyzés a futárnak
Alapértelmezett: null
comment Házhozsszállítás
Csomagautomata
Csomag megjegyzés
Alapértelmezett: null
label Házhozsszállítás
Legyen-e címkenyomtatás
Alapértelmezett: null
fragile Házhozsszállítás
Törékeny
Alapértelmezett: null
uniqueBarcode Csomagautomata Egyedi vonalkód
Alapértelmezett: null
refCode Házhozsszállítás
Csomagautomata
Csomag azonosítószáma
Alapértelmezett: null
voucher Házhozsszállítás
Csomagautomata
Alapértelmezett: null
barcode Házhozsszállítás
Csomagautomata
Módosítás esetén a módosított csomag CLFOX kezdetű azonosítója.
Alapértelmezett: null
errors Házhozsszállítás
Csomagautomata
A hibákat tartalmazó kulcs. Ha legalább egy hiba van, akkor értéke egy json, ami egyesével tartalmazza a hibákat. Minden hiba egy json objektum, két kulccsal: {field: 'mező neve', 'message': 'hiba kódja'}
Alapértelmezett: null
barcodeTof Házhozsszállítás
A csomag Express ONE (házhozszállítást végző partner) vonalkódja. Házhozszállításos csomag esetén ez kerül a címkére, illetve ez használható a tracking lekérdezésnél is.
Alapértelmezett: null
sendCode Házhozsszállítás
Csomagautomata
Csomag feladási kódja, B2C feladás esetén nem releváns.
clFoxId Házhozsszállítás
Csomagautomata
A csomag CLFOX kezdetű Foxpost-os azonosítója
partnerType Házhozsszállítás
Csomagautomata
A feladó típusa. Lehetséges értékei: B2C
parcelType Csomagautomata Csomag típusa, értéke automatikusan töltődik.
Lehetséges értékei: "NORMAL" (Normál csomagküldés)
"RE" (Visszaküldött csomag)
"XRE" (Más csomagküldő által kiszállított csomag visszaküldése)
"IRE" (Lejárt tárolási idejű csomag visszaküldése)
sendType Házhozsszállítás
Csomag típusa. Lehetséges értékei: "HD", "APM"
orderId Házhozsszállítás
Csomagautomata
Rendelési azonosító, integrációs szempontból nem releváns.
destination Csomagautomata A cél automata kódja
Alapértelmezett: null

Hibakezelés

Minden csomag visszakapott adatai között található egy errors kulcs. Amennyiben egy beküldés hibára fut, abban az esetben aez az errors kulcs fogja tartalmazni azokat a hibákat, amiket javítani kell a sikeres beküldéshez.

Hibakódok
Hibakód Leírás
MIN_VALUE A kapott érték kisebb, mint a minimálisan elfogadott.
MAX_VALUE A kapott érték nagyobb, mint a maximálisan elfogadott.
MAX_LENGTH A kapott érték hossza nagyobb, mint a maximálisan elfogadott.
INVALID_COD Érvénytelen utánvét érték.
INVALID_ZIP Érvénytelen irányítószám. A megfelelő érték 1000 és 9999 közötti egész szám.
INVALID_SIZE A kapott csomagméret nem megfelelő. A lehetséges értékek: "XS", "S", "M", "L", "XL"
INVALID_NAME Érvénytelen név
CANT_BE_NULL A mező értéke nem lehet null (üres).
INVALID_EMAIL Érvénytelen email cím (formailag hibás)
CANT_BE_EMPTY Mező értéke nem lehet üres
INVALID_PHONE Telefonszám formátuma érvénytelen.
reguláris kifejezés: ^(\+36|36)(20|30|31|70|50)\d{7}$
INVALID_APM_ID A megadott automata id-ja érvénytelen. Az aktuális automata lista innen elérhető: https://cdn.foxpost.hu/apms.json
INVALID_FORMAT A kapott formátum érvénytelen
ADDRESS_NOT_SET Nincs beállítva cím
INVALID_VOUCHER Érvénytelen voucher
INVALID_PARCEL_ID
DUPLICATED_UNIQUE_BARCODE
PUT
/api/parcel

Csomagok módosítása.

Csak azok a csomagok módosíthatók, melyeknek a státusza a Foxpost rendszerében CREATED!

Egy hívással több csomag is átadható, amennyiben egynél több elemű json kerül átadásra.

Request query

Paraméter név Típus Leírás
isWeb Opcionális
Boolean
Megadja, hogy a csomag megjelenjen-e a Foxpost.hu oldalon a csomagok között.
Engedélyezett értékek: true, false
Alapértelmezett érték: true

Request body

Paraméter név Típus Leírás
[] Kötelező
RequestItem[]
Tetszőleges számú HD vagy API Request Item tömb.

Request Items

Paraméter név Típus Leírás
barcode Kötelező String A korábban a csomaghoz kapott clfoxid
cod Opcionális Integer Utánvét értéke
Minimális érték: 0
Maximális érték: 150000
Alapértelmezett érték: 0
deliveryNote Opcionális String Futárnak szóló üzenet
Minimális hossz: 0
Maximális hossz: 50
Alapértelmezett érték: null
fragile Opcionális Bool Törékeny
Engedélyezett értékek: true, false
Alapértelmezett érték: false
label Opcionális Bool Foxpost nyomtasson címkét. Csak c2c csomag esetén használatos.
Engedélyezett értékek: true, false
Alapértelmezett érték: false
recipientAddress Kötelező String Szállítási cím (utca, házszám, emelet, ajtó)
Minimális hossz: 1
Maximális hossz: 150
recipientCity Kötelező String Szállítási cím város
Minimális hossz: 1
Maximális hossz: 50
recipientName Kötelező String Címzett neve
Minimális hossz: 1
Maximális hossz: 150
recipientEmail Kötelező String Címzett email címe
recipientPhone Kötelező String Címzett telefonszáma +36 formátumban. Csak magyarországi mobiltelefon-számokat fogad el a rendszer!
reguláris kifejezés: ^(\+36|36)(20|30|31|70|50)\d{7}$
recipientZip Kötelező Integer Címzett irányítószáma
Minimális érték: 1000
Maximális érték: 9999
refCode Kötelező String Elszámoláshoz használatos csomagoazosító szám. Értéke tetszőleges lehet. Célja, hogy a hó végi elszámolásban azonosítani lehessen a csomagot egy saját azonosítószám alapján.
Minimális hossz: 0
Maximális hossz: 30
size Kötelező String A mező értéke a betöltés során kötelező, azonban a rendszer nem veszi figyelembe, így az értéke lehet fixen M. A végleges érték a Foxpost raktári folyamatai során utóla, automatikusan kerül meghatározásra.
Lehetséges értékek: ["L", "M", "S", "XS", "XL"]
uniqueBarcode Opcionális String Az egyedi vonalkód használata csak automatába történő szállítás esetén használható. Ebben az esetben a címkére nem a Foxpost által generált CLFOX kezdetű vonalkód lesz rányomtatva, hanem a webshop által generált vonalkód.
Fontos, hogy a vonalkódnak egyedinek kell lennie, két egyforma vonalkód nem fordulhat elő a Foxpost rendszerében, ezért fontos, hogy a webshop gondoskodjon a vonalkód egyediségéről.
Amennyiben olyan vonalkód kerül átadásra, ami már létezik a rendszerben, úgy a csomag létrehozása sikertelen lesz (API feladás esetén DUPLICATED_UNIQUE_BARCODE hibakód).
Minimális hossz: 0
Maximális hossz: 20
voucher Opcionális String Csomaghoz tartozó voucher kód.
Paraméter név Típus Leírás
barcode Opcionális String Vonalkód (egyedi vonalkód használata esetén)
Alapértelmezett érték: null
cod Opcionális Integer Utánvét értéke
Minimális érték: 0
Maximális érték: 150000
Alapértelmezett érték: 0
deliveryNote Opcionális String Futárnak szóló üzenet
Minimális hossz: 0
Maximális hossz: 50
Alapértelmezett érték: null
destination Kötelező String A címzett automata kódja. Értéke a korábbi json fájl operator_id mezője.
recipientEmail Kötelező String Címzett email címe
recipientPhone Kötelező String Címzett telefonszáma +36 formátumban
refCode Kötelező String Egyedi csomagazonosító kód. Nem azonos az egyedi vonalkóddal.
Minimális hossz: 0
Maximális hossz: 30
size Kötelező String A csomag mérete
Lehetséges értékek: ["L", "M", "S", "XS", "XL"]
uniqueBarcode Opcionális String Csomaghoz tartozó egyedi vonalkód
Minimális hossz: 0
Maximális hossz: 20
voucher Opcionális String Csomaghoz tartozó voucher kód.

Response

Kód Megnevezés Leírás
201 Sikeres művelet
FIGYELEM! A 201-es sikeres kód nem jelenti azt, hogy a csomagfeladások sikeresek voltak! A visszakapott csomagadatok között (legalább egyben), ha van error kulcs, akkor a feladás sikertelen volt. Amennyiben legalább egy csomagban van hiba, úgy a többi feladása is sikertelen lesz!

Válasz objektum

A válasz objektumban minden egyes rendeléshez visszakapjuk azokat az adatokat, amik mentésre kerültek. Ezek az adatok reprezentálják, hogy a Foxpost rendszerében mi került lementésre. Mindkét rendeléstípus esetén ugyanazokat a kulcsokat kapjuk vissza.

Kulcs Szállítási típus Leírás
recipientName Házhozsszállítás
Csomagautomata
Címzett neve
recipientPhone Házhozsszállítás
Csomagautomata
Címzett telefonszáma
recipientEmail Házhozsszállítás
Csomagautomata
Címzett email címe
size Házhozsszállítás
Csomagautomata
Csomag mérete
recipientCity Házhozsszállítás
Szállítási város
Alapértelmezett: null
recipientZip Házhozsszállítás
Irányítószám
Alapértelmezett: null
recipientAddress Házhozsszállítás
Cím adatok
Alapértelmezett: null
cod Házhozsszállítás
Csomagautomata
Utánvét értéke
Alapértelmezett: 0
deliveryNote Házhozsszállítás
Megjegyzés a futárnak
Alapértelmezett: null
comment Házhozsszállítás
Csomagautomata
Csomag megjegyzés
Alapértelmezett: null
label Házhozsszállítás
Legyen-e címkenyomtatás
Alapértelmezett: null
fragile Házhozsszállítás
Törékeny
Alapértelmezett: null
uniqueBarcode Csomagautomata Egyedi vonalkód
Alapértelmezett: null
refCode Házhozsszállítás
Csomagautomata
Csomag azonosítószáma
Alapértelmezett: null
voucher Házhozsszállítás
Csomagautomata
Alapértelmezett: null
barcode Házhozsszállítás
Csomagautomata
Módosítás esetén a módosított csomag CLFOX kezdetű azonosítója.
Alapértelmezett: null
errors Házhozsszállítás
Csomagautomata
A hibákat tartalmazó kulcs. Ha legalább egy hiba van, akkor értéke egy json, ami egyesével tartalmazza a hibákat. Minden hiba egy json objektum, két kulccsal: {field: 'mező neve', 'message': 'hiba kódja'}
Alapértelmezett: null
barcodeTof Házhozsszállítás
A csomag Express ONE (házhozszállítást végző partner) vonalkódja. Házhozszállításos csomag esetén ez kerül a címkére, illetve ez használható a tracking lekérdezésnél is.
Alapértelmezett: null
sendCode Házhozsszállítás
Csomagautomata
Csomag feladási kódja, B2C feladás esetén nem releváns.
clFoxId Házhozsszállítás
Csomagautomata
A csomag CLFOX kezdetű Foxpost-os azonosítója
partnerType Házhozsszállítás
Csomagautomata
A feladó típusa. Lehetséges értékei: B2C
parcelType Csomagautomata Csomag típusa, értéke automatikusan töltődik.
Lehetséges értékei: "NORMAL" (Normál csomagküldés)
"RE" (Visszaküldött csomag)
"XRE" (Más csomagküldő által kiszállított csomag visszaküldése)
"IRE" (Lejárt tárolási idejű csomag visszaküldése)
sendType Házhozsszállítás
Csomag típusa. Lehetséges értékei: "HD", "APM"
orderId Házhozsszállítás
Csomagautomata
Rendelési azonosító, integrációs szempontból nem releváns.
destination Csomagautomata A cél automata kódja
Alapértelmezett: null

Hibakezelés

Minden csomag visszakapott adatai között található egy errors kulcs. Amennyiben egy beküldés hibára fut, abban az esetben aez az errors kulcs fogja tartalmazni azokat a hibákat, amiket javítani kell a sikeres beküldéshez.

Hibakódok
Hibakód Leírás
MIN_VALUE A kapott érték kisebb, mint a minimálisan elfogadott.
MAX_VALUE A kapott érték nagyobb, mint a maximálisan elfogadott.
MAX_LENGTH A kapott érték hossza nagyobb, mint a maximálisan elfogadott.
INVALID_COD Érvénytelen utánvét érték.
INVALID_ZIP Érvénytelen irányítószám. A megfelelő érték 1000 és 9999 közötti egész szám.
INVALID_SIZE A kapott csomagméret nem megfelelő. A lehetséges értékek: "XS", "S", "M", "L", "XL"
INVALID_NAME Érvénytelen név
CANT_BE_NULL A mező értéke nem lehet null (üres).
INVALID_EMAIL Érvénytelen email cím (formailag hibás)
CANT_BE_EMPTY Mező értéke nem lehet üres
INVALID_PHONE Telefonszám formátuma érvénytelen.
reguláris kifejezés: ^(\+36|36)(20|30|31|70|50)\d{7}$
INVALID_APM_ID A megadott automata id-ja érvénytelen. Az aktuális automata lista innen elérhető: https://cdn.foxpost.hu/apms.json
INVALID_FORMAT A kapott formátum érvénytelen
ADDRESS_NOT_SET Nincs beállítva cím
INVALID_VOUCHER Érvénytelen voucher
INVALID_PARCEL_ID
DUPLICATED_UNIQUE_BARCODE
DELETE

/api/parcel/{barcode}

Csomag törlésére szolgáló végpont. Csak azt a csomagot lehet törölni, amelyik a Foxpost rendszerében CREATE státusszal rendelkezik.

Törölni egyszerre csak egy csomagot lehet. A barcode helyére a csomag CLFOX id-ját kell behelyettesíteni.

Paraméter név Típus Leírás
isWeb Opcionális
Boolean
Megadja, hogy a csomag törlődjön-e a Foxpost.hu oldalon a csomagok közül.
Engedélyezett értékek: true, false
Alapértelmezett érték: true
Címke/szállítólevél

Címkék és szállítólevél nyomtatás

Címke
/api/label/{pageSize}

Fejlécek

A korábbi hívásokkal ellentétben itt a content-type fejlécnek nem json-t kell beállítani, hanem application/pdf-et.

                    
{
    "Accept-Encoding": "Application/json",
    "Content-Type": "Application/pdf",
    "Api-key": "...",
}
            
        

Request path

Paraméter név Típus Leírás
pageSize Kötelező
String
Megadja, hogy mekkora méretben adja vissza a Foxpost rendszere a PDF fájlt.
A hívás egy pdf fájllal tér vissza, ami közvetlenül lementhető/kinyomtatható.
Engedélyezett értékek: A5,A6,A7,_85X85

Request body

Paraméter név Típus Leírás
[] Kötelező
String[]
Azon csomagok clfoxid-jai, amikből címkét szeretnénk nyomtatni.
Címkét bármilyen státuszú rendelésből lehet nyomtatni.

Request query

Paraméter név Típus Leírás
startPos Opcionális
integer
Csak A7 méretű címkénél használható. Megadja, hogy hanyadik pozícióban kezdődjön az A4-es lapon a címkék nyomtatása.
Engedélyezett értékek: 1,2,3,4,5,6,7

Response

Sikeres hívás esetén a válaszban egy pdf fájlt kapunk, amit lementve azonnal nyomtathatóvá válik a címke.

Szállítólevél
/api/label/deliveryNote

Fejlécek

A korábbi hívásokkal ellentétben itt a content-type fejlécnek nem json-t kell beállítani, hanem application/pdf-et.

                    
{
    "Accept-Encoding": "Application/json",
    "Content-Type": "Application/pdf",
    "Api-key": "...",
}
            
        

Request body

Paraméter név Típus Leírás
clFoxCodes Kötelező
String[]
Azon csomagok clfoxid-jai, melyekből szállítólevelet szeretnénk nyomtatni.
Szállítólevelet bármilyen státuszú rendelésből lehet nyomtatni.
sender Kötelező
String
Cégnév, ami a szállítólevélen szerepeljen.
Minimális hossz: 3
Maximális hossz: 20

Response

Sikeres hívás esetén a válaszban egy pdf fájlt kapunk, amit lementve azonnal nyomtathatóvá válik a szállítólevél.

Tracking

Csomagkövetési információk

Tracking
/api/tracking/{barcode}

Request path

Paraméter név Típus Leírás
barcode Kötelező
String
A lekérdezni kívánt csomag CLFOXID-ja, vagy egyedi vonalkód esetén a vonalkód.

Response

Sikeres hívás esetén az API válaszban visszaküldi a tracking információkat.

Kulcs Típus Leírás
clFox String A lekérdezett csomag CLFOXID-ja
estimatedDelivery String A várható kézbesítési dátum
parcelType String Csomag típusa, értéke automatikusan töltődik.
Lehetséges értékei: "NORMAL" (Normál csomagküldés)
"RE" (Visszaküldött csomag)
"XRE" (Más csomagküldő által kiszállított csomag visszaküldése)
"IRE" (Lejárt tárolási idejű csomag visszaküldése)
relatedParcel String Csak RE vagy XRE típusú csomagoknál van relevanciája. A kapcsolódó csomagszámot mutatja.
sendType String Szállítás módja.
Lehetséges értékek: ["APM", "HD"]
traces [] Minden egyes tracking status, amit a csomag felvett, időrendben visszafele. Az első elem (0. kulcs) a legújabb státusz.
Egy elem (tömb) tartalma:
longName: státusz leírása
shortName: státusz elnevezse
status: státusz kódja
statusDate: státusz időpontja
statusStatidionId: ???
Tracking codes

A rendszer által használt tracking státuszok:

code Relevancia elnevezés
CREATE Házhozsszállítás
Csomagautomata
Csomagod elkészült
OPERIN Csomagautomata Automatában
OPEROUT Csomagautomata Úton
RECEIVE Házhozsszállítás
Csomagautomata
Átvéve
REDIRECT Házhozsszállítás
Csomagautomata
Raktárban
OVERTIMEOUT Csomagautomata Visszaküldve
SORTIN Házhozsszállítás
Csomagautomata
Raktárban
SORTOUT Házhozsszállítás
Csomagautomata
Úton
HDSENT Házhozsszállítás Raktárban
HDDEPO Házhozsszállítás Úton
HDRETURN Házhozsszállítás Visszaszállítva
HDRECEIVE Házhozsszállítás Átvéve
BACKTOSENDER Házhozsszállítás
Csomagautomata
Úton
HDHUBOUT Házhozsszállítás Úton
HDCOURIER Házhozsszállítás Úton
HDUNDELIVERABLE Házhozsszállítás Úton
PREPAREDFORPD Házhozsszállítás Raktárban
INWAREHOUSE Házhozsszállítás
Csomagautomata
Raktárban
COLLECTSENT Házhozsszállítás
Csomagautomata
Átvéve
C2BIN Csomagautomata Automatában
RETURNED Házhozsszállítás
Csomagautomata
Visszaküldve
COLLECTED Házhozsszállítás
Csomagautomata
Úton
BACKLOGINFULL Csomagautomata Túltelítettség miatt nem betölthető
BACKLOGINFAIL Csomagautomata Műszaki hiba miatt nem betölthető
MISSORT Házhozsszállítás
Csomagautomata
Téves szortolás
EMPTYSLOT Csomagautomata Üres rekesz
RESENT Házhozsszállítás
Csomagautomata
Raktárban