Documentación API de GTD

Piloto RAT · Sólo datos ficticios

Actualiza una actividad desde tu sistema

Envía una actividad de tratamiento autorizada, actualiza su nombre y consulta qué ocurrió. El mismo registro aparece en el mapa de tratamientos de GTD.

Requiere habilitación específica del equipo GTD

Una conexión de sólo consulta no permite estos envíos. Este piloto permite crear una actividad sintética previamente acordada y actualizar únicamente su nombre. No completa todos los campos de un RAT ni está habilitado para datos de clientes reales.

Para conexiones con habilitación sostenida, consulta la guía de varias actividades y revisiones en GTD.

1. Prepara el acceso

  1. En Conexiones API, registra el sistema de prueba con el permiso Enviar observaciones de tratamiento. La consulta de resultados se incluye. Conserva la conexión de consulta que ya tengas.
  2. Genera y guarda la clave privada; registra sólo la pública. Sigue la guía de conexión si necesitas ayuda.
  3. Coordina con GTD la habilitación y la versión inicial de la actividad: referencia de origen, nombre, finalidad, categorías y estado. Esa versión queda registrada como límite de la regla automática.
  4. Continúa cuando GTD confirme la habilitación. Comprueba los permisos efectivos y la fecha de vencimiento de la conexión.

Descarga estos tres archivos en la misma carpeta. Necesitas Node.js 20 o posterior y la clave privada guardada en tu equipo.

Autenticación (.mjs)Envío y consulta RAT (.mjs)Evento de ejemplo (.json)Contrato OpenAPI (.yaml)

2. Envía la versión inicial

En el JSON, reemplaza source.connectionRef por el identificador de tu conexión y occurredAt por la fecha y hora UTC actual. El contenido de payload debe coincidir exactamente con la versión autorizada por GTD. El ejemplo descargado no concede esa autorización.

node gtd-api-rat.mjs --client-id "IDENTIFICADOR_DEL_CLIENTE" --key-file "./gtd-api-clave-privada.json" --event-file "./gtd-api-rat-evento.json" --idempotency-key "rat-prueba-inicial-0001"

Guarda el publicEventId de la respuesta. accepted significa recibido; todavía debes consultar si el cambio quedó aplicado.

3. Consulta el resultado

node gtd-api-rat.mjs --client-id "IDENTIFICADOR_DEL_CLIENTE" --key-file "./gtd-api-clave-privada.json" --event-id "inevt_REFERENCIA_RECIBIDA"
applied — Aplicado
La actividad fue creada o actualizada. activity.id identifica el mismo registro entre envíos; activity.name contiene el nombre aplicado por ese envío.
awaiting_review — Necesita atención
No se aplicó el cambio. reason.message explica por qué. Contacta a GTD con la referencia del evento: este piloto no incluye aprobación de excepciones por API.
failed — No completado
No asumas que el registro se actualizó. Conserva la referencia y pide ayuda.

En GTD, abre Conexiones API → tu sistema → Historial de la conexión y consulta el resultado. Las actividades aplicadas también aparecen en Mapa de tratamientos.

4. Actualiza el nombre

Conserva sourceRecordRef y todos los datos de la actividad excepto name. Asigna un nuevo eventId, una fecha occurredAt posterior y una nueva clave de idempotencia. Envía el evento y consulta su resultado como en los pasos anteriores.

Una finalidad, categoría o estado diferente necesita revisión. Si alguien modificó el nombre, finalidad o categorías de personas directamente en GTD, la automatización se detiene para evitar reemplazar esa edición.

Los demás campos del RAT permanecen bajo gestión de GTD; este alcance no promete sincronizar el RAT completo.

Reintentos y soporte

Si se interrumpe la comunicación, conserva el mismo cuerpo completo, eventId, fecha y clave de idempotencia. Si tienes la referencia, consulta primero el resultado. Reenviar exactamente el mismo evento devuelve duplicate y no aplica el cambio dos veces.

IDEMPOTENCY_CONFLICT indica que reutilizaste la misma referencia con otro contenido. Para una modificación nueva, crea un evento y una clave nuevos. Los recibos e idempotencia de este piloto se conservan durante siete días; consulta a GTD antes de reintentar fuera de ese plazo.

Un error 401 requiere revisar la autenticación; 403 indica permisos insuficientes; 404 puede indicar piloto cerrado o referencia no accesible; 409 puede indicar una capacidad no habilitada. No crees conexiones adicionales para resolver errores.

Al pedir soporte incluye organización, nombre del sistema, publicEventId, código del error y hora. No compartas la clave privada ni tokens. Usa contacto@gestionatusdatos.cl?subject=Ayuda%20con%20la%20API%20de%20GTD.