Crear un enlace para conectar un sistema

Crea un enlace de un solo uso donde la persona entrega sus credenciales del sistema para conectarlo.

Tool IDconexiones.enlace.crear
Nombre MCPconexiones__enlace__crear
Conectorconexiones
Planoaction
Scope (permiso)conexiones:write
Authnone
Versión3
Sensiblesí
Deprecadono
ComportamientoreadOnly=false, destructive=false, idempotent=false, openWorld=false

Ruta REST exacta: esta operación es la tool conexiones.enlace.crear, ejecutada mediante POST /api/v1/tools/conexiones.enlace.crear/execute con Content-Type: application/json y el cuerpo {"input":{...}} de esta ficha. Para crear enlaces también existe POST /v1/connect_sessions, con su propio cuerpo: API de control. El título de esta ficha no define otra ruta.

Qué hace

Devuelve el enlace SIEMPRE con su dominio completo visible y explicando quién lo pidió y para qué; nunca lo presentes como un aviso del banco ni del SII. La credencial se cifra en el vault de esta misma organización y no la ve nadie más, tampoco tú. El enlace vence y sirve una sola vez. Puedes fijar 'acceso', 'emitir' y 'alcances' para que la persona solo entregue sus claves; si los omites, los elige ella. Los códigos de acceso salen de 'accesos' en conexiones.sistemas.listar. Si 'costoAdicional' no es null, la conexión nueva se suma al próximo cobro de la organización: díselo a la persona antes de entregar el enlace. Con modo 'activar_emision' y 'conexionId' de una conexión del SII con clave de persona que todavía no emite, la persona solo entrega la clave del certificado digital y la misma conexión pasa a emitir facturas, notas de crédito y boletas. Una conexión con la clave tributaria de la empresa no puede emitir: para eso crea una conexión nueva con modo 'crear', acceso 'portal_credentials_representante' y 'emitir' true. Con modo 'cambiar_clave_certificado' y 'conexionId' de una conexión del SII que ya emite, la persona solo entrega la clave nueva del certificado digital (por ejemplo, porque lo renovó o el SII rechazó la firma); la conexión sigue emitiendo con el mismo id y la clave se comprueba con el próximo documento que emita. Shopify sólo admite modo reconectar con una conexión existente; las tiendas nuevas se instalan desde Shopify App Store. Los demás sistemas de acceso 'oauth_source' (como Mercado Pago) no se conectan ni se renuevan por enlace: la persona los conecta en el panel (Conexiones → Conectar) o los vuelve a autorizar en Ajustes de la conexión. Después de que la persona lo complete, usa 'conexiones.estado.consultar' para saber si ya hay datos.

Entrada

