Boufin API v2 — Casos de prueba (Sandbox)

Conjunto de casos de prueba listos para usar contra el sandbox de la API v2 de Boufin, pensados como herramienta de desarrollo: copia el request, ejecútalo y obtén un resultado determinista por cada escenario. Todos los casos son de banca empresa. Para el contrato completo de la API consulta Boufin API v2 y la referencia OpenAPI.

Resultados deterministas

En el sandbox, el resultado de cada tarea se decide por la combinación de username + businessId: cada par de la tabla produce siempre el mismo taskStatus. El password solo necesita cumplir el esquema de la entidad (ver Requerimientos de Credenciales); en estos ejemplos se usa el placeholder ********.

El flujo es siempre el mismo: POST /api/v2/tasks devuelve un taskId, y luego GET /api/v2/tasks/{taskId} entrega el resultado.

Webhook no disponible en sandbox (por el momento)

Por el momento el webhook no está disponible en sandbox: aunque envíes el objeto webhook en el request, no se emitirá ninguna notificación. Consulta el resultado por polling con GET /api/v2/tasks/{taskId}. Por eso ningún caso de esta página usa webhook.

Credenciales: raw vs encrypted

Por legibilidad, los casos de esta página envían las credenciales en modo raw (texto plano, protegido por TLS). Los modos encrypted (cifrado temporal) y persisted (cifrado persistente) son equivalentes: cambian solo cómo viaja el campo value, no el resultado.

Banca empresa requiere businessId, username y password. El mismo payload se ve así en cada modo:

raw — los campos van anidados bajo value:

{
  "mode": "raw",
  "value": {
    "businessId": "55696323-1",
    "username": "7261704-5",
    "password": "********"
  }
}

encrypted — los mismos campos se cifran con tu token de sesión y se envían como un único string ${CIPHER_TEXT}-${IV}:

{
  "mode": "encrypted",
  "value": "czuqliRO1DKMj4bbPIzMEIYyj4+GqFLBXXc/TM7d3x0==-Qlih4F8+I6kZv8xCuSAc2A=="
}

Cómo generar el value cifrado usando tu token de sesión está explicado en la guía de cifrado temporal.

Resumen de casos

#	Entidad	Acciones	taskStatus	username	businessId
1	banco-santander-business	movement	COMPLETED	7261704-5	55696323-1
2	banco-estado-business	product-balance + movement	COMPLETED	29385544-7	64989126-5
3	banco-chile-business	product-balance + movement	PARTIAL	28028749-0	95531304-6
4	banco-itau-business	product-balance	CREDENTIALS_WRONG	19213533-8	78964912-K
5	banco-santander-business	product-balance + movement	FAILED	23151994-7	92450468-4

---

Caso 1 — COMPLETED (acción simple)

Una sola acción movement sobre banco-santander-business. Devuelve COMPLETED con los movimientos del rango solicitado.

Request (raw):

curl --request POST \
  'https://${URL}/api/v2/tasks' \
  -H 'Authorization: Bearer ${TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "entity": "banco-santander-business",
    "credentials": {
      "mode": "raw",
      "value": {
        "businessId": "55696323-1",
        "username": "7261704-5",
        "password": "********"
      }
    },
    "actions": [
      { "id": "movement", "params": { "dateRange": { "startDate": "2026-05-22", "endDate": "2026-06-22" } } }
    ]
  }'

El mismo request en modo encrypted (solo cambia credentials):

curl --request POST \
  'https://${URL}/api/v2/tasks' \
  -H 'Authorization: Bearer ${TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "entity": "banco-santander-business",
    "credentials": {
      "mode": "encrypted",
      "value": "czuqliRO1DKMj4bbPIzMEIYyj4+GqFLBXXc/TM7d3x0==-Qlih4F8+I6kZv8xCuSAc2A=="
    },
    "actions": [
      { "id": "movement", "params": { "dateRange": { "startDate": "2026-05-22", "endDate": "2026-06-22" } } }
    ]
  }'

Respuesta de creación:

{ "taskId": "5cbae0b5e1b5d035d99469f42c653ff4bb8aecdf9dbdb8e10f45a31677683369" }

Resultado (GET /api/v2/tasks/{taskId}):

{
  "taskStatus": "COMPLETED",
  "results": {
    "username": "7261704-5",
    "businessId": "55696323-1",
    "entityId": "banco-santander-business",
    "actions": [
      {
        "id": "movement",
        "status": "COMPLETED",
        "output": [
          /* movimientos */
        ]
      }
    ]
  }
}

