GSA API
Comgate aktuálně umožňuje 2 způsoby využití GSA protokolu a to v lokální síti nebo přes cloudové řešení.
Níže naleznete dokumentaci k oběma variantám:
Propojení přes cloud:
GSA+ protokol umožňuje ovládat terminály z pokladního či jiného obchodního systému přes internet v podstatě stejným způsobem, jako pomocí původního protokolu GSA po lokální síti.
Zabezpečení
Pro zajištění integrity a důvěrnosti přenášených dat probíhá veškerá komunikace výhradně přes šifrovaný protokol HTTPS. Každý požadavek musí obsahovat autorizační hlavičku. Přístup ke všem metodám API musí být také povolen pouze z předem nastavených (rozsahů) IP adres.
Implementace
Pro implementaci je možné vycházet z dokumentace GSA protokolu (pro komunikaci v lokální síti), pro využití internetového GSA+ je však potřeba provést několik změn v implementaci:
- Je potřeba upravit začátek volané adresy endpointů tak, že místo původních adres http://{ip_terminalu}:{port33350}/paya/ popř. http://{ip_terminalu}:{port33350}/api/switchio/pay/v{x}/ bude nově adresa začínat https://payments.comgate.cz/ecr/api/v1.0/
- Zároveň každý požadavek musí obsahovat autorizační HTTP hlavičku ve tvaru Authorization: Basic [base64_encode(merchant:secret)] Parametr 'merchant' je přihlašovací identifikátor ke konkrétnímu terminálu a 'secret' je heslo. Tyto údaje najdete v Klientském portálu v sekci Integrace - Nastavení obchodů - Terminály. Zároveň zde lze pro každý terminál nastavit i rozsahy povolených IP adres pro přístup k API (IP adresa nebo adresy, ze kterých může přes API komunikovat pokladna s daným terminálem). Každý příchozí požadavek z IP adresy mimo nastavený rozsah bude zamítnut.
- Není nutné nadále posílat v požadavcích parametr ‘secureString’ (ale může v požadavcích i zůstat)
- Pro správnou konfiguraci terminálu je potřeba, aby Comgate od klienta (popř. od dodavatele pokladního systému) dostal informaci, zda pokladní systém bude s terminálem komunikovat lokálně po místní síti (GSA) nebo vzdáleně přes internet (GSA+) - a to zejména v případech, kdy pokladní systém používaný klientem podporuje oba dva protokoly.
Upozornění: GSA+ protokol nyní nepodporuje endpointy s callbackem.
Odpověď z API může být krom HTTP 200 OK i následující:
- HTTP 401 Unauthorized (v případě nesprávných údajů merchant/secret),
- HTTP 403 Forbidden (v případě požadavku z nepovolené IP adresy)
- HTTP 400 Bad Request (v případě nesprávně zaslaných parametrů)
- HTTP 500 Internal Server Error v případě jiné chyby
Propojení přes lokální síť
Protokol pro propojení je zde