Stable Pro API · v1
Autenticación y permisos
Claves, entornos, permisos, límites de solicitudes.
Las claves
Cada solicitud lleva una clave en la cabecera Authorization:
Authorization: Bearer sp_live_7Kq2…
Una clave es sp_live_ (producción) o sp_test_ (staging) seguido de 40 letras y dígitos. La cuadra viene de la clave: nunca pasas el id de una cuadra, y una clave lee una sola cuadra.
Las claves las crea el titular de la cuadra en Stable Pro, en Ajustes → Conexiones. Una conexión es tu programa; con el tiempo puede tener más de una clave. El titular ve de cada clave los últimos cuatro caracteres, su último uso y el número de solicitudes, y puede revocarla cuando quiera.
- Una clave se muestra una sola vez, cuando se crea. Stable Pro solo guarda una huella: si se pierde, el titular crea una nueva.
- Rotación: cuando el titular crea una clave nueva para la conexión, la anterior sigue funcionando 7 días y después deja de funcionar. Sustitúyela en tu programa dentro de ese plazo.
- Caducidad: el titular puede dar a una clave una fecha de caducidad (90 días, un año o ninguna).
- Una clave
sp_test_se rechaza en producción, y unasp_live_en staging (401,reason: wrong_environment).
Cuando una clave no es válida, la respuesta es 401 con WWW-Authenticate: Bearer y un reason: missing, malformed, wrong_environment, unknown, connection_revoked, revoked, expired, rotated.
GET /connection devuelve la conexión de la clave que llama: su nombre, sus permisos y la propia clave (nunca el secreto).
Los permisos
El titular elige qué puede leer la conexión:
| Permiso | Abre |
|---|---|
charges:read | cargos y correcciones, el saldo de los clientes |
payments:read | cobros y reembolsos, asignaciones, movimientos del crédito |
receipts:read | los recibos de Stable Pro y su PDF |
customers:read | los clientes: código, tipo, nombre, si siguen activos |
customers.fiscal:read | los datos de facturación de los clientes: dirección estructurada, identificadores fiscales, código fiscal; y los datos fiscales de quien pagó por cuenta de un cliente |
Una solicitud sin el permiso de su endpoint responde 403 con type: …/forbidden y missing_permission. Sin customers.fiscal:read los datos de facturación no aparecen en la respuesta, no valen null: no están en absoluto, objetos anidados incluidos. Cada lectura de los datos de facturación se cuenta aparte en el registro de solicitudes de la cuadra.
/connection, /organization, /codes y /events no necesitan un permiso concreto. Cada evento se muestra solo con el permiso del objeto al que apunta (consulta Eventos).
El área Contabilidad
La API forma parte del área Contabilidad del plan de la cuadra. Si la cuadra no la tiene, cada solicitud responde 403 con type: …/accounting-disabled.
Límites de solicitudes
| Límite | Valor | Al superarlo |
|---|---|---|
| por clave | 60 solicitudes por minuto | 429, Retry-After: 60 |
| por cuadra | 10.000 solicitudes al día | 429, Retry-After: 86400 |
Si el propio limitador no está disponible, la API responde 503 con Retry-After: 30: nunca deja pasar una solicitud sin comprobarla.
Solo lectura
La versión 1 lee. No puede crear, cambiar ni borrar nada en Stable Pro. Devolver a Stable Pro los documentos que emite tu programa (número, estado, qué hechos cubren) es la próxima fase de la API.