Gabimet dhe statuset
Kodet e qëndrueshme të gabimeve, cikli i statuseve të komandës dhe si të dallosh një dështim të përkohshëm nga një refuzim.
Formati i gabimit
Gabimet përdorin të njëjtin zarf si suksesi:
{ "success": false, "errors": ["insufficient_capability"] }errors është një varg kodesh të qëndrueshme, jo proze. Mos i shfaq
drejtpërdrejt te përdoruesi dhe mos u mbështet te teksti — mbështetu te kodi.
Mund të shoqërohet nga një varg opsional warnings.
Kodet
| Kodi | HTTP | Kuptimi |
|---|---|---|
bad_json | 400 | Trupi nuk analizohet si JSON |
invalid_request | 400 | Payload i pavlefshëm sipas rregullave |
invalid_api_key | 401 | Çelës i panjohur ose i revokuar |
insufficient_capability | 403 | Çelësit i mungon aftësia e rrugës |
resource_not_found | 404 | Mungon, i huaj, i pamapuar ose i paautorizuar |
idempotency_conflict | 409 | I njëjti çelës me trup të ndryshëm |
request_in_progress | 409 | Kërkesë e njëkohshme mban lease-in e çelësit |
resource_conflict | 409 | Konflikt në gjendjen e burimit |
fiscalization_unavailable | 502 | Shërbimi i fiskalizimit prapa gateway-it nuk u përgjigj |
resource_not_found nuk do të thotë 'u fshi'
Burimet që mungojnë, ato të një biznesi tjetër dhe ato të paautorizuara janë të padallueshme qëllimisht, që një çelës të mos mund të zbulojë identifikuesit e bizneseve të tjera. Nëse ID-ja duket e saktë, dyshimi i parë duhet të jetë fushëveprimi i çelësit.
Cilat gabime ritentohen
| Kodi | Ritento? |
|---|---|
fiscalization_unavailable | Po — me të njëjtin Idempotency-Key |
request_in_progress | Po — pas një pauze të shkurtër |
bad_json, invalid_request | Jo — payload-i është i gabuar |
idempotency_conflict | Jo — defekt në kodin tënd |
invalid_api_key, insufficient_capability | Jo — problem konfigurimi |
502 nuk do të thotë se shitja humbi
fiscalization_unavailable do të thotë se gateway-i nuk mori përgjigje nga
shërbimi prapa tij. Ridërgo me të njëjtin çelës idempotence: nëse
komanda ishte krijuar, do të marrësh atë; nëse jo, do të krijohet një herë të
vetme.
Cikli i statuseve
| Statusi | Përfundimtar? | Kuptimi |
|---|---|---|
PENDING | Jo | Në radhë |
PROCESSING | Jo | Në fluturim |
RETRY | Jo | Dështoi dhe do të ritentohet automatikisht |
SUCCEEDED | Po | E lëshuar |
REJECTED | Po* | E refuzuar nga ATK |
RETRY nuk kërkon ndërhyrje — shërbimi ritenton vetë. Fusha next_retry_at
tregon se kur.
REJECTED është përfundimtar derisa ritentohet me dorë. Fusha last_error
mban shkakun.
Fushat ndihmëse
attempt_count— sa tentativa janë bërë.last_error— shkaku i dështimit të fundit.next_retry_at— kur do të ndodhë ritentimi automatik.receipt_ready— nëse kuponi mund të merret tashmë.
Gjetja e një komande
Nëse një kërkesë dështoi dhe nuk je i sigurt nëse komanda ekziston, kërkoje me referencën tënde në vend që të hamendësosh.
curl "$BASE_URL/v1/pos/$POS_ID/commands?external_id=order_123" \
-H "Authorization: Bearer $FISKALIZA_API_KEY"external_id përputhet saktësisht, duke dalluar shkronjat e mëdha nga të
voglat, brenda POS-it; hapësirat anësore hiqen dhe një vlerë shprehimisht bosh
është e pavlefshme. Kombinohet me status, dhe të dyja zbatohen përpara
faqezimit.
Një rrugë e vetme liston komanda:
GET /v1/pos/{pos_id}/commands. Kthen
shitjet, kthimet dhe anulimet së bashku, të renditura sipas created_at
zbritës, pastaj ID zbritëse.
Kufizoje në një lloj me kind:
kind | Kthen |
|---|---|
| i hequr | Shitje, kthime dhe anulime së bashku |
SALE | Vetëm shitjet |
RETURN | Vetëm kthimet |
CANCELLATION | Vetëm anulimet |
kind, status, external_id dhe aksesi POS që mban çelësi yt ndërpriten të
gjitha përpara se të numërohet total-i dhe të zbatohet faqezimi.
kind është i saktë
Pranohen vetëm tri vlerat me shkronja të mëdha. Një vlerë shprehimisht bosh,
shkronjat e vogla, një lloj i panjohur, i njëjti parametër i përsëritur, një
listë me presje dhe forma kanonike CANCEL japin të gjitha
400 invalid_request.
Rezultati bosh është 200, jo 404
Një POS pa komanda që përputhen kthen 200 me commands: []. Një 404 do të
thotë se vetë POS-i mungon ose është jashtë fushëveprimit të çelësit.
Ritentimi me dorë
POST /v1/commands/{command_id}/retry
e vendos komandën sërish në radhë. Nuk merr trup dhe nuk merr çelës
idempotence.
curl -X POST "$BASE_URL/v1/commands/$COMMAND_ID/retry" \
-H "Authorization: Bearer $FISKALIZA_API_KEY"Mos krijo komandë të re për të rregulluar një refuzim
Një shitje e re me Idempotency-Key të ri regjistron një shitje të dytë
te ATK. Nëse komanda ekziston, përdor retry.
Mënyra e lëshimit
issuance_mode merr ONLINE ose OFFLINE.
OFFLINE do të thotë se kuponi u lëshua kundrejt certifikatës lokale dhe
transmetimi është ende në pritje — jo se dështoi. Shitja është e vlefshme
dhe kuponi është i lëshueshëm.
Monitorimi
GET /v1/operations/summary
jep shëndetin e radhës për çdo POS që çelësi arrin:
| Fusha | Kuptimi |
|---|---|
retrying_commands | Komanda në ritentim |
rejected_commands | Komanda të refuzuara |
oldest_offline_age_seconds | Mosha e komandës më të vjetër offline |
alert_level | NONE, WARNING ose CRITICAL |
expiring_certificate_count | Certifikata që po skadojnë |
expired_certificate_count | Certifikata të skaduara |
Një certifikatë e skaduar ndalon shitjen
expired_certificate_count nuk është paralajmërim: ato POS kanë ndaluar së
shituri. Përdor
GET /v1/pos/certificate-problems
për të parë cilat, dhe alarmo mbi këtë.
Strategjia e rekomanduar
Poll-o derisa statusi të bëhet përfundimtar
Lexo komandën derisa status të jetë SUCCEEDED ose REJECTED. Përdor
prapavijë eksponenciale; mos poll-o në cikël të ngushtë.
Ritento gabimet e përkohshme me çelësin e njëjtë
502 dhe request_in_progress janë të sigurta për ridërgim.
Alarmo mbi certifikatat, jo vetëm mbi radhën
Një radhë e shëndetshme me certifikatë të skaduar do të thotë se POS-i nuk po shet fare.
Dokumentet e kuponit
Kuponi PDF ORIGINAL që lëshohet me çdo komandë, lëshimi i një COPY të shënuar, dhe shkarkimi i bajtave.
Register a point of sale POST
Requires ALL POS access. Business and fiscal identifiers are assigned by the service. An identical idempotency key and body replay the POS; a changed body returns idempotency_conflict. Concurrent onboarding under the same key returns request_in_progress while its two-minute lease is active.