API v1 de RouterClip RouterClip API v1

Guía para integradores (ES/EN). Estado: v1, disponible. Las novedades se añaden sin romper lo que ya funciona.

• API de tareas y funciones (función api.tasks): para conectar herramientas de tareas (Jira, Asana, ClickUp, Linear, Monday, Trello, Notion…) y leer, modificar y ejecutar el trabajo de todas las funcionalidades. Tiene su propia guía para integradores: /developers/api-v1-tareas.html, con scopes y paquetes, actor y delegación (X-AIO-Act-As), dryRun, idempotencia, feed de cambios, webhooks y recetas. Su catálogo estático de tipos y acciones está en https://www.routerclip.com/developers/api-v1-task-kinds.json. / Task and function API (api.tasks feature): guide for integrators in /developers/api-v1-tareas.html; static catalog of kinds and actions at /developers/api-v1-task-kinds.json.
• Contrato OpenAPI (generado de las rutas reales, filtrado a /api/v1): https://www.routerclip.com/developers/api-v1.json. En producción /openapi.json y /docs no están disponibles.
• Documentación publicada / Published documentation: esta guía, la de la API de tareas, el contrato y el catálogo están en https://www.routerclip.com/developers/, enlazados desde Integraciones → API y eventos, desde el panel de la API de tareas y desde el pie de la web pública. / This guide, the task API guide, the contract and the catalog are published at /developers/.

Español

1. Qué es

La API v1 conecta los servidores de tu empresa (ERP, tienda, backend, CRM anterior) con RouterClip. Es de servidor a servidor: no tiene CORS y la clave nunca debe estar en un navegador, en una app móvil, en un gestor de etiquetas (GTM) ni en una URL. Para medir lo que pasa en tu web se usa el script aiocrm.js de un sitio verificado, que nunca lleva claves.

2. Activación, fuentes y claves

1. El equipo de RouterClip activa la función «API y eventos» (marketing.api) para tu empresa.
2. Un administrador crea una fuente por sistema en Ajustes → Integraciones → API y eventos. La fuente decide qué puede hacer la integración: tipos de evento permitidos, campos de contacto, contactos a los que llega (por defecto, solo los vinculados a ella) y recorridos.
3. En la fuente emite una clave con sus permisos (scopes). Se muestra una sola vez: guárdala en el gestor de secretos de tu integración. Puede haber dos claves activas por fuente para rotarlas sin cortes; caducidad opcional de hasta 365 días (con avisos a 14 y 3 días). Revocar una clave o desactivar la fuente surte efecto en la petición siguiente.

API de tareas y funciones (función api.tasks; detalle, paquetes y actor en /developers/api-v1-tareas.html). Los scopes son <área>:<nivel> y los niveles no se heredan: read (leer), write (crear y editar), execute (acciones operativas), admin (acciones de administrador; exigen actuar como un administrador) y content (cuerpos, notas internas y transcripciones). Además de contacts:read, contacts:write, subscriptions:invite y automations:enroll, ya descritos:

Los scopes *:admin, *:content, team:emails y act_as son sensibles: la pantalla pide confirmarlos. La UI ofrece paquetes predefinidos: lectura, gestión, operación completa y personalizado.

Comprueba una clave sin efectos: GET /api/v1/key.

3. Autenticación, respuestas y errores

Authorization: Bearer aio_<keyId>.<secreto>
Content-Type: application/json
X-Request-ID: erp-7f3c1a2b            (opcional)

• Toda respuesta de /api/v1/ lleva X-Request-ID: el tuyo si es válido (8-128 caracteres A-Z a-z 0-9 . _ : -) o uno nuevo. Cítalo al pedir soporte.
• Los errores tienen la forma {"detail": {"code": "CODIGO", "message": "…", "requestId": "…", "field": "ruta.del.campo"}}. field indica dónde está el problema; los valores enviados nunca se repiten. El código es estable; el mensaje puede cambiar.

4. Cuotas

Límites técnicos (no comerciales), aplicados antes de escribir; ninguna petición queda aceptada a medias:

• 120 peticiones por minuto por clave y 600 por empresa (una clave nueva no reinicia la de empresa);
• 50.000 eventos nuevos por empresa y día UTC; un duplicado no consume esta cuota;
• importación histórica (events:import): 200.000 eventos importados por empresa y día UTC, aparte de los 50.000 en vivo; cada lote cuenta como una petición en las cuotas por minuto y un duplicado no consume (§5 bis);
• invitaciones de doble opt-in: las mismas cuotas que el formulario público (200 por hora y empresa, 3 por día y dirección, compartidas con él);
• tokens de vínculo (identity:link): 60 por minuto y clave;
• las credenciales inválidas se frenan por dirección IP.

5. Enviar un evento: POST /api/v1/events

Un evento por petición (sin lotes). Requiere events:write.

{
  "eventId": "erp-order-842-paid-v1",
  "eventType": "order.paid",
  "schemaVersion": 1,
  "occurredAt": "2026-09-28T10:15:30Z",
  "subject": { "externalId": "customer_872" },
  "data": { "orderId": "order_842", "paymentId": "payment_603", "amountMinor": 12990, "currency": "EUR" }
}

