# API de tratos Un trato es una oportunidad de venta en su tablero de [Sales Pipeline](../deals/sales-pipeline.md): un título, un valor, la etapa en la que se encuentra y, opcionalmente, el contacto al que pertenece y el miembro del equipo al que está asignado. Esta guía cubre la lectura y gestión de tratos a través de la API. - **URL base** — `https://api.youraiconnector.com/v1` - **Autenticación** — tu clave de API (consulta [Autenticación](authentication.md)) - **Errores y paginación** — consulta [Errores y paginación](errors-and-pagination.md) Todos los ejemplos a continuación muestran la forma de consulta `?apiKey=` en cURL y el encabezado `X-API-Key` en JavaScript y Python; cualquiera de los dos funciona en todos los endpoints. --- ## El objeto de trato ```json { "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "description": "Asked for pricing on the annual plan.", "company": "Jane's Clinic", "notes": "Prefers a call after 5pm.", "stage": "stage-2", "pipeline_id": "default", "value": 4800, "probability": 60, "priority": "high", "status": "open", "source": "whatsapp", "position": 0, "contact_id": "ctc_9f8e7d", "assigned_to": "usr_4a2b", "tags": ["clinic"], "close_date": "2026-10-01T00:00:00.000Z", "created_at": "2026-09-05T09:12:00.000Z", "updated_at": "2026-09-05T09:40:00.000Z", "stage_entered_at": "2026-09-05T09:40:00.000Z" } ``` `stage` es el id de una de las etapas de su pipeline; léalas con `GET /pipelines` (vea [Pipelines](#pipelines) a continuación). Los ids de etapa son únicos en todos sus pipelines, por lo que `pipeline_id` se deriva de la etapa y es de solo lectura: `default` es su pipeline principal, y es `null` cuando la etapa ya no existe. Las marcas de tiempo están en formato ISO 8601. Un trato solo almacena los campos mostrados arriba. Cuando creas o actualizas uno, cualquier otro campo es rechazado con un `400` que lo nombra, por lo que nada de lo que envíes se pierde silenciosamente. Mantén los datos adicionales en los campos personalizados del contacto vinculado. --- ## Listar tratos `GET /deals` — devuelve los tratos de su cuenta, empezando por el más reciente. **Parámetros de consulta** (todos opcionales): `stage` (un id de etapa), `pipeline_id` (solo los tratos en ese pipeline), `contact_id`, `limit` (predeterminado 50, máx 200), `cursor` (de la `next_cursor` de la página anterior). **cURL** ```bash curl "https://api.youraiconnector.com/v1/deals?apiKey=YOUR_API_KEY&stage=stage-2&limit=50" ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/deals?stage=stage-2&limit=50", { headers: { "X-API-Key": "YOUR_API_KEY" }, }); const { deals, next_cursor } = await res.json(); ``` **Python** ```python res = requests.get( "https://api.youraiconnector.com/v1/deals", headers={"X-API-Key": "YOUR_API_KEY"}, params={"stage": "stage-2", "limit": 50}, ) deals = res.json()["deals"] ``` **Respuesta** (`200`) ```json { "success": true, "deals": [{ "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." }], "next_cursor": null } ``` --- ## Obtener un trato `GET /deals/{dealId}` ```bash curl "https://api.youraiconnector.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY" ``` **Respuesta** (`200`) ```json { "success": true, "deal": { "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." } } ``` Un trato que no existe, o que pertenece a otra cuenta, devuelve `404`. --- ## Crear un trato `POST /deals` — `title` y `stage` son obligatorios; `stage` debe ser uno de los ids de etapa de su pipeline. ```bash curl -X POST "https://api.youraiconnector.com/v1/deals?apiKey=YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "title": "Annual plan – Jane'"'"'s Clinic", "stage": "stage-1", "value": 4800, "contact_id": "ctc_9f8e7d" }' ``` **Respuesta** (`201`) ```json { "success": true, "deal_id": "deal_abc123" } ``` --- ## Actualizar un trato `PUT /deals/{dealId}` — envía solo los campos que deseas cambiar (`title`, `description`, `notes`, `value`, `stage`, `status`, `priority`, `contact_id`, …). `value` debe ser un número. ```bash curl -X PUT "https://api.youraiconnector.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "value": 5200, "priority": "high" }' ``` **Respuesta** (`200`): `{ "success": true, "deal_id": "deal_abc123" }` --- ## Mover un trato a otra etapa `POST /deals/{dealId}/move` — cuerpo `{ "new_stage_id": "stage-3", "new_position": 0 }`. La posición `0` coloca la tarjeta en la parte superior de la columna. ```bash curl -X POST "https://api.youraiconnector.com/v1/deals/deal_abc123/move?apiKey=YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "new_stage_id": "stage-3", "new_position": 0 }' ``` **Respuesta** (`200`): `{ "success": true, "deal_id": "deal_abc123", "stage": "stage-3", "position": 0 }` --- ## Eliminar un trato `DELETE /deals/{dealId}` — elimina el trato. **Esto no se puede deshacer.** ```bash curl -X DELETE "https://api.youraiconnector.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY" ``` **Respuesta** (`200`): `{ "success": true }` --- ## Pipelines Cada cuenta tiene un pipeline principal (`id: "default"`); puede añadir hasta nueve más, cada uno con sus propias etapas. Los ids de etapa y las etiquetas de activación deben ser únicos en todos los pipelines de la cuenta, y cada pipeline puede marcar una etapa como su `won` y otra como su resultado `lost`. ### Listar pipelines `GET /pipelines` — todos los pipelines, primero el principal, cada uno con sus etapas ordenadas por posición. ```bash curl "https://api.youraiconnector.com/v1/pipelines?apiKey=YOUR_API_KEY" ``` **Respuesta** (`200`): ```json { "success": true, "data": { "pipelines": [ { "id": "default", "name": "Sales", "position": 0, "is_default": true, "settings": { "sync_stage_tags": false }, "stages": [ { "id": "stage-1", "name": "New lead", "color": "#3B82F6", "position": 0, "trigger_tag": null }, { "id": "won", "name": "Won", "color": "#10B981", "position": 1, "outcome": "won" } ] } ] } } ``` ### Crear un pipeline `POST /pipelines` — cuerpo `{ "id"?, "name", "stages"?, "settings"? }`. Deje `id` vacío para que se genere uno. Cada etapa utiliza los mismos campos que el cuadro de diálogo Etapas: `id`, `name`, `color`, `position`, `trigger_tag` opcional (una ruta de etiqueta, `users/{uid}/tags/{tagId}`), `default_value`, `auto_move_after_days` + `auto_move_to_stage` (una etapa del mismo pipeline) y `outcome` (`"won"` o `"lost"`). ```bash curl -X POST "https://api.youraiconnector.com/v1/pipelines?apiKey=YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "id": "reviews", "name": "Review requests", "stages": [ { "id": "rv_asked", "name": "Asked", "color": "#3B82F6", "position": 0 }, { "id": "rv_done", "name": "Review posted", "color": "#10B981", "position": 1, "outcome": "won" } ] }' ``` **Respuesta** (`201`): `{ "success": true, "data": { "pipeline": { ... } } }`. Un id de etapa o etiqueta de activación ya utilizado por otro pipeline es un `400` que nombra ese pipeline; un id que ya existe es un `409`. ### Actualizar un pipeline `PUT /pipelines/{pipelineId}` — cuerpo `{ "name"?, "stages"?, "settings"? }`. `stages` reemplaza toda la lista, como en el cuadro de diálogo Etapas. Use `default` para el pipeline principal. El id del pipeline en sí no puede cambiarse. ### Eliminar un pipeline `DELETE /pipelines/{pipelineId}` — elimina un pipeline adicional (el principal no puede eliminarse). Si todavía hay tratos en sus etapas, la llamada responde `409` con `deal_count`; añada `?delete_deals=true` para eliminar esos tratos junto con el pipeline. **Esto no se puede deshacer.** **Respuesta** (`204`). --- ## Próximos pasos - [Embudo de ventas](../deals/sales-pipeline.md) — cómo funcionan las etapas, las etiquetas de etapa, varios embudos y el tablero. - [API de tareas](tasks.md) — las tareas pueden vincularse a un trato con `deal_id`. - [Automatizaciones](../automations/automations.md) — los pasos **Buscar tratos** y **Buscar trato** leen los mismos datos dentro de un flujo de trabajo.