Kull żball, spjegat f'indirizz stabbli.
Din il-paġna hija referenza operattiva, mhux diskors ta' bejgħ. Kull klassi ta' żball tal-API Connect għandha hawn ankra permanenti; it-tweġibiet ta' żball tal-API se jippuntaw lejn dawn l-indirizzi. Tikseb il-kawża probabbli u r-rimedju — f'dik l-ordni. Lura għad-dokumentazzjoni tal-iżviluppaturi.
Ċavetta nieqsa, malformata jew mhux magħrufa
L-API tawtentika esklussivament permezz tal-header Authorization: Bearer vgk_… — qatt permezz ta' cookie tas-sessjoni. Ċavetta revokata ssir mhux magħrufa fil-mument stess li tiġi revokata.
Ir-rimedju. Iċċekkja li l-header verament jitlaq (il-proxies xi drabi jneħħuh), li ċ-ċavetta tibda b'vgk_ u li ma ġietx revokata mill-console tal-uffiċċju. Peress li s-sigriet jintwera biss mal-ħolqien, ċavetta mitlufa tinbidel, ma tiġix irkuprata.
Ċavetta skaduta
Kull ċavetta tiskadi sena wara l-ħolqien — id-data expire_le hija viżibbli fil-console tal-uffiċċju mill-ewwel jum. Il-401 tal-iskadenza huwa espliċitu: jgħid li ċ-ċavetta kienet teżisti u m'għadhiex valida.
Ir-rimedju. Oħloq ċavetta ġdida, aqleb is-sejħiet tiegħek fuqha, irrevoka l-qadima. Ippjana din is-sostituzzjoni fl-operazzjonijiet tiegħek minflok ma tiskopriha: id-data hija magħrufa sena bil-quddiem.
Skop insuffiċjenti
Iċ-ċwievet iġorru lecture (qari, l-issettjar awtomatiku) u/jew ecriture (kitba). Il-kwalifikazzjoni ta' avveniment teħtieġ ecriture; ċavetta tal-qari biss tirċievi 403 tkun xi tkun ir-riżorsa.
Ir-rimedju. Oħloq ċavetta li ġġorr l-iskop meħtieġ — u dak biss. L-inqas privileġġ huwa apposta: integrazzjoni li taqra biss m'għandha l-ebda raġuni żżomm ċavetta tal-kitba.
Ma nstabx — jew ta' uffiċċju ieħor
404 ifisser li r-riżorsa ma teżistix jew li hija ta' uffiċċju ieħor. L-API qatt ma tiddistingwi ż-żewġ każijiet: li tiddistingwi jfisser tikxef x'jeżisti band'oħra. Is-separazzjoni hija infurzata fil-livell tad-database, mhux biss fil-kodiċi tal-applikazzjoni.
Ir-rimedju. Iċċekkja s-seq mal-ġurnal tal-uffiċċju li tiegħu hija ċ-ċavetta (GET /api/v1/evenements). Jekk tintegra diversi uffiċċji, kull uffiċċju għandu ċ-ċwievet tiegħu: seq ma jivvjaġġax bejn l-uffiċċji.
Rata maqbuża
60 talba fil-minuta għal kull ċavetta, b'mod awtomatiku (tista' tinbidel għal kull ċavetta). It-tweġiba ġġorr Retry-After u l-headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
Ir-rimedju. Irrispetta Retry-After — l-ebda tentattiv mill-ġdid immedjat. Li tolqot il-limitu waqt il-polling huwa kważi dejjem is-sinjal ta' skan mill-ġdid sħiħ: il-kursur depuisSeq qatt ma jerġa' jaqra dak li nqara diġà.
Il-firma ma tiġix ivverifikata min-naħa tiegħek
Ir-riċevitur tiegħek irid jerġa' jikkalkula v1 = HMAC-SHA256(secret, t + "." + body) mill-body mhux ipproċessat (raw) li rċieva, u jirrifjuta kull t eqdem minn 5 min. Il-fallimenti klassiċi: il-body serjalizzat mill-ġdid qabel il-verifika (JSON ifformattjat mill-ġdid m'għadx għandu l-istess bytes), arloġġ li jiżloq lil hinn mit-tolleranza, u rotazzjoni injorata — għal 24 h il-header iġorr v1 waħda għal kull sigriet għadu validu, u trid taċċetta jekk taqbel kwalunkwe waħda.
Ir-rimedju. Ivverifika mal-bytes mhux ipproċessati, issinkronizza l-arloġġ (NTP), ittestja l-verifika tiegħek waqt rotazzjoni. Is-snippets Node u Python fid-dokumentazzjoni jagħmlu eżattament dan — ikkupjahom minflok terġa' tiktibhom.
Avveniment jasal darbtejn
Il-kunsinna hija at-least-once, f'lottijiet ta' mhux aktar minn 100, fl-ordni tal-ġurnal; il-kursur jimxi 'l quddiem biss mat-2xx tiegħek, lott b'lott. Falliment wara r-riċezzjoni iżda qabel ma jimxi l-kursur jikkawża kunsinna mill-ġdid — dak huwa l-kuntratt, mhux difett.
Ir-rimedju. Is-seq hija ċ-ċavetta tal-idempotenza tiegħek: ipproċessa kull sekwenza eżattament darba, u wieġeb 2xx biss wara li tippersisti. 2xx kmieni segwit minn crash huwa l-uniku mod kif jintilef avveniment.
Il-ġurnal jidher mhux komplut jew jirrepeti ruħu
depuisSeq huwa strettament esklussiv: jiġu rritornati biss l-avvenimenti b'seq ogħla, ordnati tielgħin, mhux aktar minn 500 f'paġna. It-tweġiba tirritorna prochainSeq, x'terġa' tgħaddi kif inhu. Paġna iqsar minn limite tfisser tmiem il-ġurnal.
Ir-rimedju. Ippersisti prochainSeq bejn l-eżekuzzjonijiet u qatt terġa' tikkalkulah int. Duplikati jfissru li rġajt tlaqt minn kursur qadim wisq; lakuni jfissru li qbiżt paġna li falliet mingħajr ma erġajt għamiltha.
Parametru barra mill-iskema
Status mhux magħruf, dispożizzjoni barra mil-lista (planifie, traite, ecarte), limite mhux numru sħiħ: it-tweġiba ssemmi l-qasam ħati, u xejn aktar — il-messaġġi ta' żball qatt ma jġorru kontenut tal-fajls.
Ir-rimedju. L-ispeċifikazzjoni OpenAPI hija s-sors: l-enumerazzjonijiet u l-limiti li tiddikjara huma dawk li s-server jinforza, peress li hija servuta minnu stess.
Skop insuffiċjenti (API tar-riżorsi)
L-endpoints tar-riżorsi (/clients, /dossiers, dokumenti, skrinjar, twissijiet) jeħtieġu skop fin: clients:*, dossiers:*, pieces:*, criblage:* jew l-iskop iddedikat alertes:qualifier. Ċavetta legacy lecture tagħti kull skop *:lecture u ecriture kull *:ecriture — iżda alertes:qualifier qatt ma jintiret: il-kwalifikazzjoni ta' twissija hija att tar-responsabbli tal-konformità, iddelegat billi timmarka dak l-iskop mal-ħolqien taċ-ċavetta.
Ir-rimedju. Oħloq ċavetta li ġġorr eżattament l-iskopijiet li teħtieġ l-integrazzjoni tiegħek — u dawk biss. Id-detail tat-tweġiba jsemmi l-iskop nieqes.
Riżorsa ma nstabitx — jew ta' uffiċċju ieħor
L-istess regola bħal #cloisonnement, applikata għar-riżorsi: klijent, fajl, dokument jew twissija li ma jeżistux jew li huma ta' uffiċċju ieħor jirċievu l-istess 404. L-API qatt ma tiddistingwi ż-żewġ każijiet.
Ir-rimedju. Iċċekkja l-identifikatur mal-listi tal-uffiċċju li tiegħu hija ċ-ċavetta. Identifikatur qatt ma jivvjaġġa minn uffiċċju għal ieħor.
Header Idempotency-Key nieqes
Kull POST ta' ħolqien jew ta' skattar (klijent, fajl, dokument, skrinjar, sidien benefiċjarji) jeħtieġ il-header Idempotency-Key: sensiela stabbli ta' mhux aktar minn 200 karattru, waħda għal kull operazzjoni. Meta l-istess ċavetta terġa' tintbagħat bl-istess body, tirritorna l-istess tweġiba, mingħajr effett — il-protezzjoni tiegħek kontra d-duplikati f'inċident tan-netwerk.
Ir-rimedju. Iġġenera ċ-ċavetta qabel l-ewwel tentattiv (UUID wieħed għal kull operazzjoni tan-negozju) u erġa' użaha mhux mibdula għal kull tentattiv mill-ġdid ta' dik l-istess operazzjoni.
Ċavetta tal-idempotenza użata mill-ġdid b'body differenti
Din l-Idempotency-Key diġà ntużat għal body differenti fl-aħħar 24 siegħa. Iċ-ċavetta terġa' tirriproduċi tweġiba, qatt ma tissostitwixxiha: l-użu mill-ġdid tagħha għal operazzjoni ġdida huwa kważi dejjem is-sinjal ta' ċavetta derivata minn kontatur jew minn data mqassra.
Ir-rimedju. Ċavetta ġdida għal kull operazzjoni ġdida. Qatt tidderiva ċ-ċavetta minn data li tirrepeti ruħha bejn l-operazzjonijiet.
Fajl issiġillat: ir-reġistru huwa ffriżat
Is-siġillar jiffriża l-katina tal-integrità tal-fajl — dak huwa l-valur probatorju tiegħu. Fajl issiġillat ma jistax jiġi editjat aktar, ma jirċevix aktar dokumenti u ma jerġax jiġi skrinjat minn dan il-kanal. Tibqa' possibbli biss il-kwalifikazzjoni tat-twissijiet: tinkiteb off-chain, ir-ras issiġillata qatt ma tiċċaqlaq.
Ir-rimedju. Xejn x'"tikkoreġi": din hija immutabbiltà apposta. Jekk id-data trid tinbidel, dik hija operazzjoni ġdida ta' diliġenza fl-applikazzjoni, mhux mutazzjoni tal-fajl issiġillat.
Format tad-dokument mhux aċċettat
Id-dokumenti ta' sostenn jaċċettaw PDF, JPG, JPEG, PNG u WEBP — l-istess formati bħall-applikazzjoni. Il-kontroll isir fuq l-estensjoni tal-filename obbligatorju: dokument mingħajr isem ta' fajl validu jiġi rrifjutat, ikun xi jkun il-kontenut tiegħu.
Ir-rimedju. Ikkonverti qabel ma tibgħat (scan TIFF jew HEIC jiġi kkonvertit f'PDF jew JPEG) u ibgħat il-kontenut bħala base64 standard f'contenu, b'type minn fost il-kodiċijiet stabbli a_doc_*.
Dokument akbar minn 6 MB
Il-limitu japplika għall-fajl iddekodifikat (6 MB), l-istess bħal fl-applikazzjoni u fil-portal tal-ġbir. Peress li base64 iżid terz ta' piż ta' kodifikazzjoni, il-body tat-talba jaċċetta sa 9 MB.
Ir-rimedju. Ikkomprimi d-dokument (PDF skannjat bil-kulur f'300 dpi kważi dejjem jinżel taħt il-limitu bil-griż) minflok ma taqsmu.
Sors tal-iskrinjar mhux disponibbli
L-ebda waħda mill-entitajiet tal-fajl ma setgħet tiġi vverifikata mal-listi: is-sors (l-indiċi tal-listi uffiċjali jew il-fornitur) ma weġibx. L-API tirrifjuta li tikkonkludi — rapport "nadif" fuq sors mejjet ikun l-agħar negattiv falz possibbli. Il-falliment jiġi rreġistrat fuq il-fajl (erreurSource). Interruzzjoni parzjali ma tipproduċix dan il-502: it-tweġiba 200 iżżomm il-qbil tal-entitajiet li wieġbu u ssemmi dawk li fallew f'erreurSourceEntites.
Ir-rimedju. Erġa' agħmel l-istess sejħa aktar tard, bl-istess Idempotency-Key: l-idempotenza tiftakar biss it-tweġibiet ta' suċċess — meta terġa' tipprova wara żball, isir skrinjar reali.
Din il-paġna se tevolvi mal-API; l-ankri eżistenti, madankollu, qatt ma jibdlu l-indirizz — tista' taħżinhom fil-logs operattivi tiegħek.