Setup: autenticación y entornos
Antes de recibir pagos necesitas tres cosas: tus credenciales, un token para autenticarte, y saber contra qué entorno apuntas.
Lo que recibes al darte de alta
Tu alta la hace el equipo de SPIDI y te llega por tu canal de soporte. Comprueba que tienes las cinco cosas antes de empezar a integrar — la que más tarde se echa de menos es la última, y se echa de menos justo cuando ya llevas medio día montado.
| Lo que recibes | Para qué lo vas a necesitar |
|---|---|
| Usuario | Iniciar sesión. Es tu alias, no tu correo — y va en short_name |
| Contraseña | Iniciar sesión. Cámbiala antes de nada |
| UUID de tu cuenta bancaria | Va en default_bank_account_id de tus acuerdos. No hay forma de consultarlo después: guárdalo |
| URL de tu tablero | Ver tus operaciones fuera del API |
| Secreto de webhooks | Verificar la firma de cada aviso que recibas → Manejar notificaciones |
Especialmente el secreto de webhooks: sin él no puedes verificar la firma, y eso no lo descubres hasta que ya tienes tu receptor montado y no entiendes por qué no valida. Pídelo por el mismo canal por el que te dieron el resto.
Al pasar a producción recibes otro juego completo —las credenciales de pruebas no sirven— más la URL base de producción. → Pasar a producción
Autenticación
La API Productos usa Bearer token. Lo obtienes al iniciar sesión:
curl -X POST https://sandbox.api.spidipagos.com/api/spidipagos/login \
-H "Content-Type: application/json" \
-d '{"short_name":"<TU_USUARIO>","password":"<TU_CLAVE>"}'
La respuesta trae token. Envíalo en cada llamada:
Authorization: Bearer <token>
El token dura poco, y es a propósito: no construyas tu integración sobre un token que esperes conservar. → Límites y reglas de operación
Refresca sin volver a iniciar sesión
La respuesta del login trae también un refreshToken, que vive mucho más. Con él pides una pareja nueva sin volver a mandar usuario y contraseña:
curl -X POST https://sim-productos.abiertolab.com/api/spidipagos/refresh-token -H "Content-Type: application/json" -d '{"refreshToken":"<tu-refresh-token>"}'
Devuelve un token nuevo y un refreshToken nuevo. Guarda los dos: el refresh rota en cada uso, así que el siguiente refresco necesita el último que recibiste, no el original.
No esperes a que falle. Si tu token está cerca de caducar, refréscalo antes de la llamada; y si aun así te llega un 401, refresca una vez y reintenta. Volver a hacer login con usuario y contraseña queda como último recurso.
El simulador hosteado te da una cuenta de prueba con su token al registrarte, en diez segundos y sin login real. Trabajas en tu propio espacio aislado.
Esa cuenta es solo del simulador: no te da acceso al sandbox ni a producción.
Entornos
| Entorno | URL base (Productos) | Para qué |
|---|---|---|
| Simulador | https://sim-productos.abiertolab.com | Aprender y probar sin dinero real, sin credenciales |
| Sandbox | https://sandbox.api.spidipagos.com | Probar contra el entorno real, con tus credenciales de prueba |
| Producción | La recibes con tus credenciales definitivas | Pagos reales |
Lo único que cambia entre entornos es la configuración. Si tienes que tocar código para cambiar de uno a otro, tienes algo incrustado que no debería estarlo — y eso se nota en la certificación.
Siguiente paso
Con tu token listo → Recibe tu primer pago.