Gestiona Tus DatosDocumentación API

Personas y agentes · Edición 2026-09-23.3

Integra un sistema con GTD

Esta guía acompaña a una persona técnica o a un agente desde la elección del sistema hasta la comprobación del resultado. GTD es agnóstico al sector: el sistema de origen puede ser un sitio web, CRM, ERP u otra aplicación con acceso autorizado. La documentación no concede acceso.

Estado de esta edición: el piloto de conexión y el piloto RAT requieren admisión expresa y datos ficticios. La base transversal de cuatro áreas y sus rutas /core están desplegadas para calificación con datos ficticios. Su uso exige una admisión vigente por conexión y por área. El despliegue no acredita una integración validada ni abre acceso comercial. Consulta con el operador qué versión está instalada y qué operaciones están admitidas antes de ejecutarlas.

Dispones de esta guía en Markdown, un índice estructurado, la guía del piloto de conexión y la guía RAT vigente. El índice es una descripción estática versionada, no una consulta de permisos, vigencia ni salud en tiempo real.

1. Selecciona la fuente y el resultado

Identifica el sistema de origen, la organización GTD de destino, quién autoriza los accesos y el primer resultado verificable. Empieza por un flujo pequeño: por ejemplo, proponer un proveedor ficticio y comprobar su revisión y aplicación en GTD cuando la base esté habilitada.

Comprueba si la fuente ofrece API, exportación u otro acceso soportado. Examina una muestra autorizada y su estructura. No confundas generar un JSON de prueba con extraer datos del sistema real. No reutilices credenciales entre sistemas ni envíes a GTD datos personales reales durante esta calificación.

Evidencia para avanzar: fuente identificada, método de acceso comprobado, muestra sintética, destino confirmado y responsable de revisión. Intervención pendiente: si no hay interfaz accesible o permiso del origen, documenta esa falta; GTD o MCP no crean una API en el sistema externo. No está ofrecida la conexión automática a cualquier producto.

2. Prepara identidad, permisos y vigencia

En GTD selecciona la organización, abre Conexiones API y prepara el sistema en modo Prueba siguiendo la guía de conexión. Conserva la clave privada en el equipo o almacén de secretos que ejecutará la integración; registra únicamente la pública. No pegues claves privadas, contraseñas ni tokens en conversaciones con agentes, tickets o repositorios.

El operador debe admitir la conexión y confirmar los permisos, módulos, datos permitidos y fecha de vencimiento. Solicitar un scope no lo concede. Registrar una clave, disponer de un token o haber conectado antes tampoco acredita una autorización vigente. Para la base /core hace falta además una admisión vigente de los módulos correspondientes y que esa superficie esté habilitada.

Evidencia para avanzar: identificador del cliente y conexión correctos, clave pública registrada, habilitación confirmada, permisos efectivos y vigencia revisados. Intervención pendiente: la admisión y su renovación requieren al operador; el agente no se las concede. No crees conexiones adicionales para evadir una denegación.

3. Autentica y comprueba la conexión

Descarga el ejemplo de comprobación. Con Node.js 20 o posterior y el archivo privado local, ejecuta:

node gtd-api-comprobar.mjs --client-id "IDENTIFICADOR_DEL_CLIENTE" --key-file "./gtd-api-clave-privada.json"

El ejemplo firma localmente, solicita un token y consulta GET /api/v1/integrations/connection. No imprime el token ni envía la clave privada. El destino HTTP es https://gestionatusdatos.cl; la audiencia lógica del token API es https://api.gestionatusdatos.cl.

Para implementar el flujo directamente, usa POST https://identity.gestionatusdatos.cl/realms/gtd/protocol/openid-connect/token con Content-Type application/x-www-form-urlencoded. Los parámetros son grant_type=client_credentials, client_id, scope, client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer y client_assertion. La declaración JWT usa RS256, typ=JWT y el kid registrado; iss y sub son el client_id, aud es la URL completa del endpoint de token, iat es el tiempo Unix actual, exp=iat+60 y jti es único para cada solicitud. Envía después el access_token como Authorization: Bearer y respeta expires_in. Consulta el contrato del piloto y el código del ejemplo para los detalles.

El comando de comprobación consulta sólo la conexión. Para las cuatro áreas descarga también el cliente core y conserva ambos archivos .mjs en la misma carpeta. Requiere Node.js 22. Con --client-id y --key-file obtiene en memoria un token con los permisos mínimos de cada operación; el helper admite los diez scopes del contrato. La alternativa GTD_API_ACCESS_TOKEN permite usar un token obtenido previamente por el mecanismo autorizado. Ninguna opción concede permisos ni habilita áreas.

Evidencia para avanzar: comprobación autenticada satisfactoria de la conexión correcta, hora y requestId sin secretos. Intervención pendiente: si faltan scopes o la base no está desplegada, detener ese flujo y registrar la brecha; el éxito de la comprobación no habilita las cuatro áreas.

4. Mapea sólo datos admitidos

El OpenAPI de la base define los esquemas cerrados y respuestas. El prefijo es /api/v1/integrations/core. Estos permisos son requisitos, no permisos otorgados por leer esta guía.

