Dostava: API - Specifikacija

Grupa: Dostavne operacije

Za API pozive je potrebno da koristite korisnički token (accountToken) koji vam dodijeljuje davalac usluge. Za korisnički token se vežu posebne privilegije u odnosu na grupu API poziva.

Osnovni odgovor na API poziv sadrži JSON formatiran zapis: vrijeme, poruku, HTTP status i putanju. Poruka iz odgovora (message atribut) sadrži više detalja o uspješnom odgovoru ili upućuje na kontekst moguće greške. Uz osnovi odgovor mogu biti pridružene strukture sa dodatnim informacijama u zavisnosti od konteksta konkretnog API poziva.

U opisima parametara sa zvjezdicom su naznačeni obavezni parametri.

Dostava

Slanje pošiljke

POST https://preko.edostava.me/api/v1.0/send

Poziv omogućava otpravljanje pošiljke na slanje. Poruka osnovnog odgovora na uspješan poziv sadrži: broj pošiljke, etiketu pošiljke i naziv naplatnog balansa sa iznosom. Uz osnovni odgovor se uključuju dodatne informativne strukture.

Request Body

Name	Type	Description
qualifiedTimestamp	boolean	Naznačava da se dokazi ovjeravaju kvalifikovanim vremenskim pečatom
accountToken*	string	Korisnički token za autorizaciju servisa
files*	array	Jedna ili više priloženih datoteka
fromAddress*	string	Adresa e-pošte pošiljaoca
deliveryMessage*	string	Dostavna poruka pošiljke
reference	string	Proizvoljna referenca pošiljke kod pošiljaoca
toAddress*	string	Adresa e-pošte primaoca
byRegisteredMail	string	Indikator da li se šalje pošiljka preporučenom dostavom
toGivenName	string	Ime osobe primaoca (preporučena dostava)
toSurname	string	Prezime osobe primaoca (preporučena dostava)
toOrganization	string	Naziv organizacije primaoca, da sadrži kriterijum (preporučena dostava)
toOrganizationUnit	string	Naziv organizacione jedinice primaoca, da sadrži kriterijum (preporučena dostava)
toTaxId	string	PIB broj primaoca (preporučena dostava)
requestReceipt	boolean	Indikator da li se zahtjeva potvrda prijema (preporučena dostava)
requestReceiptDeadline	integer	Rok u danima za potvrdu prijema (preporučena dostava). Ukoliko parametar nije proslijeđen predefinisana vrijednost je 7 dana.
receiptReminderDeadline	integer	Rok u danima nakon podsjetnika za potvrdu prijema (preporučena dostava). Ukoliko parametar nije proslijeđen predefinisana vrijednost je 3 dana.
langEn	boolean	Indikator da li je lokalizacija na Engleskom jeziku
templateName	string	Naziv dostavnog obrasca
ccriDeliveryType	string	Tip dostave za plaćeni odgovor (O ili R)
ccriPackageSize	integer	Veličina pošiljke za plaćeni odgovor u MB (25, 50, 75, 100 ili 125)

201: Created Pošiljka je uspješno otpravljena.

{
 "timestamp":"2021-10-22T08:00:00.000000+02:00",
 // informativna stuktura
 "submissionInfo": {submissionInfo}
 "message":"9dbdf73c-41b3-43da-b562-e208f0cefeaf njutnova_baza_8 (0.69€ - Free)",
 "status":200,
 "path":"/api/v1.0/send",
 "method":"POST"
}

400 Neispravan zahtjev.

{
..
 "message":"...",
..
}

401 Niste autorizovani.

{
..
 "message":"...",
..
}

500 Interna serverska greška.

{
..
 "message":"...",
..
}

Preuzimanje pošiljke

GET https://preko.edostava.me/api/v1.0/package/[generated_path]/:filename

Poziv omogućava preuzimanje pošiljke. Na uspješan poziv preuzimate sadržaj pošiljke - datoteka u PDF formatu.

Path Parameters

Name	Type	Description
filename	string	Naziv fajla pod kojim će se sačuvati preuzeta datoteka

Query Parameters

Name	Type	Description
accountToken*	string	Korisnički token za autorizaciju servisa
reference	string	Proizvoljna referenca za pošiljku kod primaoca

200 Pošiljka je preuzeta. Tip odgovora je: application/pdf.

[binary data]

400 Neispravan zahtjev.

{
..
 "message":"...",
..
}

401 Niste autorizovani.

{
..
 "message":"...",
..
}

403 Zabranjena operacija.

{
..
 "message":"...",
..
}