CampoTipoRequeridoDescripción
sistemastringnoCódigo del sistema, tal como lo devuelve conexiones.sistemas.listar. OMÍTELO si no sabes con cuál trabaja quien va a recibir el enlace: entonces el enlace abre el catálogo y la persona elige ahí. Es obligatorio cuando modo es 'reconectar', porque esa conexión ya tiene su sistema.
modo"crear" · "reconectar" · "activar_emision" · "cambiar_clave_certificado"no · default "crear"'crear' para una conexión nueva; 'reconectar' para renovar la credencial de una que ya existe; 'activar_emision' para que una conexión del SII con clave de persona pase a emitir; 'cambiar_clave_certificado' para reemplazar la clave del certificado de una conexión del SII que ya emite.
conexionIdstringnoconn_…, obligatorio cuando modo es 'reconectar', 'activar_emision' o 'cambiar_clave_certificado'.
accesostringnoCódigo del acceso, tal como lo devuelve 'accesos' en conexiones.sistemas.listar. Omítelo para que la persona elija. Solo con 'sistema' y en modo 'crear'.
emitirbooleanono'true' para que la conexión emita documentos tributarios (exige un acceso que emita; si hay uno solo, se fija ese), 'false' para que solo lea. Omítelo para que la persona decida. Solo con 'sistema' y en modo 'crear'.
alcanceslista de stringnoCódigos de los módulos de datos que se habilitan. Tienen que estar servidos por el acceso (o por todos, si no fijas uno). Omítelo para que la persona elija. Solo con 'sistema' y en modo 'crear'.
JSON Schema de entrada
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "sistema": {
      "description": "Código del sistema, tal como lo devuelve conexiones.sistemas.listar. OMÍTELO si no sabes con cuál trabaja quien va a recibir el enlace: entonces el enlace abre el catálogo y la persona elige ahí. Es obligatorio cuando modo es 'reconectar', porque esa conexión ya tiene su sistema.",
      "type": "string"
    },
    "modo": {
      "default": "crear",
      "description": "'crear' para una conexión nueva; 'reconectar' para renovar la credencial de una que ya existe; 'activar_emision' para que una conexión del SII con clave de persona pase a emitir; 'cambiar_clave_certificado' para reemplazar la clave del certificado de una conexión del SII que ya emite.",
      "type": "string",
      "enum": [
        "crear",
        "reconectar",
        "activar_emision",
        "cambiar_clave_certificado"
      ]
    },
    "conexionId": {
      "description": "conn_…, obligatorio cuando modo es 'reconectar', 'activar_emision' o 'cambiar_clave_certificado'.",
      "type": "string"
    },
    "acceso": {
      "description": "Código del acceso, tal como lo devuelve 'accesos' en conexiones.sistemas.listar. Omítelo para que la persona elija. Solo con 'sistema' y en modo 'crear'.",
      "type": "string"
    },
    "emitir": {
      "description": "'true' para que la conexión emita documentos tributarios (exige un acceso que emita; si hay uno solo, se fija ese), 'false' para que solo lea. Omítelo para que la persona decida. Solo con 'sistema' y en modo 'crear'.",
      "type": "boolean"
    },
    "alcances": {
      "description": "Códigos de los módulos de datos que se habilitan. Tienen que estar servidos por el acceso (o por todos, si no fijas uno). Omítelo para que la persona elija. Solo con 'sistema' y en modo 'crear'.",
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}

Ejemplo

curl
curl -X POST https://connect.emisso.ai/api/v1/tools/conexiones.enlace.crear/execute \
  -H "Authorization: Bearer connect_sk_…" \
  -H "Content-Type: application/json" \
  -d '{"input":{"sistema":"sii"}}'
MCP · meta-tool execute_write
{
  "tool": "conexiones.enlace.crear",
  "params": {
    "sistema": "sii"
  }
}

Salida esperada (200):

{
  "data": {
    "url": "https://connect.emisso.ai/c/mYw2kQ81xR4tPnZs",
    "dominio": "connect.emisso.ai",
    "sistema": "sii",
    "sistemaNombre": "Servicio de Impuestos Internos",
    "modo": "crear",
    "expiraEn": "2026-08-07T15:32:11.000Z",
    "intentosMaximos": 5,
    "acceso": null,
    "emitir": null,
    "alcances": null,
    "advertencia": "Este enlace pide credenciales de acceso al sistema. Muéstralo siempre con su dominio completo y di quién lo pidió y para qué. No lo presentes como un aviso del banco ni del SII.",
    "costoAdicional": null
  },
  "meta": {
    "request_id": "req_…",
    "tool_id": "conexiones.enlace.crear",
    "plane": "action",
    "latency_ms": 24,
    "audit_status": "recorded"
  }
}

El enlace vence una hora después de acuñado y sirve una sola vez.

Salida

