Especificación para el proveedor del ERP

Servicios que necesita Ramaflex Móvil

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

Ustedes publican una API; nosotros escribimos el traductor

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

Reglas generales

Montos en enteros

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.

Precios: una sola convención

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.

Impuestos por producto

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.

Fechas con zona horaria

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.

Paginación e incremental

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.

Errores con código estable

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.

Códigos sin relleno

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.

Ausente no es cero

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

Reglas de grabación

1. La misma clave no puede crear dos documentos

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.

2. Un error debe garantizar que no se grabó nada

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.

3. La respuesta debe devolver la clave recibida

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

Los once servicios sin los cuales la app no opera

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.

1 · Validar credenciales del vendedor

obligatorio
Para qué: es la puerta de la aplicación. El vendedor ingresa su código y su clave.
Le enviamoscódigo de vendedor y clave
CampoOblig.Para qué
Credencial válidaVerdadero o falso

tipo

booleano

ejemplo

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.

Código de vendedorEl código canónico, para el resto de las consultas

tipo

texto

formato

sin espacios de relleno

ejemplo

"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.

Ejemplo de respuesta
{
  "valida": true,
  "vendedor": "11"
}

2 · Datos del vendedor

obligatorio
Para qué: identifica al vendedor y define con qué modalidad de venta trabaja.
Le enviamoscódigo de vendedor
CampoOblig.Para qué
CódigoIdentifica al vendedor en todo el sistema

tipo

texto

formato

sin relleno

ejemplo

"11"

NombreSe muestra en pantalla y en el comprobante

tipo

texto

ejemplo

"Claudia Fuentes"

RUTnoIdentificación tributaria del vendedor

tipo

texto

formato

con dígito verificador

ejemplo

"15482930-4"

CorreonoEnvío de comprobantes

tipo

texto

ejemplo

"cfuentes@empresa.cl"

ModalidadCon qué configuración de venta opera

tipo

texto

ejemplo

"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.

InactivoUn vendedor inactivo no debe poder operar

tipo

booleano

ejemplo

false

Ejemplo de respuesta
{
  "codigo": "11",
  "nombre": "Claudia Fuentes",
  "rut": "15482930-4",
  "correo": "cfuentes@empresa.cl",
  "modalidad": "PREVENTA",
  "inactivo": false
}

3 · Empresa

obligatorio
Para qué: datos de la empresa que emite los documentos.
Le enviamosRUT de la empresa
CampoOblig.Para qué
CódigoIdentifica la empresa en el resto de las consultas

tipo

texto

ejemplo

"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.

RUT y razón socialEncabezado del comprobante

tipo

texto

ejemplo

"76543210-K"
"Distribuidora del Sur SpA"

El pedido consume créditoSi un pedido pendiente descuenta del cupo del cliente

tipo

booleano

ejemplo

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.

Ejemplo de respuesta
{
  "codigo": "01",
  "rut": "76543210-K",
  "razonSocial": "Distribuidora del Sur SpA",
  "pedidoConsumeCredito": true
}

4 · Permisos y tope de descuento

obligatorio
Para qué: qué puede hacer el vendedor y hasta qué descuento puede otorgar sin autorización.
Le enviamoscódigo de vendedor
CampoOblig.Para qué
Tope de descuentoMáximo que puede aplicar, ya resuelto a un valor

tipo

número

formato

porcentaje

ejemplo

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.

Listas de precio permitidasSobre qué listas puede vender

tipo

lista de textos

ejemplo

["01P", "02P"]

Bodegas permitidasDesde qué bodegas puede despachar

tipo

lista de textos

ejemplo

