> For the complete documentation index, see [llms.txt](https://knjiga.edostava.me/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://knjiga.edostava.me/prirucnik/integracija/dostavne-operacije/dostava-api-specifikacija.md).

# 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

<mark style="color:green;">`POST`</mark> `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<mark style="color:red;">\*</mark>    | string  | Korisnički token za autorizaciju servisa                                                                                                        |
| files<mark style="color:red;">\*</mark>           | array   | Jedna ili više priloženih datoteka                                                                                                              |
| fromAddress<mark style="color:red;">\*</mark>     | string  | Adresa e-pošte pošiljaoca                                                                                                                       |
| deliveryMessage<mark style="color:red;">\*</mark> | string  | Dostavna poruka pošiljke                                                                                                                        |
| reference                                         | string  | Proizvoljna referenca pošiljke kod pošiljaoca                                                                                                   |
| toAddress<mark style="color:red;">\*</mark>       | 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)                                                                             |

{% tabs %}
{% tab title="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"
}

```

{% endtab %}

{% tab title="400 Neispravan zahtjev." %}

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

{% endtab %}

{% tab title="401 Niste autorizovani." %}

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

{% endtab %}

{% tab title="500 Interna serverska greška." %}

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

{% endtab %}
{% endtabs %}

## Preuzimanje pošiljke

<mark style="color:blue;">`GET`</mark> `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<mark style="color:red;">\*</mark> | string | Korisnički token za autorizaciju servisa       |
| reference                                      | string | Proizvoljna referenca za pošiljku kod primaoca |

{% tabs %}
{% tab title="200 Pošiljka je preuzeta. Tip odgovora je:  application/pdf." %}

```
[binary data]
```

{% endtab %}

{% tab title="400 Neispravan zahtjev." %}

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

{% endtab %}

{% tab title="401 Niste autorizovani." %}

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

{% endtab %}

{% tab title="403 Zabranjena operacija." %}

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

{% endtab %}

{% tab title="404 Resurs nije pronađen." %}

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

{% endtab %}

{% tab title="500 Interna serverska greška." %}

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

{% endtab %}
{% endtabs %}

## Potvrda prijema pošiljke

<mark style="color:green;">`POST`</mark> `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<mark style="color:red;">\*</mark> | string | Korisnički token za autorizaciju servisa                                                                                                                    |

{% tabs %}
{% tab title="201 Uspješna potvrda prijema. " %}

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

{% endtab %}

{% tab title="400 Neispravan zahtjev." %}

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

{% endtab %}

{% tab title="401 Niste autorizovani." %}

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

{% endtab %}

{% tab title="404 Resurs nije pronađen." %}

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

{% endtab %}

{% tab title="500 Interna serverska greška." %}

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

{% endtab %}
{% endtabs %}

## Preuzmanje dostavnice

<mark style="color:blue;">`GET`</mark> `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<mark style="color:red;">\*</mark> | String | Korisnički token za autorizaciju servisa                  |

{% tabs %}
{% tab title="200 Dostavnica je preuzata. Tip odgovora: application/pdf." %}

```
[binary data]
```

{% endtab %}

{% tab title="401 Niste autorizovani." %}

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

{% endtab %}

{% tab title="404 Resurs nije pronađen." %}

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

{% endtab %}

{% tab title="500 Interna serverska greška." %}

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

{% endtab %}
{% endtabs %}

## Slanje plaćenog odgovora

<mark style="color:green;">`POST`</mark> `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<mark style="color:red;">\*</mark>    | string  | Korisnički token za autorizaciju servis             |
| files<mark style="color:red;">\*</mark>           | array   | Jedna ili više priloženih datoteka                  |
| deliveryMessage<mark style="color:red;">\*</mark> | string  | Dostavna poruka pošiljke                            |
| reference                                         | string  | Proizvoljna referenca pošiljke kod pošiljaoca       |
| langEn                                            | boolean | Indikator da li je lokalizacija na Engleskom jeziku |

{% tabs %}
{% tab title="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"
}
```

{% endtab %}

{% tab title="400: Bad Request Neispravan zahtjev." %}

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

{% endtab %}

{% tab title="401: Unauthorized Niste autorizovani." %}

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

{% endtab %}

{% tab title="500: Internal Server Error Interna serverska greška." %}

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

{% endtab %}
{% endtabs %}

## Preuzimanja obrazaca dostave

<mark style="color:blue;">`GET`</mark> `https://preko.edostava.me/api/v1.0/deliveryTemplate`

Poziv omogućava preuzimanje važećih obrazaca dostave.&#x20;

#### Query Parameters

| Name                                           | Type    | Description                                         |
| ---------------------------------------------- | ------- | --------------------------------------------------- |
| accountToken<mark style="color:red;">\*</mark> | string  | Korisnički token za autorizaciju servis             |
| langEn                                         | boolean | Indikator da li je lokalizacija na Engleskom jeziku |

{% tabs %}
{% tab title="200: OK Lista uspješno poslata" %}

<pre><code>
{
..
 // lista elemenata
 "templates": [ DeliveryTemplateInfo... ]
 "message":"...",
..
}

DeliveryTemplateInfo {
    // naziv obrasca
<strong>    String name;
</strong><strong>    // opis obrasca u domaćoj lokalizaciji
</strong>    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;
}

</code></pre>

{% endtab %}

{% tab title="400: Bad Request Neispravan zahtjev." %}

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

{% endtab %}

{% tab title="401: Unauthorized Niste autorizovani." %}

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

{% endtab %}

{% tab title="500: Internal Server Error Interna serverska greška." %}

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

{% endtab %}
{% endtabs %}

## Praćenje pošiljke

<mark style="color:blue;">`GET`</mark> `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<mark style="color:red;">\*</mark> | string  | Korisnički token za autorizaciju servis             |
| langEn                                         | boolean | Indikator da li je lokalizacija na Engleskom jeziku |

{% tabs %}
{% tab title="200: OK Info uspješno poslat" %}

<pre><code>{
..
 // 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
<strong>     String name;
</strong><strong>     // opis transakcije
</strong>     String description;
     // true: transakcija je neuspještna
     boolean failure;
     // datum transakcije
     String date;
     // izvještaji transakcije
     List&#x3C;KeyValuePairGroup> pairs;
}

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

{% endtab %}

{% tab title="400: Bad Request Neispravan zahtjev." %}

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

{% endtab %}

{% tab title="401: Unauthorized Niste autorizovani." %}

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

{% endtab %}

{% tab title="500: Internal Server Error Interna serverska greška." %}

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

{% endtab %}
{% endtabs %}

## Praćenje događaja

<mark style="color:blue;">`GET`</mark> `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<mark style="color:red;">\*</mark> | string  | Korisnički token za autorizaciju servis             |
| langEn                                         | boolean | Indikator da li je lokalizacija na Engleskom jeziku |

{% tabs %}
{% tab title="200: OK Info uspješno poslat" %}

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

{% endtab %}

{% tab title="400: Bad Request Neispravan zahtjev." %}

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

{% endtab %}

{% tab title="401: Unauthorized Niste autorizovani." %}

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

{% endtab %}

{% tab title="500: Internal Server Error Interna serverska greška." %}

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

{% endtab %}
{% endtabs %}

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

<mark style="color:green;">`POST`</mark> `/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<mark style="color:red;">\*</mark> | string  | Korisnički token za autorizaciju servis             |
| emailAddress<mark style="color:red;">\*</mark> | string  | Adresa e-pošte za koju se obavlja verifikacija      |
| langEn                                         | boolean | Indikator da li je lokalizacija na Engleskom jeziku |

{% tabs %}
{% tab title="201: Created Kod uspješno generisan i poslat" %}

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

{% endtab %}

{% tab title="400: Bad Request Neispravan zahtjev." %}

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

{% endtab %}

{% tab title="401: Unauthorized Niste autorizovani." %}

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

{% endtab %}

{% tab title="500: Internal Server Error Interna serverska greška." %}

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

{% endtab %}
{% endtabs %}

## Verifikacija adrese e-pošte: potvrda sa kodom

<mark style="color:green;">`POST`</mark> `/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<mark style="color:red;">\*</mark>     | string | Korisnički token za autorizaciju servis             |
| emailAddress<mark style="color:red;">\*</mark>     | string | Adresa e-pošte za koju se obavlja verifikacija      |
| verificationCode<mark style="color:red;">\*</mark> | string | Verifikacioni kod dobijen na adresu                 |
| langEn                                             | string | Indikator da li je lokalizacija na Engleskom jeziku |

{% tabs %}
{% tab title="200: OK Uspješno verifikovana adresa e-pošte" %}

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

{% endtab %}

{% tab title="400: Bad Request Neispravan zahtjev." %}

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

{% endtab %}

{% tab title="401: Unauthorized Niste autorizovani." %}

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

{% endtab %}

{% tab title="500: Internal Server Error Interna serverska greška." %}

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

{% endtab %}
{% endtabs %}

## 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;
}
```
