Aplicar un pago a una cuenta por cobrar

API de Wizerp › Aplicar un pago a una cuenta por cobrar

Cuentas por cobrar

Aplicar un pago a una cuenta por cobrar

# Aplicar un pago a una cuenta por cobrar

POST https://api.wizerp.com/api/v1/cxc/{clave}/pagos

Registra el cobro de una cuenta por cobrar, igual que la pantalla de Cobranza: crea el depósito en tu cuenta bancaria (sube su saldo), aplica el pago a la cuenta por cobrar (baja su saldo y el de la venta) y genera la póliza contable. NO se puede deshacer borrando: se cancela desde Wizerp.

COMPLEMENTO DE PAGO (REP): si la cuenta por cobrar es de una FACTURA PPD, se encola su complemento de pago ante el SAT (la respuesta dice "encolado"; el UUID llega después). Una factura PUE o una remisión se aplican sin REP. Una factura sin método de pago capturado se rechaza (422) antes de mover nada.

En esta versión: una cuenta por cobrar por llamada, de una factura o remisión de Wizerp con desglose de subtotal e impuestos (las antiguas sin desglose se cobran desde Wizerp); el importe no puede pasar del saldo; la cuenta bancaria debe ser de tu empresa, estar activa y estar en la misma moneda; formas de pago 02 cheque, 03 transferencia, 04 tarjeta de crédito y 28 tarjeta de débito (efectivo no); la fecha no puede ser futura ni anterior a la factura; la referencia es obligatoria. Repetir el mismo pago (cuenta, fecha, importe y referencia) responde 409, igual que si ya hay en esa cuenta un depósito con esos datos sin aplicar.

Toda escritura necesita la cabecera Idempotency-Key: un valor único por operación (por ejemplo un UUID) que repites tal cual al reintentar. Con la misma clave y los mismos datos se devuelve la respuesta guardada, sin duplicar; con la misma clave y datos distintos responde 409.

Permiso: cxc:write

## Cuerpo JSON
- `importe` (decimal): Importe del pago, mayor que cero y no mayor que el saldo pendiente. Obligatorio.
- `cuenta_bancaria` (entero): Clave de tu cuenta bancaria donde entró el dinero (activa y en la moneda de la cuenta por cobrar). Obligatorio.
- `forma_pago_sat` (texto): Forma de pago del SAT: "02" cheque, "03" transferencia, "04" tarjeta de crédito, "28" tarjeta de débito. Obligatorio.
- `fecha` (texto): Fecha del pago AAAA-MM-DD (no futura, no anterior a la factura). Va al complemento de pago. Obligatorio.
- `referencia` (texto): Referencia o número de operación del banco (máximo 100). Obligatorio.

POST https://api.wizerp.com/api/v1/cxc/{clave}/pagos

https://api.wizerp.com/api/v1/cxc/{clave}/pagos

Registra el cobro de una cuenta por cobrar, igual que la pantalla de Cobranza: crea el depósito en tu cuenta bancaria (sube su saldo), aplica el pago a la cuenta por cobrar (baja su saldo y el de la venta) y genera la póliza contable. NO se puede deshacer borrando: se cancela desde Wizerp.

COMPLEMENTO DE PAGO (REP): si la cuenta por cobrar es de una FACTURA PPD, se encola su complemento de pago ante el SAT (la respuesta dice "encolado"; el UUID llega después). Una factura PUE o una remisión se aplican sin REP. Una factura sin método de pago capturado se rechaza (422) antes de mover nada.

En esta versión: una cuenta por cobrar por llamada, de una factura o remisión de Wizerp con desglose de subtotal e impuestos (las antiguas sin desglose se cobran desde Wizerp); el importe no puede pasar del saldo; la cuenta bancaria debe ser de tu empresa, estar activa y estar en la misma moneda; formas de pago 02 cheque, 03 transferencia, 04 tarjeta de crédito y 28 tarjeta de débito (efectivo no); la fecha no puede ser futura ni anterior a la factura; la referencia es obligatoria. Repetir el mismo pago (cuenta, fecha, importe y referencia) responde 409, igual que si ya hay en esa cuenta un depósito con esos datos sin aplicar.

Toda escritura necesita la cabecera Idempotency-Key: un valor único por operación (por ejemplo un UUID) que repites tal cual al reintentar. Con la misma clave y los mismos datos se devuelve la respuesta guardada, sin duplicar; con la misma clave y datos distintos responde 409.

Requiere el permiso cxc:write en la llave · contrato del 2026-10-11

Parámetros de ruta

clave entero en la URL

Clave de la cuenta por cobrar (la de GET /cxc).

Cuerpo JSON

Además, toda escritura necesita la cabecera Idempotency-Key: un valor único por operación (por ejemplo un UUID) que repites tal cual al reintentar.

