API v Money S3 – pre vývojárov

Základné informácie

Money S3 pre komunikáciu cez API (Application Programming Interface) využíva GraphQL. Výhodou oproti REST je možnosť si definovať aké dáta je potrebné vyčítať, čím sa zmenšuje prenos zbytočných dát a aj počet volaní. Samozrejme opačným dôsledkom je nemožnosť zavolať si „všetko“ a potreba vymenovať konkrétne atribúty.

Čítanie dát z Money S3 cez API prebieha na pozadí a v reálnom čase

Zápis do Money S3 je asynchrónny, teda poslané údaje sa zapíšu do fronty a odtiaľ sa postupne zapisujú do dát Money S3.  Frontu importu je možné nájsť v Money S3 cez Nástroje / Výmena dát XML / Front importu, kde je vidieť jednotlivé záznamy na zápis a rovnako aj výsledok ich spracovania (ten samozrejme dostanete aj ako odpoveď na požiadavku na zápis).

Prípadné otázky k napojeniu smerujte na mail api@money.sk

Získať ID aplikácie pre pripojenie Money S3 API

Dôležité údaje z Money S3 na napojenie

1. Zákazník musí mať nainštalované API na PC s Money S3 (je to voľba v rámci inštalačného sprievodcu). V rámci inštalácie si zadá „doménu“ cez ktoré budete s Money komunikovať.

2. Zákazník musí mať v Money S3 zakúpený rozširujúci modul API.

3. Zákazník si musí vygenerovať Kľúč API. Cez Nástroje / Výmena dát XML / Kľúče API si dá Pridať (resp. Pridať a generovať). Dôležité údaje pre Vás sú Client ID a Client Secret. Nastavený používateľ na Kľúči API definuje ktoré oblasti Money S3 budú dostupné na čítanie alebo zápis.

4. Aby zákazník nemusel potvrdzovať import manuálne je potrebné si cez Nástroje / S3 Automatic pridať novú úlohu - S3Api – front XML importu. Túto úlohu si vie pridať zákazník aj bez zakúpenia modulu S3 Automatic (s jeho zakúpením vie pridávať aj iné úlohy). Táto úloha zabezpečí, že ak pribudne nová požiadavka na zápis do fronty, tak sa spracuje.

S3 Automatic je aplikácia bežiaca na pozadí bez ohľadu či je alebo nie je spustené Money S3.

Rozsah prenášaných dát cez API

Aktuálny rozsah oblastí pre ktoré je cez API možné načítavať a zapisovať údaje.

Podrobné informácie k možným volaniam a jednotlivým atribútom nájdete na https://s3api.api.moneys3.eu/graphql/, kde voľbou Browse Schema si viete prezerať jednotlivé volania (napr. na vyčítanie katalógových čísel skladových kariet).

Možnosti testovania napojenia API

Testovať napojenie môžete oproti dátam zákazníka alebo oproti vlastnej testovacej inštalácií.

Musia byť splnené podmienky uvedené v sekcií  Dôležité údaje z Money S3 na napojenie.

1. Testovacie prostredie pre komunikáciu s Money S3 môžete zavolať dvoma spôsobmi:

• Odkiaľkoľvek:
  • https://{meno_domény}.api.moneys3.eu/graphql/, pričom {meno_domény} je údaj zadaný pri inštalácií API do Money S3.
• Z počítača kde je Money S3 s API inštalované
  • http://localhost:85/graphql/
• Dané údaje zadáte do akéhokoľvek prehliadača, pričom odporúčame Google Chrome (ostatné prehliadače nemusia podporovať všetky funkcie).

2. Ak je všetko v poriadku, tak výsledkom bude toto okno, kde zvolíte Create Document.

3. Konfiguráciu nastavíte cez ozubené koliesko vpravo hore.

4. Na záložke General ponecháte všetko tak ako bolo nastavené. Prejdeme na záložku Authorization, kde nastavíme:

• Type: OAuth 2
• Grant Type:
  • • Client Credentials - používateľ sa preberá z Kľúča API v Money S3, kde musí byť vyplnený

  

  • Resource Owner Password Credentials - meno a heslo používateľa zadávate tu, na Kľúči API v Money nesmie byť používateľ nastavený
    • Username: názov používateľa z Money S3 (vytvoríte cez Money / Možnosti a nastavenia / Prístupové práva - zvolený používateľ pre API nesmie obsahovať medzeru)
    • Password: heslo používateľa z Money S3

    

• Acces Token URL:
  • ak sa chcete pripojiť na Money S3 odkiaľkoľvek
    • https://{meno_domény}.api.moneys3.eu/connect/token?AppId={ID_aplikácie), pričom {meno_domény} je údaj zadaný pri inštalácií API do Money S3, napr. https://testAPI.api.moneys3.eu/connect/token?AppId={ID_aplikácie) a ID_aplikácie je ID, ktoré ste si vyžiadali cez api@money.sk (viď obrázok).
  • ak ste na počítači, kde je Money S3 nainštalované
    • localhost:85/connect/token?AppId={ID_aplikácie), pričom ID_aplikácie je ID, ktoré ste si vyžiadali cez api@money.sk (viď obrázok).
• Client ID: údaj zadaný v Money S3
• Client Secret: údaj zadaný v Money S3
• Scope: s3api

Na konci kliknite na tlačidlo Fetch. Ak overenie prebehne v poriadku, tak sa vyplní riadok Access Token a môžete potvrdiť tlačidlom Apply.

V prípade, ak by ste chceli token pregenerovať (automaticky mu po nejakej dobe skončí platnosť) stačí kliknúť na tlačidlo Clear a potom znovu na Fetch.

5. Aby ste mohli komunikovať s konkrétnou agendou je potrebné nastaviť GUID agendy.

Ten zistíte ak v hlavnom okne zadáte príkaz na obrázku, čím sa Vám vypíše zoznam agend s ich GUIDom a požadovaný GUID zadáte do HTTP Headers. Tým už komunikujete len s konkrétnou agendou.

Príklady čítania a zápisu cez API

1. Príklad na vyčítanie faktúry vystavenej (so základnými údajmi o odberateľovi a položkách)

{issuedInvoices {
items {dateOfIssue documentNumber partnerAddress {
company {
identificationNumber
}
} items {
description plu amount vatRate unitPriceHc
}
}
}}


2. Vyčítanie prvých 5 záznamov

{issuedInvoices (take: 5) {
items {dateOfIssue documentNumber}
}}


3. Vyčítanie ďalších 5 záznamov

{issuedInvoices (take: 5 skip:5 )  {
items {dateOfIssue documentNumber}
}}


4. Príklad na zápis faktúry s jednou položkou

mutation {
createIssuedInvoice(
issuedInvoice: {
dateOfIssue: "01.03.2024"
dateOfTaxing: "01.03.2024"
dateOfMaturity: "01.03.2024"
numericalSerie: { prefix: ""}
documentNumber: "11223344"
items: {  amount: 2 unitPriceHc: 20 description: "TEST" warrantyType:CONSTANT isInverse:false}
}
definitionXMLTransfer: { shortCut: "_FP+FV"})
{
guid
isSuccess
}
}


5. Príklad na vyčítanie len vyfiltrovaných a zoradených záznamov

{issuedInvoices(
order: {
partnerAddress: { identificationNumber: DESC }
deliveryAddress: { address: { name: DESC } }
}
where: {
or: [
{ dateOfIssue: { gt: "2024-03-01" }
partnerAddress: {
and: [
{ businessAddress: { name: { eq: "KANCEL a.s." } } }
{ businessAddress: { name: { neq: "s.r.o." } } }
]
}
}
{ deliveryAddress: { address: { name: { eq: "Seyfor a.s." } } } }
]
}
)
{ items {
dateOfIssue
documentNumber
partnerAddress {
businessAddress {
name
}
company {
identificationNumber
}
}
deliveryAddress {
address {
name
}
}
}
}
}