OBJEDNAT

Uzávěrka

Obsah

Co přesně je dávka? Každá transakce, kterou vytvoříte, patří do tzv. dávky. Stejně jako účtenka má každá dávka své číslo a je vlastně balíčkem transakcí. Uzávěrka je administrativní operace, pomocí které terminál uzavře dávku a vyzve systémy, aby se dávka uzavřela a otevřela nová. V systémech Global Payments je možné u každé transakce vidět číslo uzávěrky a je možné transakce filtrovat podle tohoto čísla.

Přihlášení & autentifikace

Pro všechny neveřejné koncové body je potřeba ověření pomocí tokenu JWT. Token (s životností 90 dnů) získáte prostřednictvím koncového bodu /cloud/oauth/token s následujícími poskytnutými argumenty:

  • Základní autentizace pro koncové body tokenu (jméno/heslo) – bude poskytnuto pro každého uživatele.
  • Uživatelské jméno obchodníka – stejné jako pro GP tom
  • Heslo obchodníka – stejné jako pro GP tom
  • ID terminálu (TID) – ID cílového terminálu
  • Autorizační koncový bod se nachází na: https://cloud-api-dev.gptom.com/cloud/oauth/token.

Získání access tokenu

Příklad požadavku:

POST {{apiCloudHost}}/cloud/oauth/token
Authorization: Basic YXRvb…
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=jan.novak@example.com&password=ABCDEFGHIJKL&tid=999888

Příklad odpovědi:

{
"access_token": "eyJh…", // access token used in authenticated API requests
"token_type": "bearer",
"refresh_token": "GciO…",
"expires_in": 3600,
"scope": "read write",
"tid": "999888",
}

Obnovení tokenu

Po vypršení platnosti access_tokenu je k dispozici refresh_token.

Příklad požadavku:

POST {{apiHost}}/api/oauth/token
Authorization: Basic YXRvb…
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=GciO…

GPTomAuth

Typ bezpečnostního schématu
Schéma autorizace HTTP
HTTP
bearer

Vytvoření tasku

Zavolejte koncový bod POST /v1/tasks/TRANSACTION a použijte CreateCloudTaskTransactionApiRequest s následujícími údaji vyplněnými k vytvoření požadavku:

Proměnná
date
MANDATORY
apiKey
tid
MANDATORY
initiator
MANDATORY
title
MANDATORY
Formát
string
string
string
string
string
Popis
Transakce se starším nebo stejným datem budou uzavřeny. Zahrnuty budou všechny transakce do tohoto data od poslední úspěšné uzavřené dávky.
API key pro požadavek poskytnutý od nás. Používá se k rozlišení přihlášení hlavně v app2app API. Volitelné pro většinu zákazníků.
Cílové TID pro daný úkol. TID = ID terminálu, které je jedinečné pro každé zařízení. Na všech nainstalovaných zařízeních lze současně používat pouze jedno TID.
Popis iniciátoru by měl být jedinečný pro každou instanci subsystému, která může iniciovat úlohu. Příklad: „server XY“ nebo „Pokladna 1“
Lidsky čitelný název tasku. Měl by obsahovat nějakou identifikaci úkolu.
Příklad: „Faktura 37364FD“
Příklad
2025-12-18T08:21:39.427Z
333W212J3
483590
Cash desk 12
Uzávěrka 36744

Obsah odpovědi [CloudTaskDetailApiResponse]:

Možné kódy odpovědí jsou:

Odpověd
RC200
RC403
RC406
RC 502
Zpráva
OK - Task byl zaregistrován
Uživateli není povoleno registrovat úlohu na daném terminálu
Úloha není pro daný terminál přijatelná
Push notifikace nebyla odeslána
Popis
Úkol byl úspěšně vytvořen a bude zpracován.
Pokud se vaše přihlašovací údaje API neshodují s odeslanou hodnotou TID (například když je vlastník TID jiný).
K tomu obvykle dochází, když TID není schopen požadavek zpracovat.
Push notifikace nebyla odeslána z důvodu selhání upstream služby.
Jak se zachovat
Pokračujte dalším krokem ve flow transakce.
Zkontrolujte, zda jste vyplnili správné TID a zkuste to znovu.
Zkontrolujte chybovou zprávu.

Níže naleznete proměnné použité v odpovědi:

Proměnná
title
taskId
created
taskClass
status
initiator
contextId
payload
exceptionId
type
message
context
Formát
string
string
string
string
string
string
string
object
string
string
string
string
Popis
Lidsky čitelný název tasku. Použito z hodnoty požadavku.
Interní id tasku
Datum a čas vytvoření tasku.
Třída užitečného zatíženíMožné hodnoty: [TRANSACTION, BATCH, DUMMY]
Stav cloudového tasku. Možné hodnoty: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
Popis iniciátoru na straně klienta. Použito z hodnoty požadavku.
ID dotčené cílové entity, pokud existuje (transactionId / batchId)
Tělo kontextové úlohy - v závislosti na taskClass
Pseudojedinečné ID výjimky. Může sloužit jako „ID pro podporu“, které může uživatel sdělit podpoře, aby mohla prošetřit chybu.
Typ výjimky.
Zpráva o výjimce.
Kontext výjimky. Další informace.
Příklad
Uzaverka 123
dFd3sda
BATCH
CREATED
Cash desk 12
{...}
FujIk6
VALIDATION_EXCEPTION
Password too weak
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
RC200
YES
YES
YES
YES
YES
YES
YES
YES
NO
NO
NO
NO
RC403
NO
NO
NO
NO
NO
NO
NO
NO
YES
YES
YES
YES
RC406
NO
NO
NO
NO
NO
NO
NO
NO
YES
YES
YES
YES
RC502
NO
NO
NO
NO
NO
NO
NO
NO
YES
YES
YES
YES

