Preparar transferencia Santander
Beta privada.
| Tool ID | santander_empresas.transferencia.preparar |
| Nombre MCP | santander_empresas__transferencia__preparar |
| Conector | santander_empresas |
| Plano | action |
| Scope (permiso) | santander_empresas:tef:preparar |
| Auth | connection_credentials |
| Versión | 1 |
| Sensible | sí |
| Deprecado | no |
| Comportamiento | readOnly=false, destructive=true, idempotent=true, openWorld=true |
Requiere conexión. Indica cuál en cada llamada: header
X-Connect-Connectionen REST y campoconnectionIden elexecute_writede MCP. No hay resolución implícita, ni siquiera con una sola conexión activa: la conexión es la empresa. El id sale deconexiones.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
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
referencia | string | sí | Referencia única de negocio en esta conexión. Conserva la misma para recuperar la operación; no la reutilices para otro pago. |
cuentaOrigen | string ^\d{6,24}$ | sí | Número de cuenta de origen de esta conexión, como texto, conservando ceros iniciales. |
destinatario | objeto | sí | Datos del destinatario inscrito. Deben coincidir con los que el banco conserva para esta empresa. |
destinatario.banco | string | sí | santander para un destinatario Santander; para otro banco, su código bancario chileno como texto. |
destinatario.cuenta | string ^\d{4,24}$ | sí | Cuenta de destino como texto. Debe estar inscrita en la empresa. |
destinatario.rut | string | sí | RUT del destinatario; se normaliza a cuerpo-DV. |
destinatario.nombre | string | sí | Nombre del destinatario que revisarás antes de autorizar en el banco. |
monto | objeto | sí | Importe solicitado en pesos chilenos. |
monto.valor | string ^[1-9]\d{0,11}$ | sí | Pesos enteros positivos, sin puntos, comas ni notación científica. |
monto.moneda | string | sí | Esta beta admite pesos chilenos. |
glosa | string | no · 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 -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"}}'{
"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 enIdempotency-Key(REST) o enidempotencyKey(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
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
transferenciaId | string | sí | Identificador durable de Emisso. Úsalo para consultar esta operación. |
referencia | string | null | sí |
codigoBanco | string | null | sí |
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. |
accionesPendientes | lista de "firma" · "visacion" · "liberacion" | sí | Controles que el banco todavía requiere. Pueden coexistir. Vacío no acredita pago si el estado es desconocido. |
observadoEn | string | null | sí |
siguienteAccion | objeto | sí | 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.mensaje | string | sí | Instrucción para revisar, autorizar o seguir el resultado de la transferencia. |
puedeReintentar | booleano | sí | 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ódigo | HTTP | Reintentable | Qué hacer |
|---|---|---|---|
connection_disabled | 403 | no | Reactívala en /connections o usa otra conexión del mismo sistema. |
connection_not_found | 404 | no | Usa uno de los connectionId que lista el error, o revisa la conexión en /connections. No hace falta reactivar nada. |
connection_credential_required | 428 | no | Crea 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_busy | 409 | sí | Espera unos segundos y reintenta. Es una espera transitoria: no necesitas volver a conectar ni ingresar la credencial otra vez. |
upstream_error | 502 | sí | Reintenta más tarde. Si persiste, el problema está en el sistema externo, no en tu integración. |
timeout | 504 | sí | Reintenta. Para sincronizaciones largas usa la vía asíncrona y consulta el estado del trabajo. |
connector_onboarding_required | 428 | no | Lee 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_enabled | 403 | no | Pide 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_limited | 429 | sí | Espera y reintenta con backoff exponencial. |
upstream_unexpected_response | 502 | no | No reintentes: la respuesta es determinista. Repórtalo con el request_id para que actualicemos el conector. |
idempotency_key_missing | 400 | no | Genera un UUID v4, envíalo como Idempotency-Key y reutilízalo solo para reintentos de esta misma operación. |
idempotency_in_progress | 409 | sí | Espera unos segundos y reintenta con la MISMA clave. Generar una nueva para la misma operación es lo que duplica el efecto. |
idempotency_conflict | 409 | no | Genera 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.