["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.

Tipos de documento permitidosQué puede emitir: pedido, boleta, factura

tipo

lista de textos

ejemplo

["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.

Ejemplo de respuesta
{
  "topeDescuento": 15,
  "listasPermitidas": ["01P", "02P"],
  "bodegasPermitidas": ["910", "920"],
  "tiposDocumento": ["PEDIDO", "BOLETA", "FACTURA"]
}

5 · Reglas de la modalidad

obligatorio
Para qué: con qué bodega, caja y lista de precio opera el vendedor. Define el contexto de toda la venta.
Le enviamosempresa y modalidad
CampoOblig.Para qué
Lista de precio de ventaLista por defecto de la modalidad

tipo

texto

ejemplo

"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.

BodegaDesde dónde se despacha y contra qué se mide el stock

tipo

texto

ejemplo

"910"

SucursalSucursal emisora del documento

tipo

texto

ejemplo

"001"

CajanoPara el arqueo de caja

tipo

texto

ejemplo

"CAJA01"

Tipos de documento excluidosnoQué tipos no se ofrecen en el selector

tipo

lista de textos

ejemplo

["FACTURA_EXENTA"]

Ejemplo de respuesta
{
  "empresa": "01",
  "modalidad": "PREVENTA",
  "listaVenta": "01P",
  "bodega": "910",
  "sucursal": "001",
  "caja": "CAJA01",
  "tiposExcluidos": ["FACTURA_EXENTA"]
}

6 · Clientes

obligatorio
Para qué: la cartera del vendedor, con todo lo necesario para visitarla y venderle sin red.
Le enviamosempresa, código de vendedor y fecha desde (sincronización incremental)
CampoOblig.Para qué
Código y sucursalUn cliente puede tener varias sucursales de entrega

tipo

texto y texto

ejemplo

"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.

Razón socialSe muestra y se imprime

tipo

texto

ejemplo

"Minimarket Los Aromos"

RUTCon dígito verificador

tipo

texto

formato

cuerpo-DV

ejemplo

"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.

Dirección, comuna, ciudadRuta de visita y datos del documento

tipo

texto

ejemplo

"Av. Los Aromos 1450"
"Puente Alto" · "Santiago"

CoordenadasnoUbicación en el mapa de la ruta

tipo

número decimal

ejemplo

-33.61169 · -70.57556

Lista de precio del clienteQué lista se le aplica cuando difiere de la modalidad

tipo

texto

ejemplo

"02P"

Si el cliente no tiene lista propia, devuelvan nulo y se usa la de la modalidad. No devuelvan vacío ni cero.

Condición de pagoContado o plazo, y a cuántos días

tipo

texto y número

ejemplo

"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.

Día de visita y de cobronoArma la ruta semanal del vendedor

tipo

texto

ejemplo

"MA" (martes)

BloqueadonoImpide venderle

tipo

booleano

ejemplo

false

Ausente se interpreta como "no se sabe" y no bloquea. Si su ERP maneja bloqueo de clientes, conviene enviarlo siempre.

Fecha de modificaciónHabilita la sincronización incremental

tipo

fecha y hora

formato

ISO-8601 con offset

ejemplo

"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.

Ejemplo de respuesta
{
  "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"
    }
  ]
}

7 · Catálogo de productos

obligatorio
Para qué: qué se puede vender. Se combina con la lista de precio: un producto sin precio no aparece.
Le enviamosempresa, modalidad y el indicador de venta
CampoOblig.Para qué
CódigoIdentifica el producto en precio, stock y venta

tipo

texto

ejemplo

"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.

DescripciónLo que ve el vendedor y sale impreso

tipo

texto

ejemplo

"Bebida Cola 1,5 L"

Código alternativonoCódigo de barras o código del cliente

tipo

texto

ejemplo

"7801234567890"

Habilita buscar el producto escaneando o tecleando el código de barras.

Unidad primariaEn qué se vende: unidad, caja, kilo

tipo

texto

ejemplo

"UN"

Unidad secundarianoSegunda unidad de venta, si existe

tipo

texto

ejemplo

"CJ"