Kontrola stavu tasku

V dalším kroku budete kontrolovat stav tasku na koncovém bodu GET /v1/tasks/{taskID} pomocí požadavku, který zahrnuje:

Proměnná
taskId
Formát
string
Popis
ID tasku, který jste obdrželi jako součást předchozího kroku.
Příklad
dFd3sda

Možné návratové kódy:

Odpověd
RC200
RC403
Zpráva
OK - Stav tasku k dispozici
Cloudová úloha nebyla pro aktuální terminál nalezena.
Zpráva
Aktualizace stavu úlohy byla úspěšně zpracována.
Měli byste zkontrolovat své taskID a znovu odeslat správnou hodnotu.
Popis
Pokud neobdržíte konečný stav (viz níže), opakujte tento krok.
Zkontrolujte, zda jste vyplnili správné taskID a zkuste to znovu.

Proměnné v odpovědi:

Proměnná
title
taskId
created
taskClass
status
initiator
contextID
payload
exceptionId
type
message
context
Formát
string
string
string
string
string
string
string
string
string
string
string
Popis
Lidsky čitelný název úkolu. Použito z hodnoty požadavku na vytvoření úkolu.
Interní ID tasku
Datum a čas vytvoření tasku.
Možné hodnoty: [TRANSACTION, BATCH, DUMMY]
Možné hodnoty: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
Popis iniciátoru na straně klienta. Použito z hodnoty požadavku.
ID dotčené cílové entity, pokud existuje (transactionId / batchId)
Pseudojedinečné ID výjimky. Může sloužit jako „ID podpory“, které může uživatel sdělit podpoře, aby mohla prošetřit případný problém.
Typ výjimky.
Zpráva výjimky.
Kontext výjimky - další informace.
Příklad
Invoice 36744
dFd3sda
2025-12-18T08:21:39.427Z
BATCH
IN_PROGRESS
Cash desk 12
12DFSFSSF
FujIk6
VALIDATION_EXCEPTION
Password too weak
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
RC200
YES
YES
YES
YES
YES
YES
YES
YES
NO
NO
NO
NO
RC404
NO
NO
NO
NO
NO
NO
NO
NO
YES
YES
YES
YES

Požadavek na stav tasku by se měl opakovat, dokud nezískáte jeden z konečných kódů odpovědi, kterými jsou:

Stav
INIT_ERROR
COMPLETED
CANCELLED
ERROR
Popis
Inicializace platebního procesu se nezdařila. Zkontrolujte přijatou chybu.
Jakmile získáte tento stav, váš úkol byl dokončen a výsledek je k dispozici.
Task byl zrušen uživatelem.
Během zpracování úlohy došlo k nějaké chybě.
Jak se zachovat
Postupujte podle pokynů k chybě.
Můžete pokračovat dalším krokem.
Měli byste zahájit novou úlohu, protože tato úloha byla zrušena uživatelem.
Postupujte podle pokynů k chybě.

Dalším krokem můžete pokračovat pouze tehdy, když je odpověď ve stavu COMPLETED.

Získání výsledku uzávěrky

Nyní víme, že uzávěrka byla autorizována. Cílem tohoto kroku je získat stav uzávěrky a její údaje. Pro nový požadavek zavoláte koncový bod GET /v1/batches/{batchId}, kde použijete následující proměnné:

Proměnná
batchId
Formát
string
Popis
ID dávky, které získáte v předchozích krocích.
Příklad
12DFSFSSF

Možné kódy odpovědí jsou:

Odpověd
RC200
RC404
Zpráva
OK – podrobnosti uzávěrky poskytnuty
Pro aktuální TID nebyla uzávěrka nalezena.
Zpráva
Úspěšná odpověď na vaši žádost o uzávěrku.
K tomuto stavu dojde, když nebylo pro vaše zařízení nalezeno dané ID uzávěrky.
Popis
Transakce je dokončena!
Zkontrolujte ID transakce.

Odpověď obsahuje následující proměnné v závislosti na kódu odpovědi:

Proměnná
batchid
communicationId
batchNumber
date
previousBatchDate
firstTransactionDate
totalAmount
currency
totalCount
saleCount
saleAmount
voidCount
voidAmount
invalidCount
amsBatchNumber
subBatches
Formát
string
string
string
string
string
string
number
string
number
number
number
number
number
number
string
object
Popis
Interní ID dávky, OPEN pro pseudo dávku s otevřenými transakcemi.
Lze použít pro technickou podporu. Pseudo jedinečné ID pro účely protokolování.
Číslo dávky pro dané TID.
Přesné datum a čas, kdy byla dávka uzavřena.
Datum a čas začátku uzavřené dávky. Máte časové období pro tuto dávku (OD: hodnota previousBatchDate TO: datum hodnoty).
Datum nejstarší transakce.
Total amount for all types of transactions.
Měna uzávěrky
Celkový počet transakcí v dávce
Počet transakcí typu prodej v dávce.
Objem transakcí typu prodej v dávce.
Počet všech storno transakcí v dávce.
Objem všech storno transakcí v dávce.
Počet neplatných transakcí v dávce
Interní ID dávky, OPEN pro pseudo dávku s otevřenými transakcemi.
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
Příklad
12DFSFSSF
2
2025-12-18T08:21:39.427Z
2025-12-17T12:22:11.427Z
Jak se vám líbí tento návod?

Vložit komentář