Gach earráid, mínithe ag seoladh seasmhach.

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 í.

Iompraíonn an 401 céanna "motif": "fin_option_api" nuair a stopadh an eochair toisc nach bhfuil an API mar chuid de shíntiús an chomhlachta a thuilleadh. Luadh dáta an stoptha sin i ríomhphost chuig riarthóirí an chomhlachta nó, mura bhfuil aon riarthóir ann, chuig seoladh billeála an chomhlachta, agus fógraíodh ansin é sa cheanntásc Sunset de gach freagra ar ghlao a glacadh (an féilire faoi #cle-expiree). Gan chúis, d'fhéadfadh sé teacht freisin ó shíntiús ar fionraí: gearrann an fionraí na heochracha láithreach.

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 í. Le "motif": "fin_option_api", níl an locht ar an gceanntásc ná ar an eochair: scríobhann riarthóir an chomhlachta chugainn chuig contact@vigilae.org chun an API a chur ar ais sa síntiús, agus glactar leis an eochair chéanna arís chomh luath agus a dhéantar é sin, go dtí a dáta éaga féin.

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.

Is féidir freisin stopadh ag glacadh le heochair API roimh an dáta sin, nuair nach bhfuil an API mar chuid de shíntiús an chomhlachta a thuilleadh. Tagann an stopadh ansin 30 lá ar a laghad tar éis an chéad ríomhphoist, ar an dáta a thugann an dara ríomhphost, a sheoltar 7 lá ar a laghad roimh ré; seoltar an dá cheann chuig riarthóirí an chomhlachta nó, mura bhfuil aon riarthóir ann, chuig seoladh billeála an chomhlachta. Chomh luath agus a shocraítear é, tá an dáta sin le feiceáil i gconsól an chomhlachta (réimse coupure_le de GET /connect/cles), agus fógraíonn gach freagra ar ghlao a glacadh é sa cheanntásc Sunset go dtí go dtagann sé. Ina dhiaidh sin, faigheann an glao an 401 a thuairiscítear faoi #authentification, le "motif": "fin_option_api"; má thagann an API ar ais sa síntiús, glactar leis an eochair arís, go dtí a dáta éaga féin.

An leigheas. Cruthaigh eochair nua, aistrigh do ghlaonna anonn, cúlghair an seancheann. I gcás eochair API, ní mór don API a bheith fós mar chuid de shíntiús an chomhlachta: gan é, diúltaíonn an consól eochair a chruthú. Pleanáil an t-athsholáthar seo i d'oibríochtaí seachas teacht air de thaisme.

Scóip neamhleor

Iompraíonn eochracha na scóipeanna a ticeáladh nuair a cruthaíodh iad: na cinn ghinearálta lecture (léamh, an réamhshocrú) agus ecriture (scríobh), nó cinn mhionsonraithe de réir acmhainne (clients:lecture, pieces:ecriture, origine-fonds:lecture, journal:lecture…).

Leanann an oidhreacht an iarmhír, agus ní théann sí ach i dtreo amháin: clúdaíonn lecture gach *:lecture, agus ecriture gach *:ecriture — ní fíor riamh a mhalairt; ní osclaíonn scóip mhionsonraithe ach í féin.

Titeann sé scóip lasmuigh den phéire sin agus ní thagann siad le hoidhreacht ó aon eochair ghinearálta: alertes:qualifier, embed:emettre, adversemedia:consulter, conformite:consulter, dispositif:consulter, integrite:consulter. Ní leanann cáiliú imeachta, eisiúint chomhartha leabaithe, léamh preas diúltach comhaid ná scór coimeádta comhaid riamh ó cheart ginearálta léimh: ticeáiltear gach ceann acu ar leithligh.

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ú, agus ní chúiteoidh eochair leathan riamh scóip nár tarmligeadh go sainráite.

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.

Tá an cuntas seo ann cheana

Freagraíonn POST /scim/v2/Users ar userName atá soláthraithe cheana don oifig seo le 409 agus scimType: uniqueness. Is srian bunachair sonraí a choinníonn an uathúlacht, ní taisce: ní féidir le dhá chruthú ag an am céanna dhá chuntas a tháirgeadh.

An leigheas. Caith leis an 409 mar rath idempotentach, ní mar earráid: léigh an cuntas ar ais le ?filter=userName eq "…" agus lean ar aghaidh leis an aitheantóir a tugadh ar ais. Ní chruthóidh nascóir a dhéanann iarracht arís i lúb tar éis 409 aon rud breise go deo.

Tá an cuntas seo lasmuigh de raon an eolaire

Ní féidir le heolaire cuntas a iompraíonn cumhachtaí riaracháin na hoifige a ísliú ná a dhíghníomhachtú: diúltaítear don iarratas le scimType: mutability agus logáiltear é. Gan an teorainn sin, dhúnfadh nascóir a ghlacann seoladh an oifigigh chomhlíonta an oifig ar an duine féin atá freagrach aisti.

An leigheas. Bain an duine sin as an raon sioncronaithe, nó athraigh a ról ó Vigilae féin. Ní bhaineann an diúltú ach leis an gcuntas seo: cuirtear an chuid eile den bhaisc i bhfeidhm mar is gnách.

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 í.

Réimse a bhfuil a luach rófhada: Náisiúntacht

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.

Tá iarracht eile leis an eochair seo ar siúl go fóill

Shroich dhá iarratas leis an Idempotency-Key céanna ag an am céanna: ritheann an chéad cheann, agus diúltaítear don dara ceann sula mbíonn aon éifeacht. Is é an diúltú sin a chosnaíonn ar an dúbailt. An cás coitianta: tugann seachfhreastalaí 502 nó 504 agus an freastalaí fós ag obair, agus athsheolann do chliant an iarratas. Insíonn an ceanntásc Retry-After cé mhéad soicind ina dhiaidh is féidir é a athsheoladh.

An leigheas. Athsheol an t-iarratas céanna, mar atá, leis an eochair chéanna, tar éis na moille fógartha: gheobhaidh tú freagra na chéad iarrachta. Ná cruthaigh eochair nua choíche chun « an bac a bhaint » — chruthódh sin an dúbailt a chosnaíonn an eochair ina coinne.

Timpeallacht tástála: tá an cuóta sroichte

Tá teorainneacha seasta ag timpeallacht tástála: 200 taifead cliaint, 50 comhad agus 40 cáipéis in aghaidh an chomhaid. Diúltaítear do chruthú nó d'uaslódáil a sháródh aon cheann acu sula scríobhtar aon rud, agus insíonn an diúltú cé acu atá i gceist: iompraíonn na réimsí ressource, quota agus courant an acmhainn, an uasteorainn agus an líon ag am an diúltaithe. Má bhíonn dhá chruthú ag an am céanna in iomaíocht don áit dheireanach, ní théann ach ceann amháin tríd. Ní ídítear aon rud nuair a chuirtear taifead nó comhad atá ann cheana in eagar.

An leigheas. Ní féidir na cuótaí seo a chaibidil, agus ní thabharfaidh athsheoladh an iarratais ach an diúltú céanna. Athshocraigh an timpeallacht tástála ó do spás — tosaíonn sí arís ó na sonraí taispeántais — nó glac síntiús: ní bhaineann na cuótaí seo ach le timpeallachtaí tástála.

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.

Comhad dúnta: tá an caidreamh gnó thart

Dúnadh an caidreamh san fheidhmchlár: ní ghlacann an comhad le scríobh tríd an API a thuilleadh — gan eagarthóireacht, gan cáipéis, gan scagadh, gan úinéirí tairbhiúla. Fanann an léamh oscailte: is féidir comhad dúnta a léamh agus a easpórtáil ar feadh thréimhse iomlán na coinneála.

An leigheas. Is gníomh daonna, logáilte, san fheidhmchlár é an caidreamh a athoscailt; ní dhéanann an API é in áit an duine. Más oibríocht nua atá ann, oscail comhad nua in ionad an seancheann a athbheochan.

Comhad glanta: scriosadh na sonraí

Tá tréimhse na coinneála caite agus scriosadh sonraí an chomhaid. Ní fhanann ach an lorg iniúchta, a fhianaíonn go raibh comhad ann agus gur glanadh é ar an dáta luaite; ní ghlacann sé le scríobh ar bith a thuilleadh.

An leigheas. Níl aon rud le ceartú ná le hathsheoladh: tá an scriosadh cinntitheach agus d'aon ghnó. Aitheantóir comhaid ghlanta a choinnítear i do chórais, is stair é, agus ní sprioc scríofa go deo.

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.

Giuirléidí leabaithe nach bhfuil ar siúl ar an ásc seo

Braitheann an mint POST /api/v1/embed/jetons ar bhunúis dhearbhaithe do chomhlachta — is é an liosta sin a stiúrann CSP frame-ancestors an shell leabaithe. Deir an 501 seo nach bhfuil an stóras sin ag an ásc ar ghlaoigh tú air: tá an dromchla leabaithe díomhaoin ansin de bharr an dearaidh, agus deir sé sin seachas comhartha a eisiúint nach bhféadfadh aon bhunús é a thaispeáint riamh. Ná measc é seo leis an 400 a fhaigheann comhlacht nár dhearbhaigh a bhunúis fós.

An leigheas. Baineann an 501 seo leis an ásc, ní le d'iarratas. Ar vigilae.org, dearbhaíonn riarthóir do chomhlachta na bunúis é féin, ar an scáileán « Comhtháthuithe agus slándáil » (deir an bosca sa roinn giuirléidí cén áit); athsheinn ansin an glao céanna. Níl aon rud le ceartú i do chód: bhí an t-iarratas ceart, ní raibh an ásc réidh.

Dromchla nach bhfuil ar fáil ar an imscaradh seo

Braitheann dhá léamh bhunúsacha — GET /api/v1/dossiers/{id}/origine-fonds agus GET /api/v1/dossiers/{id}/exigences — ar stórais nach n-iompraíonn gach ásc. Nuair a bhíonn ceann acu ar iarraidh, deir an API é sin in ionad liosta folamh a sheirbheáil: is fíorais chontrártha iad « níl aon ní le tuairisciú » agus « níor léadh aon ní », agus dá gcuirfí trí chéile iad d'fhéadfaí comhad nár fhéach aon duine air a chur i láthair mar chomhad gan agús. Baineann an 501 seo leis an ásc ar glaodh air, riamh le d'iarratas ná leis an gcomhad.

An leigheas. Ná hathsheinn i lúb: ní athróidh aon ní go dtí go n-iompróidh an t-ásc an stóras sin. Caith leis an gcód mar « sonraí nach bhfuil ar fáil anseo », agus thar aon ní eile ná comhair mar nialas é i do phainéil — sin mar a dhéantar figiúr mícheart de thomhas atá in easnamh. Ar vigilae.org seirbheáiltear an dá léamh; ar imscaradh tiomnaithe, is faoi d'oibreoir atá uasghrádú an stórais.