404 Resurs nije pronađen.

{
..
 "message":"...",
..
}

500 Interna serverska greška.

{
..
 "message":"...",
..
}

Potvrda prijema pošiljke

POST https://preko.edostava.me/api/v1.0/receipt/[generated_path]/

Poziv omogućava potvrdu prijema pošiljke. Uz potvrdu prijema možete priložiti proizvoljan sadržaj obavještenja o prijemu i/ili proizvoljne datoteke. Uz osnovni odgovor se uključuju dodatne informativne strukture.

Query Parameters

Name	Type	Description
receiptNote	string	Sadržaj obavještenja o prijemu pošiljke koji se šalje pošiljaocu. Ukoliko nije proslijeđen parametar uzima se predefinisani sadržaj obavještenja o prijemu.
files	array	Jedna ili više priloženih datoteka
accountToken*	string	Korisnički token za autorizaciju servisa

201 Uspješna potvrda prijema.

{
...
 // informativna stuktura
 "receiptInfo": {receiptInfo}
 "message":"...",
...
}

400 Neispravan zahtjev.

{
..
 "message":"...",
..
}

401 Niste autorizovani.

{
..
 "message":"...",
..
}

404 Resurs nije pronađen.

{
..
 "message":"...",
..
}

500 Interna serverska greška.

{
..
 "message":"...",
..
}

Preuzmanje dostavnice

GET https://preko.edostava.me/api/v1.0/deliveryNote/[generated_path]/:filename

Poziv omogućava preuzimanje dostavnice. Na uspješan poziv preuzimate sadržaj dostavnice - datoteka u PDF formatu.

Path Parameters

Name	Type	Description
filename	string	Naziv fajla pod kojim će se sačuvati preuzeta dostavnica.
accountToken*	String	Korisnički token za autorizaciju servisa

200 Dostavnica je preuzata. Tip odgovora: application/pdf.

[binary data]

401 Niste autorizovani.

{
..
 "message":"...",
..
}

404 Resurs nije pronađen.

{
..
 "message":"...",
..
}

500 Interna serverska greška.

{
..
 "message":"...",
..
}

Slanje plaćenog odgovora

POST https://preko.edostava.me/api/v1.0/ccri/[generated_path]/

Poziv omogućava slanje plaćenog odgovora/pošiljke. Uz osnovni odgovor na API poziv se uključuju dodatne informativne strukture.

Query Parameters

Name	Type	Description
accountToken*	string	Korisnički token za autorizaciju servis
files*	array	Jedna ili više priloženih datoteka
deliveryMessage*	string	Dostavna poruka pošiljke
reference	string	Proizvoljna referenca pošiljke kod pošiljaoca
langEn	boolean	Indikator da li je lokalizacija na Engleskom jeziku

201: Created Pošiljka je uspješno otpravljena.

{
 "timestamp":"2021-10-22T08:00:00.000000+02:00",
  // informativna stuktura
 "submissionInfo": {submissionInfo}
 "message":"9dbdf73c-41b3-43da-b562-e208f0cefeaf njutnova_baza_8 (0.69€ - Free)",
 "status":200,
 "path":"/api/v1.0/ccri",
 "method":"POST"
}

400: Bad Request Neispravan zahtjev.

{
..
 "message":"...",
..
}

401: Unauthorized Niste autorizovani.

{
..
 "message":"...",
..
}

500: Internal Server Error Interna serverska greška.

{
..
 "message":"...",
..
}

Preuzimanja obrazaca dostave

GET https://preko.edostava.me/api/v1.0/deliveryTemplate

Poziv omogućava preuzimanje važećih obrazaca dostave.

Query Parameters

Name	Type	Description
accountToken*	string	Korisnički token za autorizaciju servis
langEn	boolean	Indikator da li je lokalizacija na Engleskom jeziku

200: OK Lista uspješno poslata

{
..
 // lista elemenata
 "templates": [ DeliveryTemplateInfo... ]
 "message":"...",
..
}