RAT

Lectura: rat:activities:read. Envío: rat:events:write. POST /rat/observations recibe sourceRef, observedAt y data. En data, name es obligatorio; purpose, dataCategories, dataSubjectCategories y providerRefs son opcionales. GET /rat/records consulta registros vinculados a la conexión.

Proveedores

Lectura: providers:read. Envío: providers:events:write. POST /providers/observations usa la misma envoltura; data contiene name obligatorio y service y country opcionales. GET /providers/records consulta los registros vinculados.

Sistemas y activos

Lectura: integrations:capabilities:read. Envío: integrations:events:write. POST /assets/observations usa la misma envoltura; data contiene name obligatorio y description, owner, location y treatmentRefs opcionales. GET /assets/records consulta los registros vinculados. Los scopes generales no bastan: la admisión debe incluir assets. Esta área cubre inventario básico, no todo el módulo de Seguridad.

Derechos

Lectura: rights:requests:read. Ingreso: rights:requests:write. POST /rights/requests usa el contrato del portal alojado: name, email, actingAs, rights y description; subjectName se requiere para representación. Consulta las enumeraciones, campos exigidos y límites en OpenAPI. GET /rights/requests/{id} devuelve estado del caso de esa conexión y fulfillment=ASSISTED. No entrega el expediente ni los mensajes privados.

El portal de la organización debe estar publicado y configurado y disponer de correo operativo. El acuse RECORDED no verifica identidad ni resuelve el derecho. Identidad, representación, comunicaciones, respuesta y ejecución sobre sistemas fuente siguen el procedimiento humano. Usa únicamente identidades ficticias y un buzón de prueba autorizado para evitar enviar mensajes a personas ajenas.

Reglas del mapeo

Conserva una sourceRef estable del origen; no uses el nombre como identificador ni la confundas con un ID nativo GTD. Registra por campo la procedencia, transformación y decisiones pendientes. El agente no debe inferir finalidad, base jurídica, plazos de conservación o cumplimiento a partir de campos técnicos. Una descripción o categoría desconocida requiere revisión responsable.

sourceRef admite 1–100 caracteres alfanuméricos, punto, guion, guion bajo o dos puntos y comienza por alfanumérico. observedAt es ISO UTC canónico con milisegundos; una nueva observación debe ser posterior a la última aplicada y no más de cinco minutos futura. name y otros textos admiten hasta 300 caracteres; purpose y description hasta 2.000; listas hasta 50 valores únicos normalizados. Cuerpo JSON máximo: 32 KiB. Los campos desconocidos se rechazan. Campos ausentes conservan el valor; una lista vacía explícita puede eliminar relaciones tras revisión.

La preparación de permisos todavía solicita juntos integrations:events:write y rat:events:write; la admisión limita las áreas efectivas. GET /submissions/{id} exige integrations:events:read y el permiso de lectura del área.

Evidencia para avanzar: tabla de correspondencias revisada, muestra conforme al esquema y decisiones de negocio explícitas. Intervención pendiente: completar los datos que la fuente no contiene o que requieren juicio humano. No existe todavía un endpoint público de simulación del mapeo ni escritura MCP.

5. Vincula, envía y revisa

Antes del primer envío de una referencia que representa un registro manual existente, una persona autorizada debe vincularla explícitamente en GTD. No se emparejan registros por similitud de nombres. Si se aprueba un alta sin vínculo previo, se crea un registro nativo; comprobar antes el inventario evita duplicados.

Para la base admitida, cada POST de observación y de Derechos lleva Idempotency-Key de 16–128 caracteres alfanuméricos, punto, guion, guion bajo o dos puntos, comenzando por alfanumérico. Genera una clave para la operación y conserva exactamente el archivo, la fecha y la clave en los reintentos. Misma clave y mismo contenido recuperan el resultado; contenido distinto con la misma clave produce conflicto 409.

Ejemplo sintético de Proveedores; establece observedAt una vez antes del primer envío y conserva el archivo en un reintento:

{"sourceRef":"crm:vendor-demo-01","observedAt":"2026-09-23T12:00:00.000Z","data":{"name":"Proveedor ficticio","service":"Servicio de pruebas","country":"CL"}}

Antes de autenticar o enviar, comprueba el archivo local con la misma clave idempotente que conservarás en la operación:

node gtd-api-core-base.mjs observe providers proveedor.json demo-proveedor-envio-0001 --validate-only
node gtd-api-core-base.mjs rights-submit solicitud.json demo-solicitud-envio-0001 --validate-only

La salida {"validation":"structure-only","valid":true,"sent":false} acredita únicamente estructura válida. Esta opción no lee la clave privada ni usa la red. No comprueba admisión, relaciones, versiones, identidad del solicitante, reloj del servidor ni disponibilidad. No es un dry-run remoto. Sólo aplica a observe y rights-submit; no realiza consultas.

Sólo tras confirmar disponibilidad y admisión, el ejemplo de cliente se usa así (ambos archivos .mjs juntos):