CampoTipoRequeridoDescripción
urlstringsíEl enlace de un solo uso. Compártelo tal cual, con el dominio visible.
dominiostringsíEl dominio del enlace, ya extraído para mostrarlo junto a la URL.
sistemastringnullsí
sistemaNombrestringnullsí
modo"crear" · "reconectar" · "activar_emision" · "cambiar_clave_certificado"síSi el enlace crea una conexión nueva, renueva la credencial de una existente, activa la emisión del SII en una existente o cambia la clave del certificado digital de una que ya emite.
expiraEnstringsíCuándo vence el enlace (ISO 8601). Vencido, hay que crear otro.
intentosMaximosenterosíCuántos intentos de login admite antes de agotarse.
accesostringnullsí
emitirbooleanonullsí
alcanceslista de stringnullsí
advertenciastringsíTexto de presentación segura del enlace, listo para mostrar a la persona.
costoAdicionalobjetonullsí
costoAdicional.montoUsdnúmerosíLo que suma al mes, en dólares y sin IVA.
costoAdicional.montoUsdConEmisionnúmeronullsí
costoAdicional.planNombrestringsíEl plan de la organización, como lo ve la persona.
costoAdicional.incluidasenterosíCuántas conexiones incluye ese plan.
costoAdicional.mensajestringsíLa frase lista para decírsela a la persona antes de entregar el enlace.
JSON Schema de salida
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "El enlace de un solo uso. Compártelo tal cual, con el dominio visible."
    },
    "dominio": {
      "type": "string",
      "description": "El dominio del enlace, ya extraído para mostrarlo junto a la URL."
    },
    "sistema": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Código del sistema que se va a conectar, o null si el enlace deja que la persona lo elija."
    },
    "sistemaNombre": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Nombre del sistema, para presentar el enlace con claridad. null cuando el enlace no fija uno."
    },
    "modo": {
      "type": "string",
      "enum": [
        "crear",
        "reconectar",
        "activar_emision",
        "cambiar_clave_certificado"
      ],
      "description": "Si el enlace crea una conexión nueva, renueva la credencial de una existente, activa la emisión del SII en una existente o cambia la clave del certificado digital de una que ya emite."
    },
    "expiraEn": {
      "type": "string",
      "description": "Cuándo vence el enlace (ISO 8601). Vencido, hay que crear otro."
    },
    "intentosMaximos": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "Cuántos intentos de login admite antes de agotarse."
    },
    "acceso": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "El acceso que fijó el enlace, o null si lo elige la persona."
    },
    "emitir": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "description": "Si la conexión va a emitir, o null si lo decide la persona."
    },
    "alcances": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        {
          "type": "null"
        }
      ],
      "description": "Los módulos de datos que fijó el enlace, o null si los elige la persona."
    },
    "advertencia": {
      "type": "string",
      "description": "Texto de presentación segura del enlace, listo para mostrar a la persona."
    },
    "costoAdicional": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "montoUsd": {
              "type": "number",
              "description": "Lo que suma al mes, en dólares y sin IVA."
            },
            "montoUsdConEmision": {
              "anyOf": [
                {
                  "type": "number"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Lo que suma al mes si la conexión del SII se crea emitiendo DTE, que cuesta más que una de lectura. null si el sistema no emite. Siempre null en conexiones.conexion.habilitar, donde la variante ya está fijada."
            },
            "planNombre": {
              "type": "string",
              "description": "El plan de la organización, como lo ve la persona."
            },
            "incluidas": {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991,
              "description": "Cuántas conexiones incluye ese plan."
            },
            "mensaje": {
              "type": "string",
              "description": "La frase lista para decírsela a la persona antes de entregar el enlace."
            }
          },
          "required": [
            "montoUsd",
            "montoUsdConEmision",
            "planNombre",
            "incluidas",
            "mensaje"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "Lo que suma a la próxima renovación la conexión que nazca de este enlace, porque la organización ya usa lo que cubre el precio de su plan. null cuando no suma nada. Si no es null, díselo a la persona ANTES de entregar el enlace, con 'mensaje', en dólares + IVA. Con un enlace sin sistema aplica si el que elija se cobra. Si trae 'montoUsdConEmision', dile los dos montos: leer y emitir DTE. Con 'emitir' fijado, 'mensaje' ya dice el único monto que aplica."
    }
  },
  "required": [
    "url",
    "dominio",
    "sistema",
    "sistemaNombre",
    "modo",
    "expiraEn",
    "intentosMaximos",
    "acceso",
    "emitir",
    "alcances",
    "advertencia",
    "costoAdicional"
  ],
  "additionalProperties": false
}

Errores de esta tool

Toda llamada puede devolver además los códigos transversales (validation_error, unauthorized, scope_not_granted, rate_limited, entre otros): el detalle vive en el catálogo de errores.

En esta página