API de tratos

Un trato es una oportunidad de venta en su tablero de Sales Pipeline: 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)
Errores y paginación — consulta Errores y paginación

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

{
  "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 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

curl "https://api.youraiconnector.com/v1/deals?apiKey=YOUR_API_KEY&stage=stage-2&limit=50"

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

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)

{ "success": true, "deals": [{ "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." }], "next_cursor": null }

Obtener un trato

GET /deals/{dealId}

curl "https://api.youraiconnector.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY"

Respuesta (200)

{ "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.

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)

{ "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.

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.

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.

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.

curl "https://api.youraiconnector.com/v1/pipelines?apiKey=YOUR_API_KEY"

Respuesta (200):

{
  "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").

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 — cómo funcionan las etapas, las etiquetas de etapa, varios embudos y el tablero.
API de tareas — las tareas pueden vincularse a un trato con deal_id.
Automatizaciones — los pasos Buscar tratos y Buscar trato leen los mismos datos dentro de un flujo de trabajo.

API de tratos #

El objeto de trato #

Listar tratos #

Obtener un trato #

Crear un trato #

Actualizar un trato #

Mover un trato a otra etapa #

Eliminar un trato #

Pipelines #

Listar pipelines #

Crear un pipeline #

Actualizar un pipeline #

Eliminar un pipeline #

Próximos pasos #