Tengdu Öruggu rekjanlegu gagnasendingarþjónustuna (eDelivery) á innan við 3 dögum

Innleiðingin

Örugga rekjanlega gagnasendingarþjónustan hefur hlotið skráningu og heimild hjá Byggðastofnun Íslands sem póstþjónusta. Þjónustuna má því m.a. nota til að senda ábyrgðarbréf með stafrænum hætti í samræmi við ákvæði laga þar um. Kerfið þitt hleður upp PDF-skjali og segir Justikal hver á að fá það. Justikal lætur viðtakandann vita, sem þarf að auðkenna sig með rafrænum skilríkjum áður en skjalið opnast. Hvert skref — sent, opnað, undirritað — er tímastimplað í atburðaskrá, og þú getur sótt formlegt móttökuvottorð fyrir hverja heppnaða sendingu.

Leiðin: 7 skref þar til allt er komið í gang

Grænu skrefin tilheyra þér; dökku skrefin sér Justikal um. Aðeins þrjú þeirra fela í sér að skrifa kóða.

Áður en þú skrifar nokkurn kóða

Fyrsta sendingin, skref fyrir skref

Það sem þú gerir næst

Þú gerir eitt HTTP-kall sem hleður upp PDF-skjali og segir Justikal hver á að fá það. Justikal sendir viðtakandanum svo öruggan tengil í tölvupósti fyrir þína hönd. Kallið er venjulegt multipart/form-data POST — sama snið og skráarupphleðsluform á hvaða vefsíðu sem er — svo allir HTTP-clientar styðja það beint.

# Skiptu út lyklinum og notaðu þitt eigið netfang sem viðtakanda,
# svo ÞÚ fáir sendinguna og sjáir alla upplifunina.
curl -X POST "https://demoapi-is.justikal.com/external/api/v1/edeliveries" \
  -H "Authorization: Bearer jkt_þinn_lykill" \
  -F "pdfFile=@/slod/a/skjal.pdf" \
  -F "recipientName=Jón Jónsson" \
  -F "recipientCountry=IS" \
  -F "recipientPersonalCode=1234567890" \
  -F "recipientEmail=thu@fyrirtaeki.is" \
  -F "emailSubject=Prófunarsending frá okkur" \
  -F "message=Vinsamlegast kynntu þér og staðfestu móttöku þessa skjals."

import fs from "node:fs";

const form = new FormData();
form.append("pdfFile", new Blob([fs.readFileSync("skjal.pdf")]), "skjal.pdf");
form.append("recipientName", "Jón Jónsson");
form.append("recipientCountry", "IS");
form.append("recipientPersonalCode", "1234567890");
form.append("recipientEmail", "thu@fyrirtaeki.is");
form.append("emailSubject", "Prófunarsending frá okkur");
form.append("message", "Vinsamlegast kynntu þér og staðfestu móttöku þessa skjals.");

const res = await fetch(
  "https://demoapi-is.justikal.com/external/api/v1/edeliveries",
  { method: "POST",
    headers: { Authorization: `Bearer ${process.env.JUSTIKAL_TOKEN}` },
    body: form });
const delivery = await res.json();

import os, requests

with open("skjal.pdf", "rb") as f:
    res = requests.post(
        "https://demoapi-is.justikal.com/external/api/v1/edeliveries",
        headers={"Authorization": f"Bearer {os.environ['JUSTIKAL_TOKEN']}"},
        files={"pdfFile": f},
        data={
            "recipientName": "Jón Jónsson",
            "recipientCountry": "IS",
            "recipientPersonalCode": "1234567890",
            "recipientEmail": "thu@fyrirtaeki.is",
            "emailSubject": "Prófunarsending frá okkur",
            "message": "Vinsamlegast kynntu þér og staðfestu móttöku þessa skjals.",
        })
delivery = res.json()

Hvað kemur til baka

{
  "id": "550e8400-e29b-41d4-a716-446655440000",   ← geymdu þetta — allt annað vísar í það
  "status": "pending",
  "delivery_url": "https://delivery.justikal.is/550e8400-...",
  "created_at": "2026-08-11T13:54:31+00:00"
}

Lokið — viðtakandinn er kominn með póst. Geymdu id; allir aðrir endapunktar (staða, atburðaskrá, PDF-niðurhal, skýrsla, afturköllun) vísa í það.

Hvað sér viðtakandinn?

Gott að skilja áður en þú tengir — þetta er upplifunin sem viðskiptavinir þínir fá, og nákvæmlega það sem þú sérð þegar þú sendir fyrstu sendinguna á sjálfan þig.

Ferill sendingarinnar

