# Cotizaciones por API y MCP

> Lee cotizaciones, arma un borrador para una unidad con las reglas de su esquema de venta y envíalo al cliente en dos pasos —vista previa y confirmación— desde la API REST o el servidor MCP.

Source: https://docs.watsi.ai/guides/quotes-api

Las acciones del [Cotizador](/quotes/overview) están en la API REST y en el servidor MCP. Un agente de IA o tu integración puede **leer** cotizaciones, **armar un borrador** para una unidad y **prepararlo para enviar**; el envío al cliente siempre pasa por **una confirmación** de la misma persona que lo pidió.

> **Note**

El Cotizador es para espacios de trabajo inmobiliarios. Si tu espacio de trabajo no lo tiene activado, todas estas acciones responden `403`.

## Las acciones

| Herramienta MCP            | Ruta REST                                     | Alcance             | Qué hace                                                                  |
| -------------------------- | --------------------------------------------- | ------------------- | ------------------------------------------------------------------------- |
| `list_quotes`              | `GET quotes/list`                             | `quotes:read`       | Cotizaciones, filtradas por estado, contacto, unidad, desarrollo o asesor |
| `get_quote`                | `GET quotes/get`                              | `quotes:read`       | Una cotización: totales, calendario de pagos, unidad y estado             |
| `list_quotable_properties` | `GET quotes/quotable-properties`              | `quotes:read`       | Unidades disponibles para cotizar                                         |
| `get_quoting_setup`        | `GET quotes/setup`                            | `quotes:read`       | Esquemas de venta y sus reglas, formas de pago, lo que falta configurar   |
| `create_quote_draft`       | `POST quotes/drafts`                          | `quotes:write`      | Crea un borrador para una unidad                                          |
| `update_quote_draft`       | `POST quotes/drafts/update`                   | `quotes:write`      | Cambia un borrador                                                        |
| —                          | `POST quotes/status`                          | `quotes:write`      | Cancela una cotización (sólo REST)                                        |
| `send_quote`               | `POST quotes/send`                            | `quote_sends:write` | Vista previa del envío y un `confirmToken`. **No envía nada**             |
| `confirm_quote_send`       | `POST quotes/send/confirm`                    | `quote_sends:write` | Envía la cotización con ese `confirmToken`                                |

Las rutas REST van bajo `https://api.watsi.ai/v1/actions/`. Escribir necesita una clave o sesión **de un miembro**: una cotización pertenece a su asesor, así que sólo su asesor la edita y la envía. Los alcances de escritura no aparecen en la pantalla de claves; pídelos a watsi, o márcalos en la pantalla de consentimiento si te conectas por OAuth.

## Arma un borrador

1. `get_quoting_setup` te dice qué esquemas de venta hay, con su descuento máximo y su precio mínimo por m², y qué falta configurar.
2. `list_quotable_properties` te da las unidades disponibles.
3. `create_quote_draft` con la unidad, y opcionalmente el contacto, el esquema y un descuento. watsi arma la línea, el calendario de pagos y los totales: tú pides por intención, nunca mandas cifras.

Si el descuento pasa el tope del esquema o el precio queda bajo su mínimo, la llamada responde `422` con **cada** regla rota en `details.violations` (`COTIZADOR_DISCOUNT_OVER_CAP`, `COTIZADOR_PRICE_BELOW_FLOOR`…) y no guarda nada.

## Envía en dos pasos

Enviar llega al cliente, así que una persona lo confirma:

### Prepara el envío

`send_quote` con `quoteId`, el canal (`whatsapp`, `email` o `link`) y, si quieres, un mensaje. Responde la vista previa —folio, contacto, total, calendario de pagos, mensaje— y un `confirmToken` válido por **10 minutos**. No cambia nada.

```json
{
  "preview": {
    "quoteId": "5b0c…",
    "folio": "COT-0012",
    "status": "draft",
    "channel": "whatsapp",
    "contactName": "Ana López",
    "currency": "MXN",
    "total": 2450000,
    "schedule": [{ "date": "2026-11-15", "concept": "Enganche", "amount": 245000 }],
    "message": "Hola Ana, aquí está tu cotización."
  },
  "confirmToken": "eyJ2Ijox…",
  "expiresAt": "2026-10-31T18:40:00.000Z"
}
```

### Muéstralo y pide confirmación

Enséñale la vista previa a la persona. Un agente de IA nunca debe confirmar por su cuenta.

### Confirma

`confirm_quote_send` con el mismo `quoteId` y el `confirmToken`. Es el mismo envío que el botón **Enviar** del editor: revisa las reglas del esquema, congela la copia que recibe el cliente y, si la entrega falla, deja la cotización como estaba.

El token sólo sirve para lo que la persona vio:

| Respuesta                                | Por qué                                                                      |
| ---------------------------------------- | ---------------------------------------------------------------------------- |
| `409 QUOTE_SEND_CONFIRMATION_EXPIRED`    | Pasaron más de 10 minutos. Prepara el envío otra vez.                        |
| `409 QUOTE_SEND_CONFIRMATION_STALE`      | La cotización cambió (o ya se envió) desde la vista previa.                  |
| `403 QUOTE_SEND_CONFIRMATION_INVALID`    | El token es de otro miembro, de otro espacio de trabajo o de otra cotización. |
| `422 COTIZADOR_START_DATE_LOCKED`        | El plan de pagos empieza antes de hoy. Pon sus fechas al día en el editor y envíala desde ahí. |

El canal y el mensaje viajan dentro del token, así que la confirmación no los puede cambiar. Un token ya usado deja de servir, porque el envío cambia la cotización.

> **Warning**

Si la [ventana de 24 horas de WhatsApp](/chats/templates-24h-window) ya cerró, el envío por WhatsApp necesita una plantilla de cotización aprobada por Meta, igual que en el editor.

## Relacionado

- [Cotizador](/quotes/overview)
- [Servidor MCP](/mcp)
- [Autenticación y alcances](/guides/authentication)