Validaciones por lote

Si necesitas validar muchas cuentas a la vez, puedes enviarlas en un lote de hasta 1000 validaciones con una sola petición, en vez de una petición por cuenta. Shinkansen guarda el lote, te responde de inmediato y realiza cada validación de forma asíncrona. Cuando ya no queda ninguna pendiente, te envía los resultados de todo el lote en una sola llamada a tu webhook de lotes.

Cada validación de un lote funciona igual que una validación individual: mismos campos, mismos estados y mismas respuestas (ver Estructura y Estados). Lo que cambia es cómo se envían y cómo recibes los resultados.

sequenceDiagram
  autonumber
    Cliente-)Shinkansen: POST /v1/validation/batches
    Shinkansen--)Cliente: 200 (lote pendiente)
    Shinkansen--)Cliente: POST /webhooks/validations/batches (resultados del lote)

Enviar un lote

{
  "id": "batch-2026-10-13-001",
  "source_name": "payroll",
  "validation_requests": [
    {
      "id": "3c11df48-dfab-41eb-a3c1-b9f90a0da063",
      "account_details": {
        "name": "Romulo Gallegos",
        "identification": { "id_schema": "CLID", "id": "12383287-6" },
        "financial_institution": { "fin_id_schema": "SHINKANSEN", "fin_id": "SCOTIABANK_CL" },
        "account": "1513523451",
        "account_type": "current_account",
        "currency": "CLP",
        "email": "romulo.gallegos@shinkansen.finance"
      }
    },
    {
      "id": "e60044b2-2ecc-49c2-b20b-b20c07292753",
      "account_details": {
        "account": "012180001234567899",
        "account_type": "clabe",
        "currency": "MXN"
      }
    }
  ]
}

• id del lote: lo eliges tú y debe ser único para tu organización. Es obligatorio.
• id de cada validación: también lo eliges tú, es obligatorio y debe ser único para tu organización, considerando tanto los lotes como las validaciones individuales. No puede repetirse dentro del lote.
• source_name: opcional, una etiqueta libre para identificar el origen del lote.
• validation_requests: entre 1 y 1000 validaciones.

Si el lote es aceptado, la respuesta es 200 con el lote en estado pending y cada validación con su id y su status:

{
  "id": "batch-2026-10-13-001",
  "source_type": "api",
  "source_name": "payroll",
  "status": "pending",
  "timeout_at": "2026-10-13T15:15:00Z",
  "closed_at": null,
  "validation_requests": [
    { "id": "3c11df48-dfab-41eb-a3c1-b9f90a0da063", "status": "pending" },
    { "id": "e60044b2-2ecc-49c2-b20b-b20c07292753", "status": "pending" }
  ],
  "inserted_at": "2026-10-13T15:00:00Z",
  "updated_at": "2026-10-13T15:00:00Z"
}

Recibir los resultados

Cuando ninguna validación del lote está pendiente, Shinkansen envía una sola llamada a tu webhook de lotes, con todas las validaciones del lote en su estado final:

{
  "document": {
    "header": {
      "shinkansen_message_id": "17c3ed26-8229-8d06-e917-3ed6139eeb03",
      "message_id": "eabe65b3-c88b-fb60-6f67-aed25f72e9a6",
      "creation_date": "2026-10-13T15:02:01Z",
      "sender": { "fin_id_schema": "SHINKANSEN", "fin_id": "SHINKANSEN" },
      "receiver": { "fin_id_schema": "SHINKANSEN", "fin_id": "TU_FIN_ID" },
      "batch_id": "batch-2026-10-13-001"
    },
    "validation_requests": [
      {
        "id": "3c11df48-dfab-41eb-a3c1-b9f90a0da063",
        "status": "performed",
        "account_details": { "...": "..." },
        "response": {
          "return_code": "valid_account_details",
          "return_message": "OK"
        },
        "inserted_at": "2026-10-13T15:00:00Z",
        "updated_at": "2026-10-13T15:01:10Z"
      }
    ]
  }
}

• El webhook de lotes es distinto del webhook de validaciones individuales. Se configura por separado en el Dashboard de Shinkansen. Las validaciones de un lote no se envían al webhook de validaciones individuales.
• Se firma igual que el webhook individual: la cabecera Shinkansen-Validator-Signature lleva la firma HMAC SHA-256 del body, en hexadecimal, calculada con tu secreto compartido de Validator. Ver API Keys y Firmas.
• Responde 2xx cuando hayas guardado los resultados. Cualquier otra respuesta, o la falta de respuesta, se reintenta, hasta 5 intentos con esperas crecientes. Un 409 se considera ya recibido.
• header.shinkansen_message_id es el mismo en todos los reintentos de un lote, así que puedes usarlo para descartar entregas repetidas.
• Si no tienes configurado el webhook de lotes, no se envía nada: consulta los resultados con GET /v1/validation/batches/{id}.

Shinkansen revisa los lotes cada minuto, así que el webhook llega hasta un minuto después del último resultado.

Tiempo máximo del lote

Un lote tiene 15 minutos para completarse, contados desde que lo envías (campo timeout_at). Las validaciones que sigan pendientes a esa hora se cierran con status error, return_code unable_to_validate y return_message batch_timed_out, y el lote se cierra con lo que haya. Si necesitas otro tiempo máximo, conversa con tu ejecutivo de Shinkansen.

Reintentos e idempotencia

Si no sabes si tu lote llegó, por ejemplo por un error de red, reenvía el mismo lote con el mismo id. Nunca se crea un segundo lote:

• Si el id del lote ya existe, la respuesta es 409 con el lote guardado, en su estado actual, y "idempotent_replay": true.
• Si el id del lote es nuevo pero alguna validación tiene un id ya usado, en otro lote o como validación individual, o repetido dentro del lote, la respuesta es 409 y se rechaza el lote. El body trae solo las validaciones en conflicto: las ya guardadas, con su estado actual (igual que el 409 del endpoint de validaciones individuales), y las repetidas dentro del lote, tal como las enviaste.

Chequeo de acceso en lotes

perform_account_access_check funciona igual que en una validación individual, con las mismas condiciones: solo en 🇨🇱 CLP y solo si tienes habilitado el producto validator_variable_amount_cl.

• Si una sola validación del lote pide el chequeo sin cumplir ambas condiciones, se rechaza todo el lote con 403 y "error": "product_not_enabled", indicando cuáles validaciones lo pidieron.

Errores

En un 400, los errores de cada validación vienen identificados por su id. Solo se listan las validaciones con error:

{
  "errors": {
    "validation_requests": [
      {
        "id": "e60044b2-2ecc-49c2-b20b-b20c07292753",
        "errors": {
          "account_details": { "account": ["Invalid 'clabe' account, Invalid check digit."] }
        }
      }
    ]
  }
}

Docs detallados de APIs relacionadas