API v Money S3 – pro vývojáře

Základní informace

Money S3 pro komunikaci přes API (Application Programming Interface) využívá GraphQL. Výhodou oproti REST je možnost definovat, jaká data je potřeba vyčíst, čímž se zmenšuje přenos zbytečných dat a také počet volání. Samozřejmě opačným důsledkem je nemožnost zavolat si „všechno“ a potřeba vyjmenovat konkrétní atributy.

Čtení dat z Money S3 přes API probíhá na pozadí a v reálném čase.

Zápis do Money S3 je asynchronní, poslané údaje se zapíšou do fronty a odtud se postupně zapisují do dat Money S3.  Frontu importu je možné najít v Money S3 přes Nástroje / Výměna dat XML / Fronta importu, kde je vidět jednotlivé záznamy pro zápis a také výsledek jejich zpracování (ten samozřejmě dostanete i jako odpověď na požadavek zápisu).

Případné otázky k napojení směrujte na mail api@money.cz

Získat ID aplikace pro API propojení Money S3

Důležité údaje z Money S3 pro napojení

1. Zákazník musí mít nainstalované API na PC s Money S3 (je to volba v rámci instalačního průvodce). V rámci instalace si zadá „doménu“, přes které budete s Money komunikovat.

2. Zákazník musí mít v Money S3 zakoupený rozšiřující modul API.

3. Zákazník si musí vygenerovat Klíč API. Přes Nástroje / Výměna dat XML / Klíče API si dá Přidat (resp. Přidat a generovat). Důležité údaje pro Vás jsou Client ID a Client Secret. Nastavený uživatel na Klíči API definuje, které oblasti Money S3 budou dostupné pro čtení nebo zápis.

4. Aby zákazník nemusel potvrzovat import manuálně je třeba přes Nástroje / S3 Automatic přidat novou úlohu S3Api – fronta XML importu. Tuto úlohu si zákazník může přidat i bez zakoupení modulu S3 Automatic (s jeho zakoupením může přidávat i jiné úlohy). Tato úloha zabezpečí, že když přibude nový požadavek na zápis do fronty, tak se zpracuje.

S3 Automatic je aplikace běžící na pozadí bez ohledu na to, zda je nebo není spuštěné Money S3.

Rozsah přenášených dat přes API

Aktuální rozsah oblastí, ve kterých je přes API možné načítat a zapisovat údaje.

Podrobné informace k možným voláním a jednotlivým atributům najdete na https://s3api.api.moneys3.eu/graphql/, kde si volbou Browse Schema můžete prohlížet jednotlivá volání (např. na vyčtení katalogových čísel skladových karet).

Možnosti testování napojení API

Testovat napojení můžete proti datům zákazníka nebo proti vlastní testovací instalaci.

Musí být splněny podmínky uvedené v sekci Důležité údaje z Money S3 pro napojení.

1. Testovací prostředí pro komunikaci s Money S3 můžete zavolat dvěma způsoby:

• Odkudkoli:
  • https://{jméno_domény}.api.moneys3.eu/graphql/, kde {jméno_domény} je údaj zadaný při instalaci API do Money S3.
• Z počítače, kde je Money S3 s API nainstalované
  • http://localhost:85/graphql/
• Uvedené údaje zadáte do jakéhokoli prohlížeče, přičemž doporučujeme Google Chrome (ostatní prohlížeče nemusí podporovat všechny funkce).

2. Pokud je vše v pořádku, výsledkem bude toto okno, kde zvolíte Create Document.

3. Konfiguraci nastavíte přes ozubené kolečko vpravo nahoře.

4. Na záložce General ponechte vše tak, jak bylo nastaveno. Přejděte na záložku Authorization, kde nastavíte:

• Type: OAuth 2
• Grant Type:
  • • Client Credentials - uživatel se přebírá z Klíče API v Money S3, kde musí být vyplněn

  

  • • Resource Owner Password Credentials - jméno a heslo uživatele zadáváte zde, na Klíči API v Money nesmí být uživatel nastaven
      • Username: název uživatele z Money S3 (vytvoříte přes Money / Možnosti a nastavení / Přístupová práva - zvolený uživatel pro API nesmí obsahovat mezeru)
      • Password: heslo uživatele z Money S3

  

• Acces Token URL:
  • Pokud se chcete připojit na Money S3 odkudkoli
    • https://{jméno_domény}.api.moneys3.eu/connect/token?AppId={ID_aplikácie), kde {jméno_domény} je údaj zadaný při instalaci API do Money S3, např. https://testapi.api.moneys3.eu/connect/token?AppId={ID_aplikácie) a ID_aplikace je ID, které jste si vyžádali přes api@money.cz (viz obrázek)
  • Pokud jste na počítači, kde je Money S3 nainstalováno
    • localhost:85/connect/token?AppId={ID_aplikace), přičemž ID_aplikace, je ID, které jste si vyžádali přes api@money.cz (viz obrázek).
• Client ID: údaj zadaný v Money S3
• Client Secret: údaj zadaný v Money S3
• Scope: s3api

Na konci klikněte na tlačítko Fetch. Pokud ověření proběhne v pořádku, vyplní se řádek Access Token a můžete potvrdit tlačítkem Apply.

V případě, že byste chtěli token přegenerovat (automaticky mu po nějaké době skončí platnost) stačí kliknout na tlačítko Clear a potom znovu na Fetch.

5. Abyste mohli komunikovat s konkrétní agendou je nutné nastavit GUID agendy.

Ten zjistíte zadáním příkazu na obrázku do hlavního okna.  Vypíše se vám seznam agend s jejich GUIDem a požadovaný GUID zadáte do HTTP Headers. Dále už komunikujete jen s konkrétní agendou.

Příklady čtení a zápisu přes API

1. Příklad vyčtení faktury vystavené (se základními údaji o odběrateli a položkách)

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


2. Vyčtení prvních 5 záznamů

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


3. Vyčtení dalších 5 záznamů

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


4. Příklad zápisu faktury 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. Příklad pro vyčítání pouze vyfiltrovaných a seřazených záznamů

{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
}
}
}
}
}