Cómo funciona la API de Optifora
Esta página describe la forma de la API: cómo se demuestra la identidad, cómo avanzan las versiones, dentro de qué límites se mantiene una petición, qué aspecto tiene un error y cómo se intercambian datos con el exterior.
El producto está en desarrollo y la superficie de la API todavía se está completando. El documento de referencia de los puntos de conexión se publicará por separado; esta página no incluye ninguna dirección ni ninguna llamada de ejemplo, solo el funcionamiento.
Autenticación
Toda petición pertenece o a una persona o a una aplicación registrada. Una petición sin identidad que llegue a un punto de conexión protegido se devuelve como no autenticada.
- Token BearerEl token de acceso viaja en la cabecera de autorización de la petición. Va firmado y solo indica a quién pertenece la petición.
- Vida cortaUn token de acceso caduca al cabo de un periodo medido en minutos; su duración es un ajuste del despliegue y de forma predeterminada es de treinta minutos.
- Renovación y rotaciónLa sesión se prolonga con un token de renovación, y cada prolongación emite un par nuevo. Si un token de renovación ya gastado se presenta una segunda vez, se revocan todas las sesiones de esa persona.
- Los permisos no van incrustados en el tokenEl token solo lleva la identidad; lo que una persona puede ver se le pregunta a la base de datos en cada petición. Por eso un permiso retirado deja de funcionar antes de que caduque el token que se tiene en la mano.
- Clave del integradorUna aplicación registrada se conecta con su propia clave. El valor en claro se muestra una sola vez, al crearla; lo que se almacena es su resumen criptográfico y el prefijo no secreto que permite reconocer la clave.
- La organización concede el accesoPor muy extendida que esté una aplicación, sin una autorización registrada por la organización no ve ni una sola fila. La autorización tiene fecha, alcance definido y puede revocarse.
Versionado
- La versión va en la rutaLos puntos de conexión se publican tras un prefijo de versión; la superficie actual es la versión uno.
- Un cambio incompatible abre una ruta nuevaEl contrato de un punto de conexión existente no se rompe sobre la marcha. Un cambio incompatible se publica en una ruta de versión nueva mientras la anterior sigue funcionando.
- El documento declara su propia versiónLa referencia lleva el número de versión a partir del cual se generó; qué versión está leyendo lo responde el propio documento.
Entornos y límites
La referencia declara dos entornos: producción y desarrollo local. La dirección raíz se entrega al integrador junto con su clave; no se publica en esta página.
- La actividad y la disponibilidad se miden por separadoUn punto de conexión indica que el proceso está en marcha; el segundo envía una consulta real a la base de datos y confirma que es accesible. Solo el segundo decide si debe enviarse tráfico.
- Los orígenes del navegador se limitan a una listaLas peticiones de origen cruzado solo se aceptan desde orígenes declarados de antemano; mientras la lista esté vacía, se rechaza cualquier petición de origen cruzado hecha desde un navegador.
- Límite del cuerpoEl cuerpo de una petición no puede superar los cinco megabytes. Los conjuntos grandes viajan como una tarea de transferencia masiva con su propio registro de estado, no como una única petición.
- Los secretos no se escriben en el registroEl registro del servidor no guarda cabeceras de autorización, ni cookies, ni contraseñas, ni números de identidad.
Límite de peticiones
El límite es por dirección y por minuto. El valor predeterminado es de 120 peticiones por minuto y se fija en el despliegue. Lo que queda se informa mediante cabeceras en cada respuesta.
| Cabecera de respuesta | Qué indica |
|---|---|
| x-ratelimit-limit | La cuota total dentro de la ventana. |
| x-ratelimit-remaining | Lo que queda dentro de esta ventana. |
| x-ratelimit-reset | Segundos que faltan para que se renueve la cuota. |
| retry-after | Cuántos segundos deben pasar antes de reintentar. Solo está presente en la respuesta que rechazó la petición. |
Una vez superado el límite, la petición se rechaza y la respuesta indica cuántos segundos hay que esperar. El reintento se hace pasado ese tiempo, no de inmediato.
Formato de error
Todo error vuelve en el mismo sobre: un campo de código breve para que la máquina decida y un campo de explicación para que lo lea una persona.
- errorEl código breve sobre el que decide el cliente.
- messageLa explicación de lo ocurrido.
| Estado | Campo de código | Qué significa |
|---|---|---|
| 400 | Bad Request | La petición no se ajusta al esquema. La explicación indica el campo que falta o no es válido. |
| 401 | unauthenticated | No hay una identidad válida: no se envió token, ha caducado o no se pudo verificar. |
| 404 | Not Found | No existe ese punto de conexión, o no existe ese registro. |
| 429 | Too Many Requests | Se superó el límite de peticiones; la respuesta indica cuánto hay que esperar. |
| 5xx | internal_error | Un fallo inesperado. El detalle no se entrega al cliente; se escribe en el registro del servidor. |
Paginación
Los puntos de conexión que devuelven listas admiten los mismos dos parámetros y devuelven los mismos contadores, así que un cliente de paginación no se reescribe para cada punto de conexión.
- limitCuántos registros debe contener una página. Como mínimo uno y como máximo doscientos; cincuenta si no se indica.
- offsetCuántos registros hay que omitir. Empieza en cero.
- totalCuántos registros coinciden en total con los filtros.
- countCuántos registros lleva realmente esta respuesta.
La respuesta también devuelve el límite y el desplazamiento que ha utilizado; el cliente lee su posición en la respuesta en lugar de suponerla.
Intercambio de datos y webhooks
El modo de intercambio es un ajuste, no un producto aparte: cada aplicación registrada lleva en su propio registro el modo en el que trabaja.
| Modo | Qué significa |
|---|---|
| Unidireccional: hacia fuera | Optifora publica los datos; la otra parte los lee o se suscribe a los eventos. |
| Unidireccional: hacia dentro | La otra parte envía los datos; Optifora los valida y los escribe. |
| Bidireccional | Ambas partes escriben; la regla de conflicto se define de antemano. |
| Protocolo de enlace | Cada transferencia abre una sesión: propuesta, verificación, aprobación, transferencia y acuse. El acuse queda en poder de ambas partes. |
- Los eventos se envían hacia fueraUn webhook envía el evento a la dirección de retorno declarada por la aplicación registrada. Un evento que no se puede entregar permanece en cola y se reintenta; nunca se descarta en silencio.
- La misma petición no escribe dos vecesUna petición de escritura lleva una clave de idempotencia. Una segunda petición con la misma clave no crea un segundo registro.
- Cada llamada se mideQuién llamó, cuándo, con qué alcance y con qué resultado: todo queda registrado. El mismo registro responde tanto a la depuración como a la pregunta de quién extrajo estos datos.
- Nuestras propias aplicaciones entran por la misma puertaNo existe ninguna segunda vía privilegiada. Nuestra propia integración es la prueba de la superficie con la que se encuentra un desarrollador externo.
El modelo de datos de la capa de intercambio está listo; sus puntos de conexión aún no se han publicado. Cuando lo estén, esta sección enlazará con sus entradas en la referencia.
Documentos de referencia
La referencia no se escribe a mano; se genera a partir de los esquemas de los puntos de conexión. A medida que cada punto de conexión entrega su esquema, el documento se completa por sí solo, de modo que el documento y el comportamiento no pueden separarse.
- Hoy: en preparaciónLos esquemas avanzan módulo a módulo. Antes de que se publique el documento, en él estarán visibles la petición y la respuesta de cada punto de conexión.
- Se publicarán dos formatosUn documento OpenAPI legible por máquina y una página de referencia generada a partir de ese mismo documento y navegable desde el navegador.
- El acceso es por nivelesLa visión general está abierta a cualquiera. La referencia completa puede quedar tras un token de documentación entregado a un integrador registrado; las claves de producción y las direcciones de retorno no son en absoluto un asunto de documentación: pertenecen al registro de la aplicación.
- Estándar de direccionesSe publican dos referencias y sus direcciones son fijas: client-api.optifora.com/docs es abierta, admin-api.optifora.com/docs exige autorización y está cerrada al exterior. Hoy ninguna de las dos está activa; los enlaces se añadirán a esta sección en cuanto lo estén.
Si su plan de integración ya está claro, escríbanos desde la página de contacto: será de los primeros en saber cuándo se abre la superficie.
¿Tiene alguna petición concreta?
Estas páginas explican cómo funciona el proceso de soporte. Si tiene una petición o una duda, escríbanos desde la página de contacto.
Ir a la página de contacto