DeliveryTemplateInfo {
    // naziv obrasca
    String name;
    // opis obrasca u domaćoj lokalizaciji
    String description;
    // opis obrasca na engleskom
    String descriptionLangAlt;
    // adresa primaoca
    String toEmailAddress;
    // ime primaoca
    String toGivenName;
    // prezime primaoca
    String toSurname;
    // naziv organizacije primaoca
    String toOrganization;
    // naziv organizacione jedinice primaoca
    String toOrganizationUnit;
    // PIB organizacije primaoca
    String toTaxId;
    // true: preporučenom dostavom
    Boolean byRegisteredDelivery;
    // true: koristi se kvalifikovani vremenski žig
    Boolean qualifiedTimestamp;
    // obavještenje potvrde prijema
    String receiptNote;
    // obavještenje potvrde prijema na engleskom
    String receiptNoteLangAlt;
    // true; obavještenje potvrde prijema je fiksirano
    Boolean receiptNoteReadOnly;
    // true: uz potvrdu prijema mogu da se prilože fajlovi
    Boolean receiptNoteHasAttachments;
    // referenca kod primaoca
    String recipientReference;
    // true: referenca kod primaoca je fiksirana
    Boolean recipientReferenceReadOnly;
    // dostavna poruka
    String senderMessage;
    // dostavna poruka na engleskom
    String senderMessageLangAlt;
    // true: dostavna poruka je fiksirana
    Boolean senderMessageReadOnly;
    // true: traži se potvrda prijema
    Boolean ackReceipt;
    // prvi rok za potvrdu prijema u danima
    Integer requestReceiptDeadline;
    // drugi rok za potvrdu prijema u danima
    Integer requestReceiptReminderDeadline;
    // faktor cijene
    Integer costsFactor;
    // maksimalna dozvoljena veličina datoteke ili pošiljke
    Integer submissionMaxFileSize;
    // maksimalni dozvoljeni broj fajlova u pošiljci
    Integer submissionMaxFiles;
    // maksimalna dozvoljena veličina datoteke kod potvrde prijema
    Integer receiptMaxFileSize;
    // maksimalna dozvoljeni broj fajlova u pošiljci kod potvrde prijema
    Integer receiptMaxFiles;
    // predviđeni tip plaćenog odgovora 
    String ccriPackageType;
}

400: Bad Request Neispravan zahtjev.

{
..
 "message":"...",
..
}

401: Unauthorized Niste autorizovani.

{
..
 "message":"...",
..
}

500: Internal Server Error Interna serverska greška.

{
..
 "message":"...",
..
}

Praćenje pošiljke

GET https://preko.edostava.me/api/v1.0/track/[generated_path]

Poziv omogućava praćenje pošiljke. Uz osnovni odgovor se uključuju dodatne informativne strukture. Sadržaj odgovora je lokalizovan u odnosu na langEn parametar.

Query Parameters

Name	Type	Description
accountToken*	string	Korisnički token za autorizaciju servis
langEn	boolean	Indikator da li je lokalizacija na Engleskom jeziku

200: OK Info uspješno poslat

{
..
 // lista elemenata
 "transactionReport": [ TransactionRecord... ]
 // informativna stuktura
 "deliveryInfo": {deliveryInfo}
 "message":"...",
..
}

TransactionRecord {
     // predefinisani naziv transakcije:
     //   X-Edostava-Report-Group-Submission
     //   X-Edostava-Report-Group-Acceptance
     //   X-Edostava-Report-Group-Download
     //   X-Edostava-Report-Group-Consignment
     //   X-Edostava-Report-Group-Request-Receipt
     //   X-Edostava-Report-Group-Request-Receipt-Reminder
     //   X-Edostava-Report-Group-Receipt
     String name;
     // opis transakcije
     String description;
     // true: transakcija je neuspještna
     boolean failure;
     // datum transakcije
     String date;
     // izvještaji transakcije
     List<KeyValuePairGroup> pairs;
}

KeyValuePairGroup {
     // naziv izvještaja
     String name;
     // lista parova
     List<KeyValuePair> pairs;
}
    
KeyValuePair {
     // identifikator para
     String key;
     // pridružena vrijednost
     String value;
}

400: Bad Request Neispravan zahtjev.

{
..
 "message":"...",
..
}

401: Unauthorized Niste autorizovani.

{
..
 "message":"...",
..
}

500: Internal Server Error Interna serverska greška.

{
..
 "message":"...",
..
}

Praćenje događaja

GET https://preko.edostava.me/api/v1.0/trackEvent/[generated_path]

Poziv omogućava praćenje događaja iz procesa dostave. Uz osnovni odgovor se uključuju dodatne informativne strukture.

Query Parameters

Name	Type	Description
accountToken*	string	Korisnički token za autorizaciju servis
langEn	boolean	Indikator da li je lokalizacija na Engleskom jeziku

200: OK Info uspješno poslat

{
..
 // informativna stuktura
 "eventInfo": {TrackEventInfo}
 "message":"...",
..
}

400: Bad Request Neispravan zahtjev.

{
..
 "message":"...",
..
}

401: Unauthorized Niste autorizovani.

{
..
 "message":"...",
..
}

