Čo presne je dávka? Každá transakcia, ktorú vytvoríte, patrí do tzv. dávky. Rovnako ako účtenka má každá dávka svoje číslo a je vlastne súborom transakcií. Uzávierka je administratívna operácia, pomocou ktorej terminál uzavrie dávku a vyzve systémy, aby dávku uzavreli a otvorili novú. V systémoch Global Payments je možné pri každej transakcii vidieť číslo uzávierky a je možné transakcie filtrovať podľa tohto čísla.
Prihlásenie a overenie
Pre všetky neverejné koncové body je potrebné overenie pomocou tokenu JWT. Token (s platnosťou 90 dní) získate prostredníctvom koncového bodu /cloud/oauth/token s nasledujúcimi zadanými argumentmi:
- Základné overenie pre koncové body tokenu (meno/heslo) – bude poskytnuté každému používateľovi.
- Používateľské meno obchodníka – rovnaké ako pre GP tom
- Heslo obchodníka – rovnaké ako pre GP tom
- ID terminálu (TID) – ID cieľového terminálu
- Autorizačný koncový bod sa nachádza na:
Získanie prístupového tokenu
Príklad požiadavky:
POST {{apiCloudHost}}/cloud/oauth/token
Autorizácia: Basic YXRvbTphc2hmdWY0ZTVmYQ==
Content-Type: application/x-www-form-urlencoded
grant_type=password&username=jan.novak@example.com&password=ABCDEFGHIJKL&tid=999888
Príklad odpovede:
{
"access_token": "eyJh…", // prístupový token používaný v overených požiadavkách na API
"token_type": "bearer",
"refresh_token": "GciO…",
"expires_in": 3600,
"scope": "read write",
"tid": "999888",
}Obnovenie tokenu
Po uplynutí platnosti access_tokenu je k dispozícii refresh_token.
Príklad požiadavky:
POST {{apiHost}}/api/oauth/token
Autorizácia: Basic YXRvbTphc2hmdWY0ZTVmYQ==
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=GciO…
GPTomAuth
Typ bezpečnostného schématu
Schéma HTTP autorizácie
HTTP
na doručiteľa
Vytvorenie úlohy
Oslovte koncový bod POST /v1/tasks/BATCH a na vytvorenie požiadavky použite CreateCloudTaskTransactionApiRequest s nasledujúcimi údajmi:
Premenná
dátum
POVINNÉ
POVINNÉ
apiKey
POVINNÉ
POVINNÉ
čas
POVINNÉ
POVINNÉ
iniciátor
POVINNÉ
POVINNÉ
názov
POVINNÉ
POVINNÉ
timeToLive
Formát
reťazec
reťazec
reťazec
reťazec
reťazec
celé číslo
Popis
Transakcie so starším alebo rovnakým dátumom budú uzavreté. Zahrnuté budú všetky transakcie do tohto dátumu od poslednej úspešne uzavretej dávky.
API kľúč nájdete v aplikácii v sekcii Účet – Cloud API. Slúži na identifikáciu prihlásenia, najmä v Cloud API.
Cieľové TID pre danú úlohu. TID = ID terminálu, ktoré je jedinečné pre každé zariadenie. Na všetkých nainštalovaných zariadeniach je možné súčasne používať len jedno TID.
Popis iniciátora by mal byť jedinečný pre každú inštanciu subsystému, ktorá môže iniciovať úlohu. Príklad: „server XY“ alebo „Pokladňa 1“
Ľahko čitateľný názov úlohy. Mal by obsahovať nejakú identifikáciu úlohy.
Príklad: „Faktúra 37364FD“
Príklad: „Faktúra 37364FD“
Časový limit pre vypršanie platnosti úlohy v cloude. Je možné zadať hodnoty v rozmedzí od sekúnd.
Príklad
2025-12-18T08:21:39.427Z
333W212J3
483590
Pokladňa 12
Uzávierka 36744
10
Obsah odpovede [CloudTaskDetailApiResponse]:
Možné kódy odpovedí sú:
Odpoveď
RC200
RC403
RC406
RC 502
Správa
OK – Úloha bola zaregistrovaná
Používateľ nemá oprávnenie zaregistrovať úlohu na danom termináli
Úloha nie je pre daný terminál prijateľná
Push notifikácia nebola odoslaná
Popis
Úloha bola úspešne vytvorená a bude spracovaná.
Ak sa vaše prihlasovacie údaje API nezhodujú s odoslanou hodnotou TID (napríklad ak je vlastník TID iný).
K tomu zvyčajne dochádza, keď TID nie je schopný spracovať požiadavku.
Push notifikácia nebola odoslaná z dôvodu zlyhania služby upstream.
Ako sa správať
Pokračujte ďalším krokom v priebehu transakcie.
Skontrolujte, či ste zadali správne TID, a skúste to znova.
Skontrolujte chybovú správu.
Nižšie nájdete premenné použité v odpovedi:
Premenná
názov
ID úlohy
vytvorené
taskClass
stav
iniciátor
contextId
užitočné zaťaženie
ID výnimky
typ
správa
kontext
Formát
reťazec
reťazec
reťazec
reťazec
reťazec
reťazec
reťazec
objekt
reťazec
reťazec
reťazec
reťazec
Popis
Čitateľný názov priečinka. Použitý z hodnoty požiadavky.
Interné ID tašky
Dátum a čas vytvorenia úlohy.
Trieda užitočného zaťaženiaMožné hodnoty: [TRANSACTION, BATCH, DUMMY]
Stav úlohy v cloude. Možné hodnoty: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
Popis iniciátora na strane klienta. Použité z hodnoty požiadavky.
ID príslušnej cieľovej entity, ak existuje (transactionId / batchId)
Telo kontextovej úlohy – v závislosti od taskClass
Pseudo-jedinečné ID výnimky. Môže slúžiť ako „ID pre podporu“, ktoré môže používateľ poskytnúť podpore, aby mohla chybu prešetriť.
Typ výnimky.
Správa o výnimke.
Kontext výnimky. Ďalšie informácie.
Príklad
Uzávera 123
dFd3sda
BATCH
VYTVORENÉ
Pokladňa 12
{...}
FujIk6
VALIDATION_EXCEPTION
Heslo je príliš slabé
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
RC200
ÁNO
ÁNO
ÁNO
ÁNO
ÁNO
ÁNO
ÁNO
ÁNO
NO
NO
NO
NO
RC403
NO
NO
NO
NO
NO
NO
NO
NO
ÁNO
ÁNO
ÁNO
ÁNO
RC406
NO
NO
NO
NO
NO
NO
NO
NO
ÁNO
ÁNO
ÁNO
ÁNO
RC502
NO
NO
NO
NO
NO
NO
NO
NO
ÁNO
ÁNO
ÁNO
ÁNO
Kontrola stavu tašky
V ďalšom kroku skontrolujete stav úlohy na koncovom bode GET /v1/tasks/{taskID} pomocou požiadavky, ktorá obsahuje:
Premenná
ID úlohy
Formát
reťazec
Popis
ID tašky, ktoré ste dostali v predchádzajúcom kroku.
Príklad
dFd3sda
Možné kódy vrátenia:
Odpoveď
RC200
RC403
Správa
OK – Stav tašky k dispozícii
Pre aktuálny terminál nebola nájdená žiadna úloha v cloude.
Správa
Aktualizácia stavu úlohy bola úspešne spracovaná.
Mali by ste skontrolovať svoje taskID a znovu odoslať správnu hodnotu.
Popis
Ak nedostanete konečný stav (pozri nižšie), tento krok zopakujte.
Skontrolujte, či ste zadali správne taskID, a skúste to znova.
Premenné v odpovedi:
Premenná
názov
ID úlohy
vytvorené
taskClass
stav
iniciátor
contextID
užitočné zaťaženie
ID výnimky
typ
správa
kontext
Formát
reťazec
reťazec
reťazec
reťazec
reťazec
reťazec
reťazec
reťazec
reťazec
reťazec
reťazec
Popis
Ľahko zrozumiteľný názov úlohy. Použitý z hodnoty požiadavky na vytvorenie úlohy.
Interné ID tašky
Dátum a čas vytvorenia úlohy.
Možné hodnoty: [TRANSACTION, BATCH, DUMMY]
Možné hodnoty: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
Popis iniciátora na strane klienta. Použité z hodnoty požiadavky.
ID príslušnej cieľovej entity, ak existuje (transactionId / batchId)
Pseudo-jedinečné ID výnimky. Môže slúžiť ako „ID podpory“, ktoré môže používateľ poskytnúť podpore, aby mohla prešetriť prípadný problém.
Typ výnimky.
Správa o výnimke.
Kontext výnimky – ďalšie informácie.
Príklad
Faktúra č. 36744
dFd3sda
2025-12-18T08:21:39.427Z
BATCH
V PRÍPRAVE
Pokladňa 12
12DFSFSSF
FujIk6
VALIDATION_EXCEPTION
Heslo je príliš slabé
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
RC200
ÁNO
ÁNO
ÁNO
ÁNO
ÁNO
ÁNO
ÁNO
ÁNO
NO
NO
NO
NO
RC404
NO
NO
NO
NO
NO
NO
NO
NO
ÁNO
ÁNO
ÁNO
ÁNO
Požiadavka na stav úlohy by sa mala opakovať, kým nezískate jeden z konečných kódov odpovede, ktorými sú:
Stav
INIT_ERROR
DOKONČENÉ
ZRUŠENÉ
CHYBA
Popis
Inicializácia platobného procesu sa nepodarila. Skontrolujte hlásenú chybu.
Akonáhle dosiahnete tento stav, vaša úloha je dokončená a výsledok je k dispozícii.
Úloha bola zrušená používateľom.
Pri spracovaní úlohy došlo k chybe.
Ako sa správať
Postupujte podľa pokynov k chybe.
Môžete pokračovať ďalším krokom.
Mali by ste začať novú úlohu, pretože táto úloha bola zrušená používateľom.
Postupujte podľa pokynov k chybe.
Ďalším krokom môžete pokračovať len vtedy, ak je odpoveď v stave COMPLETED.
Získanie výsledku uzávierky
Teraz vieme, že dávka bola schválená. Cieľom tohto kroku je získať stav dávky a jej údaje. Pre novú požiadavku volajte koncový bod GET /v1/batches/{batchId}, kde použijete nasledujúce premenné:
Premenná
batchId
Formát
reťazec
Popis
ID dávky, ktoré získate v predchádzajúcich krokoch.
Príklad
12DFSFSSF
Možné kódy odpovedí sú:
Odpoveď
RC200
RC404
Správa
OK – poskytnuté podrobnosti o uzávierke
Pre aktuálne TID nebola nájdená uzávierka.
Správa
Vaša žiadosť o uzávierku bola úspešne spracovaná.
K tejto situácii dôjde, ak sa pre vaše zariadenie nepodarilo nájsť príslušné ID uzáveru.
Popis
Transakcia bola dokončená!
Skontrolujte identifikačné číslo transakcie.
Odpoveď obsahuje nasledujúce premenné v závislosti od kódu odpovede:
Premenná
batchid
identifikátor komunikácie
číslo šarže
dátum
predchádzajúci dátum dávky
dátum prvej transakcie
celková suma
mena
celkový počet
počet predajov
sumy predaja
počet neplatných
voidAmount
počet neplatných
amsČíslo šarže
podsérie
Formát
reťazec
reťazec
reťazec
reťazec
reťazec
reťazec
číslo
reťazec
číslo
číslo
číslo
číslo
číslo
číslo
reťazec
objekt
Popis
Interné ID dávky, OPEN pre pseudodávku s otvorenými transakciami.
Možno použiť na technickú podporu. Pseudo-jedinečné ID na účely protokolovania.
Číslo dávky pre daný TID.
Presný dátum a čas, kedy bola dávka uzavretá.
Dátum a čas začiatku uzavretej dávky. Pre túto dávku máte časové obdobie (OD: hodnota previousBatchDate TO: dátum hodnoty).
Dátum najstaršej transakcie.
Celková suma za všetky typy transakcií.
Mena k dátumu uzávierky
Celkový počet transakcií v dávke
Počet transakcií typu hromadný predaj.
Objem transakcií typu hromadný predaj.
Počet všetkých transakcií so zrušením v dávke.
Objem všetkých transakcií zrušených v dávke.
Počet neplatných transakcií v dávke
Interné ID dávky, OPEN pre pseudodávku s otvorenými transakciami.
Základní dávky v rámci meta dávky – rozdělení podle typu transakce a zahrnuje statistické informace o podřízených dávkách podle typu platebbní metody. Obsahuje:
-closeBatchNumber (string) - closeBatchNumber podřízené dávky
- totalCount (number) - Celkový počet transakcí v dávce
- saleCount (number) - Počet transakcí typu prodej v dávce
- saleAmount (number) - Objem transakcí typu prodej v dávce
- voidCount (number) - Počet storen transakcí
- voidAmount (number) - Objem storen transakcí v dávce
-closeBatchNumber (string) - closeBatchNumber podřízené dávky
- totalCount (number) - Celkový počet transakcí v dávce
- saleCount (number) - Počet transakcí typu prodej v dávce
- saleAmount (number) - Objem transakcí typu prodej v dávce
- voidCount (number) - Počet storen transakcí
- voidAmount (number) - Objem storen transakcí v dávce
Príklad
12DFSFSSF
2
2025-12-18T08:21:39.427Z
2025-12-17T12:22:11.427Z