Campos que fija el servidor y que se rechazan si los envías: empresa, fuente, confianza (trust; financialVerified da EVENT_TRUST_RESERVED), modo, fecha de recepción, verificación.

Datos por tipo

Los identificadores (orderId, paymentId, refundId, conversionId, opportunityId) tienen 1-64 caracteres ASCII visibles y no pueden ser un email (EVENT_REFERENCE_PERSONAL).

Importes. amount como cadena decimal ("129.90") o amountMinor como entero en unidades menores (12990), siempre con currency ISO 4217. Nunca números con decimales en JSON (MONEY_FLOAT_NOT_ALLOWED); sin redondeos (MONEY_PRECISION); sin negativos. Se admiten divisas de 0, 2 y 3 decimales (JPY, EUR, KWD…). Se guarda {"amount": "129.90", "currency": "EUR"} y el recibo devuelve amount, amountMinor y exponent. Son importes declarados por tu integración, nunca pagos verificados.

Sujeto.

• contactId: ID de un contacto de RouterClip que la fuente puede alcanzar (por defecto, uno vinculado a la fuente). Si fue fusionado, se usa la ficha que se conserva.
• externalId: tu ID de cliente vinculado a un contacto en esta fuente (1-128 caracteres ASCII visibles; nunca un email ni un teléfono: EXTERNAL_ID_EMAIL_SHAPE, EXTERNAL_ID_PHONE_SHAPE).
• Si envías varios, deben identificar al mismo contacto: si no, 409 SUBJECT_IDENTITY_CONFLICT.
• custom exige un contacto resuelto (422 SUBJECT_UNRESOLVED). Una conversión o un pedido con un externalId aún sin vincular se guardan sin contacto y no se vinculan después.
• anonymousId: solo en conversiones y pedidos, y solo con context.site. Es el identificador de visitante que tu página obtiene con aiocrm.push(['getVisitorId', cb]) y pasa a tu servidor. Sirve de referencia de atribución en ese sitio; no identifica a ningún contacto. RouterClip guarda solo su HMAC. Excepción (visitantes vinculados, marketing.identity): si la página vinculó ese navegador con aiocrm.push(['identify', token]) antes de occurredAt, el evento resuelve esa ficha cuando no envías otra identidad; entonces context.site debe estar entre los sitios permitidos de tu fuente (422 ANONYMOUS_ID_SITE_NOT_ALLOWED).

Contexto. context.site es el ID público (st_…) de un sitio activo y verificado de tu empresa. Cualquier otra clave, incluido attributionToken, da 422 CONTEXT_FIELD_NOT_ALLOWED: el sobre de atribución de los enlaces nunca se envía a esta API.

Ejemplo de pedido declarado desde el servidor de tu web:

curl -sS https://www.routerclip.com/api/v1/events \
  -H "Authorization: Bearer $AIOCRM_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: checkout_ORDER-42_paid" \
  -d '{"eventId":"checkout_ORDER-42_paid","eventType":"order.paid","occurredAt":"2026-09-28T10:20:00Z",
       "subject":{"anonymousId":"5f0c2a9e-3b7d-4c1a-9e55-0d7c1b2a6f10"},
       "data":{"orderId":"ORDER-42","paymentId":"pay_42","amountMinor":12900,"currency":"EUR"},
       "context":{"site":"st_AbCdEfGhIjKlMnOpQrStUvWx"}}'

5 bis. Importar histórico: POST /api/v1/events/import

Para cargar hechos pasados (pedidos, reembolsos y eventos propios de tu ERP o de tu CRM anterior) sin que provoquen nada. Requiere el scope events:import, que events:write no incluye: un administrador lo marca al emitir la clave. Sigue la función marketing.api como el resto de la API.

curl -sS https://www.routerclip.com/api/v1/events/import \
  -H "Authorization: Bearer $AIOCRM_API_KEY" -H "Content-Type: application/json" \
  -d '{"events":[
        {"eventId":"erp-order-512-paid-v1","eventType":"order.paid","occurredAt":"2026-03-02T09:30:00Z",
         "subject":{"externalId":"customer_872"},
         "data":{"orderId":"order_512","paymentId":"payment_377","amountMinor":4990,"currency":"EUR"}},
        {"eventId":"erp-order-512-refund-1","eventType":"order.refunded","occurredAt":"2026-03-10T16:00:00Z",
         "subject":{"externalId":"customer_872"},
         "data":{"orderId":"order_512","refundId":"refund_12","amount":"49.90","currency":"EUR","full":true}}]}'

