Skip to main content
GET
/
api
/
bancos
Gestión de Bancos y Cuentas Bancarias
curl --request GET \
  --url https://api.example.com/api/bancos \
  --header 'Content-Type: application/json' \
  --data '
{
  "nombre": "<string>",
  "codigo_sunat": "<string>",
  "activo": true,
  "id_banco": 123,
  "numero_cuenta": "<string>",
  "tipo_cuenta": "<string>",
  "moneda": "<string>",
  "saldo_actual": 123,
  "titular": "<string>",
  "cci": "<string>",
  "tipo": "<string>",
  "monto": 123,
  "fecha_movimiento": "<string>",
  "referencia": "<string>",
  "descripcion": "<string>",
  "saldo_banco": 123,
  "observaciones": "<string>"
}
'
{
  "404": {},
  "409": {},
  "success": true,
  "data": [
    {
      "id_cuenta": 123,
      "id_banco": 123,
      "numero_cuenta": "<string>",
      "tipo_cuenta": "<string>",
      "moneda": "<string>",
      "saldo_actual": 123,
      "saldo_banco": 123,
      "titular": "<string>",
      "cci": "<string>",
      "activa": true,
      "banco": {}
    }
  ]
}

​
Autenticación

Los endpoints de bancos requieren autenticación mediante token Bearer y permisos de finanzas.

​
Endpoints de Bancos

​
Listar Bancos

GET /api/bancos Retorna el catálogo de bancos disponibles.

​
Parámetros de Query

​
solo_activos
boolean
Filtrar solo bancos activos (true/false)
​
search
string
Buscar por nombre o código SUNAT

​
Respuesta

{
  "success": true,
  "data": [
    {
      "id_banco": 1,
      "nombre": "Banco de Crédito del Perú",
      "codigo_sunat": "002",
      "activo": true
    },
    {
      "id_banco": 2,
      "nombre": "BBVA Continental",
      "codigo_sunat": "011",
      "activo": true
    },
    {
      "id_banco": 3,
      "nombre": "Interbank",
      "codigo_sunat": "003",
      "activo": true
    }
  ]
}

​
Crear Banco

POST /api/bancos - Requiere permiso finanzas.create

​
Parámetros del Body

​
nombre
string
required
Nombre del banco
​
codigo_sunat
string
required
Código de 3 dígitos asignado por SUNAT
​
activo
boolean
Estado del banco (por defecto: true)

​
Actualizar Banco

PUT /api/bancos/{id} - Requiere permiso finanzas.edit

​
Eliminar Banco

DELETE /api/bancos/{id} - Requiere permiso finanzas.delete No permite eliminar si existen cuentas bancarias asociadas.

​
Cuentas Bancarias

​
Listar Cuentas Bancarias

GET /api/cuentas-bancarias - Requiere permiso banco.view Retorna todas las cuentas bancarias de la empresa.

​
Respuesta

​
success
boolean
Indica si la operación fue exitosa
​
data
array
Lista de cuentas bancarias con información del banco
{
  "success": true,
  "data": [
    {
      "id_cuenta": 1,
      "id_banco": 1,
      "numero_cuenta": "19412345678901",
      "tipo_cuenta": "Corriente",
      "moneda": "PEN",
      "saldo_actual": 15480.50,
      "saldo_banco": 15480.50,
      "titular": "SANTO DOMINGO S.A.C.",
      "cci": "00219400123456789012",
      "activa": true,
      "banco": {
        "id_banco": 1,
        "nombre": "Banco de Crédito del Perú",
        "codigo_sunat": "002"
      }
    }
  ]
}

​
Crear Cuenta Bancaria

POST /api/cuentas-bancarias - Requiere permiso banco.create

​
Parámetros del Body

​
id_banco
integer
required
ID del banco (debe existir en la tabla bancos)
​
numero_cuenta
string
required
Número de cuenta (máximo 50 caracteres, debe ser único)
​
tipo_cuenta
string
required
Tipo de cuenta: ‘Corriente’ o ‘Ahorros’
​
moneda
string
required
Moneda: ‘PEN’, ‘USD’, o ‘EUR’
​
saldo_actual
decimal
required
Saldo inicial de la cuenta (debe ser mayor o igual a 0)
​
titular
string
required
Nombre del titular de la cuenta (máximo 255 caracteres)
​
cci
string
Código de Cuenta Interbancario (debe tener exactamente 17 dígitos)

