---
title: "Crear un enlace para conectar un sistema"
method: POST
path: "/v1/tools/conexiones.enlace.crear/execute"
tags: ["conexiones"]
---

# Crear un enlace para conectar un sistema

`POST /v1/tools/conexiones.enlace.crear/execute`

## Request

- Base URL: `https://connect.emisso.ai/api`
- URL: `https://connect.emisso.ai/api/v1/tools/conexiones.enlace.crear/execute`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://connect.emisso.ai/authorize`, token URL `https://connect.emisso.ai/token`, scopes: `conexiones:write`)

Crea un enlace de un solo uso donde la persona entrega sus credenciales del sistema para conectarlo. 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. Después de que la persona lo complete, usa 'conexiones.estado.consultar' para saber si ya hay datos.

## Request body

- object
  - `input` ConexionesEnlaceCrearInput, required
    - `sistema` string: 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.
    - `modo` 'crear' | 'reconectar': 'crear' para una conexión nueva; 'reconectar' para renovar la credencial de una que ya existe.
    - `conexionId` string: conn_…, obligatorio cuando modo es 'reconectar'.
    - `acceso` string: 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'.
    - `emitir` boolean: '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'.
    - `alcances` string[]: 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'.

## Response `200`

La tool corrió bien. 'data' es la salida de la tool tal cual, y 'meta' trae el 'request_id' que identifica esta llamada en la bitácora.

- object
  - `data` ConexionesEnlaceCrearOutput, required
    - `url` string, required: El enlace de un solo uso. Compártelo tal cual, con el dominio visible.
    - `dominio` string, required: El dominio del enlace, ya extraído para mostrarlo junto a la URL.
    - `sistema` string, nullable, required: Código del sistema que se va a conectar, o null si el enlace deja que la persona lo elija.
    - `sistemaNombre` string, nullable, required: Nombre del sistema, para presentar el enlace con claridad. null cuando el enlace no fija uno.
    - `modo` 'crear' | 'reconectar', required: Si el enlace crea una conexión nueva o renueva la credencial de una existente.
    - `expiraEn` string, required: Cuándo vence el enlace (ISO 8601). Vencido, hay que crear otro.
    - `intentosMaximos` integer, required: Cuántos intentos de login admite antes de agotarse.
    - `acceso` string, nullable, required: El acceso que fijó el enlace, o null si lo elige la persona.
    - `emitir` boolean, nullable, required: Si la conexión va a emitir, o null si lo decide la persona.
    - `alcances` string[], nullable, required: Los módulos de datos que fijó el enlace, o null si los elige la persona.
    - `advertencia` string, required: Texto de presentación segura del enlace, listo para mostrar a la persona.
    - `costoAdicional` object, nullable, required: 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.
      - `montoUsd` number, required: Lo que suma al mes, en dólares y sin IVA.
      - `montoUsdConEmision` number, nullable, required: 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` string, required: El plan de la organización, como lo ve la persona.
      - `incluidas` integer, required: Cuántas conexiones incluye ese plan.
      - `mensaje` string, required: La frase lista para decírsela a la persona antes de entregar el enlace.
  - `meta` ResponseMeta
    - `request_id` string, required: Identificador que el servidor le da a esta llamada (req_…). Correlaciona con la fila de la bitácora y es lo primero que pide soporte: guárdalo en tus logs.
    - `operation_request_id` string, uuid: Identidad del intento e-Boleta original. Se conserva al reproducir el resultado del journal; request_id identifica la llamada actual.
    - `tool_id` string, required: La tool que se ejecutó, con su id punteado.
    - `plane` 'action' | 'read', required: 'read' = la llamada escribió en el plano persistido (un sync). 'action' = efímera, no persistió nada de negocio: actuar afuera, o leer lo que un sync ya dejó.
    - `latency_ms` integer, required: Cuánto tardó la ejecución, en milisegundos.
    - `audit_status` 'recorded' | 'degraded', required: 'recorded' = la bitácora recibió la fila de esta llamada. 'degraded' = la acción se hizo pero el registro cayó a un respaldo duradero. Nunca convierte una acción exitosa en un error, porque reintentar por eso sería pagar o emitir dos veces.
    - `idempotency` 'replayed': Presente solo cuando una tool destructiva devolvió la respuesta guardada de un intento previo con la misma Idempotency-Key. Significa que en ESTA llamada no ocurrió ningún efecto nuevo.

## Other responses

- `400`: validation_error (400)
- `401`: unauthorized (401)
- `403`: scope_not_granted | connection_scope_not_enabled | alcance_not_enabled
- `404`: tool_not_found (404)
- `409`: connection_ambiguous | connection_busy
- `428`: connection_credential_required (428)
- `500`: internal_error (500)

---

[API](https://skmtc.dev/emisso/apis/emisso-connect-api.md) · [All operations](https://skmtc.dev/emisso/apis/emisso-connect-api/llms.txt) · [OpenAPI document](https://skmtc.dev/emisso/apis/emisso-connect-api/revisions/e766c01ef2a0?raw)