Endpoints de bancos y filtro por afiliación

1.Listado de Bancos

Su propósito principal es permitir que el cliente consulte dinámicamente las entidades disponibles y determine, mediante sus atributos, qué capacidades operativas tiene cada banco (como la disponibilidad del flujo de afiliación.

Autenticación: No requerida (se aplica únicamente rate limit por dirección IP).
Respuesta: Una lista de objetos con la estructura de la Institución Bancaria (IBP).

Endpoint
GET api/v1/banks

Response

{
  "Code": "0001",
  "Name": "BCV",
  "Active": true,
  "SypagoClient": true,
  "HasAccountLinkingFlow": true,
  ...
}

info

Filtro para afiliación: El cliente debe usar solo bancos donde HasAccountLinkingFlow sea true. Solo esos bancos tienen flujo de vinculación de cuentas en la API.

2.Búsqueda del flujo de afiliación del banco (antes de iniciar el flujo)

Antes de iniciar el proceso de afiliación, es indispensable consultar el flujo específico del banco seleccionado. Esto permite identificar los pasos requeridos, los datos necesarios para cada etapa y las acciones disponibles (como el reenvío de OTP), facilitando así el diseño de la interfaz de usuario y la correcta implementación de las llamadas al API.

Endpoint
GET api/v1/bank/affiliate/flow

Aspecto	Detalle
Metodo	GET
URL	/api/v1/bank/affiliate/flow
Autenticación	Requerida. Header Authorization: Bearer Token del usuario.
Rate limit	Sí (por IP).

Query params (obligatorios):

Parámetro	Tipo	Requerido	Descripción
bank_code	string	Código del banco de 4 dígitos (ej. 0172).	Debe coincidir con un banco de la lista GET api/v1/banks que tenga hasAccountLinkingFlow: true.
acct_type	string	Tipo de cuenta. Debe ser exactamente CNTA (cuenta bancaria).	Cualquier otro valor devuelve 400.

GET /api/v1/bank/affiliate/flow?bank_code=0001&acct_type=CNTA
Authorization: Bearer <token>

Codigos HTTP	Descripción
400	Si bank_code falta o está vacío, con mensaje indicando que bank_code es requerido
400	Si bank_code no son 4 dígitos ("bank_code debe ser un código de 4 dígitos").
400	Si acct_type falta o está vacío ("acct_type es requerido en query param")
400	Si acct_type no es CNTA, si no hay flujo configurado para ese bank_code y tipo de cuenta respuesta de error según implementación
200	OK con un JSON que describe el flujo

El body es un objeto BankAffiliationFlow con la siguiente estructura:

Response
Response
{
  "bank_code": "0172",
  "flow_type": "MULTI_STEP",
  "account_type": "CNTA",
  "initial_requirements": {
    "standart_required_fields": ["account", "document_info"],
    "metadata_fields": []
  },
  "steps": [
    {
      "step_name": "validate_account",
      "required_data": [],
      "message": "Cuenta validada.",
      "available_actions": []
    },
    {
      "step_name": "generate_otp",
      "required_data": [],
      "message": "Se ha enviado un OTP.",
      "available_actions": []
    },
    {
      "step_name": "verify_otp",
      "required_data": [
        { "name": "otp", "type": "string" }
      ],
      "message": "Ingrese el OTP.",
      "available_actions": [
        {
          "action": "resend_otp",
          "required_data": [],
          "link": "...",
          "method": "POST",
          "cooldown_seconds": 60
        }
      ]
    }
  ]
}

Campo	Tipo	Descripción
bank_code	string	Código del banco (ej. "0172"). Coincide con el solicitado en el request.
flow_type	string(enum)	"SINGLE_STEP" o "MULTI_STEP". Indica si la afiliación se completa en un solo paso o en varios (por ejemplo validar cuenta → generar OTP → verificar OTP).
account_type	string(enum)	Tipo de cuenta; en la práctica "CNTA".
initial_requirements	object	Requisitos que debe cumplir el payload al iniciar el flujo (POST api/v1/account/affiliate).
steps	array	Lista ordenada de pasos del flujo. El cliente debe ejecutarlos en ese orden según las respuestas del API.

Objeto initial_requirements:

Campo	Tipo	Descripción
standart_required_fields	string[]	Nombres de secciones obligatorias en el JSON de inicio de afiliación. Típicamente ["account", "document_info"]: es decir, el cliente debe enviar siempre account y document_info al iniciar.
metadata_fields	array	Lista de campos de metadata opcionales (cada uno con name, type, required, description si aplica).

Cada ítem del array steps es un objeto con:

Campo	Tipo	Descripción
step_name	string	Identificador del paso. Valores estándar: validate_account, generate_otp, verify_otp. El cliente usará este valor en PUT .../affiliate/{flowId}/{stepName}.
required_data	array	Lista de campos que el cliente debe enviar en el body al ejecutar este paso. Cada elemento tiene name, type, y opcionalmente required, description. Si está vacío, el body puede ser {}.
message	string	Mensaje descriptivo para el usuario (ej. "Ingrese el OTP", "Se ha enviado un OTP").
available_actions	array	Acciones opcionales en este paso (ej. reenviar OTP). Si está vacío, no hay acciones adicionales.
link	string	(Puede venir rellenado en respuestas de afiliación; en el flujo del banco puede no estar o ser relativo.) URL o path para llamar a este paso.
method	string	Método HTTP para el paso; típicamente "PUT".
cooldown_seconds	number	Segundos de espera antes de poder repetir el paso o una acción .

Cada ítem de available_actions tiene:

Campo	Tipo	Descripción
action	string	Nombre de la acción (ej. resend_otp). Se usa en POST .../affiliate/{flowId}/action/{actionName}.
required_data	array	Campos obligatorios en el body al ejecutar esta acción (misma estructura que required_data del step).
link	string	URL o path de la acción.
method	string	Método HTTP; para acciones suele ser "POST".
cooldown_seconds	number	Segundos de espera antes de poder ejecutar de nuevo esta acción.
description	string	(Opcional.) Descripción de la acción.

Endpoints de bancos y filtro por afiliación