Sending hefur eina status-stöðu í einu; tímastimplar og atburðaskráin geyma smáatriðin. Þetta er það sem tengingin þín fylgist með:

Veldu þitt tengingarstig

Öll þrjú stigin eru fullgild í raunumhverfinu. Lágmarkið kemst hraðast í loftið, full tenging gerir allt sjálfvirkt, og ítarleg tenging gerir upplifunina alfarið þína — þitt lén, þitt vörumerki, þínar tilkynningar.

Leið A — Lágmarkstenging

Skref A1 · Sendu skjalið

Nákvæmlega fyrsta kallið sem þú gerðir áðan. Í raunkóða er eina breytingin að lesa lykilinn úr stillingum og meðhöndla svarið.

Skref A2 · Athugaðu stöðu (þrjár jafngildar leiðir)

Leið 1 — enginn kóði: skráðu þig inn í stjórnborðið og sjáðu hverja sendingu, stöðu hennar og atburðaskrá. Dugar vel fyrir lítið magn.

Leið 2 — fletta upp einni sendingu:

curl "https://demoapi-is.justikal.com/external/api/v1/edeliveries/{id}" \
  -H "Authorization: Bearer jkt_þinn_lykill"

# → staða, viðtakandi og tímastimplar: created_at, delivered_at, signed_at, deadline_at

Leið 3 — sópa öllu sem bíður (mælt með fyrir stöðuvöktun — eitt kall í stað eins á hverja sendingu, vinsamlegt við 100 kalla/mín hraðatakmörkin):

curl "https://demoapi-is.justikal.com/external/api/v1/edeliveries?status=pending&limit=50" \
  -H "Authorization: Bearer jkt_þinn_lykill"

Keyrðu þetta á áætlun — 15–30 mínútna fresti er meira en nóg fyrir flest skjalaferli.

Skref A3 · Sæktu móttökuvottorðið

# Formlega móttökuvottorðið (skilar 404 þar til afhendingu er lokið)
curl ".../edeliveries/{id}/deliveryReport" -H "Authorization: Bearer jkt_..." -o skyrsla.pdf

# Skjalið sjálft — notaðu type=signed þegar signed_at er komið
curl ".../edeliveries/{id}/pdf?type=signed" -H "Authorization: Bearer jkt_..." -o undirritad.pdf

Búið. Þetta er fullgild lágmarkstenging: eitt sendingarkall, ein stöðusópun á áætlun, eitt niðurhal við verklok.

Leið B — Full tenging

Skref B1 · Settu upp webhook-endapunkt

Það sem þú ert að gera: þú gefur Justikal HTTPS-slóð á þínum vefþjóni sem POST-að er á í hvert sinn sem staða sendingar breytist — kerfið þitt bregst við á sekúndum í stað þess að bíða eftir næstu stöðuvöktun.

// Express-dæmi — mynstrið skiptir meira máli en umgjörðin
app.post("/webhooks/justikal", async (req, res) => {
  res.sendStatus(200);                       // 1. svara strax
  const { id } = req.body;
  const delivery = await getDelivery(id);    // 2. endursækja: API-ið er sannleikurinn
  await handleStatusChange(delivery);        // 3. þolið endurtekningu: sami atburður tvisvar = skaðlaust
});

Skref B2 · Sendu með webhook + valmöguleikum

curl -X POST "https://demoapi-is.justikal.com/external/api/v1/edeliveries" \
  -H "Authorization: Bearer jkt_þinn_lykill" \
  -F "pdfFile=@samningur.pdf" \
  -F "recipientName=Jón Jónsson" \
  -F "recipientCountry=IS" \
  -F "recipientPersonalCode=1234567890" \
  -F "recipientEmail=jon@example.com" \
  -F "emailSubject=Samningurinn þinn er tilbúinn til undirritunar" \
  -F "postbackUrl=https://forritid-thitt.is/webhooks/justikal" \
  -F "expiresAt=2026-09-11" \
  -F "lang=IS" \
  -F "services[]=e_delivery_signature"

Skref B3 · Valfrjálst: taktu yfir upplifun viðtakandans

Skref B4 · Lífsferilsaðgerðir

# Afturkalla sendingu sem hefur ekki verið opnuð (aðeins meðan status = pending)
curl -X POST ".../edeliveries/{id}/revoke" -H "Authorization: Bearer jkt_..."

# Full atburðaskrá, atburð fyrir atburð
curl ".../edeliveries/{id}/audit" -H "Authorization: Bearer jkt_..."

