Smart-ID API: mwongozo wa wasanidi programu kuhusu RP API v3

Mapitio ya mwisho: 5 Oktoba 2026 · Si ushauri wa kisheria

Huu ni mwongozo wa API ya Smart-ID unaoanza na msimbo: endpoints, vikao, ukaguzi wa majibu, majaribio ya demo na hadhi ya kisheria. Kwa mikataba na sheria za AML kwa kila nchi, soma mwongozo wetu wa kuunganisha Smart-ID.

Smart-ID kwa muhtasari

Smart-ID ni programu ya simu kutoka SK ID Solutions AS; kupitia Relying Party API ya SK, huduma huitumia kumwingiza mtumiaji au kukusanya sahihi.^[13] Sehemu ya kila ufunguo iko kwenye seva ya SK, ambayo Mamlaka ya Mifumo ya Taarifa ya Estonia (RIA) inaiita "huduma ya seva ya usimamizi wa funguo za Smart-ID".^[4]

Matumizi: watumiaji na miamala

Lithuania ndilo soko kubwa zaidi la Smart-ID likiwa na watumiaji 1,857,471, ikifuatiwa na Latvia yenye 1,198,463 na Estonia yenye 797,395, kwa mujibu wa kihesabu cha moja kwa moja kwenye smart-id.com tarehe 5 Oktoba 2026.^[1] SK inaripoti "karibu miamala milioni 100 kila mwezi".^[2]

Nchini Estonia, Smart-ID ina "sehemu ya soko ya karibu asilimia 60" ya uthibitishaji, kwa mujibu wa ERR News. Kihesabu kinatoa jumla pekee; hakuna chanzo cha msingi kinachotoa sehemu ya Smart-ID kati ya watu wazima wa kila nchi (5 Oktoba 2026).

Kile ambacho mtumiaji anaona

RP API v3 inaifikia programu kwa njia tatu: msimbo wa QR unaobadilika kati ya vifaa tofauti, kiungo cha Web2App au App2App kwenye simu ile ile, au arifa ya push.^[12] SK inatangaza uzoefu wa QR na wa programu kwa programu kama Smart-ID+, ambao "hautegemei tena kuingiza msimbo wako binafsi wa utambulisho kwenye tovuti".^[8]

Jinsi Smart-ID API v3 inavyofanya kazi

API ni REST juu ya HTTPS yenye JSON ya UTF-8.^[19] Familia nne za endpoint za POST hufungua kipindi na kurudisha sessionID; GET moja hurudisha matokeo.^[13]

Familia za endpoint za RP API v3, kutoka muhtasari wa SK.^[13]

Kuingia kwa kifaa kingine kwa kutumia kiungo cha kifaa, kwa muhtasari.^[12][18]

Mitego:

• Kila ombi la awali la v3 hubeba rpChallenge nasibu unalolizalisha wewe. Lilichukua nafasi ya nonce ya v2 dhidi ya mashambulizi ya kurudia (replay).^[20]
• sessionSecret haipaswi kamwe kufika kwenye frontend yako, na mtiririko mmoja hupata ombi moja la kikao, hata unapoonyesha QR na kiungo pamoja.^[18]
• Katika mitiririko ya arifa, unakokotoa msimbo wa tarakimu nne kutoka SHA-256 ya rpChallenge.^[17]
• SK inakutambua kwa IP ya chanzo pamoja na relyingPartyUUID, na inahitaji kubandika ufunguo wa HTTPS (key pinning).^[19]
• Nyaraka za SK zinasema mtumiaji asiye na akaunti hupata HTTP 404, na zinakuomba uonyeshe ujumbe mmoja kwa makosa yote, ili kuzuia uorodheshaji (enumeration).^[19]

Kile biashara inachopokea kutoka API ya Smart-ID

Kikao kilichokamilika hurudisha state, result.endResult, cheti cha mtumiaji katika cert na kitu cha signature. serialNumber ya mhusika ina msimbo wa utambulisho, kwa mfano PNOEE-30001010004, ambapo kiambishi awali kinaonyesha nchi.^[15]

Uthibitishaji wa jibu wa SK unakuhitaji:^[15]

• Hakikisha state ni COMPLETE, endResult ni OK, itifaki ni ACSP_V2 (kuingia) au RAW_DIGEST_SIGNATURE.
• Thibitisha mnyororo dhidi ya CA za SK pekee, kwa OCSP au CRL.
• Dai kila kitambulisho cha sera cha Smart-ID, ili vyeti vingine vya SK vishindwe.
• Linganisha certificateLevel na kiwango unachohitaji.
• Unda upya maudhui yaliyosainiwa na uthibitishe saini.
• Thibitisha thamani za URL ya callback katika mitiririko ya kifaa kimoja.

