Especificación para el proveedor del ERP
Qué información necesita la aplicación para funcionar sobre su ERP. No es una lista de rutas a copiar: es el contenido que cada respuesta debe traer. Ustedes exponen los servicios como prefieran; la traducción a nuestro formato corre por nuestra cuenta.
Cada campo se puede expandir para ver tipo, formato y un ejemplo. Cada servicio trae un ejemplo completo de respuesta.
Cómo funciona la conexión
No hace falta que respeten nuestros nombres de ruta, de campo ni el formato de la respuesta. Lo que se acuerda es qué dato trae cada servicio y qué significa.
Del lado nuestro hay una pieza que traduce su API a la forma que la aplicación espera. Mientras el dato exista y su significado esté declarado, el mapeo es trabajo nuestro. Lo que no exista en su API sencillamente no se implementa: la aplicación pierde esa función y el resto sigue operando.
Los ejemplos de este documento usan nombres de campo ilustrativos, solo para mostrar el dato esperado. No son un formato obligatorio.
Aplican a todos los servicios
Todo valor monetario en pesos enteros. Los redondeos intermedios cambian los totales y descuadran la factura; conviene que el redondeo ocurra una sola vez y del lado de ustedes.
La convención pedida es: el precio unitario va antes de descuento; los totales de línea, después. Si su ERP trabaja al revés no es impedimento — declárenlo y entreguen además el descuento aplicado y la regla de redondeo, y nosotros traducimos en ambos sentidos. Lo que no puede quedar es sin declarar: traducir entre convenciones solo es exacto si el redondeo está especificado, y si no, aparecen diferencias de un peso al cuadrar.
Cada producto debe traer su tasa de IVA y la de impuestos adicionales. La aplicación totaliza sin red, así que no puede deducirlas: si faltan, asume una tasa fija y factura mal los productos exentos.
ISO-8601 con offset. Una fecha sin zona hace que los documentos del día desaparezcan del filtro del vendedor cuando el teléfono y el servidor no coinciden.
Ninguna consulta puede obligar a traer todo. Se requiere filtro desde fecha y paginación. Un catálogo de 30 mil productos sin paginar no llega por red móvil.
Cada condición de error necesita un código legible por máquina que no cambie. No sirve distinguir casos por el texto del mensaje.
Los códigos viajan recortados, sin espacios de relleno a la derecha. Un código con espacio sobrante se compara como distinto y hace desaparecer, en silencio, todo el historial del vendedor.
Un campo que no aplica debe venir nulo, no en cero ni en blanco. La aplicación distingue "no hay dato" de "el dato es cero" y toma decisiones distintas.
Lo más importante del documento
Cada documento que la aplicación envía lleva una clave única generada en el teléfono, antes del primer intento. Si no hay respuesta o la respuesta tarda, la aplicación reintenta con la misma clave, indefinidamente. Es su comportamiento normal, no una falla.
Su servicio debe garantizar que una clave repetida no crea un segundo documento, y que el reintento devuelve el folio del documento que ya existe. Sin ese folio la aplicación no puede cerrar el ciclo y el documento queda pendiente para siempre en el teléfono del vendedor.
La aplicación trata un error confirmado como permiso para reemplazar el documento: el vendedor lo edita y se envía uno nuevo, con clave nueva.
Si su servicio responde error después de haber grabado, se genera un duplicado real en el ERP. Si no pueden garantizarlo, respondan sin error y dejen que la aplicación reintente con la misma clave: el reintento es seguro, el error no.
Los documentos que la aplicación descarga después se aparean con los del teléfono por esa clave. Si el documento creado no la conserva y no la devuelve al consultarlo, la aplicación no reconoce lo que ella misma creó.
Bloque obligatorio
Con estos la aplicación inicia sesión, sincroniza y registra una venta. Todo lo demás es opcional y puede quedar para una segunda etapa.
booleano
true
Nunca devuelvan la clave ni su hash. Solo el veredicto. Si la credencial es incorrecta, un error con código estable — no una respuesta vacía.
texto
sin espacios de relleno
"11"
Es el código con que la aplicación pedirá después su cartera, su historial y sus metas. Si aquí viene con espacios y en otro servicio sin ellos, las comparaciones fallan y el vendedor ve todo vacío, sin ningún error.
{
"valida": true,
"vendedor": "11"
}texto
sin relleno
"11"
texto
"Claudia Fuentes"
texto
con dígito verificador
"15482930-4"
texto
"cfuentes@empresa.cl"
texto
"PREVENTA"
Es la llave con que se consulta el servicio de reglas de la modalidad, que define bodega, caja y lista de precio. Un vendedor sin modalidad no puede abrir una venta.
booleano
false
{
"codigo": "11",
"nombre": "Claudia Fuentes",
"rut": "15482930-4",
"correo": "cfuentes@empresa.cl",
"modalidad": "PREVENTA",
"inactivo": false
}texto
"01"
Casi todas las consultas llevan este código. Si su ERP maneja una sola empresa, igual necesitamos un valor constante con el que identificarla.
texto
"76543210-K"
"Distribuidora del Sur SpA"
booleano
true
Define si un pedido aún no facturado descuenta del cupo disponible. Si el dato falta, el control de crédito no se aplica y no se emite ningún aviso: el vendedor puede vender por sobre el cupo sin enterarse.
{
"codigo": "01",
"rut": "76543210-K",
"razonSocial": "Distribuidora del Sur SpA",
"pedidoConsumeCredito": true
}número
porcentaje
15
Debe venir resuelto, no como una regla a interpretar. Si en su ERP el tope depende del producto, de la lista o del cliente, resuélvanlo antes de responder: la aplicación aplica el número tal cual, sin red.
lista de textos
["01P", "02P"]
lista de textos
["910", "920"]
Si la lista viene vacía, el vendedor no ve stock de ningún producto y no puede vender. Es una causa frecuente de "la aplicación no muestra productos" que en realidad es configuración del ERP.
lista de textos
["PEDIDO", "BOLETA", "FACTURA"]
Los valores concretos se acuerdan al definir el vocabulario de tipos de documento. Lo importante es que sea una lista cerrada y estable.
{
"topeDescuento": 15,
"listasPermitidas": ["01P", "02P"],
"bodegasPermitidas": ["910", "920"],
"tiposDocumento": ["PEDIDO", "BOLETA", "FACTURA"]
}texto
"01P"
Sin este valor el catálogo queda vacío o cae a la lista del cliente, que puede no ser la correcta. Es el campo que más veces explica un catálogo sin precios.
texto
"910"
texto
"001"
texto
"CAJA01"
lista de textos
["FACTURA_EXENTA"]
{
"empresa": "01",
"modalidad": "PREVENTA",
"listaVenta": "01P",
"bodega": "910",
"sucursal": "001",
"caja": "CAJA01",
"tiposExcluidos": ["FACTURA_EXENTA"]
}texto y texto
"CL0042" · "001"
Las dos identifican la venta. Si su ERP no maneja sucursales, devuelvan un valor constante: la aplicación necesita el par completo para grabar.
texto
"Minimarket Los Aromos"
texto
cuerpo-DV
"77921052-9"
Incluyan el dígito verificador. Si llega sin él, calcularlo por checksum produce un RUT que también valida pero no es el del cliente; ya ocurrió y el documento sale a nombre equivocado.
texto
"Av. Los Aromos 1450"
"Puente Alto" · "Santiago"
número decimal
-33.61169 · -70.57556
texto
"02P"
Si el cliente no tiene lista propia, devuelvan nulo y se usa la de la modalidad. No devuelvan vacío ni cero.
texto y número
"CREDITO" · 30
Sin este dato el arqueo de caja emite avisos de pagos faltantes que son falsos positivos: el vendedor cree que dejó de cobrar algo que en realidad era a plazo.
texto
"MA" (martes)
booleano
false
Ausente se interpreta como "no se sabe" y no bloquea. Si su ERP maneja bloqueo de clientes, conviene enviarlo siempre.
fecha y hora
ISO-8601 con offset
"2026-09-10T14:32:05-03:00"
Es lo que permite pedir solo lo que cambió. Sin ella, cada sincronización tiene que bajar la cartera completa.
{
"pagina": 1,
"total": 214,
"clientes": [
{
"codigo": "CL0042",
"sucursal": "001",
"razonSocial": "Minimarket Los Aromos",
"rut": "77921052-9",
"direccion": "Av. Los Aromos 1450",
"comuna": "Puente Alto",
"ciudad": "Santiago",
"latitud": -33.61169,
"longitud": -70.57556,
"listaPrecio": "02P",
"condicionPago": "CREDITO",
"diasPlazo": 30,
"diaVisita": "MA",
"diaCobro": "VI",
"bloqueado": false,
"modificadoEl": "2026-09-10T14:32:05-03:00"
}
]
}texto
"116231"
Debe ser el mismo código en catálogo, lista de precio y stock. Si en alguno viene distinto, el producto aparece sin precio o sin existencia.
texto
"Bebida Cola 1,5 L"
texto
"7801234567890"
Habilita buscar el producto escaneando o tecleando el código de barras.
texto
"UN"
texto
"CJ"
Si el producto se vende en dos unidades, hace falta además cuántas unidades primarias contiene la secundaria, para poder convertir.
booleano, uno por unidad
true · false
Determina si el vendedor puede digitar 1,5 o solo enteros. Se necesita uno por cada unidad de venta.
texto por nivel
"BEB" · "GAS" · "COLA"
Los niveles pueden repetir código entre sí. El mismo código puede significar cosas distintas en el nivel 1 y en el 2, así que el nivel debe venir junto al código. Resolver el nombre sin el nivel da el nombre equivocado.
texto
"ANDINA"
número decimal
1.62
{
"pagina": 1,
"total": 3480,
"productos": [
{
"codigo": "116231",
"descripcion": "Bebida Cola 1,5 L",
"codigoBarras": "7801234567890",
"unidad1": "UN",
"unidad2": "CJ",
"unidadesPorUnidad2": 6,
"divisible1": true,
"divisible2": false,
"familia": { "nivel": 1, "codigo": "BEB", "nombre": "Bebidas" },
"subfamilia": { "nivel": 2, "codigo": "GAS", "nombre": "Gaseosas" },
"linea": { "nivel": 3, "codigo": "COLA", "nombre": "Cola" },
"marca": "ANDINA",
"pesoKg": 1.62
}
]
}texto
"116231"
entero
pesos, antes de descuento
1290
Si su convención es otra, decláren la y entreguen la regla de redondeo. Ver "Precios: una sola convención" en las reglas generales.
número
porcentaje
19
número
porcentaje
10
Si este dato falta, la aplicación asume una tasa fija y termina cobrando IVA a un producto exento. Envíen cero explícito cuando no aplique.
lista
desde 12 → 1190
Solo si esa política existe en su ERP. La aplicación los muestra como referencia al vendedor.
número
porcentaje
5
{
"lista": "01P",
"pagina": 1,
"cursorSiguiente": "116240",
"precios": [
{
"producto": "116231",
"precioUnitario": 1290,
"tasaIva": 19,
"tasaAdicional": 0,
"descuentoLista": 5,
"tramos": [
{ "desdeCantidad": 12, "precioUnitario": 1190 }
]
}
]
}texto
"116231"
texto
"910"
número decimal
248 (UN) · 41 (CJ)
Si el producto se vende en dos unidades, hacen falta las dos existencias, o la conversión para calcularlas.
{
"stock": [
{ "producto": "116231", "bodega": "910", "existencia1": 248, "existencia2": 41 },
{ "producto": "116232", "bodega": "910", "existencia1": 0, "existencia2": 0 }
]
}texto
UUID v4
"ca12ec77-62bb-4f00-8226-1bc654d5a0c1"
Sin esta clave la aplicación no puede reconocer los documentos que ella misma creó, y quedan duplicados en pantalla: uno local y otro descargado. Es el campo que cierra el ciclo de idempotencia.
texto
"0000001244" · "BOLETA"
fecha y hora
ISO-8601 con offset
"2026-09-10T11:05:00-03:00"
texto
"CL0042" · "001"
entero
12354 · 2347 · 14701
lista
Si mandan el total bruto de una línea, manden también el neto. Los dos van después de descuento. Si llega solo el bruto, la aplicación vuelve a restar el descuento y muestra un neto equivocado.
texto
"PENDIENTE"
{
"documentos": [
{
"claveOrigen": "ca12ec77-62bb-4f00-8226-1bc654d5a0c1",
"tipo": "BOLETA",
"folio": "0000001244",
"emitidoEl": "2026-09-10T11:05:00-03:00",
"cliente": "CL0042",
"sucursal": "001",
"vendedor": "11",
"totalNeto": 12354,
"totalImpuestos": 2347,
"totalBruto": 14701,
"estadoPago": "PENDIENTE",
"lineas": [
{
"producto": "116231",
"descripcion": "Bebida Cola 1,5 L",
"cantidad": 12,
"unidad": "UN",
"precioUnitario": 1290,
"descuento": 5,
"tasaIva": 19,
"tasaAdicional": 0,
"netoLinea": 14706,
"brutoLinea": 17500
}
]
}
]
}texto
UUID v4
"ca12ec77-62bb-4f00-8226-1bc654d5a0c1"
Se genera una sola vez, al crear el documento, y no cambia entre reintentos. Es la clave sobre la que se apoyan las tres reglas de grabación.
"11" · "01" · "PREVENTA"
texto
"BOLETA"
Del vocabulario acordado. Es uno de los valores que hay que fijar antes de empezar a mapear.
"CL0042" · "001"
entero
14701
La aplicación totaliza sin red y envía su resultado. Si su ERP recalcula y llega a otro número, hay que decidir cuál manda: lo esperable es que el ERP mande, pero el vendedor ya le mostró el suyo al cliente, así que la diferencia tiene que ser cero.
"CREDITO"
ISO-8601 con offset
"2026-09-12T00:00:00-03:00"
texto
lista
Cada línea lleva: producto, descripción, cantidad, unidad, precio unitario, hasta cuatro descuentos, el monto de descuento de la línea, las tasas de IVA y adicional, y los totales neto y bruto de línea. La bodega va por línea cuando difiere de la de la modalidad.
lista
Medio de pago y monto. Si el pago es cheque, además banco, número y fecha.
texto
"0000001244"
texto o número
91
"ca12ec77-62bb-4f00-8226-1bc654d5a0c1"
booleano
true
Ante una clave repetida, respondan éxito con este indicador en verdadero y el folio del documento que ya existe. No respondan error: para la aplicación un error significa que puede reemplazar el documento, y ahí se produce el duplicado.
{
"clave": "ca12ec77-62bb-4f00-8226-1bc654d5a0c1",
"vendedor": "11",
"empresa": "01",
"modalidad": "PREVENTA",
"tipoDocumento": "BOLETA",
"cliente": "CL0042",
"sucursal": "001",
"condicionPago": "CREDITO",
"fechaEntrega": "2026-09-12T00:00:00-03:00",
"observacion": "Dejar en bodega trasera",
"totalBruto": 14701,
"lineas": [
{
"producto": "116231",
"descripcion": "Bebida Cola 1,5 L",
"cantidad": 12,
"unidad": "UN",
"bodega": "910",
"precioUnitario": 1290,
"descuentos": [5, 0, 0, 0],
"montoDescuentoLinea": 774,
"tasaIva": 19,
"tasaAdicional": 0,
"netoLinea": 14706,
"brutoLinea": 17500
}
],
"pagos": [
{ "medio": "EFECTIVO", "monto": 14701 }
]
}{
"clave": "ca12ec77-62bb-4f00-8226-1bc654d5a0c1",
"folio": "0000001244",
"tipoDocumento": "BOLETA",
"id": 91,
"claveYaUsada": false
}{
"clave": "ca12ec77-62bb-4f00-8226-1bc654d5a0c1",
"folio": "0000001244",
"tipoDocumento": "BOLETA",
"id": 91,
"claveYaUsada": true
}Bloque opcional
Cada uno habilita una función de la aplicación. El que no exista simplemente no se implementa: la función queda apagada y el resto opera igual.
| Servicio | Qué debe entregar |
|---|---|
| Registrar pedido | Escritura. Mismas reglas y misma respuesta que registrar la venta |
| Pedidos del vendedor | Historial de pedidos con su estado, y búsqueda por la clave de origen |
| Detalle del pedido | Líneas y totales |
| Stock comprometido | Existencia descontando los pedidos aún no despachados |
| Servicio | Qué debe entregar |
|---|---|
| Deuda del cliente | Documentos por cobrar con monto, vencimiento y saldo |
| Registrar pago | Escritura. Qué documentos salda y con qué medio de pago |
| Bancos | Lista de bancos, para el registro de cheques |
| Servicio | Qué debe entregar |
|---|---|
| Crédito del cliente | Cupo asignado, deuda vigente y saldo disponible, ya calculados |
| Servicio | Qué debe entregar |
|---|---|
| Detalle plano de documentos | La misma información en formato plano, para el arqueo de caja |
| Cadena de documentos | Qué documento originó a cuál: pedido, guía, factura |
| Origen de la factura | Qué pedido dio origen a cada factura |
| Comprobante impreso | Imagen del comprobante lista para la impresora térmica. Opcional: la aplicación sabe componerlo sola |
| Servicio | Qué debe entregar |
|---|---|
| Crear o actualizar cliente | Escritura. Devuelve el código asignado |
| Comunas y territorios | Para completar la dirección con valores válidos |
| Servicio | Qué debe entregar |
|---|---|
| Familias | Nombre de cada nivel de agrupación. Necesario solo si el catálogo trae los códigos sin nombre |
| Promociones | Promociones vigentes y a qué productos o clientes aplican |
| Definición de impuestos | Tasa y tipo de cada impuesto. Alternativa a traerlos en la lista de precio |
| Impuesto por producto | Qué impuestos afectan a cada producto |
| Servicio | Qué debe entregar |
|---|---|
| Metas del vendedor | Meta por período y su avance |
| Definición de metas | Cómo se mide cada una: en pesos, unidades o kilos |
| Motivos de no venta | Lista de motivos con que el vendedor justifica una visita sin pedido |
Fuera del alcance
Antes de empezar