# GDPR: eyða + gera persónuupplýsingar ópersónugreinanlegar (endanleg aðgerð — notaðu revoke fyrir venjulega afturköllun)
curl -X DELETE ".../edeliveries/{id}" -H "Authorization: Bearer jkt_..."

Leið C — Ítarleg tenging (alfarið undir þínu vörumerki)

Fyrir fyrirtæki sem vilja ekkert sýnilegt frá Justikal í ferli viðskiptavinarins: tölvupóstar koma frá þínu netfangi, vefslóðin er þín, og afhendingarferlið fer fram inn á þinni vefslóð. Justikal keyrir „hauslaust“ á bak við tjöldin.

Skref C1 · Stofnaðu sendinguna í hauslausum ham

Hvað þú ert að gera: sama stofnkall og alltaf, en með fánunum sem færa upplifun viðskiptavinarins yfir til þín. Þetta er nákvæmlega samsetningin sem notuð er í banka-/innheimtutengingum í rekstri:

curl -X POST "https://demoapi-is.justikal.com/external/api/v1/edeliveries" \
  -H "Authorization: Bearer jkt_þinn_lykill" \
  -F "pdfFile=@Bref_884.pdf" \
  -F "recipientName=Jón Jónsson" \
  -F "recipientCountry=IS" \
  -F "recipientPersonalCode=1234567890" \
  -F "recipientEmail=jon@example.com" \
  -F "emailSubject=placeholder" \
  -F "expiresAt=2027-01-10" \
  -F "disableNotifications=true" \    # ★ Justikal sendir hvorki póst né SMS
  -F "companyBrandingUsed=true" \     # þitt vörumerki á afhendingarsýninni
  -F "senderNameHidden=true" \        # aðeins nafn fyrirtækis, enginn einstaklingur
  -F "hasAdditionalSecurity=true" \
  -F "postbackUrl=https://ws.fyrirtaeki.is/deliv-endpoint" \
  -F "lang=IS"

Svarið inniheldur delivery_url — stjörnumerktu reitirnir (disableNotifications og postbackUrl) eru lyklarnir sem allt mynstrið hvílir á.

Skref C2 · Birtu sendinguna á bak við þína eigin vefslóð

Það sem þú ert að gera: þú geymir delivery_url á móti þínu eigin skjalanúmeri og birtir hana í iframe á síðu sem þú stjórnar. Vafri viðtakandans sýnir aldrei Justikal-slóð:

<!-- https://skjol.fyrirtaeki.is/doc=73883 — þín síða, þitt vörumerki -->
<iframe
  src="https://delivery.justikal.com/is/e9842df4-1b9a-4d43-bccc-a06d00245d6b?lang=is"
  style="width:100%; height:100vh; border:0"
  allow="publickey-credentials-get">
</iframe>

Bættu ?lang=is (eða en) við slóðina til að stýra tungumáli innfelldu sýnarinnar. Auðkenningin með skilríkjum, birting skjalsins og staðfesting afhendingar fara öll fram inni í rammanum.

Skref C3 · Sendu þína eigin tilkynningu

Það sem þú ert að gera: þar sem Justikal þegir sendir þú viðtakandanum tölvupóst eða SMS úr þínu eigin kerfi — þitt sendandanetfang, þitt sniðmát, þinn frestur í textanum — með tengli á þína síðu úr skrefi C2 (ekki á hráu delivery_url-slóðina).

Skref C4 · Láttu webhooks keyra viðmótið þitt

postbackUrl-webhookið (sama mynstur og í leið B) uppfærir þínar eigin stöðubirtingar og keyrir þín næstu skref — áminningar frá þínu netfangi, uppfærslur mála í grunnkerfinu þínu, sjálfvirkt niðurhal staðfestingar við afhendingu.

Hvað „lágmarks-Justikal“ þýðir í hreinskilni

Þegar eitthvað fer úrskeiðis

Allar villur hafa sama JSON-snið — error-kóði ásamt læsilegum message-texta sem nefnir reitinn eða regluna sem um ræðir:

Gátlisti áður en farið er í loftið

• Tengingin virkar enda á milli í testumhverfinu (senda → staða → móttökuvottorð).
• Póstur sendur á hallo@justikal.com vegna samnings; yfirferð tengingar lokið; rekstrarlykill móttekinn.
• Grunnslóð skipt yfir í api-is.justikal.com
• Webhook-meðhöndlun þolir endurtekningar; 500 endurreynt með vaxandi bið; Retry-After virt við 429.
• hasAdditionalSecurity ákveðið fyrir hvert notkunartilvik (sjálfgefið true = auðkenni borið saman við kennitölu).
• Viðbótarþjónustur (services) í þínum samningi staðfestar við Justikal.