​
Ejemplo de Solicitud

curl -X POST \
  https://tudominio.com/api/cuentas-bancarias \
  -H 'Authorization: Bearer TU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "id_banco": 1,
    "numero_cuenta": "19412345678901",
    "tipo_cuenta": "Corriente",
    "moneda": "PEN",
    "saldo_actual": 10000.00,
    "titular": "SANTO DOMINGO S.A.C.",
    "cci": "00219400123456789012"
  }'

​
Actualizar Cuenta Bancaria

PUT /api/cuentas-bancarias/{id} - Requiere permiso banco.edit

​
Eliminar Cuenta Bancaria

DELETE /api/cuentas-bancarias/{id} - Requiere permiso banco.delete

​
Movimientos Bancarios

​
Listar Movimientos

GET /api/cuentas-bancarias/{id}/movimientos - Requiere permiso banco.view Retorna todos los movimientos de la cuenta bancaria ordenados por fecha descendente. 
{
  "success": true,
  "data": [
    {
      "id_movimiento": 1,
      "tipo": "Deposito",
      "monto": 5000.00,
      "fecha_movimiento": "2024-03-05",
      "referencia": "DEP-001234",
      "descripcion": "Depósito de clientes",
      "conciliado": true
    },
    {
      "id_movimiento": 2,
      "tipo": "Retiro",
      "monto": 1200.00,
      "fecha_movimiento": "2024-03-04",
      "referencia": "RET-005678",
      "descripcion": "Pago a proveedores",
      "conciliado": false
    }
  ]
}

​
Registrar Movimiento

POST /api/cuentas-bancarias/{id}/movimientos - Requiere permiso banco.edit Registra un movimiento bancario (depósito, retiro, transferencia, etc.).

​
Parámetros del Body

​
tipo
string
required
Tipo de movimiento: ‘Deposito’, ‘Retiro’, ‘Transferencia’, ‘Comision’, ‘Interes’
​
monto
decimal
required
Monto del movimiento (debe ser mayor a 0.01)
​
fecha_movimiento
date
required
Fecha del movimiento (formato: Y-m-d)
​
referencia
string
Número de referencia o comprobante (máximo 255 caracteres)
​
descripcion
string
Descripción detallada del movimiento

​
Conciliación Bancaria

​
Listar Conciliaciones

GET /api/cuentas-bancarias/{id}/conciliaciones - Requiere permiso banco.view Retorna el historial de conciliaciones bancarias. 
{
  "success": true,
  "data": [
    {
      "id_conciliacion": 1,
      "fecha_conciliacion": "2024-03-01",
      "saldo_empresa": 15480.50,
      "saldo_banco": 15480.50,
      "diferencia": 0.00,
      "estado": "Conciliada",
      "observaciones": null
    },
    {
      "id_conciliacion": 2,
      "fecha_conciliacion": "2024-02-28",
      "saldo_empresa": 12350.00,
      "saldo_banco": 12400.00,
      "diferencia": 50.00,
      "estado": "Diferencia",
      "observaciones": "Cheque no cobrado aún"
    }
  ]
}

​
Registrar Conciliación

POST /api/cuentas-bancarias/{id}/conciliaciones - Requiere permiso banco.edit Registra una conciliación bancaria comparando saldo del sistema con saldo del banco.

​
Parámetros del Body

​
saldo_banco
decimal
required
Saldo reportado por el banco
​
observaciones
string
Observaciones sobre diferencias encontradas
El sistema automáticamente:
  • Obtiene el saldo_empresa actual de la cuenta
  • Calcula la diferencia = saldo_banco - saldo_empresa
  • Asigna estado = ‘Conciliada’ si diferencia = 0, sino ‘Diferencia’

​
Tipos de Movimiento Bancario

  • Deposito - Ingreso de dinero a la cuenta
  • Retiro - Salida de dinero de la cuenta
  • Transferencia - Transferencia hacia otra cuenta
  • Comision - Comisiones bancarias cobradas
  • Interes - Intereses generados por la cuenta

​
Códigos de Error

​
404
object
Cuenta bancaria no encontrada
{
  "success": false,
  "message": "Cuenta bancaria no encontrada"
}
​
409
object
No se puede eliminar banco con cuentas asociadas
{
  "success": false,
  "message": "No se puede eliminar el banco porque tiene cuentas bancarias asociadas."
}

Build docs developers (and LLMs) love

Get started for freeTalk to us