Si el producto se vende en dos unidades, hace falta además cuántas unidades primarias contiene la secundaria, para poder convertir.

Divisible por unidadSi se admite vender fracción

tipo

booleano, uno por unidad

ejemplo

true · false

Determina si el vendedor puede digitar 1,5 o solo enteros. Se necesita uno por cada unidad de venta.

Familia, subfamilia, líneaTres niveles de agrupación del catálogo

tipo

texto por nivel

ejemplo

"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.

MarcanoFiltro de búsqueda

tipo

texto

ejemplo

"ANDINA"

Peso unitario en kgnoSolo si hay metas medidas en kilos

tipo

número decimal

ejemplo

1.62

Ejemplo de respuesta
{
  "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
    }
  ]
}

8 · Precio por cliente

obligatorio
Para qué: a cuánto se le vende cada producto a ese cliente. Ya resuelto: la aplicación no combina listas ni interpreta reglas de precio.
Le enviamosempresa, lista de precio, modalidad y el cursor de paginación
CampoOblig.Para qué
Código de productoCon qué producto del catálogo se corresponde

tipo

texto

ejemplo

"116231"

Precio unitarioEl precio aplicable, con la convención declarada

tipo

entero

formato

pesos, antes de descuento

ejemplo

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.

Tasa de IVALa aplicación totaliza sin red y no puede deducirla

tipo

número

formato

porcentaje

ejemplo

19

Tasa de impuesto adicionalCero si no aplica

tipo

número

formato

porcentaje

ejemplo

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.

Tramos por cantidadnoPrecio distinto según cantidad comprada

tipo

lista

ejemplo

desde 12 → 1190

Solo si esa política existe en su ERP. La aplicación los muestra como referencia al vendedor.

Descuento automáticonoDescuento de la lista, que la app aplica sola

tipo

número

formato

porcentaje

ejemplo

5

Este servicio tiene que estar paginado. Hay instalaciones con más de 30 mil productos; sin paginación la consulta no termina. Necesitamos poder pedir páginas con un cursor y un tamaño.
Ejemplo de respuesta
{
  "lista": "01P",
  "pagina": 1,
  "cursorSiguiente": "116240",
  "precios": [
    {
      "producto": "116231",
      "precioUnitario": 1290,
      "tasaIva": 19,
      "tasaAdicional": 0,
      "descuentoLista": 5,
      "tramos": [
        { "desdeCantidad": 12, "precioUnitario": 1190 }
      ]
    }
  ]
}

9 · Stock

obligatorio
Para qué: qué hay disponible para vender, por bodega.
Le enviamosempresa y bodegas
CampoOblig.Para qué
Código de productoCorrespondencia con el catálogo

tipo

texto

ejemplo

"116231"

BodegaEl stock es por bodega, no global

tipo

texto

ejemplo

"910"

Existencia por unidadUna cifra por cada unidad de venta

tipo

número decimal

ejemplo

248 (UN) · 41 (CJ)

Si el producto se vende en dos unidades, hacen falta las dos existencias, o la conversión para calcularlas.

No filtren por existencia mayor a cero. Se necesitan también las filas en cero y negativas: sin ellas es imposible ajustar el inventario de un producto agotado.
Ejemplo de respuesta
{
  "stock": [
    { "producto": "116231", "bodega": "910", "existencia1": 248, "existencia2": 41 },
    { "producto": "116232", "bodega": "910", "existencia1": 0,   "existencia2": 0  }
  ]
}

10 · Documentos del vendedor

obligatorio
Para qué: el historial de ventas, para consultarlo, reimprimirlo y aparearlo con lo que el teléfono tiene guardado.
Le enviamosvendedor y fecha desde. También por folio, para buscar uno puntual
CampoOblig.Para qué
Clave de origenLa clave que la aplicación envió al crearlo

tipo

texto

formato

UUID v4

ejemplo

"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.

Folio y tipoIdentificación del documento emitido

tipo