importe decimal obligatorio

Importe del pago, mayor que cero y no mayor que el saldo pendiente. Obligatorio.

cuenta_bancaria entero obligatorio

Clave de tu cuenta bancaria donde entró el dinero (activa y en la moneda de la cuenta por cobrar). Obligatorio.

forma_pago_sat texto obligatorio

Forma de pago del SAT: "02" cheque, "03" transferencia, "04" tarjeta de crédito, "28" tarjeta de débito. Obligatorio.

fecha texto obligatorio

Fecha del pago AAAA-MM-DD (no futura, no anterior a la factura). Va al complemento de pago. Obligatorio.

referencia texto obligatorio

Referencia o número de operación del banco (máximo 100). Obligatorio.

Respuestas

400 Petición mal formada: filtro no permitido, filtro vacío, cursor o límite inválidos, o una cabecera de navegador

401 La llave no es válida, está revocada, venció, o la empresa dejó de ser PRO

403 La llave no tiene el permiso que pide esta operación

404 La ruta no existe, o tu empresa no tiene la API habilitada

409 Conflicto: misma Idempotency-Key con datos distintos, o ya existe un registro con ese identificador (RFC, SKU)

413 El cuerpo pasa del máximo

415 El cuerpo no va como JSON (falta Content-Type: application/json)

422 Un dato no es válido para tu empresa

429 Pasaste un tope. La respuesta trae Retry-After

500 Falló de nuestro lado. Reintenta y reporta el valor de peticion

503 Tu empresa tiene demasiadas peticiones en curso, o la búsqueda no está disponible. Trae Retry-After

Lenguaje

Petición · cURL

curl -X POST https://api.wizerp.com/api/v1/cxc/{clave}/pagos \
  -H "Authorization: Bearer wzk_live_…" \
  -H "X-Wizerp-Key-Id: 208_a3f91c7d" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -d '{"importe":0,"cuenta_bancaria":1,"forma_pago_sat":"02","fecha":"ejemplo","referencia":"ejemplo"}'

$ch = curl_init('https://api.wizerp.com/api/v1/cxc/{clave}/pagos');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer wzk_live_…',
    'X-Wizerp-Key-Id: 208_a3f91c7d',
    'Content-Type: application/json',
    'Idempotency-Key: 3fa85f64-5717-4562-b3fc-2c963f66afa6',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    '{"importe":0,"cuenta_bancaria":1,"forma_pago_sat":"02","fecha":"ejemplo","referencia":"ejemplo"}');
$r = json_decode(curl_exec($ch), true);

const r = await fetch(
  "https://api.wizerp.com/api/v1/cxc/{clave}/pagos",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer wzk_live_…",
      "X-Wizerp-Key-Id": "208_a3f91c7d",
      "Content-Type": "application/json",
      "Idempotency-Key": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    },
    body: JSON.stringify({"importe":0,"cuenta_bancaria":1,"forma_pago_sat":"02","fecha":"ejemplo","referencia":"ejemplo"}),
  }
);
const datos = await r.json();

import requests

r = requests.post(
    "https://api.wizerp.com/api/v1/cxc/{clave}/pagos",
    headers={
        "Authorization": "Bearer wzk_live_…",
        "X-Wizerp-Key-Id": "208_a3f91c7d",
        "Idempotency-Key": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    },
    json={"importe":0,"cuenta_bancaria":1,"forma_pago_sat":"02","fecha":"ejemplo","referencia":"ejemplo"},
)
datos = r.json()

Las escrituras se prueban desde tu propio sistema con tu llave; la consola pública es solo para consultas. Copia el ejemplo de arriba: ya lleva el cuerpo y la cabecera Idempotency-Key.

Respuesta elige un ejemplo

{
    "ok": true,
    "pago": 184027,
    "cxc": 184027,
    "deposito": 184027,
    "importe": "texto",
    "saldo_anterior": "texto",
    "saldo_nuevo": "texto",
    "rep": "texto",
    "rep_motivo": "texto"
}

{
    "ok": false,
    "error": {
        "codigo": "json_invalido",
        "mensaje": "Petición mal formada: filtro no permitido, filtro vacío, cursor o límite inválidos, o una cabecera de navegador",
        "peticion": "req_dca2d22e3324f9a8"
    }
}

{
    "ok": false,
    "error": {
        "codigo": "llave_invalida",
        "mensaje": "La llave no es válida, está revocada, venció, o la empresa dejó de ser PRO",
        "peticion": "req_dca2d22e3324f9a8"
    }
}

{
    "ok": false,
    "error": {
        "codigo": "limite_excedido",
        "mensaje": "Pasaste un tope. La respuesta trae Retry-After",
        "peticion": "req_dca2d22e3324f9a8"
    }
}

Ver la referencia completa