Versiones y changelog
Esta página te dice cómo cambia la documentación y recoge las precisiones que te ahorran un rato: los sitios donde el contrato y la práctica no coinciden del todo, y con cuál quedarte.
Cómo se versiona
La documentación se apoya en dos fuentes:
- El contrato OpenAPI de cada API. La sección Referencia —endpoints, campos, códigos— se auto-genera desde ahí: cuando el contrato cambia, la Referencia cambia sola.
- El simulador, que implementa ese contrato de punta a punta. Las guías y el tutorial se verifican corriendo contra él, así que el código que lees es código que pasa.
Por eso no verás un número de versión de la documentación: el contenido vive con el contrato y con el simulador.
Historial del portal
| Fecha | Cambio |
|---|---|
| 2026-06 | Primera publicación: Empezar aquí, Productos (conceptos y guías), Recursos. |
| 2026-08 | Herramientas: simulador, consola y agente. Pasar a producción. Vídeos en las páginas de concepto. |
La referencia de API que ves aquí es el contrato oficial, sin retocar
La especificación que sirve la referencia navegable es copia literal de la que publica SPIDI, y una comprobación automática falla si se aparta de ella. No la anotamos ni la corregimos: si algo del contrato está mal, se dice aquí abajo y se reporta a SPIDI, pero el contrato se sirve como lo escribió su autor.
Esto importa para tres campos concretos, donde lo que recibes y lo que declara el contrato no coinciden. Los tres están comprobados contra el sandbox:
| Dónde | Qué dice el contrato | Qué pasa de verdad |
|---|---|---|
POST /agreements → data.status | pending · paid · failed · expired, descrito como estado de la sesión | Devuelve active. El contrato reusa por error el enum y la descripción de una sesión de pago; es el estado de un acuerdo |
POST /payment-sessions/buttons → data.config | No lo declara | Lo recibes. Objeto con configuración adicional de la sesión |
POST /payment-sessions/buttons → data.payment_qr | No lo declara | Lo recibes. El QR del payment_url, PNG en base64 como data-uri |
Qué hacer con esto al integrar: no valides status del acuerdo contra el enum del contrato
—no pasaría—, y no te sorprendan config ni payment_qr: llegan aunque no estén declarados, y
un cliente estricto que rechace campos desconocidos se romperá con ellos.
Reportado a SPIDI. Se retira de aquí en cuanto el contrato lo recoja.
Precisiones
Ninguna te frena: construyes contra el contrato y pruebas contra el simulador.
El nombre de los eventos
La clave que titula cada webhook en la OpenAPI es una etiqueta del documento y no viaja por el cable. Lo que llega a tu handler es el campo event del cuerpo: payment_session.paid y payment_session.accredited.
Guíate siempre por el event del payload. Un switch que compare contra la clave del contrato no entra nunca. → Webhooks
La ruta de login
La descripción del contrato trae una ruta distinta a la de la tabla de entornos. La buena es la de la tabla — /api/spidipagos/login para Productos. → Entornos y URLs
La URL de producción
El contrato declara la URL de sandbox. La de producción se te entrega junto con tus credenciales definitivas, al final de la certificación — no es un dato que se configure por tu cuenta. → Pasar a producción
Expirar una sesión a mano
El contrato declara la operación de expiración y el simulador la reproduce reflejándolo en el status. Si tu flujo depende de expirar sesiones programáticamente, compruébalo contra tu entorno antes de producción: es de las pocas cosas que pueden diferir entre el Botón y la Solicitud. → Estados y contrato de error