# Comentarios de presupuesto

Lista y crea comentarios visibles para el cliente en un presupuesto con /external/v1/budgets/:budgetId/comments y los permisos crm:budgets:comments:*.

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)

| Endpoint | Permiso obligatorio |
| - | - |
| `GET /external/v1/budgets/:budgetId/comments` | `crm:budgets:comments:read` |
| `POST /external/v1/budgets/:budgetId/comments` | `crm:budgets:comments:write` |

Sin el permiso adecuado, los endpoints responden `403 INSUFFICIENT_SCOPE`
con el permiso que falta en
`requiredScopes`; lo concede un 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](https://os.utilia.ai/docs/developers/api/scopes).

## Endpoints

**`GET /api/external/v1/budgets/:budgetId/comments`**

Lista los comentarios CLIENT del presupuesto por orden cronológico. Permiso: crm:budgets:comments:read.

Parámetro de ruta: `budgetId`.

**`POST /api/external/v1/budgets/:budgetId/comments`**

Crea un comentario con visibilidad CLIENT. Las menciones se ignoran. Permiso: crm:budgets:comments:write.

Parámetro de ruta: `budgetId`.

## Parámetros principales

| Nombre | Tipo | Obligatorio | Descripción |
| - | - | - | - |
| `X-Api-Key` | `header` | Sí | Clave de API de la aplicación externa. |
| `budgetId` | `path` | Sí | Identificador del presupuesto. |
| `body` | `string` | Sí | Texto del comentario (máximo 5.000 caracteres). Es el nombre exacto del campo en el cuerpo JSON. |
| `visibility` | `string` | Sí | Solo admite CLIENT. Envíalo siempre: si lo omites, se toma INTERNAL, que la API externa rechaza con 403. |
| `visibility (listado)` | `query` | No | En GET se ignora: el listado externo devuelve siempre y solo los comentarios CLIENT. |

> **Atención: Envía siempre visibility CLIENT al crear**
>
> La API externa solo crea comentarios visibles para el cliente. Cualquier
> otra visibilidad se rechaza con `403`, y como el valor por defecto es
> `INTERNAL`, omitir el campo no equivale a pedir `CLIENT`.

## Ejemplos

### curl

```bash
# 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"}'
```

### Python

```python
import requests

resp = requests.post(
    'https://os.utilia.ai/api/external/v1/budgets/budget-uuid/comments',
    headers={'X-Api-Key': 'utl_xxx'},
    json={
        'body': 'Adjuntamos la revisión solicitada por el cliente.',
        'visibility': 'CLIENT',
    },
    timeout=30,
)
print(resp.json())
```

## 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](https://os.utilia.ai/docs/developers/api/budget-signatures).