¶ Pripojenie na Digitálneho poštára ASSECO
Digitálny poštár ASSECO (APEX) doručuje e-faktúry medzi vašou firmou a vašimi obchodnými partnermi. Aby ho mohol systém SPIN (alebo QASIDA ERP) používať, je potrebné ho raz pripojiť. Na to slúži Sprievodca pripojením na Digitálneho poštára. Sprievodca sám skontroluje všetko potrebné, a ak niečo chýba, povie vám, čo urobiť.
Stránka má dve časti:
- Používateľská príručka – ako sprievodcu prejsť, krok za krokom.
- Technické podrobnosti pre správcu IT – čo presne sprievodca overuje a ako riešiť chyby na serveri.
¶ Používateľská príručka
¶ Čo budete potrebovať
| Čo | Kedy to potrebujete | Kde to získate |
|---|---|---|
| Server QASIDA API nainštalovaný vo vašej firme | vždy | inštaluje ho správca IT vo vašej firme |
Adresa servera QASIDA API (napr. https://server:5001/) |
ak ešte nie je v systéme nastavená | od správcu IT; v sprievodcovi ju zadáva administrátor |
| Jednorazový registračný kľúč | ak vaša firma ešte nie je zaregistrovaná | od podpory Asseco Solutions |
| Jednorazový kód na inštaláciu certifikátu | ak certifikát ešte nie je vytvorený alebo ho treba vytvoriť nanovo | vygenerujete si ho v Zákazníckom portáli |
Registračný kľúč aj kód na inštaláciu sa dajú použiť len raz a kód na inštaláciu platí iba niekoľko minút. Vygenerujte si ho, až keď ste v kroku Certifikát.
¶ Ako sprievodcu spustiť
Na karte Administrácia v skupine API komunikácia kliknite na Sprievodca Digitálny poštár (v menu Sprievodca pripojením na Digitálneho poštára).
Sprievodca sa otvorí ako samostatné okno. V hornej časti je prehľad piatich krokov – na ktorýkoľvek krok sa dá kliknúť a prejsť naň priamo. Pri kroku, ktorý ste už navštívili, sa ukáže výsledok:
- zelená kvačka – krok je v poriadku,
- červený výkričník – v kroku treba niečo vyriešiť alebo doplniť.
V spodnej lište je vždy tlačidlo Ukončiť a odkaz Dokumentácia k pripojeniu, ktorý otvorí túto stránku.
¶ Krok 1 – Úvod
Úvod vysvetľuje, čo vás čaká. Kliknite na Začať. Sprievodca hneď spustí kontroly všetkých krokov naraz – kým ich vykonáva, točí sa pri nich koliesko. Kontrola môže trvať aj niekoľko desiatok sekúnd.
¶ Krok 2 – Komunikačný server
Systém SPIN komunikuje s Digitálnym poštárom cez server QASIDA API, ktorý je nainštalovaný vo vašej firme. V tomto kroku sprievodca overí, že je server pripravený. Kontroly sú v zozname:
- Server je dostupný
- Verzia servera je aktuálna
- Komunikácia s Digitálnym poštárom je povolená
- Služba registrácie je dostupná
- Služba certifikátov je dostupná
Ak sú všetky kontroly v poriadku, uvidíte hlásenie Server je pripravený a môžete pokračovať tlačidlom Ďalej.
Ak niektorá kontrola zlyhá, sprievodca zobrazí červené hlásenie s popisom problému a s radou Čo urobiť. Kontroly, ktoré sa kvôli prvej chybe nedali vykonať, majú sivú pomlčku a poznámku, kedy sa overia.
V hlásení sú tlačidlá:
- Skontrolovať znova – zopakuje všetky kontroly, napr. keď správca IT problém odstránil.
- Kopírovať podrobnosti pre IT – skopíruje do schránky technický súhrn, ktorý môžete vložiť do e-mailu správcovi IT alebo podpore Asseco Solutions.
- Nastaviť adresu servera – zobrazí sa, keď je problémom adresa servera. Adresu môže nastaviť iba administrátor; ostatným používateľom je tlačidlo neaktívne.
Príklad hlásenia, keď je na serveri stará verzia QASIDA API:
¶ Krok 3 – Certifikát
Certifikát zaručuje, že s Digitálnym poštárom komunikuje len vaša firma. Vystavuje ho Asseco Solutions a ukladá sa na server QASIDA API. Certifikát patrí serveru, nie firme – stačí jeden pre všetky firmy, ktoré cez server komunikujú.
Certifikát ešte nie je vytvorený. V Zákazníckom portáli si vygenerujte jednorazový kód na inštaláciu, vložte ho do sprievodcu a kliknite na Vytvoriť certifikát.
Certifikát je platný. Zelené hlásenie ukazuje, dokedy certifikát platí. Server QASIDA API ho pred koncom platnosti obnovuje sám, nemusíte nič robiť.
Odkaz Potrebujete vytvoriť nový certifikát? otvorí zadanie kódu na inštaláciu aj pri platnom certifikáte. Nový certifikát nahradí súčasný.
Certifikát nie je v poriadku. Napríklad mu končí platnosť a automatická obnova neprebehla, už exspiroval alebo ho komunikačný server neprijal. Vytvorte nový certifikát pomocou jednorazového kódu na inštaláciu. Ak problém pretrváva, pošlite podrobnosti správcovi IT alebo podpore Asseco Solutions.
¶ Krok 4 – Registrácia firmy
Každá firma, ktorá posiela alebo prijíma e-faktúry cez Digitálneho poštára, musí byť zaregistrovaná. V hornej časti kroku je firma, ktorej registrácia sa zobrazuje – na začiatku je to firma, v ktorej práve pracujete. Tlačidlom Zmeniť firmu si môžete vybrať inú.
Firma ešte nie je zaregistrovaná. Vložte jednorazový registračný kľúč od podpory Asseco Solutions a kliknite na Registrovať. Výsledok registrácie sa zobrazí hneď, potom sprievodca kontroly zopakuje.
Firma je zaregistrovaná. Zelené hlásenie znamená, že spojenie s Digitálnym poštárom funguje.
Pod hlásením je odkaz Potrebujete firmu zaregistrovať znova? Opätovná registrácia nahradí súčasné pripojenie firmy – použite ju len na odporúčanie podpory Asseco Solutions.
Registráciu zatiaľ nie je možné overiť. Ak nie je v poriadku krok Komunikačný server, registráciu nemá zmysel overovať. Tlačidlom Prejsť na Komunikačný server sa vrátite k problému, ktorý treba vyriešiť najprv.
¶ Krok 5 – Zhrnutie
Zhrnutie ukazuje výsledok všetkých kontrol. Ak je všetko v poriadku, uvidíte Pripojenie je hotové – e-faktúry sa budú odosielať a prijímať automaticky. Sprievodcu zatvorte tlačidlom Dokončiť.
Ak niektorý krok nie je dokončený, je pri ňom tlačidlo Prejsť na krok. Sprievodcu môžete kedykoľvek ukončiť a vrátiť sa k nemu neskôr – pri ďalšom spustení všetko skontroluje znova.
Tlačidlo Technický súhrn zobrazí podrobný výpis všetkých kontrol. Ten istý výpis kopíruje do schránky tlačidlo Kopírovať podrobnosti pre IT. Pošlite ho podpore Asseco Solutions, keď ju žiadate o pomoc.
¶ Časté situácie
| Hlásenie v sprievodcovi | Čo urobiť |
|---|---|
| Adresa servera nie je nastavená | Administrátor nastaví adresu tlačidlom Nastaviť adresu servera. Adresu poskytne správca IT. |
| Server nie je dostupný | Správca IT overí, že server QASIDA API beží a že je adresa správna. Potom Skontrolovať znova. |
| Server hlási problém | Server odpovedá, ale hlási vlastnú chybu (napr. s databázou). Pošlite podrobnosti správcovi IT. |
| Server je potrebné aktualizovať | Správca IT aktualizuje server QASIDA API. Potom Skontrolovať znova. |
| Komunikácia s Digitálnym poštárom nie je povolená | Správca IT povolí komunikáciu v nastaveniach servera QASIDA API. |
| Služby Digitálneho poštára nie sú dostupné | Správca IT overí pripojenie servera QASIDA API do internetu (firewall, proxy). |
| Firma zatiaľ nie je zaregistrovaná | Zadajte jednorazový registračný kľúč od podpory Asseco Solutions. |
| Firmu nie je možné zaregistrovať | V systéme chýba potrebné nastavenie (napr. API token). Pošlite podrobnosti správcovi IT. |
| Pripojenie firmy nefunguje | Pošlite podrobnosti správcovi IT alebo podpore. Firmu zaregistrujte znova, len ak vám to podpora odporučí. |
| Certifikát zatiaľ nie je vytvorený | Vygenerujte si v Zákazníckom portáli kód na inštaláciu a vytvorte certifikát. |
| Certifikát nie je v poriadku | Vytvorte nový certifikát s novým kódom na inštaláciu. |
| QASIDA API neodpovedalo do … s | Registrácia alebo certifikát sa mohli napriek tomu vytvoriť. Pred ďalším pokusom kliknite na Skontrolovať znova – jednorazový kľúč alebo kód už mohol byť použitý. |
¶ Dobré vedieť
- Kontroly sa spúšťajú automaticky pri prvom prechode z úvodu, po každej zmene, ktorú sprievodca urobí (adresa servera, výber firmy, registrácia, certifikát), a tlačidlom Skontrolovať znova.
- Kým prebieha registrácia alebo vytváranie certifikátu, sprievodca sa nedá zavrieť ani prepnúť na iný krok. Jednorazový kľúč by sa minul a nedozvedeli by ste sa, ako zápis dopadol.
- Okno sa zatvára aj klávesom Esc.
- Pri každom kroku je rozbaľovací odkaz Technické podrobnosti pre správcu IT s adresami serverov a stavmi jednotlivých kontrol. Hodnoty sa dajú označiť a skopírovať.
¶ Technické podrobnosti pre správcu IT
¶ Ako pripojenie funguje
SPIN / QASIDA ERP (klient)
│ HTTP(S), API tokeny
▼
QASIDA API (server vo firme zákazníka)
│ HTTPS │ TLS so zákazníckym certifikátom (mTLS)
▼ ▼
registračný server, komunikačný server (RabbitMQ)
poskytovateľ certifikátov │
▼
Digitálny poštár ASSECO (APEX) → sieť Peppol → odberateľ
- Pri e-faktúre komunikuje klient SPIN iba so serverom QASIDA API vo vašej sieti. Spojenie do internetu potrebuje iba server QASIDA API.
- Server QASIDA API pri registrácii firmy získa od registračného servera adresu komunikačného servera a prihlasovacie údaje firmy. Pri vytvorení certifikátu si vygeneruje kľúč a vyžiada si od poskytovateľa certifikátov zákaznícky certifikát.
- E-faktúry sa potom vymieňajú cez komunikačný server (RabbitMQ). Server QASIDA API sa naň pripája zabezpečeným spojením so zákazníckym certifikátom a prihlasuje sa údajmi z registrácie firmy.
Sprievodca nič nenastavuje priamo na serveri QASIDA API – všetky kontroly a zápisy prebiehajú cez jeho rozhranie.
¶ Predpoklady na serveri QASIDA API
| Predpoklad | Podrobnosti |
|---|---|
| Verzia | QASIDA API 26.6.5 alebo novšia. Staršiu verziu sprievodca hlási ako Server je potrebné aktualizovať. |
| Povolená komunikácia | V appsettings.json servera QASIDA API musí existovať sekcia QasidaHub a v nej "Enabled": true. Chýbajúcu sekciu alebo vypnutú komunikáciu hlási kontrola Komunikácia s Digitálnym poštárom je povolená. |
| Adresy služieb | Adresy registračného servera a poskytovateľa certifikátov sú v definíciách URL adries v databáze QASIDA API pod kódmi QHUB a CERTPROVIDERAPI. Prázdnu adresu hlási príslušná kontrola ako URL adresa nie je nastavená. |
| Sieť | Server QASIDA API potrebuje odchádzajúce spojenie HTTPS na registračný server a poskytovateľa certifikátov a spojenie TCP na komunikačný server – adresu host:port dostane pri registrácii firmy. Klienti SPIN potrebujú prístup na adresu servera QASIDA API. |
| Systémový čas | Certifikát sa posudzuje podľa času servera. Pri zle nastavenom čase QASIDA API hlási Certifikát platí až od …. |
¶ Nastavenia v systéme SPIN
| Nastavenie | Podrobnosti |
|---|---|
| Adresa servera QASIDA API | Setup QASIDA_API_BASE_URL, spoločný pre všetkých používateľov. V sprievodcovi ju môže nastaviť iba administrátor (Technické podrobnosti → Zmeniť adresu servera, alebo tlačidlo v hlásení o chybe). Prijme sa iba absolútna adresa http:// alebo https://, napr. https://server:5001/. |
API token s kódom qclient |
Potrebný na registráciu firmy. Bez neho sa registračný kľúč nedá zadať a v technických podrobnostiach kroku Registrácia firmy je Nie je dostupný API token s kódom qclient. |
API token s kódom admin |
Potrebný na vytvorenie certifikátu (volá administrátorské rozhranie QASIDA API). Bez neho sa kód na inštaláciu nedá zadať. |
API tokeny sa spravujú v okne API Token v tej istej skupine API komunikácia.
¶ Čo overujú jednotlivé kontroly
Sprievodca pri kontrole zavolá na server QASIDA API tieto služby (všetky naraz, výsledky zdieľajú všetky kroky):
| Volanie | Na čo slúži | Časový limit |
|---|---|---|
health |
dostupnosť a zdravie QASIDA API | 10 s |
version |
verzia QASIDA API | 10 s |
api/CloudSync/v1/GetCloudSyncStatus?MandantId=… |
nastavenia, dostupnosť serverov, skúšobné spojenie a prihlásenie na komunikačný server | 40 s |
api/v1/RabbitMqCertificate/GetInstalledCertificate?moduleSection=QasidaHub |
nainštalované certifikáty | 10 s |
Ak QASIDA API neodpovie ani na health, na stav pripojenia sa už nečaká.
¶ Krok Komunikačný server
| Kontrola | V poriadku, keď | Typická príčina chyby |
|---|---|---|
| Server je dostupný | health odpovie úspešne |
adresa nie je nastavená, server nebeží, zlá adresa, firewall; pri HTTP 200 s chybou server hlási vlastný problém (napr. databáza) |
| Verzia servera je aktuálna | verzia ≥ 26.6.5 | staršia verzia QASIDA API |
| Komunikácia s Digitálnym poštárom je povolená | QasidaHub:Enabled = true |
chýbajúca sekcia QasidaHub alebo "Enabled": false |
| Služba registrácie je dostupná | registračný server (kód QHUB) odpovedá |
prázdna adresa v definíciách, proxy, firewall |
| Služba certifikátov je dostupná | poskytovateľ certifikátov (kód CERTPROVIDERAPI) odpovedá |
prázdna adresa v definíciách, proxy, firewall |
Hlási sa vždy prvý problém v tomto poradí – ďalšie bývajú jeho dôsledkom. Kontroly za nedostupným serverom alebo starou verziou sa označia ako neoverené.
¶ Krok Registrácia firmy
Krok sa overuje, iba ak je QASIDA API dostupné v správnej verzii, má povolenú komunikáciu a je dostupný registračný server. Poskytovateľa certifikátov nepotrebuje.
| Technická podrobnosť | Význam |
|---|---|
| Mandant, ID mandanta | firma, ktorej registrácia sa overuje (zoznam registrovaných firiem je v databáze SPIN) |
| Komunikačný server | adresa host:port z registrácie firmy a jej dostupnosť |
| Prihlásenie na komunikačný server | používateľ z registrácie firmy a výsledok skúšobného prihlásenia |
| Registračný server | adresa a dostupnosť registračného servera |
| API token s kódom | qclient – či je token dostupný |
Skúšobné prihlásenie robí QASIDA API iba vtedy, keď je certifikát použiteľný a komunikačný server dostupný. Inak je prihlásenie neoverené a dôvod hlási príslušná kontrola. Hlásenia QASIDA API pri prihlásení:
- odmietol prihlásenie používateľa – meno a heslo z registrácie už neplatia (zmenené alebo zrušená registrácia), firmu je potrebné zaregistrovať znova,
- V registrácii mandanta chýba meno alebo heslo / sa nedá prečítať – firmu je potrebné zaregistrovať znova,
- nemá prístup k virtuálnemu hostu alebo neumožňuje prihlásenie menom a heslom – nastavenie je na strane Asseco Solutions, obráťte sa na podporu.
¶ Krok Certifikát
Krok sa overuje, iba ak je QASIDA API dostupné v správnej verzii, má povolenú komunikáciu a je dostupný poskytovateľ certifikátov. Registráciu firmy nepotrebuje – certifikát patrí serveru QASIDA API.
| Technická podrobnosť | Význam |
|---|---|
| Zákaznícky certifikát | dokedy platí a koľko dní zostáva |
| Certifikát Asseco certifikačnej autority | dokedy platí certifikát CA, ktorým QASIDA API overuje komunikačný server |
| Prijatie komunikačným serverom | či komunikačný server prijal zákaznícky certifikát pri skúšobnom spojení TLS |
| Poskytovateľ certifikátov | adresa a dostupnosť |
| API token s kódom | admin – či je token dostupný |
Certifikát je chybný, keď nie je nainštalovaný, už exspiroval, ešte nezačal platiť, zostáva mu menej ako 5 dní platnosti, QASIDA API k nemu hlási chybu alebo komunikačný server certifikát neprijal. Chybou je aj vypnutá zbernica sekcie QasidaHub – certifikát sa vtedy nepoužíva, aj keď je sám v poriadku.
¶ Certifikát podrobnejšie
- Vytvorenie. QASIDA API si vygeneruje kľúč RSA a jednorazovým kódom zo Zákazníckeho portálu si vyžiada od poskytovateľa certifikátov nový zákaznícky certifikát. Nový certifikát nahradí doterajší. Ak sa žiadny nevydá, doterajšie certifikáty zostanú bez zmeny.
- Súbory. Certifikáty sú na serveri QASIDA API, predvolene v adresári
Certificates(zákaznícky certifikátclient.pfx, certifikát CAca.pemaleboca.crt). Heslo k súboruclient.pfxQASIDA API generuje samo a ukladá ho v úložisku tajomstiev servera – kópia súboru bez neho nie je použiteľná. - Automatická obnova. Certifikát sa vydáva na obmedzený čas a QASIDA API ho samo obnovuje predvolene 30 dní pred koncom platnosti (
RabbitMqCertificates:RenewBeforeExpirationDays). Obnovu vypne iba výslovnéRabbitMqCertificates:AutomaticRenewal=false. Ak je obnova potrebná a je vypnutá alebo opakovane zlyháva, QASIDA API to hlási ako varovanie. - Exspirovaný certifikát sa obnoviť nedá, pretože obnova sa prihlasuje práve ním. Vytvorte nový jednorazovým kódom na inštaláciu.
- Neuznaný certifikát komunikačného servera. Ak QASIDA API hlási, že komunikačný server sa preukázal certifikátom, ktorý QASIDA API neuznáva, skontrolujte súbor certifikátu CA a adresu komunikačného servera v registrácii firmy.
¶ Registrácia a vytvorenie certifikátu – časové limity
Registrácia firmy aj vytvorenie certifikátu čakajú na odpoveď QASIDA API najviac podľa setupu časového limitu volaní QASIDA API, nikdy však dlhšie ako 120 sekúnd. Počas tejto doby sa sprievodca nedá zavrieť.
Ak čas vyprší, požiadavka mohla na serveri napriek tomu dobehnúť a jednorazový kľúč alebo kód minúť. Pred ďalším pokusom preto vždy kliknite na Skontrolovať znova a overte, či je firma už zaregistrovaná alebo certifikát vytvorený.
¶ Technický súhrn
Technický súhrn (tlačidlo v zhrnutí, alebo Kopírovať podrobnosti pre IT v hlásení o chybe) vychádza z poslednej kontroly – nič nové nevolá. Obsahuje:
- čas vytvorenia, verziu modulu Administrátor, inštalačný kód a verziu databázy,
- výsledky všetkých kontrol po krokoch, s celým popisom chyby, vrátane dôvodu, prečo sa nedá registrovať alebo inštalovať certifikát, a výsledku poslednej registrácie alebo inštalácie,
- odpovede QASIDA API na štyri volania uvedené vyššie – HTTP stav a obsah odpovede.
Súhrn neobsahuje heslá, API tokeny ani jednorazový registračný kľúč a kód na inštaláciu certifikátu. Obsahuje adresy serverov, cesty k súborom certifikátov a meno používateľa firmy na komunikačnom serveri. Inštalačný kód v hlavičke je identifikátor vašej inštalácie SPIN, podľa ktorého podpora inštaláciu spozná.
¶ Stav pripojenia po dokončení
Server QASIDA API overuje stav pripojenia aj priebežne a zaregistrovanej firme ho zobrazuje v bočnom paneli so stavmi, napr. Komunikácia s digitálnym poštárom nehlási žiadne chyby. Bežný používateľ vidí iba súhrnný stav, administrátor aj jednotlivé chyby a platnosť certifikátu. Stav sa overuje najviac raz za 2 minúty pre každú firmu. Pri chybe spustite sprievodcu znova – ukáže, ktorý krok nie je v poriadku.