• Lote. {"events": [...]} con 1 a 500 eventos y como máximo 1 MiB (solo esta ruta; el resto de /api/v1 mantiene 32 KiB). Más de 500: 422 IMPORT_TOO_MANY_EVENTS; más de 1 MiB: 413. Otros errores del lote completo: 415, 422 IMPORT_BODY_INVALID, IMPORT_FIELD_NOT_ALLOWED (solo se admite events), IMPORT_EVENTS_REQUIRED e IDEMPOTENCY_KEY_NOT_SUPPORTED (cada evento ya es idempotente por su eventId).
• Cada evento sigue el contrato de POST /api/v1/events (§5): sobre cerrado, tipos permitidos en la fuente (conversion.reported, order.paid, order.refunded, custom), sujeto, contexto e importes. Cambia solo la fecha: occurredAt debe caer dentro de la retención de datos de tu empresa (12 meses por defecto) y como mucho 5 minutos en el futuro; fuera, se rechaza solo ese evento con EVENT_OCCURRED_OUT_OF_RETENTION (con retentionMonths). El límite de 30 días del envío en vivo no se aplica.
• Sin efectos. Los eventos se guardan con mode: "import" y sin entregas: no inscriben en recorridos, no despiertan esperas, no crean conversiones ni atribuciones, no puntúan y no envían nada. Su recibo (GET /api/v1/events/{id}) muestra mode: "import" y deliveries: []. Sí cuentan en los segmentos de compras declaradas por integración, cuya vista previa lo indica: «incluye histórico importado» (purchaseCoverage.includesImported e importedSince).
• Respuesta 200 con un resultado por evento, en orden: {"mode": "import", "received", "accepted", "duplicates", "rejected", "retention": {"months", "oldestOccurredAt"}, "dailyQuota": {"limit", "used"}, "results": [...]}. Cada results[i] lleva index, tu eventId y status:
  • accepted: guardado; con id, eventType, occurredAt, mode, contactResolved y statusUrl.
  • duplicate: ese eventId de la fuente ya se había recibido (en vivo o importado) con el mismo cuerpo normalizado; devuelve su id y su mode. No cuesta cuota.
  • rejected: con code, message, httpStatus (el que respondería el envío en vivo: 403, 409, 422 o 429) y field. Por ejemplo EVENT_TYPE_FORBIDDEN, IDEMPOTENCY_CONFLICT (mismo eventId con otro cuerpo), SUBJECT_UNRESOLVED, MONEY_FLOAT_NOT_ALLOWED, EVENT_OCCURRED_OUT_OF_RETENTION o RATE_LIMITED.
• Cada evento se procesa por separado: uno rechazado no deja rastro ni anula los demás. Reintentar un lote entero es seguro: lo ya aceptado vuelve como duplicate.
• Cuota diaria propia: 200.000 eventos importados nuevos por empresa y día UTC, aparte de los 50.000 en vivo. Al llenarse, los eventos nuevos restantes del lote se rechazan con RATE_LIMITED (quota: "companyImportsPerDay") y la respuesta lleva Retry-After; los duplicados siguen respondiendo. 503 INGEST_PAUSED si la plataforma detiene la recepción: reintenta el mismo lote más tarde.
• Un evento importado enviado después por POST /api/v1/events con el mismo eventId es el mismo hecho (duplicate: true, mode: "import"): importar no vuelve a disparar nada en vivo.

6. Recibo: 202 y GET /api/v1/events/{id}

{
  "id": "5f2c9e0b7d8a4c1e9b3f6a2d4e8c1b7a",
  "eventId": "erp-order-842-paid-v1",
  "eventType": "order.paid",
  "schemaVersion": 1,
  "status": "accepted",
  "duplicate": false,
  "occurredAt": "2026-09-28T10:15:30Z",
  "receivedAt": "2026-09-28T10:15:31Z",
  "trust": "clientDeclared",
  "mode": "live",
  "contactResolved": true,
  "normalization": { "status": "normalized", "money": { "amount": "129.90", "amountMinor": 12990, "exponent": 2, "currency": "EUR" } },
  "attribution": { "basis": "contact", "site": null },
  "deliveries": [ { "consumer": "marketing.journeys", "status": "pending", "attempts": 0, "lastError": null, "completedAt": null } ],
  "statusUrl": "/api/v1/events/5f2c9e0b7d8a4c1e9b3f6a2d4e8c1b7a"
}

• 202 significa recepción durable: el evento y sus entregas están guardados. No significa que un recorrido haya empezado, que se haya enviado nada ni que la atribución esté hecha.
• deliveries es el recibo de cada consumidor activo en tu empresa (pending, processing, done, failed, skipped), sin datos del evento. Puede estar vacío si no hay ninguno activo. done no significa mensaje entregado.
• attribution.basis: browser (visitante de context.site), contact (clics de las campañas enviadas al contacto) o none. La decisión la toma después el consumidor de atribución.
• GET /api/v1/events/{id} (con events:read o events:write) devuelve el mismo recibo, solo para eventos de la fuente de la clave (404 EVENT_NOT_FOUND en otro caso). La respuesta 202 incluye la cabecera Location con esa URL.
• El recibo nunca incluye el contenido del evento (identidades, propiedades, referencias).

6 bis. Feed de eventos: GET /api/v1/events y GET /api/v1/event-types

Lee los hechos de toda la empresa (contactos, oportunidades, conversaciones, tickets, SLA, CSAT, seguimientos, secuencias, recorridos, formularios, conversiones…) en orden, con el mismo cuerpo «despertador» que los webhooks de empresa: solo IDs, tipo y versión. Después lees el registro con tu clave.

