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.
Anmeldung & Authentifizierung
Für alle nicht öffentlichen Endpunkte ist eine Authentifizierung mittels JWT-Token erforderlich. Das Token (mit einer Gültigkeitsdauer von 90 Tagen) erhalten Sie über den Endpunkt /cloud/oauth/token mit den folgenden übergebenen Argumenten:
- Basisauthentifizierung für Token-Endpunkte (Benutzername/Passwort) – wird für jeden Benutzer bereitgestellt.
- Händlername – derselbe wie für GP tom
- Händler-Passwort – dasselbe wie für GP tom
- Terminal-ID (TID) – ID des Zielterminals
- Der Autorisierungsendpunkt befindet sich unter:
Beantragung eines Zugriffstokens
Beispielanfrage:
POST {{apiCloudHost}}/cloud/oauth/token
Autorisierung: Basic YXRvbTphc2hmdWY0ZTVmYQ==
Inhalt-Typ: anwendung/x-www-form-urlencoded
grant_type=password&username=jan.novak@example.com&password=ABCDEFGHIJKL&tid=999888
Beispielantwort:
{
"access_token": "eyJh…", // Zugriffstoken, das bei authentifizierten API-Anfragen verwendet wird
"token_type": "bearer",
"refresh_token": "GciO…",
"expires_in": 3600,
"scope": "read write",
"tid": "999888",
}Token zurücksetzen
Nach Ablauf des access_tokens steht ein refresh_token zur Verfügung.
Beispielanfrage:
POST {{apiHost}}/api/oauth/token
Autorisierung: Basic YXRvbTphc2hmdWY0ZTVmYQ==
Inhalt-Typ: anwendung/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=GciO…
GPTomAuth
Art des Sicherheitsschemas
Schema der HTTP-Autorisierung
HTTP
Inhaber
Erstellen eines Ordners
Zavolejte koncový bod POST /v1/tasks/BATCH a použijte CreateCloudTaskTransactionApiRequest s následujícími údaji vyplněnými k vytvoření požadavku:
Variabel
Datum
VERPFLICHTUNG
VERPFLICHTUNG
apiKey
VERPFLICHTUNG
VERPFLICHTUNG
tid
VERPFLICHTUNG
VERPFLICHTUNG
Initiator
VERPFLICHTUNG
VERPFLICHTUNG
Titel
VERPFLICHTUNG
VERPFLICHTUNG
timeToLive
Format
String
String
String
String
String
Ganzzahl
Beschreibung
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 najdete v aplikaci v sekci Účet-Cloud API. Používá se k rozlišení přihlášení hlavně v Cloud API.
Ziel-TID für die jeweilige Aufgabe. TID = Terminal-ID, die für jedes Gerät eindeutig ist. Auf allen installierten Geräten kann jeweils nur eine TID verwendet werden.
Die Beschreibung des Initiators sollte für jede Instanz des Subsystems, die eine Aufgabe initiieren kann, eindeutig sein. Beispiel: „Server XY“ oder „Kasse 1“
Lidsky čitelný název tasku. Měl by obsahovat nějakou identifikaci úkolu.
Beispiel: „Rechnung 37364FD“
Beispiel: „Rechnung 37364FD“
Zeitlimit für das Ablaufen eines Cloud-Auftrags. Es dürfen Werte im Bereich von Sekunden eingegeben werden.
Beispiel
2025-12-18T08:21:39.427Z
333W212J3
483590
Kasse 12
Uzávěrka 36744
10
Inhalt der Antwort [CloudTaskDetailApiResponse]:
Mögliche Antwortcodes sind:
Antwort
RC200
RC403
RC406
RC 502
Bericht
OK – Die Aufgabe wurde registriert
Der Benutzer ist nicht berechtigt, einen Auftrag auf diesem Terminal zu registrieren
Der Auftrag kann für dieses Terminal nicht angenommen werden
Die Push-Benachrichtigung wurde nicht gesendet
Beschreibung
Die Aufgabe wurde erfolgreich erstellt und wird bearbeitet.
Wenn Ihre API-Anmeldedaten nicht mit dem übermittelten TID-Wert übereinstimmen (beispielsweise wenn der TID-Inhaber ein anderer ist).
Dies geschieht in der Regel, wenn TID die Anfrage nicht bearbeiten kann.
Die Push-Benachrichtigung wurde aufgrund eines Ausfalls des Upstream-Dienstes nicht gesendet.
Wie man sich verhält
Fahren Sie mit dem nächsten Schritt im Transaktionsablauf fort.
Bitte überprüfen Sie, ob Sie die richtige TID eingegeben haben, und versuchen Sie es erneut.
Überprüfen Sie die Fehlermeldung.
Nachfolgend finden Sie die in der Antwort verwendeten Variablen:
Variabel
Titel
taskId
erstellt
Aufgabenklasse
Status
Initiator
contextId
Nutzlast
exceptionId
Typ
Nachricht
Kontext
Format
String
String
String
String
String
String
String
Objekt
String
String
String
String
Beschreibung
Ein für Menschen lesbarer Name für den Ordner. Wird aus dem Wert der Anforderung übernommen.
Interne ID des Tasks
Datum und Uhrzeit der Erstellung der Aufgabe.
Nutzlastklasse Mögliche Werte: [TRANSACTION, BATCH, DUMMY]
Status der Cloud-Aufgabe. Mögliche Werte: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
Beschreibung des Initiators auf der Client-Seite. Wird aus dem Wert der Anfrage übernommen.
ID der betreffenden Zielentität, falls vorhanden (transactionId / batchId)
Der Hauptteil der kontextbezogenen Aufgabe – abhängig von der taskClass
Pseudo-eindeutige Ausnahme-IDs. Diese können als „Support-ID“ dienen, die der Benutzer dem Support mitteilen kann, damit dieser den Fehler untersuchen kann.
Ausnahmetyp.
Meldung einer Ausnahme.
Kontext der Ausnahme. Weitere Informationen.
Beispiel
Uzaverka 123
dFd3sda
BATCH
GESCHAFFEN
Kasse 12
{...}
FujIk6
VALIDATION_EXCEPTION
Das Passwort ist zu schwach
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
RC200
JA
JA
JA
JA
JA
JA
JA
JA
NA
NA
NA
NA
RC403
NA
NA
NA
NA
NA
NA
NA
NA
JA
JA
JA
JA
RC406
NA
NA
NA
NA
NA
NA
NA
NA
JA
JA
JA
JA
RC502
NA
NA
NA
NA
NA
NA
NA
NA
JA
JA
JA
JA
Überprüfung des Taschenzustands
Im nächsten Schritt überprüfen Sie den Status der Aufgabe am Endpunkt GET /v1/tasks/{taskID} mithilfe einer Anfrage, die Folgendes enthält:
Variabel
taskId
Format
String
Beschreibung
Die ID des Tasks, den Sie im vorherigen Schritt erhalten haben.
Beispiel
dFd3sda
Mögliche Rückgabecodes:
Antwort
RC200
RC403
Bericht
OK – Status der Tasche verfügbar
Für das aktuelle Terminal wurde keine Cloud-Aufgabe gefunden.
Bericht
Die Aktualisierung des Auftragsstatus wurde erfolgreich durchgeführt.
Sie sollten Ihre Task-ID überprüfen und den richtigen Wert erneut übermitteln.
Beschreibung
Falls Sie keinen endgültigen Status erhalten (siehe unten), wiederholen Sie diesen Schritt.
Bitte überprüfen Sie, ob Sie die richtige Task-ID eingegeben haben, und versuchen Sie es erneut.
Variablen in der Antwort:
Variabel
Titel
taskId
erstellt
Aufgabenklasse
Status
Initiator
contextID
Nutzlast
exceptionId
Typ
Nachricht
Kontext
Format
String
String
String
String
String
String
String
String
String
String
String
Beschreibung
Ein für Menschen lesbarer Name für die Aufgabe. Wird aus dem Wert der Anforderung zur Erstellung der Aufgabe übernommen.
Interne ID der Aufgabe
Datum und Uhrzeit der Erstellung der Aufgabe.
Mögliche Werte: [TRANSACTION, BATCH, DUMMY]
Mögliche Werte: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
Beschreibung des Initiators auf der Client-Seite. Wird aus dem Wert der Anfrage übernommen.
ID der betreffenden Zielentität, falls vorhanden (transactionId / batchId)
Pseudo-eindeutige Ausnahme-IDs. Diese können als „Support-ID“ dienen, die der Benutzer dem Support mitteilen kann, damit dieser ein eventuelles Problem untersuchen kann.
Ausnahmetyp.
Ausnahmemeldung.
Kontext der Ausnahme – weitere Informationen.
Beispiel
Rechnung 36744
dFd3sda
2025-12-18T08:21:39.427Z
BATCH
IN_PROGRESS
Kasse 12
12DFSFSSF
FujIk6
VALIDATION_EXCEPTION
Das Passwort ist zu schwach
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
RC200
JA
JA
JA
JA
JA
JA
JA
JA
NA
NA
NA
NA
RC404
NA
NA
NA
NA
NA
NA
NA
NA
JA
JA
JA
JA
Die Abfrage des Tasks-Status sollte so lange wiederholt werden, bis Sie einen der folgenden endgültigen Antwortcodes erhalten:
Status
INIT_ERROR
ABGESCHLOSSEN
ABGESAGT
ERROR
Beschreibung
Die Initiierung des Zahlungsvorgangs ist fehlgeschlagen. Überprüfen Sie den empfangenen Fehler.
Sobald Sie diesen Status erhalten, ist Ihre Aufgabe abgeschlossen und das Ergebnis liegt vor.
Die Aufgabe wurde vom Benutzer gelöscht.
Bei der Verarbeitung des Auftrags ist ein Fehler aufgetreten.
Wie man sich verhält
Befolgen Sie die Anweisungen für den Fehler.
Sie können mit dem nächsten Schritt fortfahren.
Sie sollten eine neue Aufgabe starten, da diese Aufgabe vom Benutzer abgebrochen wurde.
Befolgen Sie die Anweisungen für den Fehler.
Sie können erst dann mit dem nächsten Schritt fortfahren, wenn der Status der Antwort „COMPLETED“ lautet.
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é:
Variabel
batchId
Format
String
Beschreibung
ID dávky, které získáte v předchozích krocích.
Beispiel
12DFSFSSF
Mögliche Antwortcodes sind:
Antwort
RC200
RC404
Bericht
OK – podrobnosti uzávěrky poskytnuty
Pro aktuální TID nebyla uzávěrka nalezena.
Bericht
Ú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.
Beschreibung
Die Transaktion ist abgeschlossen!
Überprüfen Sie die Transaktions-ID.
Die Antwort enthält je nach Antwortcode die folgenden Variablen:
Variabel
batchid
communicationId
batchNumber
Datum
previousBatchDate
firstTransactionDate
totalAmount
currency
totalCount
saleCount
saleAmount
voidCount
voidAmount
invalidCount
amsBatchNumber
subBatches
Format
String
String
String
String
String
String
Zahl
String
Zahl
Zahl
Zahl
Zahl
Zahl
Zahl
String
Objekt
Beschreibung
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
-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
Beispiel
12DFSFSSF
2
2025-12-18T08:21:39.427Z
2025-12-17T12:22:11.427Z