Comentarios de presupuesto

Con /external/v1/budgets/:budgetId/comments tu aplicación lista y crea comentarios de un presupuesto con visibilidad CLIENT: los mismos que ve el cliente en el portal. Las notas internas de tu equipo nunca salen por esta vía.

Autenticación y plan

Todas las peticiones llevan la clave de API de la aplicación:

X-Api-Key: <api_key_de_la_app>

El plan de tu organización tiene que incluir el aplicativo CRM; si no, la respuesta es 403 MODULE_NOT_ENABLED.

Permisos de la API (scopes)

Sin el permiso adecuado, los endpoints responden 403 INSUFFICIENT_SCOPE con un mensaje genérico que pide hablar con el administrador de la organización. El permiso se exige desde la primera llamada, sin periodo de gracia. El catálogo completo y las reglas de concesión están en Permisos de la API.

Endpoints

Parámetros principales

X-Api-Keyheaderobligatorio

Clave de API de la aplicación externa.

budgetIdpathobligatorio

Identificador del presupuesto.

bodystringobligatorio

Texto del comentario (máximo 5.000 caracteres). Es el nombre exacto del campo en el cuerpo JSON.

visibilitystringobligatorio

Solo admite CLIENT. Envíalo siempre: si lo omites, se toma INTERNAL, que la API externa rechaza con 403.

visibility (listado)query

En GET se ignora: el listado externo devuelve siempre y solo los comentarios CLIENT.

Ejemplos

# Listar comentarios CLIENT del presupuesto
curl -X GET 'https://os.utilia.ai/api/external/v1/budgets/budget-uuid/comments' \
  -H 'X-Api-Key: utl_xxx'
 
# Crear un comentario
curl -X POST 'https://os.utilia.ai/api/external/v1/budgets/budget-uuid/comments' \
  -H 'X-Api-Key: utl_xxx' \
  -H 'Content-Type: application/json' \
  -d '{"body": "Adjuntamos la revisión solicitada por el cliente.", "visibility": "CLIENT"}'

Errores

• 400: el cuerpo no pasa la validación (body ausente o demasiado largo).
• 401: falta la clave de API o no es válida.
• 403 MODULE_NOT_ENABLED: el plan de tu organización no incluye el CRM.
• 403 INSUFFICIENT_SCOPE: la aplicación no tiene concedido el permiso necesario.
• 403: se intentó crear un comentario con una visibilidad distinta de CLIENT.
• 404: el presupuesto no existe o es de otra organización (mensaje «Presupuesto no encontrado»). Llega como respuesta estándar (statusCode, message, error), sin errorCode: distíngelo por el código HTTP.

Seguimiento de peticiones

Envía X-Request-Id en cada petición para poder cruzarla con los registros de UTILIA OS. Si no lo envías, la respuesta trae el que se haya generado.

Siguiente paso

Tras añadir un comentario, puedes consultar el estado de las firmas del presupuesto con los endpoints de firmas de presupuesto.