• Requisitos: scope events:read, la función api.tasks y, por cada tipo, el scope de lectura de su área con la función del área activa (deals:read para deal.*, support:read para conversation.*, ticket.* y sla.*, contacts:read para contact.* y custom…). Con solo events:read las páginas salen vacías, sin error. La visibilidad la deciden los scopes de área, no contactScope.
• Catálogo: GET /api/v1/event-types lista cada tipo con su área, scope y función, si tu clave lo puede leer ya (available), si es un hecho de atención que solo se registra mientras alguien lo quiere (recordedWhenWanted) y con qué ruta se lee cada agregado (readWith, p. ej. opportunity → /api/v1/deals/{id}, marketing_site → /api/v1/sites/{id}, marketing_signup_form → /api/v1/forms/{id}). Los agregados sin ruta de detalle por ese ID salen en aggregatesWithoutDetail con el motivo: listOnly (búscalo en listPath: booking en /api/v1/bookings, pipeline en /api/v1/pipelines), externalReference (conversion y order: el ID es tu propio conversionId u orderId del evento; la conversión atribuida está en /api/v1/conversions) o noResource (journey_enrollment, marketing_link: lee el subject). task.* no está (usa GET /api/v1/task-changes) ni los hechos internos del motor (automation.*).
• Petición: GET /api/v1/events?types=deal.won,deal.lost&after=<cursor>&limit=100 (limit 1-500, 100 por defecto; types hasta 30). Sin after empieza por el hecho más antiguo conservado. Pedir un tipo de un área que la clave no lee responde 403 API_SCOPE_REQUIRED (con requiredScopes) o FEATURE_DISABLED; un tipo desconocido o fuera del feed, 422 VALIDATION_ERROR.
• Respuesta: {"items": [...], "nextCursor": "c1.…", "hasMore": false}. Cada elemento es {id, type, schemaVersion, occurredAt, subject: {type, id} | null, aggregate: {type, id} | null, version, changedFields?}: subject es el contacto del hecho (el que se conserva tras una fusión) o, sin contacto, el registro del que trata. Nunca nombres, emails, teléfonos, importes, cuerpos ni propiedades.
• Orden y garantías: cada hecho recibe un número por empresa en el orden en que se confirma, así que leyendo con el cursor no hay huecos; la entrega es al menos una vez y dos hechos del mismo registro pueden llegar desordenados: descarta los de version no mayor que la que ya tienes. nextCursor está ligado a tu fuente y a types (otro filtro u otra fuente: 400 CURSOR_INVALID), no caduca y, con la página vacía, se queda al final para que el sondeo no vuelva a recorrer nada. Si la retención de la empresa ya borró lo anterior a tu cursor: 410 CURSOR_EXPIRED (empieza sin after).
• Desde cuándo: un tipo entra en el feed mientras exista una clave activa de una fuente activa que pueda leerlo; lo anterior no se rellena. Solo entran hechos en vivo (nunca los importados) de fuentes activas.
• Datos personales: al borrar un contacto sus hechos quedan sin él; los hechos siguen la retención de la empresa.

7. Idempotencia y reintentos

• La unicidad es fuente + eventId: rotar la clave no crea otro hecho, y otra clave de la misma fuente recibe duplicate: true. Dos fuentes distintas no comparten eventId.
• Mismo eventId y mismo contenido (normalizado: amount o amountMinor equivalentes cuentan igual) → 202 con el recibo original y duplicate: true, sin coste de cuota diaria. Contenido distinto → 409 IDEMPOTENCY_CONFLICT.
• Idempotency-Key es opcional; si la envías, debe ser igual a eventId (422 IDEMPOTENCY_KEY_MISMATCH).
• Tras un timeout o un 5xx, reintenta con el mismo eventId (espera exponencial). Con 429 y 503, respeta Retry-After. Los 4xx no se reintentan sin corregir. Puedes consultar el recibo antes de reenviar.

8. Contactos

La fuente decide qué ve y qué cambia la integración (lo configura un administrador en API y eventos):

• Contactos que alcanza. Por defecto, solo los vinculados a la fuente por un externalId (tu ID de cliente). Un administrador puede ampliarlo a todos los contactos de la empresa; el cambio queda con autor y fecha.
• Campos de lectura y de escritura: name, email, phone, company, language, tags, customValues, timezone y profilingOptOut. Email y teléfono son permisos aparte. Por defecto se leen nombre, empresa, idioma y etiquetas, y se escriben nombre, empresa e idioma.
• Etiquetas que puede añadir o quitar y campos personalizados que puede leer y escribir (nunca los sensibles).
• linkOnExactMatch (off por defecto, email o phone): qué hacer cuando el contacto que creas ya existe.

Consentimientos, supresiones, conversaciones y oportunidades no se leen ni se escriben con contacts:*. Las notas sí: se leen con contacts:read y se añaden con contacts:write como el usuario delegado (con la función api.tasks). No hay DELETE.

Función exigida. Leer (GET /api/v1/contacts/{id}), buscar por tu ID (lookup), crear y actualizar funcionan si tu empresa tiene activa cualquiera de las funciones marketing.api («API y eventos») o api.tasks («API de tareas y funciones»); con las dos apagadas, 403 FEATURE_DISABLED. El listado, la búsqueda y las notas son rutas de la API de tareas y solo las abre api.tasks: con marketing.api sola responden 403 FEATURE_DISABLED (con feature: "api.tasks"), aunque la clave tenga contacts:read o contacts:write. La invitación de doble opt-in (§9) sigue exigiendo marketing.api.

