Pedidos con nota de venta¶

La nota de venta es el "pedido" de OpenTPV: un documento interno, no tributario, que registra qué compró el cliente antes de emitir el documento tributario. Es el flujo correcto para e-commerce y ventas B2B porque separa confirmar el pedido de emitir el DTE, y permite anular mientras no esté documentado.

1. POST /documento/notaventa                       → crea el pedido (no mueve stock)
2. POST /documento/notaventa/{folio}/documentar    → emite boleta/factura/guía
                                                     (aquí baja el stock y una sola vez)
   o POST /documento/notaventa/{folio}/anular      → cancela el pedido

Prerrequisitos: Primeros pasos. Si además quieres apartar el stock mientras el cliente compra (tienda online, tótem, pedidos por WhatsApp), parte por Reservar stock al tomar un pedido; este flujo es su continuación.

1. Crear la nota de venta¶

curl -X POST https://api.opentpv.cl/documento/notaventa \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{
    "fechaEmision": "2026-08-10",
    "rut": "12345678", "digito": "5",
    "razonSocial": "María Pérez",
    "direccion": "Los Aromos 456", "comuna": "Ñuñoa", "ciudad": "Santiago",
    "email": "maria@correo.cl",
    "origen": "ECOMMERCE",
    "observaciones": "Pedido web #8912",
    "neto": 25210, "iva": 4790, "total": 30000,
    "items": [
      {
        "codigo": "A001",
        "descripcion": "Zapatilla urbana 42",
        "cantidad": 2,
        "precioUnitario": 15000,
        "totalLinea": 30000,
        "bodega": 1
      }
    ],
    "pagos": [ { "idFormaPago": 2, "formaPago": "WEBPAY", "monto": 30000 } ]
  }'

Puntos clave:

La respuesta trae el folio de la nota de venta: guárdalo, es la llave de los pasos siguientes. (Es numeración interna, no un folio CAF.)
Por defecto no mueve stock. Las líneas quedan marcadas "descuento pendiente" y el stock baja recién al documentar, una sola vez, sin importar si documenta la API o el cajero desde el ERP. La excepción: si la empresa activó que la API descuente stock y además que la nota de venta lo descuente, el stock baja al crear el pedido y ya no vuelve a bajar al documentar.
Si el pedido viene de un carro con reserva, agrega "tokenReserva": el stock apartado pasa a quedar a nombre del pedido y se mantiene por más tiempo (ver Reservar stock al tomar un pedido). Con tokenReserva la nota de venta nunca descuenta stock: ya está apartado.
Los precios de cada línea pasan tal cual al documento que se emita después. Si el pedido va a terminar en boleta, van con IVA incluido (como en el ejemplo). Si va a terminar en factura o guía, van netos, o bien con IVA incluido avisándolo al documentar con "mntBruto": true (ver más abajo).
origen (ECOMMERCE, API) queda registrado para trazabilidad.

Consultas: GET /documento/notaventa/{folio} devuelve el pedido completo con su estado (pendiente / documentado / anulado).

2a. Documentar: transformar el pedido en DTE¶

curl -X POST https://api.opentpv.cl/documento/notaventa/8912/documentar \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{ "tipoDte": 39, "codigoTerminal": "TERM-01" }'

tipoDte: 39 boleta, 41 boleta exenta, 33 factura, 34 factura exenta, 52 guía de despacho.
El DTE lleva su propio folio CAF (numeración distinta a la de la NV); la respuesta incluye folio, token y URLs de PDF/XML como en Emitir DTE.
Aquí baja el stock (si la empresa tiene apiDescuentaInventario activo) y se consume la reserva si la había. La regla por línea !stockYaDescontado garantiza que nunca se descuenta dos veces, aunque la NV se haya creado en el ERP de escritorio.
Precios netos o brutos. Al emitir factura (33) o guía (52), la API lee las líneas del pedido como netas. Si el pedido se guardó con precios con IVA incluido, agrega "mntBruto": true y el documento sale con el indicador de montos brutos del SII. No aplica a boletas, que siempre van en bruto, ni a pedidos con impuestos adicionales, que deben ir en neto.
Pedidos creados en el ERP. Si documentas por API una nota de venta que digitó un cajero, sus líneas vienen como la empresa tenga configurada la nota de venta (notaVentaConIva en GET /api/OpcionesGenerales/iva). La API no convierte los precios: indícale con mntBruto cómo vienen. Si lo que declaras no coincide con esa configuración, el documento se emite igual y la respuesta lo avisa en warning.
No se puede documentar dos veces: el segundo intento recibe 409, incluso con requests simultáneos.

Receptor alternativo (empresas con varias razones sociales)¶

Cuando el pedido queda a nombre del cliente final pero el documento debe salir a nombre de otra razón social (típico: la RS del e-commerce le compra a la RS que tiene el stock, con despacho directo al cliente):

{
  "tipoDte": 52,
  "codigoTerminal": "TERM-01",
  "codigoClienteReceptor": 8021,
  "traslado": { "indTraslado": 1, "rutTransportista": "77111222-3", "patente": "ABCD12" }
}

codigoClienteReceptor: código del cliente OpenTPV que será el receptor del DTE (debe existir; solo tipos 33/34/52, las boletas lo rechazan). La guía queda asociada a él, lo que permite la facturación masiva de guías a fin de mes desde el ERP.
En la guía, el domicilio del cliente final queda como destino del traslado (dropship documentado según el schema SII).
El bloque traslado cubre la Res. Ex. SII N°154/2025 (vigente desde el 01-11-2026): tipo de traslado, destino, transportista/chofer/patentes. Si se omite, la API aplica defaults que cumplen los obligatorios (destino = domicilio del cliente, constancia de patente no conocida, hora de inicio en observaciones). Una guía por pedido: la guía ampara un traslado físico; la consolidación va en la factura mensual.

2b. Anular el pedido¶

curl -X POST https://api.opentpv.cl/documento/notaventa/8912/anular \
  -H "Authorization: Bearer eyJhbGciOi..."

No lleva cuerpo: basta el folio en la URL.
Solo mientras no esté documentada (si ya lo está, 409; la reversa es con nota de crédito sobre el DTE).
Libera las reservas asociadas. No "repone" stock: nunca se descontó.

Resumen de decisiones¶

Situación	Camino
Venta simple, pago inmediato, sin pedido	DTE directo (`procesar/json`)
Pedido que se confirma ahora y se factura/despacha después	Nota de venta → documentar
Tienda online, tótem u otro canal con stock apartado	Reservas → nota de venta → documentar
Multi-razón-social (dropship)	Nota de venta (cliente final) → guía con `codigoClienteReceptor` → factura mensual de guías