500: Internal Server Error Interna serverska greška.

{
..
 "message":"...",
..
}

Verifikacija adrese e-pošte: potraživanje koda

POST /claimEmail

Poziv omogućava potraživanje koda sa čime se započinje procec verifikacije adrese e-pošte. Kod se šalje na adresu e-pošte koja se verifikuje, nakon čega se dobijeni kod proslijeđuje preko verifyEmail API poziva i završno verifikuje posjedovanje pristupa adresi e-pošte.

Query Parameters

Name	Type	Description
accountToken*	string	Korisnički token za autorizaciju servis
emailAddress*	string	Adresa e-pošte za koju se obavlja verifikacija
langEn	boolean	Indikator da li je lokalizacija na Engleskom jeziku

201: Created Kod uspješno generisan i poslat

{
..
 "message":"...",
..
}

400: Bad Request Neispravan zahtjev.

{
..
 "message":"...",
..
}

401: Unauthorized Niste autorizovani.

{
..
 "message":"...",
..
}

500: Internal Server Error Interna serverska greška.

{
..
 "message":"...",
..
}

Verifikacija adrese e-pošte: potvrda sa kodom

POST /verifyEmail

Poziv omogućava finalnu verifikaciju adrese e-pošte. Slanje koda se pokreće preko claimEmail API poziva. Dobijeni kod na adresu e-pošte se proslijeđuje preko ovog API poziva sa čime se završno verifikuje posjedovanje pristupa adresi e-pošte.

Query Parameters

Name	Type	Description
accountToken*	string	Korisnički token za autorizaciju servis
emailAddress*	string	Adresa e-pošte za koju se obavlja verifikacija
verificationCode*	string	Verifikacioni kod dobijen na adresu
langEn	string	Indikator da li je lokalizacija na Engleskom jeziku

200: OK Uspješno verifikovana adresa e-pošte

{
..
 "message":"...",
..
}

400: Bad Request Neispravan zahtjev.

{
..
 "message":"...",
..
}

401: Unauthorized Niste autorizovani.

{
..
 "message":"...",
..
}

500: Internal Server Error Interna serverska greška.

{
..
 "message":"...",
..
}

Dodatne strukture u osnovnom odgovoru

Dodatno uz API send, ccri, receipt

Uz API za slanje pošiljke, plaćenog odgovora i potvrdu prijema se uz osnovni odgovor uključuje SubmissionInfo struktura sa dodatnim informacijama o poslatoj pošiljci.

SubmissionInfo {
    // datum otpremljene pošiljke
    String packageDate;
    // etiketa pošiljke
    String packageLabel;
    // broj pošiljke
    String packageId;
    // veličina priloga pošiljke
    Long packageSize;
    // dostavna poruka prilikom otpremanja
    String deliveryMessage;
    // tip dostave
    String deliveryType;
    // referenca kod pošiljaoca
    String senderReference;
    // ukupan trošak u EUR centima
    Integer totalCosts;
    // ukupan trošak lijepo formatirano
    String costsEUR;
}


ReceiptInfo {
    // sadrži sve kao u SubmissionInfo i dodatno:
    ...
    // tekstualni sadržaj obavještenja potvrde prijema
    String receiptNote;
    // sadržaj datoteke sa obavještenjem
    String receiptFileContent;
    // tip datoteke sa obavještenjem
    String receiptFileMimeType;
    // naziv priložene datoteke sa obavještenjem u pošiljci potvrde prijema
    String receiptFileName;
    // broj pošiljke za koju je otpremljeno obavještenje potvrde prijema
    String receiptForId;
}

Dodatno uz API track

Uz API za praćenje procesa dostave za pošiljku se uz osnovni odgovor uključuje DeliveryInfo struktura sa dodatnim informacijama.

DeliveryInfo {
   // da li je dostava okončana
   boolean isDelivered;
   // datum kada je dostava okončana
   String deliveryDate;
   // broj Dostavnice
   String deliveryNoteId;
   // broj Pošiljke
   String packageId;
   // etiketa pošiljke
   String packageLabel;
}

Dodatno uz API trackEvent

Uz API za praćenje konkretnog događaja iz procesa dostave se uz osnovni odgovor uključuje TrackEventInfo struktura sa dodatnim informacijama.

TrackEventInfo {
    // naziv događaja
    String eventName;
    // predviđen rok u danima
    Integer days;
    // datum nastupanja događaja ili isteka roka, šta prije se desi
    String date;
    // da li je rok istekao
    boolean timedOut;
    // predviđeni rok
    String untilDate;
}