Leer: GET /api/v1/contacts/{contactId} (contacts:read). Devuelve el contacto con la cabecera ETag: W/"<revisión>". Si el ID pertenece a una ficha fusionada, responde la ficha que se conserva: id es el canónico y mergedFrom el que pediste. Un contacto de otra empresa o que la fuente no alcanza da 404 CONTACT_NOT_FOUND.

{
  "id": "0c0b6f3e-…",
  "revision": 4,
  "mergedFrom": null,
  "mergedRecordIds": [],
  "externalId": "customer_872",
  "createdAt": "2026-09-28T10:15:31Z",
  "name": "Contacto de ejemplo",
  "company": "Acme",
  "language": "es",
  "tags": ["cliente_web"]
}

Solo aparecen los campos de lectura de la fuente, y solo si la clave tiene contacts:read (con contacts:write sin lectura, las respuestas llevan únicamente los identificadores). mergedRecordIds lista las fichas fusionadas en esta, por si guardabas alguno de esos IDs. Con timezone se devuelve también timezoneSource (contact, import, api o company).

Buscar por tu ID: POST /api/v1/contacts/lookup (contacts:read) con {"externalId": "customer_872"} en el cuerpo. El externalId nunca va en la ruta ni en la query, para que no quede en logs de proxies. 404 CONTACT_NOT_FOUND si no hay ningún contacto vinculado a ese valor en tu fuente.

Listar: GET /api/v1/contacts (contacts:read, función api.tasks). Devuelve por páginas los contactos que la fuente alcanza (contactScope: por defecto solo los vinculados a ella), ordenados por fecha de alta, con los mismos campos de lectura de la fuente que GET /api/v1/contacts/{id}. Las fichas absorbidas por una fusión nunca se listan.

• Parámetros de la query: ids (hasta 100 IDs separados por comas; un ID absorbido devuelve la ficha que se conserva con mergedFrom), updatedSince (RFC 3339 con zona: contactos creados, cambiados o que absorbieron otra ficha desde ese momento), limit (1-100, 50 por defecto) y cursor.
• Respuesta {"items": [...], "nextCursor": "…", "hasMore": true}. El nextCursor está firmado para tu empresa, tu fuente y los mismos filtros, y caduca a las 24 h; uno alterado, caducado o de otra consulta da 400 CURSOR_INVALID (empieza de nuevo sin él).
• Nunca lleva un término de búsqueda ni datos personales en la URL: q, email, phone, name, externalId o cualquier otro parámetro fuera de la lista dan 422 QUERY_PARAMETER_NOT_ALLOWED. Para buscar, usa POST /api/v1/contacts/search.

Buscar: POST /api/v1/contacts/search (contacts:read, función api.tasks) con el término solo en el cuerpo: {"q": "Lucía", "limit": 20}. Admite q (1-200 caracteres), ids, updatedSince, limit y cursor; cualquier otra clave da 422 FIELD_NOT_ALLOWED y cualquier parámetro en la query, 422 QUERY_PARAMETER_NOT_ALLOWED.

• Respeta contactScope y los campos de lectura de la fuente, igual que el listado, con el mismo cursor firmado (24 h).
• q se busca siempre en el nombre; en el email y el teléfono solo si la fuente puede leerlos. La respuesta lo dice en searchedFields (por ejemplo ["name", "email"]): una fuente sin permiso de email no puede averiguar un email probando búsquedas.

Notas: GET y POST /api/v1/contacts/{contactId}/notes (función api.tasks).

• Leer: GET /api/v1/contacts/{contactId}/notes (contacts:read): {"contactId", "mergedFrom", "items": [{"id", "text", "author": {"id", "name"}, "createdAt"}]}, las 100 más recientes primero, con el cuerpo completo de cada nota y su autor. Un ID absorbido responde con las notas de la ficha que se conserva (mergedFrom); un contacto que la fuente no alcanza da 404 CONTACT_NOT_FOUND.
• Añadir: POST /api/v1/contacts/{contactId}/notes (contacts:write): {"text": "…"} (1-5.000 caracteres; otra clave da 422 FIELD_NOT_ALLOWED) y respuesta 201 {"contactId", "note": {"id", "author", "createdAt"}}. La nota la escribe un usuario delegado (administrador o agente activo de la lista «Actuar como» de la fuente), así que la clave necesita también el scope act_as: el usuario es el de X-AIO-Act-As o, sin cabecera, el usuario por defecto de la fuente. Sin act_as, 403 DELEGATED_USER_NOT_ALLOWED; sin usuario delegado, 403 DELEGATED_USER_REQUIRED; con un usuario que ya no puede actuar, 403 DELEGATED_USER_INACTIVE. Usa la misma función que la UI y nunca escribe en una ficha absorbida (409 MERGED_RECORD con canonicalId). Idempotency-Key es opcional (misma clave y cuerpo, misma respuesta con Idempotent-Replayed; otro cuerpo, 409 IDEMPOTENCY_CONFLICT), cuenta en la cuota de 60 escrituras por minuto y clave y queda en la auditoría de acciones de la API (90 días).
• No hay DELETE ni edición de notas con una clave.
• Las notas de contacto no tienen un scope de contenido aparte. En la API de tareas, las notas internas de tickets y conversaciones exigen <área>:content (/developers/api-v1-tareas.html); esa regla no se aplica aquí: contacts:read da el texto y el autor de las notas del contacto. Concede contacts:read solo a integraciones que puedan ver esas notas.