Kiwango cha uhakikisho na hadhi ya kisheria

Smart-ID haimo katika orodha ya EU ya mifumo ya eID iliyoarifiwa; mfumo ulioarifiwa wa Estonia (High, 7 Novemba 2018) unahusu kitambulisho cha taifa na Mobile-ID.^[6]

Tahadhari: wakazi wa kielektroniki (e-residents) "hawatofautishwi na wakazi".^[5]

Uchunguzi wa kina wa mteja chini ya sheria ya AML ya Estonia

Sheria ya Estonia ya Kuzuia Utakatishaji Fedha na Ufadhili wa Ugaidi (RahaPTS) inaweka njia za mbali katika § 31(3).^[23]

§ 31(3)RahaPTS (Estonia)

"1) e-identimise süsteemi, millest on teatatud ... (EL) nr 910/2014 ... artikli 9 kohaselt ja mis vastab ... artikli 8 lõike 2 punktis b või c sätestatud usaldusväärsuse tasemele" au "2) kvalifitseeritud usaldusteenust"

Chanzo: Riigi Teataja, RahaPTS^[23]

Kwa Kiswahili: mfumo wa eID uliotangazwa katika kiwango kikubwa au cha juu, au huduma ya uaminifu iliyohitimu. Njia ya 1 haifai. Hakuna taarifa rasmi kufikia 5 Oktoba 2026 kuhusu kama vyeti vilivyohitimu vya Smart-ID vinafaa njia ya 2, kwa hiyo uliza Finantsinspektsioon au mshauri wa kisheria. Sheria ya AML ya Lithuania (Kifungu 11) na Kanuni ya Baraza la Mawaziri la Latvia Na. 392 (p. 7.1) zinaorodhesha sahihi ya kielektroniki iliyohitimu au salama miongoni mwa njia kadhaa za mbali.^[28][29]

Kuanzia 2027: Kifungu 22(6) cha AMLR

Kanuni ya Kupambana na Utakatishaji Fedha (AMLR) inatumika kuanzia 10 Julai 2027. Kifungu 22(6)(b) kinakubali "njia za utambulisho wa kielektroniki zinazokidhi matakwa ya Kanuni (EU) Na. 910/2014 kuhusu viwango vya uhakika 'kikubwa' au 'juu' na huduma husika za uaminifu zilizohitimu".^[30] Rasimu za mwisho za viwango za Mamlaka ya Kupambana na Utakatishaji Fedha (AMLA) za tarehe 30 Septemba 2026, ambazo bado si sheria, zinakubali eID katika kiwango kikubwa au cha juu "bila kujali kama zimetangazwa chini ya Kifungu 9".^[31] Ukurasa wetu wa EUDI Wallet unaeleza ratiba ya eIDAS 2.

Jinsi biashara inavyounganishwa: mkataba wa moja kwa moja wa RP au wakala

Mchakato wa SK: jaribu bila malipo bila makubaliano, chagua hatua za usalama, tuma anwani zako za IP na jina la huduma, saini, pokea RP UUID yako, anza kutumia "ndani ya siku chache tangu ombi lako la kwanza".^[21] Mawakala walioidhinishwa pia huuza tena Smart-ID, na taasisi za umma za Estonia zinaweza kutumia lango la TARA la RIA.^[5]

Njia tatu za kufikia Smart-ID.^[21][5]

Orodha ya bei ya SK (kuanzia 1 Juni 2026) inatoza kila "ombi la uthibitishaji au utiaji sahihi la Smart-ID": €0.109 pamoja na kiwango cha chini cha €60 kwa mwezi, hadi €0.0106 kwenye mpango wa milioni 3, na makubaliano binafsi juu ya milioni 5.^[11] SK inaeleza kuwa Smart-ID+ "haina gharama ya ziada" kwa RP waliopo tayari.^[7]

Kujaribu dhidi ya mazingira ya majaribio

Mazingira ya majaribio: https://sid.demo.sk.ee/smart-id-rp/v3/, relyingPartyUUID 00000000-0000-4000-8000-000000000000, jina DEMO. Mazingira halisi: https://rp-api.smart-id.com/v3/.^[14] Akaunti za majaribio kulingana na matokeo:^[16]

Matumizi na kanuni za sekta

