Gestión de Cuentas Bancarias

CREAR O ACTUALIZAR CUENTAS BANCARIAS DE PERSONA

CABECERA

Endpoint para registrar o actualizar cuentas bancarias de una persona (Cliente, Proveedor o Personal). Si una cuenta con el mismo número ya existe, se actualiza; si no existe, se inserta como nueva.

Endpoint: /api/persona/cuenta

POST - Para crear cuentas bancarias
PUT - Para actualizar cuentas bancarias

CUERPO

JSON de Ejemplo (Payload)

{
    "fl_proveedor": 0,
    "fl_personal": 0,
    "fl_cliente": 1,
    "cliente_synergy_id": "1234",
    "cuenta": [
        {
            "banco": "BCP",
            "tipo_cuenta": "AHORROS",
            "moneda": "PEN",
            "numero_cuenta": "19112345678",
            "cci": "00219111234567801",
            "nombre_cuenta": "JUAN PEREZ GARCIA"
        },
        {
            "banco": "BBVA",
            "tipo_cuenta": "CORRIENTE",
            "moneda": "USD",
            "numero_cuenta": "0011223344",
            "cci": "01100112233445501",
            "nombre_cuenta": "JUAN PEREZ GARCIA"
        }
    ]
}

Validaciones Detalladas

Campos Principales

Atributo	Valor Esperado	Tipo de dato	Requisito	Longitud
fl_proveedor	0 = no es proveedor 1 = es proveedor	Integer	obligatorio	1 exacto
fl_personal	0 = no es personal 1 = es personal	Integer	obligatorio	1 exacto
fl_cliente	0 = no es cliente 1 = es cliente	Integer	obligatorio	1 exacto
cliente_synergy_id	Identificador único de la persona en Synergy	String	obligatorio	1 hasta 30
cuenta	Array de objetos con información de cuentas bancarias	Array	obligatorio	mínimo 1

Nota: Al menos uno de los flags (fl_cliente, fl_proveedor, fl_personal) debe ser 1.

Estructura de Cada Cuenta (Objeto dentro del Array)

Atributo	Valor Esperado	Tipo de dato	Requisito	Longitud
banco	Nombre del banco. Ejemplo: BCP, BBVA, INTERBANK	String	obligatorio	1 hasta 100
tipo_cuenta	Tipo de cuenta. Ejemplo: AHORROS, CORRIENTE	String	obligatorio	4 hasta 20
moneda	PEN = Soles USD = Dólares	String	obligatorio	3 exactos
numero_cuenta	Número de cuenta bancaria	String	obligatorio	1 hasta 20
cci	Código de cuenta interbancario	String	obligatorio	1 hasta 50
nombre_cuenta	Nombre del titular de la cuenta	String	obligatorio	1 hasta 100

Guía Visual para el Usuario (Valores Sugeridos)

Estos valores son una ayuda visual para el usuario al momento de llenar el payload.
No son un catálogo rígido de BD para tipo_cuenta, pero se recomienda usar una nomenclatura estándar.

`tipo_cuenta` (sugerido)

CORRIENTE
AHORROS
REMUNERADA

`banco` (catálogo estático sugerido)

BANCO DE COMERCIO
BANCO DE CRÉDITO DEL PERÚ
BANCO INTERAMERICANO DE FINANZAS (BANBIF)
BANCO PICHINCHA
BBVA
CITIBANK PERÚ
INTERBANK
MIBANCO
SCOTIABANK PERÚ
BANCO GNB PERÚ
BANCO FALABELLA
BANCO RIPLEY
BANCO SANTANDER PERÚ
BANCO AZTECA
BANK OF CHINA
CENCOSUD SCOTIA
ICBC PERU BANK
AGROBANCO
BANCO DE LA NACIÓN
COFIDE
FONDO MIVIVIENDA
AMÉRIKA
CREDISCOTIA
CONFIANZA
COMPARTAMOS
CREDINKA
EFECTIVA
PROEMPRESA
MITSUI AUTO FINANCE
OH!
QAPAQ
TFC
CMAC AREQUIPA
CMAC CUSCO
CMAC DEL SANTA
CMAC TRUJILLO
CMAC HUANCAYO
CMAC ICA
CMAC MAYNAS
CMAC PAITA
CMAC PIURA
CMAC SULLANA
CMAC TACNA
CMCP LIMA
CRAC NCASUR
CRAC LOS ANDES
CRAC PRYMERA
CRAC SIPÁN
CRAC DEL CENTRO
CRAC RAÍZ

RESPUESTA EXITOSA

Código HTTP 201

{
    "codigo_http": 201,
    "estado": "success",
    "titanic_id": 123,
    "cuentas_insertadas": 1,
    "cuentas_actualizadas": 1,
    "total_procesadas": 2,
    "mensaje": "Cuentas bancarias procesadas correctamente"
}

POSIBLES ERRORES DE VALIDACIÓN

1. Método HTTP No Permitido - Código 405

Escenario: Se utiliza un método diferente a POST o PUT

{
    "codigo_http": 405,
    "estado": "method_not_allowed",
    "mensaje": "Método no permitido. Use POST o PUT."
}

2. Error de Validación de Campos - Código 400

Escenario: Los datos enviados no cumplen con las reglas de validación

{
    "codigo_http": 400,
    "estado": "validation_error",
    "mensaje": "Error en la validación",
    "detalles": {
        "cliente_synergy_id": "El campo cliente_synergy_id es requerido",
        "cuenta": "El campo cuenta es requerido"
    }
}

3. Cuenta No es un Array - Código 400

Escenario: El campo cuenta no es un array o está vacío

{
    "codigo_http": 400,
    "estado": "validation_error",
    "mensaje": "El campo cuenta debe ser un array con al menos una cuenta"
}

4. Error en Validación de Cuenta Específica - Código 400

Escenario: Una cuenta del array no cumple con las validaciones

{
    "codigo_http": 400,
    "estado": "validation_error",
    "mensaje": "Error en la validación de la cuenta índice 0",
    "detalles": {
        "banco": "El campo banco es requerido",
        "numero_cuenta": "El campo numero_cuenta debe tener entre 1 y 20 caracteres"
    }
}

5. Persona No Encontrada - Código 404

Escenario: No se encontró la persona con el cliente_synergy_id proporcionado

{
    "codigo_http": 404,
    "estado": "not_found",
    "mensaje": "No se encontró la persona con el cliente_synergy_id proporcionado en las tablas correspondientes"
}