Preparar transferencia Santander

Beta privada.

Tool IDsantander_empresas.transferencia.preparar
Nombre MCPsantander_empresas__transferencia__preparar
Conectorsantander_empresas
Planoaction
Scope (permiso)santander_empresas:tef:preparar
Authconnection_credentials
Versión1
Sensiblesí
Deprecadono
ComportamientoreadOnly=false, destructive=true, idempotent=true, openWorld=true

Requiere conexión. Indica cuál en cada llamada: header X-Connect-Connection en REST y campo connectionId en el execute_write de MCP. No hay resolución implícita, ni siquiera con una sola conexión activa: la conexión es la empresa. El id sale de conexiones.estado.consultar.

Qué hace

Crea una transferencia unitaria en CLP a un destinatario inscrito, sin visar, firmar ni liberar. Un apoderado completa la autorización en Office Banking. Exige permiso explícito en la conexión y la clave o agente, referencia única e Idempotency-Key UUID v4 estable. Conserva ambas: un resultado desconocido no autoriza crear otra transferencia. Consulta el estado después de sincronizar.

Entrada

CampoTipoRequeridoDescripción
referenciastringsíReferencia única de negocio en esta conexión. Conserva la misma para recuperar la operación; no la reutilices para otro pago.
cuentaOrigenstring ^\d{6,24}$síNúmero de cuenta de origen de esta conexión, como texto, conservando ceros iniciales.
destinatarioobjetosíDatos del destinatario inscrito. Deben coincidir con los que el banco conserva para esta empresa.
destinatario.bancostringsísantander para un destinatario Santander; para otro banco, su código bancario chileno como texto.
destinatario.cuentastring ^\d{4,24}$síCuenta de destino como texto. Debe estar inscrita en la empresa.
destinatario.rutstringsíRUT del destinatario; se normaliza a cuerpo-DV.
destinatario.nombrestringsíNombre del destinatario que revisarás antes de autorizar en el banco.
montoobjetosíImporte solicitado en pesos chilenos.
monto.valorstring ^[1-9]\d{0,11}$síPesos enteros positivos, sin puntos, comas ni notación científica.
monto.monedastringsíEsta beta admite pesos chilenos.
glosastringno · default ""Mensaje de la transferencia, hasta 100 caracteres.
JSON Schema de entrada
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "referencia": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "Referencia única de negocio en esta conexión. Conserva la misma para recuperar la operación; no la reutilices para otro pago."
    },
    "cuentaOrigen": {
      "type": "string",
      "pattern": "^\\d{6,24}$",
      "description": "Número de cuenta de origen de esta conexión, como texto, conservando ceros iniciales."
    },
    "destinatario": {
      "type": "object",
      "properties": {
        "banco": {
          "type": "string",
          "minLength": 1,
          "maxLength": 12,
          "description": "santander para un destinatario Santander; para otro banco, su código bancario chileno como texto."
        },
        "cuenta": {
          "type": "string",
          "pattern": "^\\d{4,24}$",
          "description": "Cuenta de destino como texto. Debe estar inscrita en la empresa."
        },
        "rut": {
          "description": "RUT del destinatario; se normaliza a cuerpo-DV.",
          "type": "string"
        },
        "nombre": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120,
          "description": "Nombre del destinatario que revisarás antes de autorizar en el banco."
        }
      },
      "required": [
        "banco",
        "cuenta",
        "rut",
        "nombre"
      ],
      "additionalProperties": false,
      "description": "Datos del destinatario inscrito. Deben coincidir con los que el banco conserva para esta empresa."
    },
    "monto": {
      "type": "object",
      "properties": {
        "valor": {
          "type": "string",
          "pattern": "^[1-9]\\d{0,11}$",
          "description": "Pesos enteros positivos, sin puntos, comas ni notación científica."
        },
        "moneda": {
          "type": "string",
          "const": "CLP",
          "description": "Esta beta admite pesos chilenos."
        }
      },
      "required": [
        "valor",
        "moneda"
      ],
      "additionalProperties": false,
      "description": "Importe solicitado en pesos chilenos."
    },
    "glosa": {
      "default": "",
      "description": "Mensaje de la transferencia, hasta 100 caracteres.",
      "type": "string",
      "maxLength": 100
    }
  },
  "required": [
    "referencia",
    "cuentaOrigen",
    "destinatario",
    "monto"
  ],
  "additionalProperties": false
}

