Crear una venta (cotización o pedido)

API de Wizerp › Crear una venta (cotización o pedido)

Ventas

Crear una venta (cotización o pedido)

# Crear una venta (cotización o pedido)

POST https://api.wizerp.com/api/v1/ventas

Da de alta una COTIZACIÓN o un PEDIDO. La empresa sale de tu llave. En esta versión no se crean remisiones ni facturas y no se timbra: eso llegará después.

El pedido APARTA inventario (reserva existencias); la cotización no mueve nada. Ninguno de los dos descuenta existencias reales, ni genera cuentas por cobrar, ni pólizas, ni CFDI.

Cada renglón es un PRODUCTO del catálogo ("producto") o un CONCEPTO DE TEXTO LIBRE ("concepto"), nunca los dos, y un documento es todo de catálogo o todo de texto libre. Los IMPUESTOS y TOTALES los calcula siempre el servidor: si mandas un importe o un total, se rechaza. El cliente, el almacén y cada producto deben ser de tu empresa.

PRODUCTO DEL CATÁLOGO: mandas producto, cantidad y precio_unitario (y almacen en el documento). El IVA, el IEPS y las retenciones salen del producto.

TEXTO LIBRE (sólo en COTIZACIÓN, igual que en la pantalla de Ventas): mandas concepto (la descripción), clave_sat (clave de producto o servicio del SAT, p. ej. 84111506), unidad (la clave interna de tu catálogo de unidades o una clave SAT que tengas dada de alta, p. ej. H87), iva (IVA16, IVA08, IVA00 o EXEN), cantidad y precio_unitario; opcional retencion (1 Honorarios, 2 Arrendamiento de inmuebles, 3 Arrendamiento de bienes muebles, 4 Fletes, 5 Desperdicios, 6 Comisionistas, 7 Residentes en el extranjero, 9 Servicio prestado, 10 Retención IVA 100 %). El texto libre no lleva almacén, no admite descuento por renglón (pon el precio ya con descuento) ni IEPS, y no se puede usar en un pedido.

El servidor calcula también el IEPS (si el producto lo causa y el cliente está marcado para IEPS) y las retenciones de IVA e ISR del producto; todo se refleja en el total. No se admiten kits, variantes (longitud, espesor, color o peso) ni productos con número de serie (responden 422). La venta se registra en la matriz (sucursal 0).

condicion_pago es "contado" o "credito". forma_pago_sat y metodo_pago_sat usan las claves del SAT (03 = transferencia; PUE / PPD). uso_cfdi y regimen_receptor usan las claves del SAT y se validan contra el RFC del cliente, igual que en el alta de clientes.

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: ventas:write

## Cuerpo JSON
- `tipo` (texto): Tipo de documento: "cotizacion" o "pedido". Obligatorio.
- `cliente` (entero): Clave del cliente de tu empresa (la de GET /clientes). Obligatorio.
- `almacen` (entero): Clave del almacén de tu empresa (la de GET /almacenes). Obligatorio con productos del catálogo; no aplica a texto libre.
- `moneda` (texto): Código ISO de la moneda (p. ej. MXN). Si lo omites, la moneda de tu empresa.
- `condicion_pago` (texto): "contado" o "credito". Obligatorio.
- `forma_pago_sat` (texto): Clave de forma de pago del SAT (p. ej. 01 efectivo, 03 transferencia).
- `metodo_pago_sat` (texto): Método de pago del SAT: "PUE" (una sola exhibición) o "PPD" (parcialidades).
- `uso_cfdi` (texto): Clave de uso de CFDI del SAT (p. ej. G03). Debe ser compatible con el régimen y el RFC del cliente.
- `regimen_receptor` (entero): Clave del régimen fiscal del SAT del receptor (p. ej. 601, 612).
- `pedido_cliente` (texto): Número de pedido/orden de compra del cliente (texto libre). Máximo 50.
- `renglones` (array): Lista de renglones (1 a 200). Catálogo: producto (clave), cantidad (> 0), precio_unitario, descuento_pct (0 a 100), lista (p. ej. L1), observaciones. Texto libre (sólo cotización): concepto, clave_sat, unidad, iva, cantidad (> 0), precio_unitario y, opcional, retencion.

POST https://api.wizerp.com/api/v1/ventas

https://api.wizerp.com/api/v1/ventas

Da de alta una COTIZACIÓN o un PEDIDO. La empresa sale de tu llave. En esta versión no se crean remisiones ni facturas y no se timbra: eso llegará después.

El pedido APARTA inventario (reserva existencias); la cotización no mueve nada. Ninguno de los dos descuenta existencias reales, ni genera cuentas por cobrar, ni pólizas, ni CFDI.

