Saltar al contenido principal

​
¿Qué es la API de integraciones?

La API de integraciones es un servicio HTTP que permite a sistemas externos (ERP, automatizaciones, scripts) leer y, según los permisos del token, actualizar datos de una empresa concreta: empresa, cuentas bancarias, transacciones, categorías y adjuntos. Cada solicitud lleva un token de API emitido desde la aplicación Unisaldos. El token determina la empresa y un conjunto fijo de permisos (scopes). Si falta un permiso necesario para una ruta, la API responde con error 403 e indica el permiso requerido (required_scope).

​
URLs públicas

RecursoURL
Aplicación (panel y tokens de integración)https://app.unisaldos.com/
API de integraciones (base para rutas /v1/...)https://api.unisaldos.com/
Documentación (este sitio en producción)https://docs.unisaldos.com/
En detalle y con ejemplos curl, véase Inicio rápido — URL base.

​
Flujo general

En la práctica solo hay tres actores: Unisaldos (donde se crea el token), tu integración (donde guardas el token de API de forma segura y desde donde lanzas las peticiones HTTP) y la API de integraciones (expone /v1/...).
1

Crear el token en Unisaldos

Un usuario con permisos de API abre la gestión de claves en app.unisaldos.com, elige una etiqueta opcional y marca los permisos que necesita la integración. Al guardar, la app muestra el token en texto plano una sola vez: cópialo a un gestor de secretos o variable de entorno protegida; no se puede recuperar después.
2

Configurar tu sistema integrador

​
URL base del cliente

Configura tu cliente HTTP con la URL base del servicio de integraciones. En producción suele ser https://api.unisaldos.com; otras URLs y el detalle están en Inicio rápido — URL base.
No uses app.unisaldos.com (panel y tokens) como host de las llamadas a la API: ese dominio no sirve como base de /v1/....

​
Autenticación en cada petición

Incluye siempre esta cabecera:
Authorization: Bearer <tu_token>

​
Errores frecuentes y reintentos

En producción conviene registrar fallos y usar reintentos acotados (por ejemplo, backoff exponencial). Contexto rápido:
  • 401 — La API rechaza el token (mal copiado, caducado o revocado). No reintentes con el mismo valor sin corregirlo.
  • 403 — El token es válido pero falta un permiso para ese endpoint. La respuesta incluye required_scope con el identificador que necesitas en el token.
  • 422 — La petición no supera la validación del esquema (cuerpo JSON, parámetros de consulta o ruta). El cuerpo de error detalla qué campo o valor falló; corrige la petición según la Referencia de API antes de reintentar.
3

Llamar a los endpoints `/v1`

La API valida el token, resuelve la empresa asociada y solo devuelve o modifica datos de esa empresa. La lista exacta de rutas y cuerpos está en la pestaña Referencia de API (contrato OpenAPI interactivo); los identificadores de permiso por ruta siguen el prefijo integrations:v1:.

​
Próximos pasos

Inicio rápido

Primera petición, URL base y gestión de tokens.

Permisos

Tabla integrations:v1: y relación con el error 403.

Búsqueda y paginación

Filtros, página, ordenación y texto de búsqueda en listas.

Archivos adjuntos

Subida multipart y permisos en transacciones.

Referencia OpenAPI

Cómo usar la pestaña de referencia con el contrato publicado.