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. Za korisničko uputstvo krenite odavde.

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.

Za praktičnu probu API poziva je potrebno da prethodno obezbijedite:

• Linux terminal i cURL alat (yum install curl)

• korisnički token za API pozive (kako da dobijem korisnički token?)

• verifikovanu mejl adresu pošiljaoca (verifikovana preko servisnog portala)

• mejl adresu primaoca (može ista kao i adresa pošiljaoca).

• klijentski certifikat u p12 formatu (CA: CoreIT, PoštaCG, Telekom)

U primjerima koristimo vrijednost token123 za korisnički token. Za mejl adrese koristimo [e-mail] i [e-mail]. Za certifikat koristimo naziv datoteke clientCert.p12 i lozinku qwerty za pristup certifikatu.

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

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

Pobrinite se da u istom direktorijumu kopirate datoteku sa certifikatom (p12 datoteka).

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.

Parametar fromAddress sadrži mejl adresu pošiljaoca koja prethodno mora biti verifikovana preko servisnog portala. Pogledajte uputstvo kako uraditi verifikaciju.

curl -v --cert-type P12 --cert clientCert.p12:qwerty \
 -F accountToken=token123 \
 -F "files=@datoteka1.txt" \
 -F "files=@datoteka2.txt" \
 -F fromAddress=[e-mail] \
 -F toAddress=[e-mail] \
 -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).

curl -v --cert-type P12 --cert clientCert.p12:qwerty \
 -F accountToken=token123 \
 -F "files=@datoteka1.txt" \
 -F "files=@datoteka2.txt" \
 -F fromAddress=[e-mail] \
 -F toAddress=[e-mail] \
 -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).

curl -v --cert-type P12 --cert clientCert.p12:qwerty \
 -F accountToken=token123 \
 -F "files=@datoteka1.txt" \
 -F "files=@datoteka2.txt" \
 -F fromAddress=[e-mail] \
 -F toAddress=[e-mail] \
 -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.

curl -v --cert-type P12 --cert clientCert.p12:qwerty \
 -F accountToken=token123 \
 -F "files=@datoteka1.txt" \
 -F "files=@datoteka2.txt" \
 -F fromAddress=[e-mail] \
 -F toAddress=[e-mail] \
 -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.

U zaglavljima mejla se nalaze upisani i drugi parametri dostave koji mogu biti korisni prilikom obrade. Prethodno potvrdite autentičnost mejla.

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".

Potrebno je provjeriti integritet sadržaja mejla u skladu sa S/MIME priloženim potpisom davaoca usluge.

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.

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).

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.

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).

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

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