Saltar al contenido

Apartado 13 de 15 · Apps y canales

Embudo de ventas: oportunidades con importe

Crea, mueve, gana y pierde oportunidades de venta con importe, probabilidad y etapa desde la API de Chatendo: las rutas, los permisos, el tablero y los avisos.

Revisado el API 1.34.0 3 min de lectura

En esta página (2)
  1. 13.1 · Las rutas
  2. 13.2 · Lo que conviene saber

Con la app «Embudo de ventas» encendida en la cuenta, cada oportunidad lleva importe (en céntimos y con su moneda), probabilidad, fecha prevista de cierre, responsable y etiquetas, y se mueve por las mismas etapas que ya tienen tus chats. Con la app apagada, todas estas rutas contestan 403 APP_INACTIVE y no cambian nada. Encender la app no le escribe a nadie: lo único que sale son los avisos a los servidores que tú hayas dado de alta.

Permisos del token: opportunities:read (leer, tablero, historial, exportar) y opportunities:write (crear, editar, mover, ganar, perder, reabrir, borrar y los motivos de pérdida). Además, el rol de quien creó el token tiene que tener la clave embudo.* de cada ruta, y su alcance (propias, de su equipo o todas) recorta lo que ve: lo que no alcanza da 404, igual que lo que no existe.

13.1 · Las rutas

Ruta Para qué
GET /opportunities Lista paginada (page, per_page ≤ 100). Por defecto solo las abiertas (status=open; también won, lost, closed, all). Filtros: stage (o none), responsible_id (me, none o un id), tag_id, source, ad_id, contact_id, conversation_id, date_field + date_from / date_to, q. Orden sort (con - delante, al revés), siempre estable
POST /opportunities Alta. Obligatorios title y contact_id; conversation_id opcional (de ese contacto). Sin conversación, stage_key (por defecto la primera etapa); con conversación, la tarjeta sigue la etapa del chat
GET /opportunities/{id} La ficha, con payments: lo cobrado y lo pendiente de sus enlaces de pago, por moneda
PATCH /opportunities/{id} Editar título, importe (null lo vacía, nunca 0), moneda, probabilidad, fecha prevista, responsable, temperatura, procedencia y etiquetas. Con version, si alguien la cambió antes: 409 VERSION_CONFLICT. Si la oportunidad tiene líneas del catálogo, el importe lo calculan ellas: uno distinto da 422 AMOUNT_MANAGED_BY_LINES
POST /opportunities/{id}/move Mover de etapa: to_stage, el from_stage que viste y la version. Si otro la movió entre medias: 409 STAGE_CONFLICT con cómo está ahora
POST /opportunities/{id}/win Ganar: final_amount_cents y won_on obligatorios (422 WIN_DATA_REQUIRED si falta alguno)
POST /opportunities/{id}/lose Perder: loss_reason_id obligatorio (422 LOSS_REASON_REQUIRED) y note opcional
POST /opportunities/{id}/reopen Reabrir una ganada, perdida o cerrada. Queda en el historial
GET /opportunities/{id}/history Todo lo que le ha pasado: alta, movimientos (también los del chat), ganada, perdida, reabierta; quién y cuándo
GET /opportunity-board El tablero: una columna por etapa con su recuento, sus totales por moneda (importe y ponderado por probabilidad) y sus primeras tarjetas; y las columnas de ganadas y perdidas. Más tarjetas: /opportunity-board/stages/{etapa} o /lanes/{won\|lost\|unstaged}
GET /opportunities/export CSV (;, UTF-8 con BOM) con los mismos filtros que la lista. Más de 20 000 filas: 422 EXPORT_TOO_LARGE
GET\|POST /opportunity-loss-reasons · PATCH\|DELETE /{id} Los motivos de pérdida de tu cuenta (máximo 50). Uno que usa alguna oportunidad no se borra: 409 LOSS_REASON_IN_USE, se archiva
Terminal
# Alta sin conversación
curl -X POST https://TU-DOMINIO/api/v1/opportunities \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Idempotency-Key: alta-oportunidad-0001" \
  -d '{"title":"Renovación anual","contact_id":4120,"stage_key":"cualificado","amount_cents":240000,"expected_close_on":"2026-11-15"}'

# Moverla (version y from_stage, los que te devolvió el alta)
curl -X POST https://TU-DOMINIO/api/v1/opportunities/7702/move \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{"to_stage":"propuesta","from_stage":"cualificado","version":1}'

# Ganarla
curl -X POST https://TU-DOMINIO/api/v1/opportunities/7702/win \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{"final_amount_cents":235000,"won_on":"2026-10-18"}'

13.2 · Lo que conviene saber

  • El dinero no se convierte nunca. Céntimos enteros y moneda ISO de tres letras; los totales van siempre por moneda.
  • Una oportunidad ligada a un chat está en la etapa del chat. Moverla mueve el chat (con sus avisos y automatizaciones, igual que moverlo en la bandeja) y lo mueve quien puede moverlo en la bandeja (403 STAGE_FORBIDDEN si no). Si el chat ya tiene una oportunidad abierta, el alta da 409 OPEN_OPPORTUNITY_EXISTS.
  • La probabilidad es la de la oportunidad o, si no tiene, la de su etapa. El ponderado es importe × probabilidad / 100.
  • Un enlace de pago creado con oportunidad_id (POST /contacts/{id}/enlaces-de-pago) queda ligado a esa oportunidad.
  • Los avisos opportunity.created, opportunity.stage_changed, opportunity.won y opportunity.lost usan el sobre de siempre (§5) y solo salen con la app encendida. won trae el importe final y la fecha; lost, el motivo.
  • Parámetro o campo que la ruta no conoce: 422 (UNKNOWN_QUERY_PARAM, UNKNOWN_BODY_FIELD). Errores siempre {message, code}.
Escríbenos por WhatsApp Te contesta nuestro agente de IA al momento