Introducción

La API de Integración Uvicuo permite que tu ERP cree, en Uvicuo, presupuestos (budgets) y planes de gasto (spending plans) de forma programática, sin entrar a la aplicación web.

• Formato: JSON sobre HTTPS.
• Autenticación: una API key (X-API-Key) que Uvicuo te entrega. Ver Autenticación.
• Versión actual: v1.

URL base

Entorno	URL base	Uso
Preproducción	https://api.sandbox.partner.uvicuo.com	Pruebas e integración
Producción	https://api.partner.uvicuo.com	Operación real

Todos los paths de los ejemplos son relativos a la URL base. Por ejemplo: POST {URL_base}/v1/budgets.

Flujo recomendado

1. Crea un presupuesto con POST /v1/budgets y guarda su id.
2. Crea un plan de gasto con POST /v1/spending-plans referenciando ese budget_id y el empleado correspondiente.

Límites de uso (rate limit)

• 60 solicitudes por minuto por cliente (ventana fija).
• Al excederlo, la API responde 429 rate_limited con la cabecera Retry-After (segundos a esperar antes de reintentar).

Trazabilidad de solicitudes

• Cada respuesta incluye la cabecera x-request-id y, en los errores, el campo requestId.
• Puedes enviar tu propio x-request-id en la solicitud y lo devolvemos tal cual.
• Úsalo para correlacionar tus logs con los nuestros al reportar una incidencia.

Notas de integración

• Idempotencia: la API no deduplica solicitudes; evita reintentar un POST que ya respondió 2xx. Ante errores 5xx o de red, es seguro reintentar (con backoff).
• Montos: envía cantidades con punto decimal (10000.00) y la moneda como código ISO de 3 letras.
• Soporte: al reportar un problema, incluye el requestId de la respuesta.