Las tareas de un contacto (GET /api/v1/contacts/{contactId}/tasks) son de la API de tareas (función api.tasks y el scope read de cada área): ver /developers/api-v1-tareas.html.

Crear: POST /api/v1/contacts (contacts:write) con Idempotency-Key obligatoria:

{
  "externalId": "customer_872",
  "name": "Contacto de ejemplo",
  "email": "[email protected]",
  "language": "es",
  "customValues": { "customer_tier": "professional" },
  "tagsToAdd": ["cliente_web"]
}

• Campos admitidos: externalId, name (obligatorio), email, phone, company, language, tagsToAdd, customValues, timezone y profilingOptOut (solo true). Cualquier otra clave, incluidas consent, tags o marketingPermission, da 422 CONTACT_FIELD_UNKNOWN. Un campo, etiqueta o campo personalizado no permitido en la fuente da 403 CONTACT_FIELD_FORBIDDEN, CONTACT_TAG_FORBIDDEN o CONTACT_CUSTOM_FIELD_FORBIDDEN.
• externalId es obligatorio si la fuente solo alcanza sus contactos vinculados (422 EXTERNAL_ID_REQUIRED): sin él no podrías volver a leer el contacto. Si ya identifica a un contacto de tu fuente: 409 EXTERNAL_ID_TAKEN con contactId.
• Respuesta 201 con result: "created", ETag y Location. Crea el contacto por el mismo servicio que la UI (evento contact.created con origin: "api"). No concede ningún consentimiento de marketing.
• Idempotencia: la misma Idempotency-Key con el mismo cuerpo devuelve el mismo resultado durante 7 días; con otro cuerpo, 409 IDEMPOTENCY_CONFLICT. Si el alta falla, la clave queda libre para reintentar con el cuerpo corregido.
• Coincidencias. Con linkOnExactMatch: off, un email o teléfono que ya usa otro contacto da 409 IDENTITY_EXISTS (con matchedId solo si la fuente alcanza todos los contactos). Con email o phone, si hay una ficha con ese dato exacto, se vincula tu externalId a ella y se responde 200 con result: "linked" sin sobrescribir nada (ni campos, ni etiquetas, ni consentimientos); si hay varias, 409 AMBIGUOUS_IDENTITY sin decir cuáles; si esa ficha ya tiene otro externalId de tu fuente, 409 EXTERNAL_ID_CONFLICT.
• Capacidad. El límite de contactos del plan (o la capacidad que asigne RouterClip) se aplica por defecto: con la capacidad llena, 409 CONTACT_LIMIT_REACHED con limit, used, available y plan. Libera plazas fusionando o eliminando fichas, o amplía el plan; en Empresa (el plan de mayor capacidad) o con una capacidad asignada por RouterClip, escribe a RouterClip para ampliarla.

Actualizar: PATCH /api/v1/contacts/{contactId} (contacts:write) con If-Match (el ETag que leíste):

PATCH /api/v1/contacts/0c0b6f3e-…
If-Match: W/"4"
Content-Type: application/json

{"customValues": {"customer_tier": "enterprise"}, "tagsToAdd": ["vip"], "tagsToRemove": ["cliente_web"]}

• Sin If-Match: 428 PRECONDITION_REQUIRED. Con una revisión que ya no es la actual (alguien la cambió en la UI, en una importación o por la API): 412 REVISION_CONFLICT con currentRevision y el ETag actual; vuelve a leer y reintenta. Cualquier cambio en RouterClip cambia el ETag.
• Sobre una ficha fusionada: 409 MERGED_RECORD con canonicalId (la ficha que se conserva). Nunca se escribe en una ficha oculta.
• Campos: los de crear salvo externalId, más tagsToRemove. tagsToAdd y tagsToRemove solo tocan etiquetas permitidas (se guardan con la grafía de la fuente); el resto de etiquetas del contacto no cambia. customValues valida tipos y opciones reales y nunca crea definiciones (null borra un valor).
• email y phone pasan las mismas comprobaciones de identidad que en la UI (409 IDENTITY_EXISTS); un email nuevo no hereda los consentimientos del anterior. Los alias ocultos de WhatsApp y los visitantes del chat conservan sus restricciones.
• timezone (zona IANA) se guarda con procedencia api y nunca sustituye una zona declarada por el propio contacto. profilingOptOut: true registra la oposición al perfilado; una clave no puede retirarla (422 PROFILING_OPT_OUT_LOCKED).
• Sin cambios efectivos, 200 con la misma revisión y sin evento.

