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 reservas stock mientras el cliente compra, parte por Reserva de stock para e-commerce; 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.)
No mueve stock. Las líneas quedan marcadas "descuento pendiente" (stockYaDescontado = 0); el físico baja recién al documentar, una sola vez, sin importar si documenta la API o el cajero desde el ERP.
Si el pedido viene de un carro con reserva, agrega "tokenReserva": la reserva pasa a colgar del pedido con TTL largo (ver la guía de reservas).
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.
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..." \
  -H "Content-Type: application/json" \
  -d '{ "razon": "Cliente canceló la compra", "usuario": "integracion-web" }'

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
Carro web con stock asegurado	Reservas → nota de venta → documentar
Multi-razón-social (dropship)	Nota de venta (cliente final) → guía con `codigoClienteReceptor` → factura mensual de guías