• Uandikishaji wa wateja wa KYC na AML. Jina na nambari ya utambulisho binafsi vilivyotiwa saini; ufaafu kwa AML hutofautiana kati ya nchi.^[23][28][29]
• Kamari na umri. Sheria ya Kamari ya Estonia inawazuia walio chini ya miaka 21 kushiriki michezo ya bahati (§ 34(2)). Pia inawataka waendeshaji wa mtandaoni kuthibitisha kila mchezaji na kusajili nambari yake ya utambulisho binafsi (§ 53(1)).^[24] Hatukupata dai la umri pekee katika API.
• Kutia saini. Akaunti zilizohitimu hutia saini kupitia v3/signature; "Walithuania 4 kati ya 10 walitumia sahihi ya kielektroniki iliyohitimu mwaka 2025".^[13][33]
• Mawasiliano ya simu. Hakuna kanuni ya nchi za Baltiki inayotaja Smart-ID kwa usajili wa SIM (5 Oktoba 2026).

Vikwazo na njia mbadala

"Nchini Estonia na Latvia, Smart-ID kwa sasa inapatikana tu kwa watu wenye nambari za utambulisho za kitaifa za Estonia au Latvia"; wasio wakazi wa Lithuania wanaweza kupata Smart-ID Basic katika benki mbili.^[22] Smart-ID haina kikomo cha umri, lakini njia za usajili zina kikomo hicho (kitambulisho cha Latvia kuanzia miaka 14). Akaunti za walio chini ya miaka 18 zinahitaji idhini ya mzazi.^[32]

Hatukupata hitilafu ya huduma iliyorekodiwa hadi 5 Oktoba 2026; hatari kuu ni phishing. Karibu €23 milioni ziliibwa kutoka akaunti za benki za Estonia mwaka 2025 kupitia ulaghai wa PIN, kwa mujibu wa ERR News. Tangu 29 Aprili 2026, usajili nchini Estonia husoma kitambulisho kupitia NFC badala ya kisoma kadi.^[34]

eID kwanza, hati kama njia mbadala; rekodi sababu ya kila njia mbadala iliyohitajika.^[31]

Orodha ya ukaguzi ya utekelezaji wa API ya Smart-ID

Jenga kwanza kwenye demo ya bure ya SK, ili mkataba usubiri hadi msimbo wako ufanye kazi.^[21] Uthibitishaji wa majibu ndio kiini cha kazi.^[15]

• Jenga ukitumia URL ya demo na akaunti za majaribio zilizochapishwa.^[14][16]
• Pendelea mitiririko ya kiungo cha kifaa (device link); ruhusu arifa (notification) tu kwenye vifaa vinavyojulikana.^[13]
• Tengeneza rpChallenge mpya ya nasibu kwa kila kuingia.^[20]
• Bana (pin) ufunguo wa HTTPS wa SK na uweke sessionSecret kwenye seva.^[19][18]
• Tekeleza kila hatua ya uthibitishaji wa majibu wa SK.^[15]
• Tuma kwa SK anwani zako za IP na jina la huduma, kisha tia saini.^[21]
• Andika msingi wako wa kisheria wa matumizi kwa AML katika kila nchi.^[23]
• Ongeza njia ya hati kwa watumiaji wasio na Smart-ID.

Jinsi Didit inavyosaidia kwa Smart-ID

Smart-ID inafanya kazi sasa kwenye Didit kwa uthibitishaji wa eID nchini Estonia, Latvia, Lithuania na Ubelgiji. Didit inashikilia muunganisho wa SK, kwa hiyo huhitaji mkataba wa RP, orodha ya IP zilizoruhusiwa wala msimbo wa vyeti.

Kwenye console, nenda Workflows, hatua ya ID Verification, Countries, chagua nchi na uweke alama kwenye Smart-ID chini ya "Wallets accepted". Kupitia API, weka methods.EST.wallet, unda kikao, kisha soma GET /v3/session/{id}/decision/ au webhook: verification_method ni "wallet" pamoja na kipengele cha wallet_verification, kwa mujibu wa nyaraka za pochi za kidijitali za utambulisho.^[35] Mtumiaji anaidhinisha msimbo wa kulinganisha kwenye programu ya Smart-ID. Didit haiombi PIN kamwe.

Unapata jina kamili, tarehe ya kuzaliwa, nambari binafsi ya utambulisho ya Baltiki, kiwango cha uhakikisho (kilichoandikwa High) na ukaguzi wa sahihi. Hakuna anwani, hakuna picha ya uso. Watumiaji wasio na Smart-ID hutumia badala yake uthibitishaji wa hati pamoja na usomaji wa chipu ya NFC ($0.15), ukaguzi wa uhai (liveness) na ulinganishaji wa uso. KYC kamili ni $0.33 na uchunguzi wa AML ni $0.20. Ni kuingia kwa eID kulikokamilika pekee ndiko kunakotozwa. Uthibitishaji wa Smart-ID uliokamilika unagharimu $0.20 (ukurasa wa bei), na kila eID iko kwenye ukurasa wa pochi za utambulisho wa kidijitali.