Registro de lecturas. Cada lectura de un contacto con una clave se anota en api_contact_reads por fuente, clave, contacto y día, y se conserva 90 días: GET, lookup, el 200 linked del alta, el listado y la búsqueda (una lectura por cada contacto devuelto) y la lectura de sus notas. También cuentan los datos del contacto que viajan en otras respuestas de /api/v1: los enlaces de una tarea y el feed, los tickets y conversaciones, las llamadas (teléfonos), las reservas (nombre y email del invitado), las oportunidades y los seguimientos (contactName), los destinatarios de campañas (address), las inscripciones en recorridos, las encuestas CSAT y los trabajos de voz (dirección enmascarada), las inscripciones en secuencias y las sesiones de playbooks (nombre y respuestas que escriben campos del contacto), y los duplicados y fusiones (campos, claves de identidad y nombres, también los de los blockers de un error), una vez por clave, contacto y petición y solo cuando se muestra algún valor. Las lecturas de una petición se escriben juntas y siempre en el mismo orden (clave, contacto y día), no en el de la respuesta, así que las peticiones en paralelo de una misma clave no se bloquean entre sí. Los administradores lo consultan por fuente y por contacto (Integraciones → API y eventos → Lecturas de contactos) y, mientras la empresa tenga la API de eventos o la de tareas activada, también en la ficha del cliente (Lecturas por integraciones (API)).

Actividad de la API. Las altas, vinculaciones (200 linked) y cambios de contactos, las invitaciones (§9) y las inscripciones (§10) hechas con una clave quedan en la actividad de la fuente 90 días, con su resultado y su X-Request-ID y sin cuerpos ni direcciones; también sus rechazos 403, 404, 409 y 412. Se consulta en Integraciones → API y eventos → API de tareas → Actividad de la API; si la empresa solo tiene la API de eventos, ese panel muestra únicamente Actividad de la API.

9. Invitaciones de doble opt-in: POST /api/v1/subscriptions/invite

Requiere subscriptions:invite y que el administrador haya elegido en la fuente una conexión SMTP verificada. Encola el mismo email de confirmación que el formulario público; el permiso de marketing solo existe cuando la persona confirma.

{
  "externalId": "customer_872",
  "purpose": "marketing",
  "policyVersion": "newsletter-2026-09",
  "policyText": "Quiero recibir novedades por email. Puedo darme de baja en cualquier momento.",
  "evidence": "Casilla sin marcar por defecto aceptada en el checkout, pedido 842"
}

• Destinatario: contactId o externalId de un contacto que la fuente alcanza (se usa su email) y/o email. Con contacto y email, deben coincidir (422 INVITE_EMAIL_MISMATCH).
• policyVersion, policyText (el aviso que verá la persona) y evidence (cómo pidió la invitación) son obligatorios; purpose es marketing por defecto.
• Respuesta 202 {"status": "pending"} igual si se encola, si ya había una pendiente o si la dirección está suprimida: la API no revela si alguien está suscrito.
• 409 INVITE_CONNECTION_REQUIRED o INVITE_CONNECTION_NOT_READY si la conexión de la fuente falta o no está verificada y activa; 429 con las cuotas del formulario público.
• 409 MARKETING_SEND_DISABLED mientras el envío de marketing del servidor (MARKETING_SEND_ENABLED) está apagado: el email de confirmación no podría salir, así que no se encola nada ni se gasta cuota. Reintenta cuando el operador lo active.

10. Recorridos: GET /api/v1/automations y POST /api/v1/automations/{id}/enroll

Requieren automations:enroll. Un administrador elige en la fuente qué recorridos permite (Integraciones → API y eventos) y el recorrido debe tener el disparador «Desde una integración (API)» y estar activo. La clave nunca ve otros recorridos.

• Lista: GET /api/v1/automations devuelve solo los recorridos permitidos en la fuente, con id, name, status, trigger y enrollable (activo y con disparador API). Como la inscripción, esta lista exige la función marketing.api: con solo api.tasks responde 403 FEATURE_DISABLED (feature: "marketing.api") y los recorridos se listan con journeys:read (/developers/api-v1-tareas.html).
• Inscripción: POST /api/v1/automations/{automationId}/enroll con Idempotency-Key obligatoria y este cuerpo:

{
  "subject": { "externalId": "customer_872" },
  "reasonEventId": "5f2c9e0b7d8a4c1e9b3f6a2d4e8c1b7a"
}

• subject: contactId (un contacto que la fuente alcanza; una ficha fusionada se resuelve en la que se conserva) y/o externalId (vinculado en tu fuente; nunca un email ni un teléfono). Si envías los dos, deben ser el mismo contacto (409 SUBJECT_IDENTITY_CONFLICT).
• reasonEventId (opcional): el id del recibo de un evento de tu misma fuente y del mismo contacto (no tu eventId). Queda como causa de la entrada; cualquier otro es 422 REASON_EVENT_INVALID.
• La decisión es síncrona y la toma la política de reinscripción del recorrido:
  • 201 {"result": "enrolled", "enrollmentId": "…", "automationId": "…"};
  • 200 {"result": "skipped", "reason": "…", "automationId": "…"} con reason: alreadyEnrolled (ya pasó por el recorrido y la política es «una sola vez»), activeEnrollmentExists (está dentro ahora), cooldown (terminó hace menos del periodo de espera), entryLimitReached (alcanzó el máximo de entradas del periodo), automationNotActive (en pausa, borrador o cancelado) o subjectUnavailable (no hay un contacto que la fuente alcance con esa identidad).
