Mezní případy a zpracování chyb

Před nasazením do produkce je třeba promyslet řadu scénářů, aby integrace byla kompletní. Část z nich leží ve vašem vlastním kódu; Twisto je výslovně nekontroluje a předpokládáme, že budou hotové před žádostí o přístup do produkce.

Něco nefunguje podle očekávání? Na technické dotazy nás kontaktujte na merchant-tech@twisto.cz.

Mezní případy

Důkladně otestujte integraci včetně scénářů s:

Neúplnými daty
Neplatnými daty
Duplicitními daty (např. opakujte stejný požadavek a sledujte chování)

Timeouty a opakované transakce

Někdy kvůli výpadku spojení nepřijde žádná odpověď. V takovém případě Twisto očekává, že transakce budete opakovat, dokud nepřijde platná odpověď, nebo dokud nevyprší časový limit.

Netransakční volání API

Některá volání API lze prostě znovu odeslat bez označení opakování. Endpoint /checkouts například lze volat opakovaně se stejnými referencemi a stejným tělem bez problému. Načasování těchto volání nemá velký dopad, protože každý požadavek je nový a nezávislý na předchozím neúspěšném pokusu.

Transakční volání API

U jiných volání musí být opakování jednoznačně identifikováno, aby nedošlo k dvojímu zaúčtování a aby se předešlo chybám duplicitní reference u předávané objednávky.

U transakčních volání API na endpointy /charges nebo /refunds je např. nutné v hlavičce použít stejný Idempotency-key jako u původního požadavku.

METODA	TYP
POST /checkouts	Netransakční
POST /checkouts/{id}/cancel	Transakční
POST /charges	Transakční
POST /refunds	Transakční

Doporučené časování opakování:

ČÍSLO POKUSU	PAUZA PŘED POKUSEM (S)	TIMEOUT POKUSU (S)	CELKEM UPLYNULO (S)
1	—	20	20
2	10	10	40
3	5	5	50
4	5	5	60

Kontrola logů

Doporučujeme si u sebe logovat všechna důležitá data. Vlastní logy budou neocenitelné, pokud váš server nemůže kontaktovat Twisto, nebo pokud nastane problém s API klíči — v obou případech nemusíme váš požadavek zaznamenat.

Pravidelně logy kontrolujte, zda ukládají vše potřebné a neukládají citlivé údaje navíc. Hledejte opakující se chyby, které mohou vyžadovat úpravu integrace.

Měňte a chraňte API klíče

Dbát na to, aby přístupové údaje k API zůstaly soukromé.

Chybové kódy

API vrací konzistentní chybové odpovědi a tam, kde to dává smysl, dodržuje konvence REST stavových kódů.

Pro detailnější informace nebo podtyp stavových kódů se u odpovědí mimo řadu 2xx vrací objekt Error s konkrétnějším kódem a chybovou zprávou.

Stavové kódy, které API může vracet:

STAVOVÝ KÓD	POPIS
2xx	OK — vše proběhlo v pořádku.
400	Bad Request — v objektu požadavku je chyba.
401	Unauthorized — nebyl poskytnut platný API klíč.
402	Request Failed — požadavek nešlo zpracovat, více v chybovém kódu.
403	Forbidden — operace není povolena (zákazník akci neautorizoval).
404	Not Found — prostředek neexistuje.
409	Conflict — požadavek je duplicitní vůči předchozímu
429	Too Many Requests — překročen limit počtu požadavků.
5xx	Server Error — na straně Twisto došlo k chybě.

Konkrétní chybové kódy pro jednotlivé endpointy jsou uvedeny na stránkách příslušných endpointů.

U odpovědí BadRequest najdete detail chyby v části details objektu Error.

"error": {
  "code": "string",
  "message": "string",
  "details": [
    {
      "name": "string",
      "message": "string"
    }
  ]
  }