Conecta tu sistema con GTD

1. Prepara la conexión

Necesitas una organización admitida al piloto, permiso para administrar sus conexiones y un navegador actualizado. Para ejecutar el ejemplo necesitarás Node.js 20 o posterior en tu equipo o servidor; no requiere instalar paquetes adicionales.

Registra el sistema

1. Entra a GTD, selecciona tu organización y abre Conexiones API. Si el menú no aparece, consulta al equipo GTD.
2. Pulsa Conectar sistema, escribe un nombre reconocible —por ejemplo, «CRM de pruebas»— y conserva el uso Prueba.
3. Pulsa Continuar a permisos. En Consultas incluidas, «Comprobar conexión» es la operación disponible. Las funciones reservadas se indican en pantalla. Si GTD habilitó el piloto RAT para tu organización, también podrás solicitar sus permisos específicos; consulta la guía RAT.
4. Pulsa Guardar sistema. Quedará registrado y pendiente de habilitación.

Guarda la clave privada y registra la pública

1. En Prepara la credencial del sistema, pulsa Generar clave para este sistema.
2. Pulsa Descargar clave privada y guarda gtd-api-clave-privada.json en una ubicación protegida.
3. Marca Confirmo que guardé el archivo de clave privada y pulsa Registrar clave pública.

La clave se genera en tu navegador. GTD recibe la parte pública; la privada permanece contigo y permite autenticar tu sistema. Descárgala antes de cerrar o recargar la página. GTD no puede recuperar ese archivo por ti. No lo subas a un repositorio ni lo adjuntes a soporte.

Coordina la habilitación

Cuando aparezca Clave pública registrada, comunica al equipo GTD qué organización y sistema preparaste. Registrar una clave no concede acceso automáticamente.

Continúa cuando veas Lista para comprobar. Abre Datos para configurar tu sistema y copia el Identificador del cliente. Revisa también Autorización de prueba hasta: esa fecha limita el acceso.

Si aparece «GTD debe revisar el registro», pide ayuda. No crees otra conexión para intentar resolver ese estado.

2. Realiza la primera comprobación

Descarga el ejemplo en el equipo que tiene acceso a la clave privada. El archivo se puede revisar antes de ejecutarlo.

Abre una terminal en la carpeta del ejemplo y ejecuta:

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

Reemplaza IDENTIFICADOR_DEL_CLIENTE por el valor de GTD. Si guardaste la clave en otra carpeta, cambia la ruta de --key-file. No pegues el contenido de la clave en el comando.

El ejemplo firma la autenticación localmente, obtiene un token y realiza una consulta. No envía el archivo privado ni imprime el token. Hace un solo intento, sin reintentos automáticos.

Cómo reconocer el éxito

La terminal muestra "status":"succeeded", la referencia de tu conexión y, cuando está disponible, una referencia de la petición para soporte. El programa termina con código de salida 0.

Vuelve al detalle del sistema en GTD y pulsa Consultar resultado. Debes ver Conexión comprobada, «Tu sistema ya se comunicó con GTD» y la fecha de Última comprobación recibida. Después puedes usar Actualizar.

El éxito acredita esa petición. No significa que se hayan enviado datos de negocio ni que exista acceso indefinido.

3. Referencia técnica

Esta sección es para quien implementa la integración. El contrato OpenAPI descargable describe la única operación de consulta habilitada en el piloto.

Autenticación del sistema

Usa OAuth con client_credentials y autenticación private_key_jwt. La clave privada firma una declaración JWT; no se envía al servidor. El ejemplo descargable implementa el flujo completo.

POST · Obtener un token

https://identity.gestionatusdatos.cl/realms/gtd/protocol/openid-connect/token

Envía Content-Type: application/x-www-form-urlencoded y estos campos:

grant_type

client_credentials

client_id

El identificador del cliente mostrado en GTD.

scope

integrations:connection:read

client_assertion_type

urn:ietf:params:oauth:client-assertion-type:jwt-bearer

client_assertion

La declaración JWT firmada con la clave privada correspondiente a ese cliente.

En una respuesta correcta utiliza access_token como Bearer y respeta expires_in. Cuando venza, solicita un nuevo token con una nueva declaración firmada. Este flujo no depende de un token de renovación. Obtener un token nuevo no amplía la autorización del piloto.

Consultar la conexión propia

GET /api/v1/integrations/connection

GET https://gestionatusdatos.cl/api/v1/integrations/connection
Authorization: Bearer <access_token>
Accept: application/json

No envíes cuerpo ni identificadores de organización como parámetros. GTD determina la conexión a partir del token. No uses HEAD para esta comprobación.

Ejemplo ilustrativo de una respuesta 200 —las referencias y fechas son ficticias—:

{
  "id": "cn_example0000000001",
  "providerKey": "gtd_api_v1",
  "environment": "test",
  "direction": "inbound",
  "status": "active",
  "health": {
    "state": "unknown",
    "checkedAt": "2026-01-01T00:00:00.000Z"
  },
  "capabilities": []
}

health describe una evaluación de salud registrada; puede indicar unknown aunque esta solicitud sea aceptada. Su fecha no es necesariamente la de tu última petición. Consulta esa última comprobación en GTD.

Las capacidades de capabilities son descriptivas: no habilitan otras rutas. El piloto sólo admite el GET documentado aquí.

Respuestas y límites

Las cabeceras RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset, cuando estén presentes, informan la cuota. No asumas una cuota fija. Conserva X-Request-Id para soporte.

Los errores del GET usan error.code, error.message y error.requestId. Clasifica por el código, no por el texto. El endpoint de token pertenece al servicio de identidad y puede devolver un formato de error diferente.

4. Resuelve un error del ejemplo

El ejemplo termina con código de salida 1 cuando falla y muestra uno de estos códigos. Primero conserva el mensaje y revisa el estado de la conexión en GTD.

5. Vigencia, suspensión y revocación

Clave del sistema

Permite firmar la autenticación. Conservarla no prolonga la autorización.

Token de acceso

Tiene una duración corta. Respeta su vencimiento; obtener otro no renueva el periodo del piloto.

Autorización de prueba

Termina en la fecha acordada con GTD, visible en el detalle de la conexión. Coordina su continuidad antes de que venza.

Suspender detiene el acceso y conserva la configuración y el historial. Reanudar preparación, cuando aparece, sólo permite continuar la preparación: no habilita automáticamente la API. Si ya estaba habilitada, coordina la continuidad con GTD.

Revocar retira el acceso de forma definitiva. Para volver a conectar ese sistema necesitarás una conexión nueva y su habilitación.

Un token que aún no vence no garantiza acceso si se suspende o revoca la conexión o termina su autorización. Una comprobación exitosa anterior permanece como dato histórico.

El piloto no ofrece renovación automática del periodo ni rotación de claves por autoservicio.

6. Pide ayuda a GTD

En el detalle del sistema abre Información para soporte. Comparte la referencia de la conexión, su estado de habilitación, el código de error y la fecha y hora del intento. Añade la referencia de la petición cuando esté disponible.

No compartas claves privadas, tokens ni contraseñas. Si envías una captura, oculta esos datos. La documentación pública no contiene las credenciales ni los resultados de tu organización.

Este enlace abre tu aplicación de correo; no envía un mensaje automáticamente. Si no se abre, escribe a contacto@gestionatusdatos.cl desde tu correo habitual.

Dentro de GTD, selecciona tu organización y abre Conexiones API. Si todavía no tienes acceso al piloto, contacta al equipo antes de preparar credenciales.