• Mismo Idempotency-Key y mismo cuerpo → la misma respuesta durante 7 días; otro cuerpo → 409 IDEMPOTENCY_CONFLICT.
• 404 AUTOMATION_NOT_FOUND si el recorrido no está en la lista de la fuente; 409 AUTOMATION_TRIGGER_NOT_API si su disparador no es la API. No se admiten campos adicionales (422 ENROLL_FIELD_UNKNOWN): ni anónimos, ni mensajes, ni conexiones, ni activación, ni consentimiento.
• enrolled no significa enviado: cada paso «Enviar» comprueba permiso, bajas, cuotas y transporte como cualquier envío. Los recorridos que empiezan por un evento no se inscriben con esta ruta: les basta con enviar el evento (POST /api/v1/events), y solo cuentan los eventos recibidos después de activarlos.

10 bis. Vincular navegadores: POST /api/v1/identity/link-tokens

Cuando un cliente inicia sesión en tu web, tu servidor (nunca el navegador) pide un token de vínculo para él y se lo pasa a la página, que lo entrega a aiocrm.js (['identify', token]). RouterClip vincula entonces ese navegador (el visitante del tracker, con consentimiento analítico) o su suscripción push con la ficha. La clave nunca llega al navegador y el navegador nunca elige el contacto. Vincular no concede ningún consentimiento (ni push, ni email, ni SMS).

Requisitos, en este orden: scope identity:link (403 API_SCOPE_REQUIRED); la función «Vincular navegadores con contactos» (marketing.identity) activa para tu empresa (403 FEATURE_DISABLED); la base jurídica de marketing.identity confirmada por un administrador en Integraciones → API y eventos (403 LEGAL_BASIS_REQUIRED); y la cuota de 60 tokens por minuto y clave (429).

{
  "subject": { "externalId": "customer_872" },
  "site": "st_AbCdEfGhIjKlMnOpQrStUvWx",
  "purposes": ["push", "push_manage"]
}

• subject: uno de externalId (vinculado en tu fuente) o contactId (un contacto que la fuente alcanza). Una ficha fusionada emite el token para la que se conserva. Sin contacto: 404 CONTACT_NOT_FOUND.
• site: el publicId de un sitio web activo y verificado de tu empresa que el administrador haya permitido en la fuente (Sitios web en los que puede vincular navegadores). Cualquier otro caso, también un sitio de otra empresa, responde igual: 403 SITE_NOT_ALLOWED.
• purposes: una o varias, sin repetir: push (vincular la suscripción push de ese navegador), anonymous (vincular el visitante del tracker; un contacto que se ha opuesto al perfilado da 409 CONTACT_OPTED_OUT) y push_manage (permitir que la página cambie las preferencias push del contacto).
• Respuesta 201 con Cache-Control: no-store: {"token": "ilt_…", "tokenType": "identity_link", "expiresAt": "…", "expiresIn": 300, "site": "st_…", "purposes": […], "shownOnce": true}. El token es aleatorio (32 bytes), vale 5 minutos, solo en ese sitio, y cada finalidad se usa una vez. RouterClip guarda solo su hash (se purga al día) y registra cada emisión (fuente, clave, sitio, contacto y finalidades).
• Pásalo a la página en el HTML o en una respuesta JSON de tu servidor, nunca en una URL; aiocrm.js lo envía solo en el cuerpo. Si el token caducó, ya se usó, es de otro sitio o de otra finalidad, la vinculación no ocurre y la página recibe la misma respuesta neutra: pide otro.
• Otros errores: 415 sin Content-Type: application/json; 422 LINK_TOKEN_BODY_INVALID, LINK_TOKEN_FIELD_UNKNOWN, SUBJECT_REQUIRED, SUBJECT_INVALID, EXTERNAL_ID_*, SITE_REQUIRED, SITE_INVALID o PURPOSES_INVALID.
• Una fusión revoca los tokens pendientes de la ficha absorbida. Si se apaga la función, se revoca la base jurídica, se revoca la clave que lo pidió, se desactiva la fuente, se quita el sitio de la fuente o el contacto se opone al perfilado (finalidad anonymous), los tokens pendientes dejan de valer.

11. Seguridad y datos personales

• Clave solo en el servidor; nunca en URLs, logs ni repositorios. Si se filtra, revócala: el operador de la plataforma también puede revocarla, una a una o todas las activas de la empresa a la vez, siempre con motivo. Con una sola de las dos funciones apagada, «API y eventos» (marketing.api) o «API de tareas y funciones» (api.tasks), las claves siguen funcionando en las rutas de la otra (y en las de contactos, que admiten cualquiera de las dos): para cortar todas las integraciones de la empresa hay que apagar las dos.
• No envíes datos personales en referencias ni en propiedades que no los necesiten. El externalId no puede ser un email o un teléfono.
• RouterClip guarda el evento mínimo: los datos normalizados, el externalId solo si no está vinculado, el HMAC del visitante y un hash del cuerpo para la idempotencia. Al borrar un contacto se desvinculan y depuran sus eventos; los eventos siguen la retención de tu empresa.
• Las lecturas de contactos quedan registradas (§8). Pide solo los campos que tu integración necesita: el administrador puede reducirlos en cualquier momento.

12. Fuera de v1

Lotes de eventos en vivo (la importación histórica sí existe: §5 bis), callbacks de recibos, pagos verificados (financialVerified), carritos (cart.*) y webhooks salientes de estos tipos. En contactos: borrado (DELETE), escritura de consentimientos o supresiones y vinculación masiva por CSV.