texto

ejemplo

"0000001244" · "BOLETA"

Fecha de emisiónOrdena el historial y alimenta el filtro por día

tipo

fecha y hora

formato

ISO-8601 con offset

ejemplo

"2026-09-10T11:05:00-03:00"

Cliente y sucursalA quién se le vendió

tipo

texto

ejemplo

"CL0042" · "001"

Totales neto, impuestos y brutoSe muestran y se reimprimen

tipo

entero

ejemplo

12354 · 2347 · 14701

Líneas del documentoProducto, cantidad, precios, descuentos e impuestos

tipo

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.

Estado de pagonoSi está pagado o pendiente, para la cobranza

tipo

texto

ejemplo

"PENDIENTE"

Ejemplo de respuesta
{
  "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
        }
      ]
    }
  ]
}

11 · Registrar la venta

obligatorio · escritura
Para qué: es el servicio que justifica la aplicación. Recibe el documento que el vendedor cerró en terreno.
Le enviamosla clave única del documento, el encabezado y las líneas
Campo del encabezadoOblig.Qué es
Clave únicaClave de idempotencia generada en el teléfono

tipo

texto

formato

UUID v4

ejemplo

"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.

Vendedor, empresa, modalidadQuién vende y bajo qué configuración

ejemplo

"11" · "01" · "PREVENTA"

Tipo de documentoPedido, boleta o factura

tipo

texto

ejemplo

"BOLETA"

Del vocabulario acordado. Es uno de los valores que hay que fijar antes de empezar a mapear.

Cliente y sucursalA quién se le vende

ejemplo

"CL0042" · "001"

Total brutoTotal del documento calculado por la aplicación

tipo

entero

ejemplo

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.

Condición de pagoContado o plazo

ejemplo

"CREDITO"

Fecha de entreganoCuándo se compromete el despacho

formato

ISO-8601 con offset

ejemplo

"2026-09-12T00:00:00-03:00"

ObservaciónnoNota que escribe el vendedor

tipo

texto

LíneasProducto, cantidad, unidad, precios, descuentos y tasas

tipo

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.

PagosnoSi la venta se cobra en el momento

tipo

lista

Medio de pago y monto. Si el pago es cheque, además banco, número y fecha.

Qué debe responderOblig.Para qué
Folio asignadoLa app lo muestra al vendedor y cierra el documento

tipo

texto

ejemplo

"0000001244"

Identificador internoPermite consultarlo después

tipo

texto o número

ejemplo

91

La clave recibidaCierra el ciclo de idempotencia

ejemplo

"ca12ec77-62bb-4f00-8226-1bc654d5a0c1"

Si la clave ya se había usadoIndicador explícito, con el folio existente

tipo

booleano

ejemplo

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.

Las tres reglas de grabación aplican enteras a este servicio. Es donde un incumplimiento produce documentos duplicados en el ERP, no una falla de pantalla.
Ejemplo de lo que enviamos
{
  "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 }
  ]
}
Ejemplo de respuesta — documento creado
{
  "clave": "ca12ec77-62bb-4f00-8226-1bc654d5a0c1",
  "folio": "0000001244",
  "tipoDocumento": "BOLETA",
  "id": 91,
  "claveYaUsada": false
}
Ejemplo de respuesta — la clave ya se había usado
{
  "clave": "ca12ec77-62bb-4f00-8226-1bc654d5a0c1",
  "folio": "0000001244",
  "tipoDocumento": "BOLETA",
  "id": 91,
  "claveYaUsada": true
}

Bloque opcional

Los veinte servicios de la segunda etapa

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.

Pedidos (nota de venta)

4 servicios
Habilita: tomar pedidos en terreno en vez de emitir la venta directa. Es la modalidad de preventa.
ServicioQué debe entregar
Registrar pedidoEscritura. Mismas reglas y misma respuesta que registrar la venta
Pedidos del vendedorHistorial de pedidos con su estado, y búsqueda por la clave de origen
Detalle del pedidoLíneas y totales
Stock comprometidoExistencia descontando los pedidos aún no despachados

