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 lo anotamos ni lo corregimos: si algo del contrato está mal, se dice aquí abajo, pero el contrato se sirve tal cual.
Hay una sola excepción, y es de omisión, no de corrección. De lo que se renderiza se
suprime una declaración de seguridad que ninguna operación del contrato referencia y que
pertenece a un producto que este portal no cubre. El fichero versionado sigue siendo el oficial
intacto, y una comprobación automática falla el día que esa declaración deje de estar muerta —
es decir, el día que documente comportamiento de verdad. El detalle está en contrato/delta.md.
Ninguna otra cosa se toca. Cuando una descripción del contrato dice algo que no coincide con la plataforma, lo señalamos aquí abajo y dejamos la descripción como está.
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