Registro de cambios
Lo que se suma a la API, a los webhooks y al MCP, con la fecha en que salió. La v1 no rompe lo que ya funciona: lo que conviene revisar en una integración existente va marcado «Para revisar».
API v1
Guías de integraciones
El portal suma cuatro guías paso a paso para conectar una cuenta sin programar. La API no cambia.
- NuevoPortalGuías para llevar las consultas a Google Sheets (con Apps Script o con un webhook), armar escenarios en Make y en n8n, y conectar el asistente con el MCP.
API v1
Recursos por módulo, alcances, idempotencia, webhooks y portal
La v1 suma rutas por recurso, paginación, alcances por módulo en los tokens, repetición segura de pedidos, webhooks firmados y este portal. Lo que ya funcionaba sigue funcionando igual, salvo dos códigos de error que se corrigieron.
- NuevoAPIRecursos por módulo: además de POST /v1/herramientas/{nombre}, las operaciones tienen su propia ruta con GET, POST o PATCH, como GET /v1/gestion/clientes/{id}.
- NuevoAPIPaginación en las operaciones que listan o buscan: entrada limite (1 a 100, 25 si no se manda) y cursor; salida { datos, paginacion: { siguiente, total } }.
- NuevoAPIAlcances por módulo en los tokens: modulo:lectura y modulo:escritura, o * para todos los módulos. Los tokens que ya existían conservan lo que podían hacer.
- NuevoAPIEncabezado Idempotency-Key en las operaciones que cambian algo: repetir el pedido con la misma clave devuelve la respuesta guardada, con Idempotent-Replayed: true.
- NuevoAPICada respuesta a un pedido con token lleva el identificador del pedido en x-kaptativa-pedido, también el 401, y los errores lo repiten en error.pedido. Los errores de entrada suman detalles por campo.
- NuevoAPIEncabezados de cuota RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset en toda respuesta a un pedido con un token válido de una cuenta con la API activa (un 401 y un no_activo no los traen). Retry-After en el 429 dice los segundos reales que faltan.
- Para revisarAPIUn cuerpo que no es JSON válido responde 400 con el código cuerpo (antes 422 entrada), y un registro que no existe o no es de la cuenta responde 404 con el código no_encontrado (antes 409 servicio). Si tu integración mira esos códigos, actualizala.
- NuevoWebhooksWebhooks salientes: la cuenta registra destinos https, elige eventos y recibe cada uno firmado con HMAC-SHA256 (formato Standard Webhooks), con reintentos y reenvío desde el panel.
- NuevoMCPEl MCP respeta los alcances del token, valida el encabezado Origin, responde con los encabezados de cuota y suma recursos de lectura (resources).
- NuevoPortalPortal de desarrolladores con guías, la referencia generada del mismo registro que usa la API y este registro de cambios.