Cobranza

3 servicios
Habilita: que el vendedor cobre documentos vencidos y rinda caja.
ServicioQué debe entregar
Deuda del clienteDocumentos por cobrar con monto, vencimiento y saldo
Registrar pagoEscritura. Qué documentos salda y con qué medio de pago
BancosLista de bancos, para el registro de cheques
Los pagos no tienen cola offline: requieren red en el momento. Si su servicio no está disponible, el pago se pierde. Conviene tenerlo presente al dimensionar la disponibilidad.

Crédito

1 servicio
Habilita: avisar al vendedor antes de vender que el cliente no tiene cupo.
ServicioQué debe entregar
Crédito del clienteCupo asignado, deuda vigente y saldo disponible, ya calculados

Historial ampliado

4 servicios
Habilita: consultas que van más allá del listado básico de ventas.
ServicioQué debe entregar
Detalle plano de documentosLa misma información en formato plano, para el arqueo de caja
Cadena de documentosQué documento originó a cuál: pedido, guía, factura
Origen de la facturaQué pedido dio origen a cada factura
Comprobante impresoImagen del comprobante lista para la impresora térmica. Opcional: la aplicación sabe componerlo sola

Alta de clientes

2 servicios
Habilita: que el vendedor cree o actualice clientes desde terreno.
ServicioQué debe entregar
Crear o actualizar clienteEscritura. Devuelve el código asignado
Comunas y territoriosPara completar la dirección con valores válidos

Complementos de catálogo

4 servicios
Habilita: agrupación, promociones e impuestos como maestros aparte.
ServicioQué debe entregar
FamiliasNombre de cada nivel de agrupación. Necesario solo si el catálogo trae los códigos sin nombre
PromocionesPromociones vigentes y a qué productos o clientes aplican
Definición de impuestosTasa y tipo de cada impuesto. Alternativa a traerlos en la lista de precio
Impuesto por productoQué impuestos afectan a cada producto

Metas y visitas

3 servicios
Habilita: seguimiento de objetivos del vendedor y registro de visitas sin venta.
ServicioQué debe entregar
Metas del vendedorMeta por período y su avance
Definición de metasCómo se mide cada una: en pesos, unidades o kilos
Motivos de no ventaLista de motivos con que el vendedor justifica una visita sin pedido

Fuera del alcance

Lo que no tienen que implementar

  • Sesión, licencia y configuración de la aplicación. Son nuestras y no dependen del ERP.
  • Notificaciones push y telemetría de uso. Nuestras.
  • Motor de pedidos sugeridos y servicios de fidelización. Viven fuera del ERP.
  • Optimizador de rutas. Servicio externo con alternativa local.
  • Cálculo de totales en pantalla. Lo hace la aplicación, sin red. Lo que necesitamos de ustedes son las tasas y los precios, no el total.

Antes de empezar

Qué necesitamos que confirmen

  • Si su API puede garantizar la idempotencia por clave del cliente, y si un error suyo garantiza que no se grabó nada. Son las dos condiciones cuyo incumplimiento produce documentos duplicados.
  • Si el precio por cliente y el tope de descuento vienen ya resueltos, o si entregan las reglas para que los calculemos. Lo primero es un mapeo; lo segundo es un desarrollo.
  • Qué límites de paginación y tamaño soporta su API, y si admite filtro por fecha de modificación en catálogo, clientes y precios.
  • Cómo autentican las llamadas y con qué vigencia.
  • Los vocabularios: qué valores usan para tipo de documento, unidad de medida, condición de pago, medio de pago y estado de un documento. Se acuerdan una vez y se mapean.
  • Qué servicios del bloque opcional existen hoy, para decidir el alcance de la primera etapa.