Crear presupuestos

Un presupuesto define cuánto pueden gastar sus miembros, en qué ciclo se renueva el monto y con qué restricciones (días, horarios, canal y categorías de comercio). Esta receta crea un presupuesto completo en cuatro pasos:

1. Elegir la compañía.
2. Crear el presupuesto con POST /budgets.
3. Agregar los miembros con su tope individual.
4. Configurar las restricciones.

Si tu API key tiene acceso a varias compañías, presta atención a los avisos de multi-compañía de cada paso (ver también Uso multi-compañía).

1. Elige la compañía

Cada presupuesto pertenece a una compañía, y no se puede cambiar después de crearlo. Obtén el uniqueCode de la compañía con GET /companies, o búscala por su identificación fiscal:

curl -X GET 'https://{HOST}/api/public/v1/companies?taxIdentificationValue=XAXX010101000' \
  -H 'X-API-KEY: tu_api_key_aqui'

Busca también a las personas que van a ser miembros (GET /people) y guarda su uniqueCode.

2. Crea el presupuesto

curl -X POST 'https://{HOST}/api/public/v1/budgets' \
  -H 'X-API-KEY: tu_api_key_aqui' \
  -H 'Content-Type: application/json' \
  -d '{
    "companyCode": "UNIQUE_CODE_DE_LA_COMPANIA",
    "name": "Viajes comerciales",
    "goal": 50000,
    "cycleType": "RECURRING",
    "startDate": "2026-11-01",
    "expirationDate": "2026-12-31",
    "externalId": "ERP-BUD-0042",
    "members": ["PERSONA_1", "PERSONA_2"]
  }'

La respuesta es el presupuesto creado, con su uniqueCode (guárdalo), su companyCode y membersCount. La API responde 200, no 201.

3. Agrega los miembros y sus topes

Los miembros de members se agregan sin tope individual. Para asignar un tope por persona, usa POST /budgets/{code}/members:

curl -X POST 'https://{HOST}/api/public/v1/budgets/UNIQUE_CODE_DEL_PRESUPUESTO/members' \
  -H 'X-API-KEY: tu_api_key_aqui' \
  -H 'Content-Type: application/json' \
  -d '[
    { "personCode": "PERSONA_3", "spendLimit": 10000 },
    { "personCode": "PERSONA_4" }
  ]'

• spendLimit omitido o 0: el miembro comparte el disponible del presupuesto sin tope propio.
• Es idempotente: si una persona ya es miembro, devuelve su membresía sin cambios y ignora el spendLimit enviado.
• Los personCode que la API no encuentra se omiten sin error. Compara la respuesta con lo que enviaste para detectar los que no se agregaron.

Para cambiar el tope o bloquear a un miembro existente, usa PATCH /budgets/{code}/members/{memberCode}. memberCode es el uniqueCode de la membresía, no el de la persona. Obtenlo con GET /budgets/{code}/members?personCode=PERSONA_1:

curl -X PATCH 'https://{HOST}/api/public/v1/budgets/UNIQUE_CODE_DEL_PRESUPUESTO/members/UNIQUE_CODE_DE_LA_MEMBRESIA' \
  -H 'X-API-KEY: tu_api_key_aqui' \
  -H 'Content-Type: application/json' \
  -d '[{ "op": "replace", "path": "/spendLimit", "value": 15000 }]'

Solo se admiten los paths /spendLimit y /status (ENABLED o BLOCKED). El tope no puede ser menor a lo que el miembro ya gastó.

4. Configura las restricciones

PUT /budgets/{code}/restrictions reemplaza por completo la configuración: lo que no envíes vuelve a su valor por defecto, y los indicadores booleanos omitidos quedan en false. Envía siempre la configuración completa:

curl -X PUT 'https://{HOST}/api/public/v1/budgets/UNIQUE_CODE_DEL_PRESUPUESTO/restrictions' \
  -H 'X-API-KEY: tu_api_key_aqui' \
  -H 'Content-Type: application/json' \
  -d '{
    "transactionLimit": 5000,
    "daysOfWeekList": [0, 1, 2, 3, 4],
    "startTime": "08:00",
    "endTime": "20:00",
    "onlinePurchaseEnabled": true,
    "physicalPurchaseEnabled": true,
    "localPurchaseEnabled": true,
    "internationalPurchaseEnabled": false,
    "restrictionMode": "INCLUDE",
    "merchantCategories": [{ "categoryUniqueCode": "CODIGO_DE_CATEGORIA" }]
  }'

Problemas frecuentes