Com funciona l'API d'Optifora
Aquesta pàgina descriu la forma de l'API: com es demostra la identitat, com avancen les versions, dins de quins límits es manté una petició, quin aspecte té un error i com s'intercanvien les dades amb l'exterior.
El producte està en desenvolupament i la superfície de l'API encara s'està completant. El document de referència dels punts finals es publicarà a part; aquesta pàgina no conté cap adreça ni cap crida d'exemple, només la mecànica.
Autenticació
Cada petició pertany o bé a una persona o bé a una aplicació registrada. Una petició sense identitat que arriba a un punt final protegit torna com a no autenticada.
- Testimoni de portador (Bearer)El testimoni d'accés viatja a la capçalera d'autorització de la petició. Va signat i només indica a qui pertany la petició.
- Vida curtaUn testimoni d'accés caduca al cap d'un període mesurat en minuts; la durada és un paràmetre de desplegament i per defecte és de trenta minuts.
- Renovació i rotacióUna sessió s'allarga amb un testimoni de renovació, i cada allargament emet una parella nova. Si es presenta per segona vegada un testimoni de renovació ja consumit, es revoquen totes les sessions d'aquella persona.
- Els permisos no queden gravats dins del testimoniEl testimoni només porta la identitat; el que pot veure una persona es consulta a la base de dades a cada petició. Per això, un permís retirat deixa de funcionar abans que caduqui el testimoni que es té a la mà.
- Clau d'integradorUna aplicació registrada es connecta amb la seva pròpia clau. El valor en clar es mostra un sol cop, en crear-la; el que es desa és el seu resum i el prefix no secret que permet reconèixer la clau.
- L'organització concedeix l'accésPer molt estesa que sigui una aplicació, sense una concessió registrada per l'organització no veu ni una sola fila. La concessió té data, abast i es pot revocar.
Versionatge
- La versió viu dins del camíEls punts finals es publiquen darrere d'un prefix de versió; la superfície d'avui és la versió u.
- Un canvi trencador obre un camí nouEl contracte d'un punt final existent no es trenca sobre la marxa. Un canvi incompatible es publica en un camí de versió nou mentre l'antic continua funcionant.
- El document indica la seva pròpia versióLa referència porta el número de versió a partir del qual s'ha generat; quina versió esteu llegint us ho respon el document mateix.
Entorns i límits
La referència declara dos entorns: producció i desenvolupament local. L'adreça arrel es lliura a l'integrador juntament amb la seva clau; no es publica en aquesta pàgina.
- La vitalitat i la disponibilitat es mesuren per separatUn punt final diu que el procés està actiu; el segon envia una consulta real a la base de dades i confirma que és accessible. Només el segon decideix si cal enviar-hi trànsit.
- Els orígens de navegador es limiten a una llistaLes peticions d'origen creuat només s'accepten des dels orígens declarats per endavant; mentre la llista sigui buida, una petició de navegador d'origen creuat es rebutja.
- Límit del cosEl cos d'una petició no pot superar els cinc megabytes. Els conjunts grans viatgen com una tasca de transferència massiva amb el seu propi registre d'estat, no com una única petició.
- Els secrets no s'escriuen al registreEl registre del servidor no desa cap capçalera d'autorització, cap galeta, cap contrasenya ni cap número d'identificació nacional.
Límit de velocitat
El límit és per adreça i per minut. Per defecte són 120 peticions per minut i es fixa en el desplegament. El que queda s'informa amb capçaleres a cada resposta.
| Capçalera de resposta | Què indica |
|---|---|
| x-ratelimit-limit | L'assignació total dins de la finestra. |
| x-ratelimit-remaining | Què queda dins d'aquesta finestra. |
| x-ratelimit-reset | Segons que falten perquè es renovi l'assignació. |
| retry-after | Quants segons cal esperar abans de reintentar. Només apareix a la resposta que ha rebutjat la petició. |
Un cop superat el límit, la petició es rebutja i la resposta indica quants segons cal esperar. El reintent es fa passat aquest temps, no immediatament.
Format d'error
Tots els errors tornen dins el mateix sobre: un camp de codi curt perquè la màquina hi bifurqui, i un camp d'explicació perquè una persona el llegeixi.
- errorEl codi curt sobre el qual decideix el client.
- messageL'explicació del que ha passat.
| Estat | Camp de codi | Què significa |
|---|---|---|
| 400 | Bad Request | La petició no s'ajusta a l'esquema. L'explicació indica quin camp falta o no és vàlid. |
| 401 | unauthenticated | No hi ha cap identitat vàlida: no s'ha enviat cap testimoni, ha caducat o no s'ha pogut verificar. |
| 404 | Not Found | No existeix aquest punt final, o no existeix aquest registre. |
| 429 | Too Many Requests | S'ha superat el límit de velocitat; la resposta indica quant cal esperar. |
| 5xx | internal_error | Una fallada inesperada. El detall no s'entrega al client; s'escriu al registre del servidor. |
Paginació
Els punts finals que retornen llistes accepten els mateixos dos paràmetres i retornen els mateixos comptadors, de manera que un client de paginació no s'ha de reescriure per a cada punt final.
- limitQuants registres ha de contenir una pàgina. Com a mínim un, com a màxim dos-cents; cinquanta si no s'indica.
- offsetQuants registres cal saltar. Comença a zero.
- totalQuants registres coincideixen amb els filtres en total.
- countQuants registres porta realment aquesta resposta.
La resposta també repeteix el límit i el desplaçament que ha fet servir; el client llegeix la seva posició de la resposta en comptes d'endevinar-la.
Intercanvi de dades i webhooks
El mode d'intercanvi és un paràmetre, no pas un producte a part: cada aplicació registrada porta al seu propi registre el mode en què treballa.
| Mode | Què significa |
|---|---|
| Unidireccional — de sortida | Optifora publica les dades; l'altra banda les llegeix o se subscriu als esdeveniments. |
| Unidireccional — d'entrada | L'altra banda envia les dades; Optifora les valida i les escriu. |
| Bidireccional | Escriuen totes dues bandes; la regla de conflicte es defineix per endavant. |
| Encaixada de mans | Cada transferència obre una sessió: oferta, verificació, aprovació, transferència i rebut. El rebut queda a totes dues bandes. |
- Els esdeveniments s'envien cap enforaUn webhook envia l'esdeveniment a l'adreça de retorn que ha declarat l'aplicació registrada. Un esdeveniment que no es pot lliurar queda a la cua i es reintenta; mai no es descarta en silenci.
- La mateixa petició no escriu dues vegadesUna petició d'escriptura porta una clau d'idempotència. Una segona petició amb la mateixa clau no crea cap segon registre.
- Cada crida es mesuraQui ha trucat, quan, amb quin abast i amb quin resultat: tot queda registrat. El mateix registre respon tant a la depuració com a la pregunta de qui ha extret aquestes dades.
- Les nostres aplicacions passen per la mateixa portaNo existeix cap segon camí privilegiat. La nostra pròpia integració és la prova de la superfície que troba un desenvolupador extern.
El model de dades de la capa d'intercanvi ja hi és; els seus punts finals encara no s'han publicat. Quan ho estiguin, aquesta secció enllaçarà amb les seves entrades a la referència.
Documents de referència
La referència no s'escriu a mà; es genera a partir dels esquemes dels punts finals. A mesura que cada punt final lliura el seu esquema, el document s'omple sol, de manera que el document i el comportament no poden divergir.
- Avui: en preparacióEls esquemes avancen mòdul a mòdul. Abans de publicar el document, la petició i la resposta de cada punt final hi seran visibles.
- Es publicaran dos formatsUn document OpenAPI llegible per màquines, i una pàgina de referència generada a partir d'aquest mateix document i consultable al navegador.
- L'accés és per nivellsLa visió general és oberta a tothom. La referència completa pot quedar darrere d'un testimoni de documentació lliurat a un integrador registrat; les claus de producció i les adreces de retorn no són pas una qüestió de documentació — pertanyen al registre de l'aplicació.
- Estàndard d'adrecesEs publiquen dues referències i les seves adreces són fixes: client-api.optifora.com/docs és oberta, admin-api.optifora.com/docs requereix autorització i és tancada a l'exterior. Cap de les dues està activa avui; els enllaços s'afegiran a aquesta secció quan ho estiguin.
Si el vostre pla d'integració ja és clar, escriviu-nos des de la pàgina de contacte: sereu dels primers a saber quan s'obri la superfície.
Teniu alguna petició concreta?
Aquestes pàgines expliquen com funciona el procés de suport. Si teniu una petició o una pregunta, escriviu-nos des de la pàgina de contacte.
Vés al contacte