Ejemplo

curl
curl -X POST https://connect.emisso.ai/api/v1/tools/santander_empresas.transferencia.preparar/execute \
  -H "Authorization: Bearer connect_sk_…" \
  -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
  -H "Idempotency-Key: 9d1f4c2a-7b30-4e58-9c11-2f6a8de5b743" \
  -H "Content-Type: application/json" \
  -d '{"input":{"referencia":"factura-1842","cuentaOrigen":"000123456789","destinatario":{"banco":"santander","cuenta":"000987654321","rut":"76123456-0","nombre":"Proveedor SpA"},"monto":{"valor":"150000","moneda":"CLP"},"glosa":"Factura 1842"}}'
MCP · meta-tool execute_write
{
  "tool": "santander_empresas.transferencia.preparar",
  "params": {
    "referencia": "factura-1842",
    "cuentaOrigen": "000123456789",
    "destinatario": {
      "banco": "santander",
      "cuenta": "000987654321",
      "rut": "76123456-0",
      "nombre": "Proveedor SpA"
    },
    "monto": {
      "valor": "150000",
      "moneda": "CLP"
    },
    "glosa": "Factura 1842"
  },
  "connectionId": "conn_9tKfR2mQx4Vb",
  "idempotencyKey": "9d1f4c2a-7b30-4e58-9c11-2f6a8de5b743"
}

Clave de idempotencia obligatoria. Sin ella la llamada responde idempotency_key_missing. Genera un UUID v4 nuevo por operación y envíalo en Idempotency-Key (REST) o en idempotencyKey (MCP). Repite la misma clave solo al reintentar esa operación.

Salida esperada (200):

{
  "data": {
    "transferenciaId": "trf_5tYw2nRk88Ma",
    "referencia": "factura-1842",
    "codigoBanco": "00012345",
    "estado": "pendiente_firma",
    "accionesPendientes": [
      "firma"
    ],
    "observadoEn": "2026-11-20T19:00:00Z",
    "siguienteAccion": {
      "tipo": "autorizar_en_banco",
      "mensaje": "Un apoderado debe revisar y autorizar la transferencia en Office Banking."
    },
    "puedeReintentar": false
  },
  "meta": {
    "request_id": "req_…",
    "tool_id": "santander_empresas.transferencia.preparar",
    "plane": "action",
    "latency_ms": 7410,
    "audit_status": "recorded"
  }
}

Salida

