Nota de Venta en Softland: qué es y cómo crearla por API

La Nota de Venta es el documento central de la operación comercial en Softland ERP. Es el punto de partida de cualquier venta: antes de que exista una factura o un despacho, existe una Nota de Venta. Para las empresas que operan e-commerce, automatización de ventas o integraciones entre sistemas, entender cómo funciona este documento es el primer paso para construir cualquier integración útil.

Qué es una Nota de Venta en Softland

En Softland On-Premise, la Nota de Venta (NV) es el documento de preventa que registra el compromiso comercial con un cliente. Equivale al concepto de "pedido de venta" o "orden de venta" en otros ERPs.

Una Nota de Venta en Softland contiene:

• Encabezado: cliente (RUT, razón social), fecha, condición de venta, lista de precios, vendedor asignado, bodega de despacho
• Líneas: los artículos con código, descripción, cantidad, precio unitario, descuento y total
• Totales: subtotal neto, IVA, total bruto

No genera movimiento contable ni de stock al momento de la creación. El impacto en inventario ocurre cuando se despacha, y el impacto contable cuando se factura.

Estados de una Nota de Venta

Softland maneja un ciclo de vida para las Notas de Venta. Los estados más relevantes son:

Pendiente — La NV fue ingresada pero aún no tiene aprobación de crédito ni despacho. Es el estado inicial cuando se crea por API o por el operador.

Aprobada — La NV pasó la validación de crédito del cliente. Puede continuar al despacho.

En despacho — Se emitió una Guía de Despacho asociada. El stock queda comprometido.

Facturada — Se emitió la factura. El ciclo comercial está completo.

Anulada — La NV fue cancelada. No genera movimientos.

La transición entre estados puede ser manual (operador en Softland) o automática según la configuración de cada empresa. En integraciones con e-commerce, lo más común es crear la NV en estado Pendiente y dejar que el proceso interno de Softland avance el flujo.

Por qué es importante para integraciones con e-commerce

En una tienda online con Softland On-Premise, el flujo típico es:

1. El cliente hace un pedido en WooCommerce o Shopify
2. El sistema externo crea una Nota de Venta en Softland via API
3. El operador en Softland revisa, aprueba y despacha
4. Softland genera la Guía de Despacho y luego la Factura Electrónica

Sin automatización, el paso 2 es manual: el operador de Softland recibe un aviso (email, WhatsApp, planilla) y crea la NV a mano. Con integración via API, ese paso es automático: el pedido llega a Softland en segundos, sin intervención humana.

Esto elimina la doble digitación, reduce errores de transcripción y permite operar con mayor volumen sin escalar el equipo de operaciones.

Datos que necesita una NV para ser válida en Softland

Para crear una Nota de Venta vía API, Softland requiere:

Del cliente:

• RUT (debe existir como auxiliar en Softland)
• Condición de venta (contado, crédito 30 días, etc.)
• Lista de precios a aplicar

De los productos:

• Código de artículo (debe existir en Softland)
• Cantidad
• Precio (puede tomarse de la lista de precios de Softland o enviarse explícitamente)
• Bodega de despacho

Si el cliente o el artículo no existen en Softland, la NV no se puede crear. Por eso las integraciones bien construidas primero validan que el cliente existe (o lo crean si no existe) y luego crean la NV.

Cómo crear una Nota de Venta desde un sistema externo

Con ConexionERP, el endpoint para crear una Nota de Venta acepta una estructura JSON con el encabezado y las líneas:

POST /api/v1/notas-de-venta
X-Api-Key: ws_xxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "RutCliente": "76123456-7",
  "CodListaPrecio": "01",
  "CodCondicionVenta": "01",
  "CodVendedor": "001",
  "CodBodega": "01",
  "Observacion": "Pedido ecommerce #4521",
  "Lineas": [
    {
      "CodArticulo": "NOTEBOOK-HP",
      "Cantidad": 2,
      "PrecioUnitario": 599990
    },
    {
      "CodArticulo": "MOUSE-LOG",
      "Cantidad": 2,
      "PrecioUnitario": 19990
    }
  ]
}

La respuesta devuelve el número de la NV creada en Softland:

{
  "data": {
    "NumNV": "0042891",
    "Estado": "Pendiente",
    "Total": 1239960
  }
}

Con ese NumNV, el sistema externo puede hacer seguimiento, mostrar al cliente el número de pedido o usarlo para asociar la NV con el pedido en el e-commerce.

Flujos comunes con Nota de Venta

WooCommerce → Softland: Cuando se confirma un pedido en WooCommerce, un webhook o cron llama al endpoint de ConexionERP y crea la NV automáticamente. El operador de Softland solo necesita despachar.

n8n o Zapier → Softland: Un flujo de automatización que escucha pedidos de cualquier fuente (formulario web, app interna, canal de ventas B2B) y los convierte en NV en Softland en segundos.

Sistema ERP externo → Softland: En empresas con múltiples sistemas, las órdenes generadas en otro sistema se replican como NV en Softland para que el equipo de despacho trabaje desde un único punto.

Validación de crédito antes de crear la NV

En ventas B2B, es común que se requiera validar el crédito disponible del cliente antes de aceptar el pedido. Softland maneja el crédito en 4 niveles:

• CreditoAut: límite de crédito autorizado
• SaldoContable: facturas emitidas no pagadas
• FacturasNoCentralizadas: facturas sin procesar contablemente
• NvSinDespacho: Notas de Venta aprobadas pero sin despachar

El crédito disponible real es: CreditoAut - SaldoContable - FacturasNoCentralizadas - NvSinDespacho. ConexionERP expone este cálculo en el endpoint de saldo de cliente, lo que permite validar automáticamente si el cliente puede comprar antes de crear la NV.

Consideraciones para implementaciones de producción

Idempotencia: si el sistema externo envía la misma solicitud dos veces (por timeout o retry), pueden crearse dos NV duplicadas en Softland. Una buena práctica es guardar el NumNV retornado y verificar si ya existe antes de reintentar.

Artículos inexistentes: si un código de artículo no existe en Softland, la API devuelve error. El sistema externo debe manejar este caso, ya sea filtrando productos o notificando al operador.

Creación de clientes on-the-fly: en e-commerce B2C, el cliente puede ser nuevo. ConexionERP permite crear el cliente (auxiliar) en Softland antes de crear la NV, dentro del mismo flujo.

Si tiene Softland On-Premise y necesita crear Notas de Venta desde un sistema externo, la guía de implementación explica el proceso completo. O puede contactarnos directamente para evaluar su caso específico.