Maswali yanayoulizwa mara kwa mara

Vyanzo

1. Ukurasa wa nyumbani wa Smart-ID, kihesabu cha watumiaji cha moja kwa moja, SK ID Solutions, ulisomwa 5 Oktoba 2026.
2. 2025: kuendeleza uaminifu wa kidijitali kuvuka mipaka, SK ID Solutions, 19 Januari 2026.
3. Uaminifu na ushindani katika utambulisho wa kidijitali barani Ulaya, e-Estonia, 2026.
4. Utambulisho wa kielektroniki (eID), Mamlaka ya Mifumo ya Habari (RIA).
5. Maelezo ya kiufundi ya TARA, RIA.
6. Muhtasari wa mifumo ya eID iliyoarifiwa awali na iliyoarifiwa chini ya eIDAS, Tume ya Ulaya, ulisomwa 5 Oktoba 2026.
7. Smart-ID+, SK ID Solutions.
8. Smart-ID mpya inanilinda vipi dhidi ya ulaghai, Maswali Yanayoulizwa Mara kwa Mara ya Smart-ID.
9. Serikali ya Estonia yapitisha Smart-ID+ ili kuimarisha usalama, SK ID Solutions, 28 Januari 2026.
10. Kwa nini wakati mwingine naona msimbo mmoja wa uthibitisho na wakati mwingine mitatu, Maswali ya mara kwa mara ya Smart-ID.
11. Orodha ya bei, SK ID Solutions, inatumika kuanzia 1 Juni 2026.
12. Relying Party API: utangulizi, SK ID Solutions, toleo 3.2.3.
13. Relying Party API: muhtasari wa endpoints za API, SK ID Solutions.
14. Vigezo vya kiufundi vya mazingira, SK ID Solutions.
15. Relying Party API: uthibitishaji wa majibu, SK ID Solutions.
16. Akaunti za majaribio kwa upimaji wa kiotomatiki, SK ID Solutions.
17. Relying Party API: mitiririko inayotumia arifa, SK ID Solutions.
18. Relying Party API: mitiririko ya kiungo cha kifaa, SK ID Solutions.
19. Relying Party API: maelezo ya kiufundi ya API, SK ID Solutions.
20. Relying Party API: kumbukumbu ya mabadiliko, SK ID Solutions.
21. Mchakato wa kuunganisha kwa watoa huduma za kielektroniki, Smart-ID.
22. Je, wageni na wasio wakazi wanaweza kutumia Smart-ID, Maswali ya mara kwa mara ya Smart-ID.
23. Rahapesu ja terrorismi rahastamise tõkestamise seadus (RahaPTS), § 31, Riigi Teataja.
24. Hasartmänguseadus (Sheria ya Michezo ya Kubahatisha), Riigi Teataja.
25. Elektroniskā identifikācija, Wizara ya Ulinzi ya Latvia.
26. Smart-ID imepata hadhi ya ndani ya kuidhinishwa (qualified) kwa uthibitishaji nchini Latvia, SK ID Solutions, 29 Mei 2023.
27. Smart-ID na Mobile-ID zatambuliwa kama zana zilizoidhinishwa na serikali nchini Lithuania, SK ID Solutions, 19 Desemba 2024.
28. Sheria ya Kuzuia Utakatishaji Fedha na Ufadhili wa Ugaidi, Ibara ya 11, Lithuania, maandishi yaliyounganishwa ya INFOLEX.
29. Kanuni ya Baraza la Mawaziri Na. 392, Latvia, likumi.lv.
30. Kanuni (EU) 2024/1624 (AMLR), EUR-Lex, Gazeti Rasmi la tarehe 19 Juni 2024.
31. Ripoti ya Mwisho, rasimu ya RTS chini ya Ibara ya 28(1) ya AMLR, AMLA, 30 Septemba 2026.
32. Vikwazo vya umri vya kutumia Smart-ID, Maswali ya mara kwa mara ya Smart-ID.
33. SK ID Solutions ilitoa karibu vyeti milioni tatu nchini Lithuania mwaka 2025, SK ID Solutions, 7 Mei 2026.
34. Usajili wa Smart-ID kwa kitambulisho cha Estonia sasa unapatikana kupitia NFC, Smart-ID, 29 Aprili 2026.
35. Pochi za utambulisho wa kidijitali, nyaraka za Didit.
36. Relying Party API: mwingiliano, SK ID Solutions.

Smart-ID ni mojawapo ya eID tano zinazofanya kazi katika uthibitishaji wa eID wa Didit. Tazama pia uthibitishaji wa eID ni nini na mwongozo wa API ya BankID Sweden.