CampoTipoRequeridoDescripción
transferenciaIdstringsíIdentificador durable de Emisso. Úsalo para consultar esta operación.
referenciastringnullsí
codigoBancostringnullsí
estado"creada" · "pendiente_firma" · "pendiente_visacion" · "pendiente_liberacion" · "en_proceso" · "realizada" · …síÚltimo resultado confirmado. creada no significa autorizada; realizada no acredita recepción por el destinatario. resultado_desconocido nunca autoriza volver a crear.
accionesPendienteslista de "firma" · "visacion" · "liberacion"síControles que el banco todavía requiere. Pueden coexistir. Vacío no acredita pago si el estado es desconocido.
observadoEnstringnullsí
siguienteAccionobjetosíQué debe hacer la persona o integración después de esta respuesta.
siguienteAccion.tipo"autorizar_en_banco" · "revisar_en_banco" · "consultar_estado" · "ninguna"síPróximo paso según la última observación de esta operación.
siguienteAccion.mensajestringsíInstrucción para revisar, autorizar o seguir el resultado de la transferencia.
puedeReintentarbooleanosíConserva la referencia y clave. Una repetición recupera esta operación; no solicita otro envío al banco.
JSON Schema de salida
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "transferenciaId": {
      "type": "string",
      "minLength": 1,
      "description": "Identificador durable de Emisso. Úsalo para consultar esta operación."
    },
    "referencia": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Referencia de negocio; null únicamente si se recuperó un resultado incierto sin su registro de preparación."
    },
    "codigoBanco": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Identificador de transferencia confirmado por el banco, como texto; null cuando no se conoce."
    },
    "estado": {
      "type": "string",
      "enum": [
        "creada",
        "pendiente_firma",
        "pendiente_visacion",
        "pendiente_liberacion",
        "en_proceso",
        "realizada",
        "rechazada",
        "resultado_desconocido"
      ],
      "description": "Último resultado confirmado. creada no significa autorizada; realizada no acredita recepción por el destinatario. resultado_desconocido nunca autoriza volver a crear."
    },
    "accionesPendientes": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "firma",
          "visacion",
          "liberacion"
        ]
      },
      "description": "Controles que el banco todavía requiere. Pueden coexistir. Vacío no acredita pago si el estado es desconocido."
    },
    "observadoEn": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Instante ISO 8601 con zona de la última respuesta bancaria confirmada; null si no la hay."
    },
    "siguienteAccion": {
      "type": "object",
      "properties": {
        "tipo": {
          "type": "string",
          "enum": [
            "autorizar_en_banco",
            "revisar_en_banco",
            "consultar_estado",
            "ninguna"
          ],
          "description": "Próximo paso según la última observación de esta operación."
        },
        "mensaje": {
          "type": "string",
          "description": "Instrucción para revisar, autorizar o seguir el resultado de la transferencia."
        }
      },
      "required": [
        "tipo",
        "mensaje"
      ],
      "additionalProperties": false,
      "description": "Qué debe hacer la persona o integración después de esta respuesta."
    },
    "puedeReintentar": {
      "type": "boolean",
      "const": false,
      "description": "Conserva la referencia y clave. Una repetición recupera esta operación; no solicita otro envío al banco."
    }
  },
  "required": [
    "transferenciaId",
    "referencia",
    "codigoBanco",
    "estado",
    "accionesPendientes",
    "observadoEn",
    "siguienteAccion",
    "puedeReintentar"
  ],
  "additionalProperties": false
}

Errores de esta tool

CódigoHTTPReintentableQué hacer
connection_disabled403noReactívala en /connections o usa otra conexión del mismo sistema.
connection_not_found404noUsa uno de los connectionId que lista el error, o revisa la conexión en /connections. No hace falta reactivar nada.
connection_credential_required428noCrea un enlace con conexiones.enlace.crear (modo reconectar si la conexión ya existe) y pide a la persona que entregue la credencial de nuevo. No reintentes con la credencial anterior.
connection_busy409síEspera unos segundos y reintenta. Es una espera transitoria: no necesitas volver a conectar ni ingresar la credencial otra vez.
upstream_error502síReintenta más tarde. Si persiste, el problema está en el sistema externo, no en tu integración.
timeout504síReintenta. Para sincronizaciones largas usa la vía asíncrona y consulta el estado del trabajo.
connector_onboarding_required428noLee el mensaje: dice qué falta. Se completa en el portal de ese sistema, no en Emisso, y después la llamada funciona sin cambios.
connection_scope_not_enabled403noPide a un owner/admin que habilite el scope en /connections para esa conexión, o usa otra que ya lo tenga activo. Cambiar la credencial del actor no resuelve este error.
rate_limited429síEspera y reintenta con backoff exponencial.
upstream_unexpected_response502noNo reintentes: la respuesta es determinista. Repórtalo con el request_id para que actualicemos el conector.
idempotency_key_missing400noGenera un UUID v4, envíalo como Idempotency-Key y reutilízalo solo para reintentos de esta misma operación.
idempotency_in_progress409síEspera unos segundos y reintenta con la MISMA clave. Generar una nueva para la misma operación es lo que duplica el efecto.
idempotency_conflict409noGenera una clave nueva para una operación nueva; reutiliza la clave solo para reintentar la misma.

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