node gtd-api-core-base.mjs observe providers proveedor.json demo-proveedor-envio-0001 --client-id ID --key-file clave.json
node gtd-api-core-base.mjs submission providers ID_DEL_RECIBO --client-id ID --key-file clave.json
node gtd-api-core-base.mjs records providers --limit 20 --client-id ID --key-file clave.json

Las altas y los cambios ordinarios generan AWAITING_REVIEW; una revisión humana termina en APPLIED o REJECTED. Un cambio de nombre que cumpla la regla autoName expresamente habilitada puede devolver APPLIED directamente. En /core, HTTP 200 devuelve el recibo; su campo status indica AWAITING_REVIEW, APPLIED o REJECTED. La respuesta HTTP por sí sola no acredita aplicación. El piloto RAT anterior usa HTTP 202 para recepción. Sólo puede haber una propuesta pendiente por referencia. Para relaciones, aplica primero proveedores, después RAT con providerRefs y después activos con treatmentRefs; todas las referencias deben pertenecer a la misma conexión y existir en GTD.

Una edición manual posterior a la propuesta bloquea su aprobación; rechaza y prepara una nueva observación revisada. La automatización opcional del nombre requiere configuración expresa, aprobación inicial y que no haya otros cambios; no es una facultad general para sobreescribir fichas.

Evidencia para avanzar: recibo reconciliado, decisión, registro nativo y versión correctos, sin duplicados ni cambios humanos perdidos. Intervención pendiente: revisión humana o resolución del conflicto. Un timeout no autoriza una clave nueva ni prueba que el envío falló: consulta el recibo si conservas su ID o repite la operación con archivo y clave originales.

6. Comprueba resultados y operación

En GET /{module}/records distingue observation, los últimos datos de origen aplicados, de current, el estado vigente en GTD. observation=null significa que no hay observación aplicada. En la primera llamada usa GET /{module}/records?limit=20 sin after. Para continuar, envía GET /{module}/records?limit=20&after=<nextAfter de la respuesta anterior>, codificando el valor para URL. nextAfter es un campo de respuesta; after es el parámetro de petición. Termina cuando nextAfter sea null; limit admite 1–50. El comando records obtiene una página; continúa con records ÁREA --limit 20 --after REFERENCIA y las mismas opciones de autenticación, usando el nextAfter recibido. La lista cubre vínculos propios, no todo el inventario; no constituye una instantánea. unmappedRelationshipCount indica relaciones que no tienen referencia accesible para esa conexión.

Clasifica errores por el código estructurado cuando esté disponible y conserva el requestId; no registres tokens ni cuerpos de Derechos. Ante 401/403 revisa identidad, permisos, vigencia y revocación. Ante 404 confirma la versión habilitada y el recurso autorizado. Ante 409 reconcilia idempotencia, versión o propuesta pendiente. Ante 422 corrige el contrato. Ante 429 respeta Retry-After cuando venga informado. No repitas escrituras a ciegas ante errores de red o servidor.

Prepara un responsable, frecuencia de sincronización, registro de resultados y tratamiento de fallos. Un proceso convencional puede sostener la sincronización; no requiere un agente en cada ejecución. No hay batch ni webhooks habilitados por esta base ni renovación automática del piloto.

Evidencia de cierre: datos aprobados visibles en GTD, repetición sin duplicados, edición manual preservada, recuperación de un envío incierto y rechazo tras suspensión o revocación en una prueba coordinada. Intervención pendiente: coordinar renovación, rotación o revocación con la administración autorizada. Revocar corta el acceso aunque el token no haya vencido; conserva los registros e historial.

7. Qué aporta MCP

MCP permite a un cliente compatible descubrir e invocar operaciones descritas. No garantiza que cualquier agente que visite la web descubra, instale y autorice automáticamente el servidor. Obtén del operador autorizado la dirección, transporte, autenticación y alcance habilitados para tu cliente; esta guía no inventa un endpoint público operativo.

API y MCP tienen audiencias distintas. No reutilices un token API ni una sesión humana como credencial MCP. Descubrir herramientas tampoco concede permisos. El catálogo existente contiene ocho operaciones de consulta; su presencia en el contrato no acredita servicio desplegado ni acceso vigente:

Estas herramientas no crean conexiones, no escriben registros, no extraen automáticamente datos de cualquier sistema externo y no resuelven solicitudes de derechos. La ampliación de MCP dependerá de obstáculos demostrados en el recorrido. La integración debe seguir siendo utilizable mediante API sin depender de un agente.

8. Entrega del agente

Entrega el adaptador y su configuración sin secretos, correspondencias aprobadas, pasos reproducibles, recibos saneados, resultados comprobados y limitaciones. Separa lo ejecutado de lo preparado y de lo bloqueado. No declares éxito sólo porque generaste código, obtuviste un token o recibiste HTTP 200/202.

Una persona o un agente nuevo debe poder repetir el recorrido desde esta guía y los accesos concedidos, sin nuestras conversaciones internas. Para solicitar ayuda usa el canal de soporte de la API con etapa, código y requestId, nunca credenciales.