Gach earráid, mínithe ag seoladh seasmhach.
Tagairt oibríochtaí an leathanach seo, ní píosa díolacháin. Tá ancaire buan anseo ag gach aicme earráide den Connect API; díreoidh freagraí earráide an API ar na seoltaí seo. Faigheann tú an chúis dhóchúil agus an leigheas — san ord sin. Ar ais chuig doiciméadú na bhforbróirí.
Eochair ar iarraidh, míchumtha nó anaithnid
Ní fhíordheimhníonn an API ach tríd an gceanntásc Authorization: Bearer vgk_… — ní trí fhianán seisiúin go deo. Éiríonn eochair chúlghairthe anaithnid an nóiméad a chúlghairtear í.
An leigheas. Seiceáil go n-imíonn an ceanntásc i ndáiríre (baineann seachfhreastalaithe é uaireanta), go dtosaíonn an eochair le vgk_ agus nár cúlghaireadh í ó chonsól an chomhlachta. Ós rud é nach dtaispeántar an rún ach tráth an chruthaithe, athsholáthraítear eochair chaillte, ní aisghabhtar í.
Eochair éagtha
Éagann gach eochair bliain tar éis a cruthaithe — tá an dáta expire_le le feiceáil i gconsól an chomhlachta ón gcéad lá. Tá 401 an éaga follasach: deir sé go raibh an eochair ann agus nach bhfuil sí bailí a thuilleadh.
An leigheas. Cruthaigh eochair nua, aistrigh do ghlaonna anonn, cúlghair an seancheann. Pleanáil an t-athsholáthar seo i d'oibríochtaí seachas teacht air de thaisme: tá an dáta ar eolas bliain roimh ré.
Scóip neamhleor
Iompraíonn eochracha lecture (léamh, an réamhshocrú) agus/nó ecriture (scríobh). Éilíonn cáiliú imeachta ecriture; faigheann eochair léimh amháin 403 is cuma cén acmhainn.
An leigheas. Cruthaigh eochair a iompraíonn an scóip riachtanach — agus í sin amháin. D'aon ghnó atá an phribhléid is lú: níl aon chúis ag comhtháthú nach ndéanann ach léamh eochair scríofa a shealbhú.
Gan aimsiú — nó le comhlacht eile
Ciallaíonn 404 nach ann don acmhainn nó gur le comhlacht eile í. Ní dhéanann an API idirdhealú idir an dá chás go deo: nochtfadh an t-idirdhealú a bhfuil ann in áit eile. Cuirtear an t-aonrú i bhfeidhm ag leibhéal an bhunachair sonraí, ní i gcód an fheidhmchláir amháin.
An leigheas. Seiceáil an seq in aghaidh dhialann an chomhlachta ar leis an eochair (GET /api/v1/evenements). Má chomhtháthaíonn tú roinnt comhlachtaí, tá a eochracha féin ag gach comhlacht: ní thaistealaíonn seq ó chomhlacht go comhlacht.
Ráta sáraithe
60 iarratas sa nóiméad in aghaidh na heochrach, mar réamhshocrú (in-sáraithe in aghaidh na heochrach). Iompraíonn an freagra Retry-After agus na ceanntásca X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
An leigheas. Urramaigh Retry-After — gan atriail láithreach. Nuair a bhuailtear an teorainn le linn an cheistithe rialta, is comhartha ath-scanadh iomlán é beagnach i gcónaí: ní athléann an cúrsóir depuisSeq an méid atá léite cheana.
Ní fhíoraítear an síniú ar do thaobh féin
Caithfidh do ghlacadóir v1 = HMAC-SHA256(secret, t + "." + body) a athríomh ón gcorp amh a fuarthas, agus diúltú d'aon t níos sine ná 5 nóim. Na teipeanna clasaiceacha: an corp athshraithithe roimh an bhfíorú (ní hionann bearta JSON athfhormáidithe a thuilleadh), clog ag imeacht thar an lamháltas, agus rothlú a ndearnadh neamhaird de — ar feadh 24 u iompraíonn an ceanntásc v1 amháin in aghaidh gach rúin atá fós bailí, agus caithfidh tú glacadh leis má mheaitseálann ceann ar bith díobh.
An leigheas. Fíoraigh in aghaidh na mbeart amh, sioncronaigh do chlog (NTP), tástáil d'fhíorú le linn rothlaithe. Déanann na blúirí Node agus Python sa doiciméadú é seo go díreach — cóipeáil iad seachas iad a athscríobh.
Sroicheann imeacht faoi dhó
Is at-least-once an seachadadh, i mbaisceanna de 100 ar a mhéad, in ord na dialainne; ní théann an cúrsóir chun cinn ach ar do 2xx, baisc ar bhaisc. Teip tar éis an ghlactha ach roimh dhul chun cinn an chúrsóra, is athsheachadadh a leanann aisti — sin an conradh, ní locht.
An leigheas. Is é an seq d'eochair idempotence: próiseáil gach seicheamh díreach uair amháin, agus ná freagair 2xx ach tar éis na buanaithe. 2xx róluath agus tuairteáil ina dhiaidh — sin an t-aon bhealach le himeacht a chailleadh.
Tá cuma neamhiomlán ar an dialann, nó athdhéanann sí í féin
Tá depuisSeq go docht eisiach: ní thugtar ar ais ach imeachtaí a bhfuil seq níos airde acu, sórtáilte in ord ardaitheach, 500 ar a mhéad sa leathanach. Tugann an freagra prochainSeq ar ais, le seachadadh mar atá. Leathanach níos giorra ná limite, sin deireadh na dialainne.
An leigheas. Buanaigh prochainSeq idir rití agus ná hathríomh tú féin é go deo. Dúbailtí, is comhartha iad gur atosaigh tú ó chúrsóir atá róshean; bearnaí, gur léim tú thar leathanach teipthe gan é a athsheinm.
Paraiméadar lasmuigh den scéimre
Stádas anaithnid, diúscairt lasmuigh den liosta (planifie, traite, ecarte), limite nach slánuimhir í: ainmníonn an freagra an réimse ciontach, agus sin uile — ní iompraíonn teachtaireachtaí earráide ábhar comhaid go deo.
An leigheas. Is í an tsonraíocht OpenAPI an fhoinse: na háirimh agus na teorainneacha a dhearbhaíonn sí, sin iad na cinn a chuireann an freastalaí i bhfeidhm, ós é a sheirbheálann í.
Scóip neamhleor (API acmhainní)
Éilíonn na críochphointí acmhainne (/clients, /dossiers, cáipéisí, scagadh, foláirimh) scóip mhionghrádaithe: clients:*, dossiers:*, pieces:*, criblage:* nó an scóip thiomnaithe alertes:qualifier. Bronnann sean-eochair lecture gach scóip *:lecture agus ecriture gach ceann *:ecriture — ach ní fhaightear alertes:qualifier le hoidhreacht go deo: gníomh de chuid an oifigigh fhreagraigh is ea foláireamh a cháiliú, arna tharmligean tríd an scóip sin a thiceáil nuair a chruthaítear an eochair.
An leigheas. Cruthaigh eochair a iompraíonn go díreach na scóipeanna atá de dhíth ar do chomhtháthú — agus iad sin amháin. Ainmníonn detail an fhreagra an scóip atá ar iarraidh.
Acmhainn gan aimsiú — nó le comhlacht eile
An riail chéanna le #cloisonnement, curtha i bhfeidhm ar acmhainní: cliant, comhad, cáipéis nó foláireamh nach ann dó nó ar le comhlacht eile é, faigheann sé an 404 céanna. Ní scarann an API an dá chás óna chéile go deo.
An leigheas. Seiceáil an t-aitheantóir in aghaidh liostuithe an chomhlachta ar leis an eochair. Ní thaistealaíonn aitheantóir ó chomhlacht go chéile go deo.
Ceanntásc Idempotency-Key ar iarraidh
Éilíonn gach POST cruthaithe nó truicearaithe (cliant, comhad, cáipéis, scagadh, úinéirí tairbhiúla) an ceanntásc Idempotency-Key: teaghrán seasmhach de 200 carachtar ar a mhéad, ceann in aghaidh na hoibríochta. Má athsheinntear an eochair chéanna leis an gcorp céanna, tugtar an freagra céanna ar ais, gan aon éifeacht — do chosaint ar dhúbailtí i dteagmhas líonra.
An leigheas. Gin an eochair roimh an gcéad iarracht (UUID amháin in aghaidh na hoibríochta gnó) agus athúsáid gan athrú í do gach atriail den oibríocht chéanna sin.
Eochair idempotence athúsáidte le corp difriúil
Úsáideadh an Idempotency-Key seo cheana le corp difriúil le 24 uair an chloig anuas. Athsheinneann an eochair freagra, ní fhorscríobhann sí ceann go deo: í a athúsáid d'oibríocht nua, is comhartha é beagnach i gcónaí ar eochair a díorthaíodh ó áiritheoir nó ó dháta teasctha.
An leigheas. Eochair nua do gach oibríocht nua. Ná díorthaigh an eochair go deo ó shonraí a athdhéantar ó oibríocht go chéile.
Comhad séalaithe: tá an clár reoite
Reonn an séalú slabhra sláine an chomhaid — sin é a luach fianaise. Ní féidir comhad séalaithe a chur in eagar a thuilleadh, ní ghlacann sé cáipéisí a thuilleadh agus ní ath-scagtar tríd an gcainéal seo a thuilleadh é. Ní fhanann indéanta ach cáiliú na bhfoláireamh: scríobhtar off-chain é, ní bhogann an ceann séalaithe go deo.
An leigheas. Níl aon rud le « ceartú »: do-athraitheacht d'aon ghnó í seo. Má chaithfidh sonraí athrú, oibríocht nua díchill chuí san fheidhmchlár é sin, ní sóchán ar an gcomhad séalaithe.
Formáid cháipéise nach nglactar léi
Glacann cáipéisí tacaíochta le PDF, JPG, JPEG, PNG agus WEBP — na formáidí céanna leis an bhfeidhmchlár. Ar iarmhír an filename éigeantaigh atá an tseiceáil: diúltaítear do cháipéis gan ainm comhaid bailí, is cuma cén t-ábhar atá inti.
An leigheas. Tiontaigh roimh sheoladh (tiontaíonn scan TIFF nó HEIC go PDF nó JPEG) agus seol an t-ábhar mar base64 caighdeánach in contenu, le type as na cóid sheasmhacha a_doc_*.
Cáipéis os cionn 6 MB
Baineann an teorainn leis an gcomhad díchódaithe (6 MB), mar an gcéanna leis an bhfeidhmchlár agus le tairseach an bhailithe. Ós rud é go gcuireann base64 trian d'fhorchostas ionchódaithe leis, glacann corp an iarratais le suas le 9 MB.
An leigheas. Comhbhrúigh an cháipéis (titeann PDF scanta daite 300 dpi faoin teorainn beagnach i gcónaí sa liathscála) seachas í a scoilteadh.
Foinse scagtha gan a bheith ar fáil
Níorbh fhéidir aon cheann d'eintitis an chomhaid a sheiceáil in aghaidh na liostaí: níor fhreagair an fhoinse (innéacs na liostaí oifigiúla nó an soláthraí). Diúltaíonn an API teacht ar chonclúid — tuairisc « ghlan » ar bharr foinse mairbhe, sin an diúltach bréagach is measa dá bhféadfadh a bheith ann. Taifeadtar an teip ar an gcomhad (erreurSource). Ní tháirgeann briseadh páirteach an 502 seo: coinníonn an freagra 200 meaitseálacha na n-eintiteas a d'fhreagair agus ainmníonn sé na cinn ar theip orthu in erreurSourceEntites.
An leigheas. Athsheinn an glao céanna ar ball, leis an Idempotency-Key céanna: ní choinnítear i gcuimhne na idempotence ach na freagraí ratha — má athsheinntear tar éis earráide, ritear fíor-scagadh.
Tiocfaidh forbairt ar an leathanach seo in éineacht leis an API; na hancairí atá ann, áfach, ní athraíonn siad seoladh go deo — is féidir leat iad a stóráil i do logaí oibríochtaí.