Crear cuenta
POST /api/bank-accounts
Autenticación: Bearer del usuario del tenant (Authorization: Bearer <api_token>).
Registra una cuenta bancaria, billetera, pasarela o tarjeta.
Quién puede usarlo: solo usuarios de tipo administrador (type = admin). Con el token de un vendedor responde 403.
| Campo | Tipo | Obligatorio | Descripción / valores permitidos |
|---|---|---|---|
type |
string | Sí | bank cuenta bancaria, wallet billetera digital (Yape, Plin...), gateway pasarela de pago (Culqi, Niubiz...), card tarjeta de la empresa. |
bank_id |
integer | Sí si type = bank |
Banco. Para otros tipos se guarda null. Los ids de banco se pueden ver en bank_id/bank_description de cuentas existentes (GET /api/bank-accounts) o pedirlos al administrador. |
description |
string | Sí | Nombre de la cuenta (p. ej. BCP SOLES, YAPE TIENDA). |
number |
string | Sí | Número de cuenta, celular de la billetera o código del comercio. |
currency_type_id |
string | Sí | Moneda: PEN soles, USD dólares. |
cci |
string | No | Código de cuenta interbancario. |
initial_balance |
numeric | Sí | Saldo inicial (≥ 0). |
show_in_documents |
boolean | Sí | true para imprimir la cuenta en los comprobantes. Solo aplica a bank y wallet; para los otros tipos se guarda false. |
status |
integer | No | 1 activa, 0 inactiva. |
establishment_id |
integer | No | Establecimiento al que pertenece. null = cuenta general, disponible en todos. |
receives_income |
boolean | No | Si puede recibir cobros (ventas, ingresos). |
allows_payments |
boolean | No | Si puede usarse para pagar (gastos, compras). |
Errores: 422 si falta un campo obligatorio, type no es válido o falta bank_id en una cuenta bancaria.
Cuerpo
Content-Type: application/json
{
"type": "bank",
"bank_id": 2,
"description": "BCP SOLES",
"number": "191-12345678-0-12",
"currency_type_id": "PEN",
"cci": "00219100123456780122",
"initial_balance": 0,
"show_in_documents": true,
"status": 1,
"establishment_id": null,
"receives_income": true,
"allows_payments": true
}
Respuestas
201 — Creada
{
"success": true,
"data": {
"id": 3,
"type": "bank",
"bank_id": 2,
"description": "BCP SOLES",
"number": "191-12345678-0-12",
"currency_type_id": "PEN",
"cci": "00219100123456780122",
"status": 1,
"initial_balance": "0.00",
"show_in_documents": true,
"establishment_id": null,
"receives_income": true,
"allows_payments": true,
"bank_description": "BANCO DE CREDITO DEL PERU",
"type_description": "Cuenta bancaria"
},
"message": "Cuenta registrada con éxito"
}
422 — Falta el banco
{
"success": false,
"message": {
"bank_id": [
"El campo bank id es obligatorio."
]
}
}
Pruébalo
Prueba este endpoint con tu empresa y tu token: elige la URL en Servers, pega el token en Authorize y haz clic en Try it out.