API de tareas y funciones Task and function API

Guía para integradores (ES/EN) de la API de tareas de RouterClip: conecta tu herramienta de tareas (Jira, Asana, ClickUp, Linear, Monday, Trello, Notion…) para leer, modificar y ejecutar el trabajo pendiente de todas las funcionalidades con una clave de servidor. Estado: disponible. Es parte de la API v1: lo común (fuentes, claves, formato de errores, X-Request-ID, eventos y contactos) está en /developers/api-v1.html.

• Contrato OpenAPI (generado de las rutas reales, una etiqueta por área, con ejemplos): https://www.routerclip.com/developers/api-v1.json.
• Catálogo estático de tipos y acciones (lo mismo que GET /api/v1/task-kinds con todos los permisos, más las rutas de recurso de cada acción y el catálogo de scopes): https://www.routerclip.com/developers/api-v1-task-kinds.json.
• Documentación publicada / Published documentation: esta guía, la de la API v1, el contrato y el catálogo están en https://www.routerclip.com/developers/, enlazados desde el panel de la API de tareas (Integraciones → API y eventos) y desde el pie de la web pública. / This guide, the API v1 guide, the contract and the catalog are published at /developers/, linked from the task API panel and the public site footer.

Español

1. Activación

1. El equipo de RouterClip activa para tu empresa la función «API de tareas y funciones» (api.tasks). Sin ella, todas las rutas de esta guía responden 403 FEATURE_DISABLED. Algunas áreas necesitan además su propia función (secuencias crm.sequences, guiones crm.playbooks, duplicados crm.merge, conversiones marketing.tracking…): sin ella sus tipos desaparecen del feed y sus rutas responden 403 FEATURE_DISABLED.
2. Si vas a usar webhooks, pide también que la plataforma autorice el origen HTTPS de tu herramienta (por ejemplo, https://hooks.example.com). El envío de webhooks de tareas tiene además un interruptor global; mientras está apagado, las entregas esperan en cola hasta 30 días: si se activa antes, salen; si no, caducan como fallidas (Expired: not sent within 30 days) y, con el envío activado, se pueden reintentar a mano (POST …/deliveries/{id}/retry). Los 30 días cuentan desde que la entrega entró en la cola, desde su último intento o desde el último reintento manual: un reintento empieza una serie nueva de intentos con su propio plazo, aunque el primero vuelva a fallar.
3. Un administrador crea una fuente por herramienta en Ajustes → Integraciones → API y eventos (por ejemplo, «Jira Soporte»), elige un paquete de scopes (§2) y, en «Actuar como», los usuarios que la herramienta puede representar (§3).
4. Emite la clave de la fuente (aio_<keyId>.<secreto>, se ve una sola vez; dos claves activas para rotar sin cortes) y, si quiere, registra el webhook de tareas (§9). Comprueba la clave con GET /api/v1/key y lo que puede hacer con GET /api/v1/key/capabilities (áreas y tipos visibles, funciones activas, usuarios delegables y usuario por defecto).

Todas las peticiones llevan Authorization: Bearer aio_<keyId>.<secreto> y Content-Type: application/json. Es una API de servidor a servidor: sin CORS; la clave nunca va en un navegador, en una URL ni en un log. Comprobaciones de cada petición, en orden: clave y fuente, empresa activa (401), acceso al servicio (402), función (403), cuotas (429) y scopes (403).

2. Scopes y paquetes

Los scopes tienen la forma <área>:<nivel>. Los niveles no se heredan (execute no incluye write ni read):

Paquetes de la pantalla de administración: Lectura de tareas (*:read de las áreas activas y team:read), Gestión de tareas (lo anterior más activities:write/execute, deals:write/execute, support:write/execute, playbooks:write/execute, csat:execute, voice:execute, calendar:execute y act_as), Operación completa (más los *:admin de las áreas activas y webhooks:manage) y Personalizado. Los scopes *:admin, *:content, team:emails y act_as son sensibles y piden confirmación expresa.

Reglas: el feed solo muestra los tipos de las áreas que la clave puede leer (en webhooks, webhooks:manage cuenta como lectura); el PATCH exige <área>:write y, si cambia el estado, también el nivel de la acción equivalente; cada acción exige el scope que declara el catálogo. Ningún scope equivale a un administrador completo.

3. Actor y delegación

Una clave no es un usuario. Cada acción declara qué actor admite:

• La petición elige el usuario con X-AIO-Act-As: <userId>; sin cabecera actúa el usuario por defecto de la fuente, si lo hay. La clave necesita el scope act_as.
• Errores: 403 DELEGATED_USER_REQUIRED (la acción necesita un delegado), 403 DELEGATED_USER_NOT_ALLOWED (usuario fuera de la lista o clave sin act_as), 403 DELEGATED_USER_INACTIVE (inactivo o de otra empresa, mismo mensaje), 403 ACTOR_ROLE_INSUFFICIENT (su rol no alcanza el de la ruta de la UI), 403 MAILBOX_OWNER_REQUIRED y 403 MENTION_RECIPIENT_REQUIRED.
• El permiso efectivo es la intersección de los scopes de la clave, el rol del delegado y las condiciones de titular o destinatario. La delegación no crea sesión y solo sirve en /api/v1.
• Lista de la fuente: hasta 20 usuarios activos (administradores o agentes) y un usuario por defecto opcional; cada cambio guarda autor y fecha. Para mapear responsables, GET /api/v1/members (team:read; el email solo con team:emails).

4. Modelo de tarea

Una tarea es una proyección de su entidad de origen (actividad, ticket, campaña…), no una copia: no hay tabla de tareas, y responsable, fecha, prioridad y notas solo se editan donde la entidad los tiene. El identificador es <kind>:<clave> (hasta 200 caracteres A-Z a-z 0-9 . _ : -, va en la ruta sin codificar), por ejemplo support.ticket:9d2f… o crm.duplicate_review:contact:<idMenor>:<idMayor>.

{ "id": "support.ticket:9d2f4b1c0a7e4e21b3c5d6e7f8091a2b", "kind": "support.ticket", "area": "support", "schemaVersion": 1,
  "title": "No llega la factura de septiembre", "status": "waiting", "sourceStatus": "waiting_customer",
  "signals": ["sla_resolution_at_risk"], "priority": "high", "assignee": { "type": "user", "id": "3c1f…", "name": "Ana Ruiz" },
  "dueAt": "2026-09-30T16:00:00Z", "dueKind": "sla_resolution", "links": [ { "type": "contact", "id": "77aa…", "name": "Lucía Gómez" } ],
  "appUrl": "https://www.routerclip.com/app/tickets/9d2f…", "version": 18, "etag": "W/\"h:3fa9c2d17b0e4a55\"",
  "editable": ["status", "sourceStatus", "assigneeId", "teamId", "priority", "title", "category"],
  "actions": [ { "name": "resolve", "scope": "support:execute", "actor": "service", "available": true, "preview": false } ],
  "externalLink": { "externalId": "SUP-431", "url": "https://jira.example.com/browse/SUP-431" } }

• status normalizado: open, in_progress, waiting, needs_review, done o cancelled; sourceStatus conserva el estado nativo y signals añade marcas de un catálogo cerrado (overdue, due_soon, unassigned, sla_resolution_breached, uncertain, reconnect_required…). Ignora los valores que no conozcas.
• dueAt va con dueKind (due, sla_resolution, wake, send_at, undo_until…); fechas en RFC 3339 y UTC.
• etag: W/"<n>" en las entidades con revisión y W/"h:<16 hex>" (hash del estado escribible, calculado en vivo) en el resto. Es la precondición de escritura (§7).
• actions: cada acción con su scope, actor, available y, si no lo está, unavailableReason (STATE, DELEGATED_USER_REQUIRED, MAILBOX_OWNER_REQUIRED, SCOPE_MISSING, FEATURE_DISABLED, SEND_SWITCH_OFF, ACTOR_ROLE_INSUFFICIENT, MENTION_RECIPIENT_REQUIRED), calculada con la clave y el delegado de esta petición.
• Contenido y datos personales: title nunca es un cuerpo; los textos de clientes y notas exigen <área>:content; un contacto enlazado solo lleva los campos de lectura de la fuente, y mostrar alguno cuenta como una lectura del contacto en el registro de lecturas (una por clave, contacto y petición; /developers/api-v1.html §8), igual en el feed, los tickets, las conversaciones, las llamadas y las reservas. Nada personal viaja en la URL: búsquedas y lookups van por POST.

Tipos (28; el detalle de estados, campos de PATCH y acciones está en el catálogo estático):

Sin acción de cierre, cerrar la tarea exige una decisión: muestra sus acciones en la herramienta en vez de un simple «hecho».

5. Endpoints

• Flujos de automatización (automation:read; función automation.flows): estado, tipo de disparador y versión en uso, nunca la configuración (definición, borrador, condiciones, nombres ni detalles de los pasos). Las ejecuciones (más recientes primero, filtros status y subjectId, cursor firmado de 24 h) dan su estado, paso, códigos, el hecho que las inició (triggerEventId, un id del feed de eventos) y, en la ficha, cada paso con su tipo, estado, resultCode y el registro que creó (effect). Iniciar (automation:enroll): POST …/flows/{flowId}/enroll con {"subject": {"type": "contact" | "deal" | "conversation", "id": "…"}} e Idempotency-Key obligatoria (428); solo flujos publicados con disparador «Por la API» (409 FLOW_NOT_PUBLISHED / FLOW_TRIGGER_NOT_API) y del tipo de sujeto del flujo (422 SUBJECT_TYPE_MISMATCH). Decide en la petición con las comprobaciones de entrada del flujo: 201 {"result": "started", "runId"} o 200 {"result": "skipped", "reason"} con flowNotActive, subjectUnavailable, conditionsNotMet, activeRunExists, alreadyRan, cooldown o entryLimitReached. La misma clave y cuerpo repiten la respuesta (Idempotent-Replayed: true); otro cuerpo, 409 IDEMPOTENCY_CONFLICT. started no es «hecho»: los pasos los ejecuta el motor con todas sus comprobaciones y un flujo nunca escribe al cliente por su cuenta. Cuenta en la cuota de acciones y queda en «Actividad de la API». automation:enroll no es automations:enroll (recorridos).
• Listado GET /api/v1/tasks: filtros kind y area (listas de hasta 10), status (por defecto los abiertos), assigneeId, assignee=me (el delegado), unassigned=true, teamId, dueBefore, dueAfter, overdue=true, signal, priority, contactId, dealId, ticketId, conversationId y updatedSince; sort (dueAt, -updatedAt, -priority, createdAt); limit de 1 a 100 (50) y cursor opaco y firmado, ligado a la empresa, la fuente, los filtros y el orden (sort), válido 24 h (400 CURSOR_INVALID); lo acepta cualquier clave de la misma fuente, también la nueva tras una rotación. Responde {items, nextCursor, hasMore, indexedThrough}: los filtros van sobre un índice que va segundos por detrás y cada tarea se hidrata en vivo.
• Detalle GET /api/v1/tasks/{taskId} con la cabecera ETag. Una tarea de otra empresa, inexistente o que ya no es tarea responde igual: 404 TASK_NOT_FOUND.
• PATCH con If-Match obligatorio y cuerpo estricto (title, description, status, sourceStatus, priority, dueAt, assigneeId, teamId, category, activityKind, contactId, dealId, ticketId): 422 FIELD_NOT_ALLOWED si el campo no existe, 422 TASK_FIELD_NOT_SUPPORTED (con supportedFields) si el tipo no lo admite, 422 TASK_PATCH_SPLIT_REQUIRED si exigiría dos llamadas internas y 422 TASK_STATUS_REQUIRES_ACTION (con actions) para los estados que solo se alcanzan con una acción.
• Alta POST /api/v1/tasks: solo crm.activity (un seguimiento ligado a contacto, oportunidad o ticket), con Idempotency-Key obligatoria y externalLink opcional. Responde 201 con Location y ETag.
• Notas (support.ticket y sales.conversation): leerlas exige <área>:content; añadirlas, <área>:write y un delegado (text ≤ 5.000, mentionUserIds?). Historial sin cuerpos en crm.activity, crm.deal_attention, support.ticket y crm.playbook_session.
• Enlace externo PUT …/external-link con {externalId, url} (un enlace por fuente y tarea; url HTTPS) y lookup POST /api/v1/tasks/lookup con {externalId} en el cuerpo: la tarea que tu fuente enlazó.
• Recursos: cada uno con listado por cursor, ficha con ETag, If-Match en sus PATCH, Idempotency-Key en sus altas y las mismas acciones que sus tareas en POST /api/v1/<recurso>/{id}/actions/{action} (la referencia de acciones da la ruta de cada una). Sin DELETE de datos: solo se retiran vínculos y webhooks propios.

6. Acciones y dryRun

POST /api/v1/tasks/support.ticket:9d2f…/actions/resolve
Authorization: Bearer aio_<keyId>.<secreto>
Idempotency-Key: jira-SUP-431-transition-51
If-Match: W/"h:3fa9c2d17b0e4a55"          (opcional)
X-AIO-Act-As: 3c1f…                         (si la acción lo exige)
Content-Type: application/json

{ "input": {}, "dryRun": false }

• La acción llama a la misma función que la ruta de la UI, con sus validaciones, bloqueos y permisos. Tras las comprobaciones de cada petición (§1), el orden es:

  1. El tipo de la taskId y la acción existen (404 TASK_NOT_FOUND / TASK_ACTION_NOT_FOUND; en la ruta del recurso, RESOURCE_NOT_FOUND / ACTION_NOT_FOUND).
  2. Función y scope (403 FEATURE_DISABLED / API_SCOPE_REQUIRED).
  3. Formato de If-Match (422 IF_MATCH_INVALID) y del cuerpo (415 sin Content-Type: application/json, 422).
  4. Actor (403).
  5. Sin dryRun: Idempotency-Key (428 IDEMPOTENCY_KEY_REQUIRED; 422 si no es válida) y su recibo. Un replay (Idempotent-Replayed: true) o un 409 IDEMPOTENCY_* / ACTION_OUTCOME_UNKNOWN responden antes de mirar la tarea: un reintento con la misma clave recibe la misma respuesta aunque la tarea ya se haya cerrado o ya no exista.
  6. La tarea existe y es de tu empresa (404 TASK_NOT_FOUND; en el recurso, RESOURCE_NOT_FOUND).
  7. If-Match si viene (412 REVISION_CONFLICT).
  8. Disponibilidad en el estado actual (409 TASK_ACTION_NOT_AVAILABLE con reason, o 409 SEND_SWITCH_OFF; los motivos de persona, como MAILBOX_OWNER_REQUIRED, responden 403).
  9. input (422).
  10. Cuota (429, también con dryRun).
  11. Ejecución.

  Por eso una tarea inexistente con una clave sin el scope responde 403, no 404.

• input sigue el inputSchema de la acción en el catálogo. Un error de la función interna conserva su estado y su código (MERGED_RECORD, ACTIVITY_CHANGE_VETOED, OUTBOUND_UNCERTAIN…); uno sin código llega como ACTION_REJECTED.
• Respuesta 200 con outcome: "succeeded" si el efecto está aplicado o 202 con outcome: "accepted" si la función solo encola (reintentos de envío, refresco de conocimiento, envío de CSAT); result es mínimo (IDs, recuentos, tokens) y task trae el estado y el ETag nuevos.
• dryRun: true no escribe nada, no exige Idempotency-Key y no consume idempotencia (sí cuenta en la cuota). Si la acción tiene un paso previo nativo, lo ejecuta y devuelve su token en confirm; la ejecución lo exige:

En el resto, dryRun solo valida todas las precondiciones y responde {dryRun: true, valid: true, effects: […]}: nunca se ejecuta para deshacer después.

• Envíos inciertos: las acciones que podrían duplicar un envío (review_* con retry, voice.job.retry, review_notification) exigen confirmPossibleDuplicate: true, como la UI. Si el interruptor global de envío está apagado: 409 SEND_SWITCH_OFF.

7. Idempotencia

• If-Match es obligatorio en todo PATCH (428 PRECONDITION_REQUIRED sin él; 412 REVISION_CONFLICT con currentEtag y la cabecera ETag si no es el actual) y opcional en las acciones (si viene, se comprueba igual). Ante un 412: lee la tarea, fusiona y reintenta con el ETag nuevo.
• Idempotency-Key (1-200 caracteres A-Z a-z 0-9 . _ : ~ -, empezando por letra o dígito) es obligatoria en las altas y en las acciones salvo con dryRun (428 IDEMPOTENCY_KEY_REQUIRED). Su ámbito es la fuente y dura 7 días. Usa el ID del evento de tu herramienta (transición, comentario, entrada del changelog).

Repetir una nota (POST …/notes) con la misma clave devuelve la misma nota: se vuelve a leer con su texto y, si ya no se puede leer, llegan su ID, autor, menciones y fecha (las ejecuciones nunca guardan cuerpos).

Todas las escrituras y acciones quedan auditadas 90 días (fuente, clave, delegado, tarea, acción, resultado y X-Request-ID, sin cuerpos); los administradores las ven en Integraciones → API y eventos → API de tareas → Actividad de la API. La misma actividad incluye las altas, vinculaciones y cambios de contactos, las invitaciones de doble opt-in, las inscripciones en recorridos, los inicios de flujos por la API («Inicio de flujo por la API» / «Flujo no iniciado», operación enroll sobre automation_flow) y los cambios en los webhooks de tareas hechos con claves de la fuente, y sus rechazos (403, 404, 409, 412).

8. Feed de cambios

cursor0 = GET /api/v1/task-changes/cursor          → {"cursor": "c1.…"}   (antes de la carga inicial)
for page in GET /api/v1/tasks?kind=support.ticket,crm.activity:
    upsert_in_tool(page.items)                     (guarda etag y version de cada tarea)
cursor = cursor0
loop (al recibir un webhook o cada 2 minutos):
    changes = GET /api/v1/task-changes?cursor=<cursor>&limit=500
    for c in changes.items:                        {taskId, kind, change: upsert|deleted, status, version, changedAt}
        if c.version <= known_version(c.taskId): continue
        if c.change == "deleted": archive_in_tool(c.taskId)
        else: upsert_in_tool(GET /api/v1/tasks/{c.taskId})
    cursor = changes.nextCursor                    (persístelo después de aplicar)
    si 410 CURSOR_EXPIRED: vuelve a empezar desde cursor0

• Entrega al menos una vez y sin huecos para un cursor válido; una tarea puede reaparecer si vuelve a cambiar. Las tareas que la clave no puede ver no salen, pero el cursor avanza.
• Las tareas cerradas o desaparecidas se conservan como lápidas 30 días; un cursor más antiguo responde 410 CURSOR_EXPIRED y obliga a resincronizar.
• GET /api/v1/task-summary devuelve recuentos por tipo, estado y responsable con los filtros del listado, para cuadros de mando.

9. Webhooks

• Alta con webhooks:manage: POST /api/v1/webhooks con {name, url, kinds?, events?, skipOwnChanges?, enabled?}. url es HTTPS en el puerto 443 dentro de un origen autorizado por la plataforma; kinds vacío significa todos los que la clave puede leer; events entre task.created, task.updated, task.completed y task.deleted. Límites: 5 por fuente y 20 por empresa. La respuesta trae el secreto whsec_… una sola vez (también POST …/rotate-secret); los listados y fichas nunca lo muestran.
• Payload mínimo, sin títulos, nombres ni cuerpos: {id, type, schemaVersion, occurredAt, data: {taskId, kind, status, previousStatus, version, changedFields, causedBy, cursor, url}}. El webhook solo despierta la lectura: pide el detalle con tu clave o lee el feed desde data.cursor.
• Cabeceras: X-CRM-Signature: sha256=HMAC(secreto, "<timestamp>.<nonce>.<cuerpo>"), X-CRM-Timestamp, X-CRM-Attempt (el nonce), X-CRM-Delivery-Id (igual en cada intento e Idempotency-Key) y X-CRM-Event-Id.
• Reintentos: hasta 8 intentos con espera creciente; un 4xx distinto de 429 es fallo definitivo y un 410 desactiva el endpoint. POST …/test envía un ping; GET …/deliveries y POST …/deliveries/{id}/retry permiten revisar y reintentar.
• Reparto: cada endpoint recibe una petición a la vez y las empresas se turnan, así que un receptor lento no retrasa a los demás. Tras 5 intentos fallidos seguidos el endpoint espera 5 minutos (el doble cada vez, hasta una hora) sin gastar intentos, tampoco las entregas que ya estaban en el mismo lote, y después se prueba con una sola entrega; una respuesta 2xx, una URL nueva, reactivarlo, un reintento manual o un ping de prueba (POST …/test, que además adelanta un ping pendiente que esperaba su reintento) lo liberan. El webhook informa de ello en failureStreak (intentos fallidos seguidos) y deferredUntil (hasta cuándo espera; null si no espera), y la pantalla de administración lo explica. Si el resolutor DNS de la plataforma está ocupado no se envía nada: la entrega recupera su intento, se reintenta a los 30 segundos y no cuenta como fallo del endpoint.

Verificar la firma (Python):

import hashlib
import hmac
import time


def verify(secret: str, headers: dict, raw_body: bytes) -> bool:
    timestamp, nonce = headers["X-CRM-Timestamp"], headers["X-CRM-Attempt"]
    if abs(time.time() - int(timestamp)) > 300:  # ventana anti-replay de 5 minutos
        return False
    signed = timestamp.encode() + b"." + nonce.encode() + b"." + raw_body
    expected = "sha256=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, headers["X-CRM-Signature"])

Verifica sobre el cuerpo crudo, deduplica por X-CRM-Delivery-Id, descarta lo que llegue con version menor o igual que la que ya conoces (no hay orden garantizado) y responde 2xx en menos de 10 s.

10. Errores

Formato de la API v1: {"detail": {"code", "message", "requestId", "field?"}}. El código es estable; el mensaje puede cambiar.

11. Cuotas

12. Recetas

Patrón común: una fuente y una clave por herramienta; cursor del feed fijado antes de la carga inicial; un webhook de tareas con skipOwnChanges que despierta la sincronización; externalLink en cada tarea creada en la herramienta; y la acción de cierre (completion) del tipo cuando la herramienta marca algo como hecho. Guarda version y etag de cada tarea.

12.1 Jira

• Proyectos: uno por área (Soporte con kind=support.ticket,support.customer_message; Comercial con crm.activity,crm.deal_attention,sales.enrollment; Marketing; Operación). Crea las incidencias con la carga inicial y guarda el id de RouterClip en una propiedad «RouterClip Task ID»; enlázalas con PUT …/external-link ({"externalId": "SUP-431", "url": "https://jira.example.com/browse/SUP-431"}).
• Estados: open → To Do, in_progress → In Progress, waiting → Waiting, needs_review → Needs review, done → Done, cancelled → Won't do.
• De Jira a RouterClip: una automatización de Jira (webhook saliente a tu servicio) en la transición a Done llama a la acción completion del tipo con Idempotency-Key: jira-<issue>-changelog-<id>; el cambio de assignee o de fecha de vencimiento es un PATCH con If-Match; un comentario público de un agente es reply con X-AIO-Act-As del agente.
• De RouterClip a Jira: el webhook despierta tu servicio, que lee el feed y actualiza la incidencia. Para buscar la tarea de una incidencia: POST /api/v1/tasks/lookup con {"externalId": "SUP-431"}.

12.2 Asana

• Proyecto por área con secciones por status; el id de RouterClip en un campo personalizado y external-link a la tarea de Asana.
• Completar en Asana (completed: true) → acción completion (complete en crm.activity, resolve en support.ticket). Las tareas sin completion se crean con una regla o botón que llama a la acción con dryRun primero.
• Los webhooks de Asana llegan a tu servicio; usa su resource.gid + created_at como Idempotency-Key.

12.3 ClickUp

• Lista por área; los estados de ClickUp se mapean 1:1 con los seis normalizados. El id en un campo personalizado.
• Un cambio de estado en ClickUp a «closed» → acción completion; a «in review» no hace nada en RouterClip (es estado de la herramienta). El cambio de assignee → PATCH assigneeId en los tipos que lo editan (editable).
• Las automatizaciones de ClickUp pueden llamar a tu servicio, que añade Idempotency-Key: clickup-<task>-<history_item_id>.

12.4 Linear

• Equipo o proyecto por área; los estados del flujo se mapean con status (Backlog/Todo ← open, In Progress ← in_progress, Done ← done, Canceled ← cancelled).
• El webhook de Linear (Issue con updatedFrom) dispara en tu servicio el PATCH o la acción; usa el webhookId + updatedAt como clave de idempotencia.
• Prioridad: urgent/high/normal/low ↔ Urgent/High/Medium/Low.

12.5 Monday

• Tablero por área con una columna de estado (los seis normalizados), una de persona (mapeada con GET /api/v1/members) y una de fecha (dueAt).
• Una automatización «cuando el estado cambie a Hecho» llama a tu servicio, que ejecuta la acción completion; los botones de Monday pueden lanzar acciones concretas (assign, snooze, schedule) con dryRun primero cuando tienen paso previo.

12.6 Trello

• Tablero por área y una lista por status (To do, En curso, Esperando, Revisar, Hecho). La tarjeta guarda el id de RouterClip en su descripción o en un campo personalizado y external-link apunta a la tarjeta.
• Mover una tarjeta a «Hecho» → acción completion; a otra lista no cambia nada en RouterClip si el tipo no admite ese estado por PATCH (422 TASK_STATUS_REQUIRES_ACTION indica qué acciones lo consiguen).
• Los webhooks de Trello (action.id) dan la Idempotency-Key.

12.7 Notion

• Base de datos por área con propiedades RouterClip ID, Estado (select con los seis valores), Responsable, Vence y Enlace (appUrl). Si tu integración de Notion no recibe eventos de cambios, sondea su API cada pocos minutos; del lado de RouterClip, el webhook de tareas o GET /api/v1/task-changes bastan.
• Cambiar Estado a «Hecho» en Notion → acción completion con Idempotency-Key: notion-<pageId>-<last_edited_time>.

13. Cómo evitar bucles

• Deja skipOwnChanges activado (por defecto): un endpoint no recibe los cambios causados solo por su propia fuente (causedBy: {kind: "api", sourceId}).
• Envía a RouterClip solo los cambios que hizo una persona en la herramienta, nunca los que escribió tu propia sincronización (marca en la herramienta qué cambios hizo el integrador).
• Usa como Idempotency-Key el ID del evento de la herramienta: si el mismo evento llega dos veces, RouterClip devuelve la misma respuesta (replayed: true) sin ejecutar nada.
• Compara version antes de aplicar y descarta lo antiguo; el webhook solo despierta, el estado se lee del feed o del detalle.
• Ante un 412 o un 409, lee y fusiona: lo que RouterClip gestiona (SLA, envíos, fusiones, recorridos) manda.

14. Qué no se expone

Ningún DELETE de datos (solo se retiran vínculos y webhooks propios); escritura de consentimientos y preferencias; importaciones y exportaciones; borrado o exportación de la empresa; configuración (pipelines, campos, SLA, equipos, reglas, macros, etiquetas, política CSAT, ajustes de voz, calendarios, bases jurídicas, widget); autoría de recorridos, secuencias, guiones, formularios y colocaciones, y envíos de prueba; credenciales y canales (cuentas, conexiones, OAuth, Meta, WAHA, buzones, Stripe); enlaces portadores (portal de tickets, encuestas CSAT, /meet, baja); audio de llamadas y subida de adjuntos; llamadas salientes y funciones de IA; seguridad, invitaciones, contraseñas, facturación, funciones, plataforma y administración de claves; correcciones de resultados comerciales. Ampliar esta lista exige una decisión nueva; la prueba de cobertura comprueba que ninguna de esas rutas existe bajo /api/v1.

Referencia de acciones · Action reference

Cada acción del registro con su scope, su actor y un ejemplo: la ruta de la tarea (/api/v1/tasks/<kind>:<clave>/actions/<acción>) o, si no tiene tipo, la de su recurso. Las de una tarea se ejecutan igual por su recurso (la columna «paths» del catálogo estático da todas las rutas). (admin): exige un delegado administrador; dryRun → …: el token que devuelve el paso previo y que la ejecución exige; 202: solo encola. Every action of the registry with its scope, actor and an example: the task route or, without a kind, the resource route; actions of a task also run through their resource (the paths of the static catalog list every route).

Oportunidades · Deals

Actividades y seguimientos · Activities and follow-ups

Secuencias comerciales · Sales sequences

Guiones comerciales · Sales playbooks

Duplicados y fusiones · Duplicates and merges

Conversaciones y tickets · Conversations and tickets

Encuestas de satisfacción · Satisfaction surveys

Voz · Voice

Calendario y reuniones · Calendar and meetings

Campañas · Campaigns

Recorridos · Journeys

Formularios y páginas · Forms and pages

Sitios web · Websites

Conversiones y atribución · Conversions and attribution

Conocimiento · Knowledge

Canales y conexiones · Channels and connections

Webhooks de tareas · Task webhooks