Saltar al contenido
Facturador

Crear método de pago

POST /api/payment-method-types

Autenticación: Bearer del usuario del tenant (Authorization: Bearer <api_token>).

Registra un método de pago. El servidor asigna el código.

Quién puede usarlo: solo usuarios de tipo administrador (type = admin). Con el token de un vendedor responde 403.

Formato de respuesta: estándar {success, data, message?} (registro único). Responde 201 con el método creado (incluye su id).

Cuerpo (JSON):

Campo Tipo Obligatorio Descripción / valores permitidos
description string (máx. 255) Sí al crear Nombre que ve el cajero (p. ej. Yape, Transferencia BBVA).
is_credit boolean No true = condición de crédito (plazo de cobro, p. ej. A 45 días), no una forma de cobro. Por defecto false.
number_days integer (0 a 3650) No Días de plazo de una condición de crédito. Por defecto 0.
goes_to_cash_drawer boolean No true = el dinero entra y sale del cajón (efectivo) y se cuadra en el arqueo de la caja. Por defecto false.
use_for_income boolean No Se ofrece para cobrar (ventas, cobranzas, ingresos). Por defecto true.
use_for_expense boolean No Se ofrece para pagar (compras, gastos). Por defecto false.
destination_rule string No any · type:bank · type:wallet · type:gateway · type:card · account:<id>. Por defecto any. Ver la tabla de reglas.
is_active boolean No Activo (se ofrece en los formularios). Por defecto true.
has_card boolean No Pide marca de tarjeta al registrar el pago.
charge numeric (0 a 100) No Recargo porcentual informativo del método.

Regla de destino (destination_rule) — un solo valor decide a dónde va (o de dónde sale) el dinero:

Valor Significado Cómo queda el método
any Se elige la cuenta al registrar cada cobro o pago. default_destination_id = null, allowed_destination_type = null
type:bank Solo cuentas bancarias. allowed_destination_type = "bank"
type:wallet Solo billeteras digitales (Yape, Plin...). allowed_destination_type = "wallet"
type:gateway Solo pasarelas de pago (Niubiz, Izipay...). Una pasarela recibe cobros pero no paga. allowed_destination_type = "gateway"
type:card Solo tarjetas de la empresa. Una tarjeta de la empresa paga pero no recibe cobros. allowed_destination_type = "card"
account:<id> Siempre esa cuenta (id de Cuentas bancarias, bank-accounts). Al registrar un pago con este método hay que enviar esa misma cuenta como payment_destination_id; otra se rechaza. default_destination_id = <id>

Un método que va al cajón (goes_to_cash_drawer: true, el efectivo) no tiene cuenta: su regla siempre queda en any y sus cobros van a la caja abierta (payment_destination_id = "cash").

Reglas:

  • El código (id) lo asigna el servidor al crear: el primer libre desde 11 (los códigos 01 a 10 están reservados). No se envía ni cambia al editar; si se envía, se ignora.
  • Un método nuevo se coloca al final del orden (sort_order).
  • is_credit: true → no es medio de pago (is_payment_medium: false): se fuerza goes_to_cash_drawer, use_for_income y use_for_expense a false y no aparece al registrar pagos.
  • Un medio de pago sin uso (ni cobrar ni pagar) queda inactivo aunque envíes is_active: true (has_no_use: true). Márcale un uso para activarlo.
  • goes_to_cash_drawer: true → la regla de destino queda en any (el efectivo no tiene cuenta).
  • La cuenta (o el tipo) tiene que servir para todo lo marcado: si use_for_income y la cuenta no recibe cobros, o use_for_expense y la cuenta no permite pagos, responde 409 y no guarda nada.

Errores:

  • 403 si el usuario no es administrador.
  • 422 {success: false, message: {campo: [errores]}} si falla la validación de campos. (falta description, destination_rule con formato inválido o account:<id> de una cuenta que no existe).
  • 409 si la cuenta o el tipo elegido no sirve para lo marcado, o si ya no quedan códigos libres.
  • 401 sin token o con un token inválido.

Cuerpo

Content-Type: application/json

{
  "description": "Plin",
  "goes_to_cash_drawer": false,
  "use_for_income": true,
  "use_for_expense": true,
  "destination_rule": "account:5"
}

Respuestas

201 — Creado

{
  "success": true,
  "data": {
    "id": "21",
    "description": "Plin",
    "sort_order": 140,
    "is_active": true,
    "is_credit": false,
    "number_days": 0,
    "has_card": false,
    "charge": 0.0,
    "is_payment_medium": true,
    "goes_to_cash_drawer": false,
    "use_for_income": true,
    "use_for_expense": true,
    "destination_rule": "account:5",
    "default_destination_id": 5,
    "allowed_destination_type": null,
    "destination_label": "PLIN TIENDA CENTRO",
    "uses_label": "Cobros y pagos",
    "has_no_use": false,
    "can_delete": true,
    "logo_url": null,
    "initials": "PL",
    "monogram_color": "#155e75"
  },
  "message": "Método de pago registrado con éxito"
}

409 — La cuenta no sirve para lo marcado

{
  "success": false,
  "message": "\"NIUBIZ TIENDA\" no permite pagos. Desmarca \"Para pagar\" o elige otra cuenta."
}

422 — Regla de destino inválida

{
  "success": false,
  "message": {
    "destination_rule": [
      "destination_rule debe ser \"any\", \"type:bank\", \"type:wallet\", \"type:gateway\", \"type:card\" o \"account:<id de la cuenta>\"."
    ]
  }
}

403 — Usuario no administrador

{
  "success": false,
  "message": "Solo un administrador puede gestionar este recurso."
}

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.