Son los archivos que el módulo de campo intercambia con tu ERP (página de planes): lo que importas en «Ajustes de la cuenta» › «Catálogo» › «Importar un CSV» y lo que descargas en «Pedidos» › «Entregar al ERP» y en «Albaranes» › «CSV para tu ERP». En Enterprise, las mismas importaciones van por la API de escritura: POST /api/portal/v1/imports/{kind}, con el archivo como cuerpo text/csv y una clave con catalogue:write. Las columnas van en inglés, sea cual sea el idioma del portal.
Reglas de toda importación
- UTF-8, con o sin marca de orden de bytes; lo demás se lee como Windows-1252, como lo guarda una hoja de cálculo en español.
- Coma o punto y coma (punto y coma solo si la cabecera no tiene comas); una cabecera solo con las columnas de abajo, todas las de negrita, en cualquier orden y sin distinguir mayúsculas, una vez cada una (si no, se rechaza el archivo); como máximo 1 MB y 5.000 filas.
- En el portal, un archivo con otras columnas, o en Excel o JSON, abre la confirmación de sus columnas (Catálogo e importaciones). Por la API (
import_csv), cualquier columna fuera de la lista rechaza todo el archivo (noHeader). - Una celda entre comillas puede contener el separador; ninguna celda ocupa varias líneas; se rechaza la fila que tenga más o menos celdas que la cabecera (
badColumns). - Cada fila se comprueba por separado: la rechazada se indica con su línea (la cabecera es la 1) y un motivo, y las demás se aplican, salvo que varias choquen por un mismo código o EAN: entonces no se aplica ninguna. Los caracteres de control e invisibles quedan como espacios.
- El archivo se lee en memoria y se descarta; de cada importación la cuenta guarda los recuentos y hasta 20 problemas, con su línea y motivo, nunca una celda.
- En una columna opcional, una celda vacía (o la columna que falta) deja el campo como está; en una de negrita, una celda vacía rechaza su fila; una celda con solo
-lo borra. - Un número entero admite decimales a cero, como los guarda Excel en español (
12,00,6.0).
Ni pedidos ni albaranes llevan precios, totales, impuestos ni plazos de pago, solo referencias y unidades: tu ERP pone los precios, factura y cobra.
Importaciones
| Archivo | Columnas (obligatorias en negrita) | Reglas |
|---|---|---|
Referencias (skus) |
code, name, case_size, ean, units_per_facing, product | code: tu propio código (letras, cifras, . _ - / y espacios, 40 como máximo). Un código nuevo necesita name y case_size (si no, incomplete). ean: el código de barras de la unidad que se lleva el comprador (la unidad de consumo), no el de la caja: GTIN-8, -12, -13 o -14 con su dígito de control, una referencia por código de barras en la cuenta (eanTaken); no un GTIN-14 que empieza por 1 a 9, de caja o embalaje (caseEan), ni 8 cifras que empiezan por 0 o 2, de circulación restringida (restrictedEan; un UPC-E, con sus 12 cifras). case_size: unidades por caja, de 1 a 10.000. units_per_facing: de 1 a 1.000. product: nuestro identificador de producto, o el nombre exacto de uno de tus productos, sin distinguir mayúsculas. Se rechaza una referencia retirada (archivedSku): ponla antes en uso. Como máximo 5.000 referencias en uso. |
Códigos de tienda (store_codes) |
store, code, chain_code, gln, email, price_list, chain, address, postcode, locality | store: nuestro identificador de tienda (la columna store_id de cualquier exportación); sin él, la cadena y la dirección. gln: 13 cifras con su dígito de control. email: adonde van los albaranes de la tienda, guardado en minúsculas (más abajo). price_list: el nombre de una de tus tarifas, sin distinguir mayúsculas. El código de una tienda es único en la cuenta. Una fila con todo vacío borra lo guardado de esa tienda. |
Precios de una tarifa (price_list) |
code, unit_price | En la tarifa elegida en el formulario (priceListId por la API). unit_price: en euros, con coma o punto delante de los céntimos (1,25, 0.99); con miles, solo si siguen los céntimos (1.250,00, 1,250.00): 1.250, ambiguo, se rechaza; como máximo 100.000; - saca la referencia de la tarifa. |
Respuestas del ERP a los pedidos (order_status) |
order, status, external_ref, reason | order: nuestro identificador de pedido (la columna order_id del archivo de entrega). status: acknowledged o rejected. external_ref: la referencia del ERP, 64 caracteres como máximo. reason: solo con rejected, 200 como máximo. Solo se responden pedidos entregados al ERP; la misma respuesta dos veces no cambia nada. |
Cargas de furgoneta (van_load) |
member, code, units | member: el correo de un miembro de campo de la cuenta. code: una referencia en uso. units: de 1 a 100.000, cargadas en su furgoneta. El mismo archivo, importado dos veces, carga una vez (alreadyLoaded). |
Descargas
Las dos van separadas por comas, empiezan con una marca de orden de bytes y usan CRLF; una celda que una hoja de cálculo leería como fórmula empieza por '. Excel en español espera punto y coma: ábrelas desde «Datos» › «Obtener datos» y pon como «Texto» las columnas de códigos, EAN y GLN, o perderán los ceros de delante.
| Archivo | Columnas | Reglas |
|---|---|---|
Pedidos entregados al ERP (pedidos-AAAA-MM-DD.csv) |
order_id, channel, confirmed_at, store_id, store_code, gln, store_name, line, sku_code, ean, units, note | Una línea por referencia de cada pedido confirmado, 1.000 pedidos por archivo (el resto espera al siguiente), marcados como entregados en el mismo paso para que ninguno salga dos veces; las entregas de los últimos 7 días se vuelven a descargar, 1.000 pedidos por parte, escritas con el catálogo de ese día. channel: visit, phone u office. Un pedido cuyo albarán se anula vuelve a estar confirmado y sale con la siguiente entrega, salvo que se vuelva a servir o se cancele. |
Albaranes (albaranes-AAAA-MM-DD.csv) |
delivery_number, status, delivered_at, store_id, store_code, gln, store_name, order_id, line, sku_code, ean, units | Una línea por referencia de cada albarán que nuestro servidor recibió en los últimos 7 días o 31 días, a elegir en la página (uno firmado sin conexión y recibido hoy va en el de hoy), 1.000 albaranes por parte. delivery_number: la serie y el número de la cuenta (A-000123). status: recorded o voided; un albarán anulado conserva su número. |
Los feeds de campo de la API
En Enterprise, una clave los lee en /api/portal/v1/feeds/{kind}.csv con el permiso de lectura del feed, mientras el módulo de campo esté abierto. Se escriben como las descargas: no nombran a nadie (assigned es true o false), no llevan precios y fechan las observaciones de los recorridos por semana ISO (de lunes a domingo, hora peninsular) y el trabajo del equipo por su hora UTC. Un archivo cortado en su límite lo dice en su última línea.
| Feed | Permiso | Columnas | Filas |
|---|---|---|---|
issues.csv |
issues:read |
id, store_id, store, chain, province, product_id, product, category_id, kind, status, priority, source, opened_week, last_checked_week, observed_at, done_at, team_check, team_checked_at, independent, independent_week, closed_week, resolution, reason_code, campaign_id, visit_id, assigned | Las incidencias abiertas y las cerradas movidas en las últimas 26 semanas, las más urgentes primero; 50.000 como máximo. |
orders.csv |
orders:read |
id, store_id, store, channel, status, version, external_ref, lines, units, created_at, confirmed_at, handed_off_at, answered_at, cancelled_at | Los pedidos escritos en los últimos days días (90 si no se indica, 365 como máximo), una fila cada uno; las líneas están en GET /orders/{id}. |
deliveries.csv |
deliveries:read |
como la descarga de albaranes | Los albaranes recibidos en los últimos days días (90 como máximo), 1.000 albaranes por part. |
scorecards.csv |
scorecards:read |
week, grain, key, store_id, territory_id, kind, total, fixed, verified, team_checked, independent, declined | Una week publicada (la última si no se indica), una fila por nivel y tipo; nunca por persona. |
Direcciones para los albaranes
El email de un código de tienda recibe los albaranes de la tienda cuando esta lo confirma; Venta en ruta y albaranes explica cómo.