# Preparar transferencia Santander

> Beta privada.



{/* AUTO-GENERATED by @emisso/codegen. DO NOT EDIT. */}

|                     |                                                                   |
| ------------------- | ----------------------------------------------------------------- |
| **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-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`](/docs/referencia/conexiones/estado-consultar).

## Qué hace [#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 [#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.                                                                            |

<details>
  <summary>
    JSON Schema de entrada
  </summary>

  ```json
  {
    "$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
  }
  ```
</details>

## Ejemplo [#ejemplo]

```bash title="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"}}'
```

```json title="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):**

```json
{
  "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 [#salida]

| Campo                     | Tipo                                                                                                                      | Requerido | Descripción                                                                                                                                                             |                                                                                                             |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `transferenciaId`         | string                                                                                                                    | sí        | Identificador durable de Emisso. Úsalo para consultar esta operación.                                                                                                   |                                                                                                             |
| `referencia`              | string                                                                                                                    | null      | sí                                                                                                                                                                      | Referencia de negocio; null únicamente si se recuperó un resultado incierto sin su registro de preparación. |
| `codigoBanco`             | string                                                                                                                    | null      | sí                                                                                                                                                                      | Identificador de transferencia confirmado por el banco, como texto; null cuando no se conoce.               |
| `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í                                                                                                                                                                      | Instante ISO 8601 con zona de la última respuesta bancaria confirmada; null si no la hay.                   |
| `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.                                                                |                                                                                                             |

<details>
  <summary>
    JSON Schema de salida
  </summary>

  ```json
  {
    "$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
  }
  ```
</details>

## Errores de esta tool [#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](/docs/referencia/errores).


---

Esta página es parte de la documentación de Emisso. El índice completo, con cada página y su descripción, está en https://connect.emisso.ai/llms.txt. Esta misma página en HTML: https://connect.emisso.ai/docs/referencia/santander_empresas/transferencia-preparar.