Cada renglón es un PRODUCTO del catálogo ("producto") o un CONCEPTO DE TEXTO LIBRE ("concepto"), nunca los dos, y un documento es todo de catálogo o todo de texto libre. Los IMPUESTOS y TOTALES los calcula siempre el servidor: si mandas un importe o un total, se rechaza. El cliente, el almacén y cada producto deben ser de tu empresa.

PRODUCTO DEL CATÁLOGO: mandas producto, cantidad y precio_unitario (y almacen en el documento). El IVA, el IEPS y las retenciones salen del producto.

TEXTO LIBRE (sólo en COTIZACIÓN, igual que en la pantalla de Ventas): mandas concepto (la descripción), clave_sat (clave de producto o servicio del SAT, p. ej. 84111506), unidad (la clave interna de tu catálogo de unidades o una clave SAT que tengas dada de alta, p. ej. H87), iva (IVA16, IVA08, IVA00 o EXEN), cantidad y precio_unitario; opcional retencion (1 Honorarios, 2 Arrendamiento de inmuebles, 3 Arrendamiento de bienes muebles, 4 Fletes, 5 Desperdicios, 6 Comisionistas, 7 Residentes en el extranjero, 9 Servicio prestado, 10 Retención IVA 100 %). El texto libre no lleva almacén, no admite descuento por renglón (pon el precio ya con descuento) ni IEPS, y no se puede usar en un pedido.

El servidor calcula también el IEPS (si el producto lo causa y el cliente está marcado para IEPS) y las retenciones de IVA e ISR del producto; todo se refleja en el total. No se admiten kits, variantes (longitud, espesor, color o peso) ni productos con número de serie (responden 422). La venta se registra en la matriz (sucursal 0).

condicion_pago es "contado" o "credito". forma_pago_sat y metodo_pago_sat usan las claves del SAT (03 = transferencia; PUE / PPD). uso_cfdi y regimen_receptor usan las claves del SAT y se validan contra el RFC del cliente, igual que en el alta de clientes.

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 ventas:write en la llave · contrato del 2026-10-10

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.

tipo texto obligatorio

Tipo de documento: "cotizacion" o "pedido". Obligatorio.

cliente entero obligatorio

Clave del cliente de tu empresa (la de GET /clientes). Obligatorio.

almacen entero

Clave del almacén de tu empresa (la de GET /almacenes). Obligatorio con productos del catálogo; no aplica a texto libre.

moneda texto

Código ISO de la moneda (p. ej. MXN). Si lo omites, la moneda de tu empresa.

condicion_pago texto obligatorio

"contado" o "credito". Obligatorio.

forma_pago_sat texto

Clave de forma de pago del SAT (p. ej. 01 efectivo, 03 transferencia).

metodo_pago_sat texto

Método de pago del SAT: "PUE" (una sola exhibición) o "PPD" (parcialidades).

uso_cfdi texto

Clave de uso de CFDI del SAT (p. ej. G03). Debe ser compatible con el régimen y el RFC del cliente.

regimen_receptor entero

Clave del régimen fiscal del SAT del receptor (p. ej. 601, 612).

pedido_cliente texto

Número de pedido/orden de compra del cliente (texto libre). Máximo 50.

renglones array obligatorio

Lista de renglones (1 a 200). Catálogo: producto (clave), cantidad (> 0), precio_unitario, descuento_pct (0 a 100), lista (p. ej. L1), observaciones. Texto libre (sólo cotización): concepto, clave_sat, unidad, iva, cantidad (> 0), precio_unitario y, opcional, retencion.

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/ventas \
  -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 '{"tipo":"cotizacion","cliente":1,"almacen":1,"condicion_pago":"contado","renglones":"ejemplo"}'

$ch = curl_init('https://api.wizerp.com/api/v1/ventas');
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,
    '{"tipo":"cotizacion","cliente":1,"almacen":1,"condicion_pago":"contado","renglones":"ejemplo"}');
$r = json_decode(curl_exec($ch), true);

const r = await fetch(
  "https://api.wizerp.com/api/v1/ventas",
  {
    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({"tipo":"cotizacion","cliente":1,"almacen":1,"condicion_pago":"contado","renglones":"ejemplo"}),
  }
);
const datos = await r.json();

import requests

r = requests.post(
    "https://api.wizerp.com/api/v1/ventas",
    headers={
        "Authorization": "Bearer wzk_live_…",
        "X-Wizerp-Key-Id": "208_a3f91c7d",
        "Idempotency-Key": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    },
    json={"tipo":"cotizacion","cliente":1,"almacen":1,"condicion_pago":"contado","renglones":"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,
    "venta": 184027,
    "tipo": "texto",
    "folio": "texto",
    "moneda": "texto",
    "subtotal": "texto",
    "iva": "texto",
    "total": "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