---

Caso 2 — COMPLETED (composición)

Dos acciones en una sola tarea sobre banco-estado-business: product-balance y movement. Ambas completan.

Request (raw):

curl --request POST \
  'https://${URL}/api/v2/tasks' \
  -H 'Authorization: Bearer ${TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "entity": "banco-estado-business",
    "credentials": {
      "mode": "raw",
      "value": {
        "businessId": "64989126-5",
        "username": "29385544-7",
        "password": "********"
      }
    },
    "actions": [
      { "id": "product-balance" },
      { "id": "movement", "params": { "dateRange": { "startDate": "2026-05-22", "endDate": "2026-06-22" } } }
    ]
  }'

Resultado:

{
  "taskStatus": "COMPLETED",
  "results": {
    "username": "29385544-7",
    "businessId": "64989126-5",
    "entityId": "banco-estado-business",
    "actions": [
      {
        "id": "product-balance",
        "status": "COMPLETED",
        "output": {
          /* productos */
        }
      },
      {
        "id": "movement",
        "status": "COMPLETED",
        "output": [
          /* movimientos */
        ]
      }
    ]
  }
}

---

Caso 3 — PARTIAL

Sobre banco-chile-business: product-balance completa pero movement falla. La tarea consolida en PARTIAL y cada acción reporta su propio estado.

Request (raw):

curl --request POST \
  'https://${URL}/api/v2/tasks' \
  -H 'Authorization: Bearer ${TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "entity": "banco-chile-business",
    "credentials": {
      "mode": "raw",
      "value": {
        "businessId": "95531304-6",
        "username": "28028749-0",
        "password": "********"
      }
    },
    "actions": [
      { "id": "product-balance" },
      { "id": "movement", "params": { "dateRange": { "startDate": "2026-05-22", "endDate": "2026-06-22" } } }
    ]
  }'

Resultado:

{
  "taskStatus": "PARTIAL",
  "results": {
    "username": "28028749-0",
    "businessId": "95531304-6",
    "entityId": "banco-chile-business",
    "actions": [
      {
        "id": "product-balance",
        "status": "COMPLETED",
        "output": {
          /* productos */
        }
      },
      {
        "id": "movement",
        "status": "FAILED",
        "output": null,
        "error": {
          "code": "TIMEOUT_ERROR",
          "message": "Entity did not respond during extraction"
        }
      }
    ]
  }
}

---

Caso 4 — CREDENTIALS_WRONG

Credenciales incorrectas para la entidad. La tarea no ejecuta ninguna acción y results es null.

Request (raw):

curl --request POST \
  'https://${URL}/api/v2/tasks' \
  -H 'Authorization: Bearer ${TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "entity": "banco-itau-business",
    "credentials": {
      "mode": "raw",
      "value": {
        "businessId": "78964912-K",
        "username": "19213533-8",
        "password": "********"
      }
    },
    "actions": [
      { "id": "product-balance" }
    ]
  }'

Resultado:

{
  "taskStatus": "CREDENTIALS_WRONG",
  "results": null
}

---

Caso 5 — FAILED (error general)

Sobre banco-santander-business: ninguna acción se completa. A diferencia de las fallas de credenciales, results sí se incluye con la misma estructura que en COMPLETED/PARTIAL: cada acción reporta su status y un objeto error, para que veas qué se intentó y por qué falló.

Request (raw):

curl --request POST \
  'https://${URL}/api/v2/tasks' \
  -H 'Authorization: Bearer ${TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "entity": "banco-santander-business",
    "credentials": {
      "mode": "raw",
      "value": {
        "businessId": "92450468-4",
        "username": "23151994-7",
        "password": "********"
      }
    },
    "actions": [
      { "id": "product-balance" },
      { "id": "movement", "params": { "dateRange": { "startDate": "2026-05-22", "endDate": "2026-06-22" } } }
    ]
  }'

Resultado:

{
  "taskStatus": "FAILED",
  "results": {
    "username": "23151994-7",
    "businessId": "92450468-4",
    "entityId": "banco-santander-business",
    "actions": [
      {
        "id": "product-balance",
        "status": "FAILED",
        "output": null,
        "error": {
          "code": "ACTION_ERROR",
          "message": "The service is currently unavailable"
        }
      },
      {
        "id": "movement",
        "status": "FAILED",
        "output": null,
        "error": {
          "code": "ENTITY_API_ERROR",
          "message": "Entity rejected the request"
        }
      }
    ]
  }
}