> 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-prakticni-primjeri.md).

# Dostava: API - Praktični primjeri

Koristeći cURL CLI alat preko Linux terminala

Prije nego što nastavite potrebno je da barem jednom prođete kroz proces dostave  [preko servisnog portala](https://preko.edostava.me). Za korisničko uputstvo krenite [odavde](https://knjiga.edostava.me/prirucnik/servisni-portal/autentifikacija-navigacija.md).&#x20;

{% hint style="info" %}
Prilikom prvog otpremanja pošiljke preko servisnog portala ćete verifikovati mejl adresu sa koje šaljete pošiljku (adresa pošiljaoca). Ukoliko nijeste verifikovali adresu, onda nećete moći ni da prozivate API pozive. Verifikacija mejl adrese nije potrebna ukoliko je upisana u sam certifikat.&#x20;
{% endhint %}

Za praktičnu probu API poziva je potrebno da prethodno obezbijedite:&#x20;

* [x] Linux terminal i cURL alat (`yum install curl`)
* [x] korisnički token za [API pozive](https://knjiga.edostava.me/prirucnik/integracija/dostavne-operacije/dostava-api-specifikacija.md) ([kako da dobijem korisnički token?](https://knjiga.edostava.me/prirucnik/integracija/kako-da-dobijem-korisnicki-token.md))
* [x] verifikovanu mejl adresu pošiljaoca ([verifikovana preko servisnog portala](https://knjiga.edostava.me/prirucnik/servisni-portal/verifikacija-adrese-posiljaoca.md))
* [x] mejl adresu primaoca (može ista kao i adresa pošiljaoca).
* [x] klijentski certifikat u p12 formatu (CA: CoreIT, PoštaCG, Telekom)

U primjerima koristimo vrijednost `token123` za korisnički token. Za mejl adrese koristimo `posiljalac@example.com` i `primalac@example.com`. Za certifikat koristimo naziv datoteke `clientCert.p12` i lozinku `qwerty` za pristup certifikatu.&#x20;

Na početku, napravićemo datoteke koje otpremamo na slanje preko servisa elektronske dostave. U terminalu izvršite sljedeće komande:

```bash
echo "Sadržaj datoteke1" > datoteka1.txt
echo "Sadržaj datoteke2" > datoteka2.txt
```

{% hint style="info" %}
Pobrinite se da u istom direktorijumu kopirate datoteku sa certifikatom (p12 datoteka).
{% endhint %}

## Slanje pošiljke

U nastavku su dati primjeri otpremanja pošiljke na slanje. Ukoliko je API poziv uspješan dobija se povratna HTTP poruka `201 Created`, a u poruci iz odgovora jedinstveni broj pošiljke, etiketa, cijena i sa kojeg bilansa se naplaćuje.

`9e07c5cd-1ae8-40ad-935c-34d3da684458 hirovita_metrika_14 (0.69€ - Free)`

### Primjer 1: Obična dostava (O)

Šaljemo datoteke, naznačavamo primaoca i pošiljaoca, definišemo dostavnu poruku, kao i referencu pošiljke na strani primaoca.&#x20;

{% hint style="info" %}
Parametar fromAddress sadrži mejl adresu pošiljaoca koja prethodno mora biti verifikovana [preko servisnog portala](https://preko.edostava.me). Pogledajte uputstvo kako uraditi [verifikaciju](https://knjiga.edostava.me/prirucnik/servisni-portal/verifikacija-adrese-posiljaoca.md).
{% endhint %}

```bash
curl -v --cert-type P12 --cert clientCert.p12:qwerty \
 -F accountToken=token123 \
 -F "files=@datoteka1.txt" \
 -F "files=@datoteka2.txt" \
 -F fromAddress=posiljalac@example.com \
 -F toAddress=primalac@example.com \
 -F deliveryMessage="U prilogu su dvije datoteke" \
 -F reference="ref-slanja-123" \
 https://preko.edostava.me/api/v1.0/send
```

### Primjer 2: Preporučena dostava (R)

Dodatno u odnosu na prethodni primjer naznačavamo preporučenu dostavu (byRegisteredMail) i identifikaciju primaoca koristeći PIB broj 12345678 (toTaxId).

```bash
curl -v --cert-type P12 --cert clientCert.p12:qwerty \
 -F accountToken=token123 \
 -F "files=@datoteka1.txt" \
 -F "files=@datoteka2.txt" \
 -F fromAddress=posiljalac@example.com \
 -F toAddress=primalac@example.com \
 -F deliveryMessage="U prilogu su dvije datoteke" \
 -F reference="ref-slanja-123" \
 -F byRegisteredMail=true \
 -F toTaxId=12345678 \
 https://preko.edostava.me/api/v1.0/send
```

### Primjer 3: Preporučena (R) sa kvalifikovanim žigom (K)

Dodatno u odnosu na prethodni primjer naznačavamo ovjeru dokaza sa kvalifikovanim vremenskim žigom (qualifiedTimestamp).

```bash
curl -v --cert-type P12 --cert clientCert.p12:qwerty \
 -F accountToken=token123 \
 -F "files=@datoteka1.txt" \
 -F "files=@datoteka2.txt" \
 -F fromAddress=posiljalac@example.com \
 -F toAddress=primalac@example.com \
 -F deliveryMessage="U prilogu su dvije datoteke" \
 -F reference="ref-slanja-123" \
 -F byRegisteredMail=true \
 -F toTaxId=12345678 \
 -F qualifiedTimestamp=true \
 https://preko.edostava.me/api/v1.0/send
```

### Primjer 4: Potvrda prijema (AR)

Dodatno u odnosu na prethodni primjer naznačavamo zahtjev za potvrdu prijema (requestReceipt), rok za potvrdu od 7 dana (requestReceiptDeadline), rok za podsjetnik od 3 dana (receiptReminderDeadline), a i uklanjamo naznaku za ovjeru kvalifikovanim vremenskim žigom.

```bash
curl -v --cert-type P12 --cert clientCert.p12:qwerty \
 -F accountToken=token123 \
 -F "files=@datoteka1.txt" \
 -F "files=@datoteka2.txt" \
 -F fromAddress=posiljalac@example.com \
 -F toAddress=primalac@example.com \
 -F deliveryMessage="U prilogu su dvije datoteke" \
 -F reference="ref-slanja-123" \
 -F byRegisteredMail=true \
 -F toTaxId=12345678 \
 -F requestReceipt=true \
 -F requestReceiptDeadline=7 \
 -F receiptReminderDeadline=3 \
 https://preko.edostava.me/api/v1.0/send
```

## Preuzimanje pošiljke

Nakon uspješnog slanja, primalac dobija mejl sa dostavnim obavještenjem -`Nova pošiljka` . Otvorite izvorni oblik mejla tako da možete da vidite sva zaglavlja (headers). U zaglavlju `X-Edostava-Api-Package-Get` je sadržan link preko kojeg možete da preuzmete pošiljku.

{% hint style="info" %}
U zaglavljima mejla se nalaze upisani i drugi [parametri](https://knjiga.edostava.me/prirucnik/integracija/dostavne-operacije/notifikacije.md) dostave koji mogu biti korisni prilikom obrade. Prethodno potvrdite autentičnost mejla.
{% endhint %}

{% hint style="info" %}
Potvrdite autentičnosti primljenog mejla - DMARC provjera, kao i DKIM potpis koji se odnosi na API zaglavlja. API zaglavlja iz mejla su potpisana pod DKIM domenom "api.edostava.me".
{% endhint %}

{% hint style="info" %}
Potrebno je provjeriti integritet sadržaja mejla u skladu sa S/MIME priloženim potpisom davaoca usluge.
{% endhint %}

### Primjer 1: Preuzimanje prvi put

Prvi put kada preuzimate pošiljku možete da naznačite prijemnu referencu (moguće samo prvi put).  Prijemna referenca se upisuje u dokaze.

```bash
curl -v -X GET -OJ \
--cert-type P12 --cert clientCert.p12:qwerty \
-d accountToken=token123 \
-d reference="ref-prijema-456" \
https://preko.edostava.me/api/v1.0/package/eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJlZG9zdGF2YS5tZSIsInN1YiI6InByZXV6bWkiLCJleHAiOjE2MjcxMzU0OTQsImp0aSI6ImExYzMxNWI2LTRhYzktNDVjNC05ZWNiLTZiYTEwNmFiYTY5OSJ9.pUi-3V9DS3QvLfHq1RBPtbof3QVTeWhE-aUK1WWhRZg
```

### Primjer 2: Ponovno preuzimanje

U odnosu na prethodni primjer, prilikom ponovnog preuzimanja pošiljke, izostavljate naznaku prijemne reference (prijemnu referencu je moguće naznačiti samo prilikom prvog preuzimanja).&#x20;

```bash
curl -v -X GET -OJ \
--cert-type P12 --cert clientCert.p12:qwerty \
-d accountToken=token123 \
https://preko.edostava.me/api/v1.0/package/eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJlZG9zdGF2YS5tZSIsInN1YiI6InByZXV6bWkiLCJleHAiOjE2MjcxMzU0OTQsImp0aSI6ImExYzMxNWI2LTRhYzktNDVjNC05ZWNiLTZiYTEwNmFiYTY5OSJ9.pUi-3V9DS3QvLfHq1RBPtbof3QVTeWhE-aUK1WWhRZg
```

## Potvrda prijema

Nakon uspješnog preuzimanja pošiljke, primalac dobija mejl sa dostavnim obavještenjem - `Zahtjev za potvrdu prijema`. Otvorite izvorni oblik mejla tako da možete da vidite sva zaglavlja (headers). U zaglavlju `X-Edostava-Api-Receipt-Post` je sadržan link preko kojeg možete da izvršite potvrdu prijema.

### Primjer 1: Potvrda prijema

Ukoliko se eksplicitno ne navede sadržaj potvrde prijeme onda se koristi predefinisani obrazac.

```bash
curl -v -X POST --cert-type P12 --cert clientCert.p12:qwerty \
 -F accountToken=token123 \
 https://preko.edostava.me/api/v1.0/receipt/eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJlZG9zdGF2YS5tZSIsInN1YiI6InBvdHZyZGkiLCJleHAiOjE2MjU0MTAxOTYsImp0aSI6IjllMDdjNWNkLTFhZTgtNDBhZC05MzVjLTM0ZDNkYTY4NDQ1OCJ9.-EtNNQG3F9uXbBi0HJ2K44EYxn6WAvCNqFArzKZ7Pcc 
```

### Primjer 2: Proizvoljno obavještenje

Dodatno u odnosu na prethodni primjer se naznačava proizvoljan sadržaj potvrde prijema (mora barem 7 riječi).

```bash
curl -v -X POST --cert-type P12 --cert clientCert.p12:qwerty \
 -F accountToken=token123 \
 -F receiptNote="Obavještavamo vas da smo uspješno primili pošiljku i priložene datoteke." \
 https://preko.edostava.me/api/v1.0/receipt/eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJlZG9zdGF2YS5tZSIsInN1YiI6InBvdHZyZGkiLCJleHAiOjE2MjU0MTAxOTYsImp0aSI6IjllMDdjNWNkLTFhZTgtNDBhZC05MzVjLTM0ZDNkYTY4NDQ1OCJ9.-EtNNQG3F9uXbBi0HJ2K44EYxn6WAvCNqFArzKZ7Pcc 
```

## Preuzimanje dostavnice

Nakon uspješnog primanja pošiljke (sa potvrdom prijema ili bez), pošiljalac i primalac dobijaju mejl sa dostavnim obavještenjem - `Dostavnica` . Otvorite izvorni oblik mejla tako da možete da vidite sva zaglavlja (headers). U zaglavlju `X-Edostava-Api-Delivery-Note-Get` je sadržan link preko kojeg možete da preuzmete dostavnicu.

### Primjer: Preuzimanje

```bash
curl -v -X GET -OJ \
--cert-type P12 --cert clientCert.p12:qwerty \
-d accountToken=token123 \
 https://preko.edostava.me/api/v1.0/deliveryNote/eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJlZG9zdGF2YS5tZSIsInN1YiI6ImRvc3Rhdm5pY2EiLCJleHAiOjE2MjU5Mjk0ODgsImp0aSI6IjllMDdjNWNkLTFhZTgtNDBhZC05MzVjLTM0ZDNkYTY4NDQ1OCJ9.bPM6aUW_RXzRE9EVtmWDeofx8y6lJGeORMmiMr-Rdqg
```
