Importador de datos

El importador permite dar de alta, modificar e inactivar datos maestros en forma masiva (artículos, clientes, precios de costo, rutas de preventa y otras tablas). No es un comando /data/cmd/...: tiene su propia URL y recibe los datos como multipart/form-data.

Request

POST https://<sitioweb>/data/import-export/import

Requiere el mismo token que el resto de la API (ver Convenciones). El body es multipart/form-data con dos partes, en este orden:

Parte (name)	Content-Type	Oblig.	Contenido
options	cualquiera	No	JSON con las opciones de importación (ver abajo). Tiene que ser la primera parte. Si se omite se usan los valores por defecto.
<nombre del importador>	application/json	Sí	Los datos a importar. El nombre de la parte indica qué importador usar (por ejemplo articulo o cliente, ver Tipos de importadores) y el contenido es el JSON de tablas que espera ese importador.

Se procesa una sola parte de datos por request: si se envían varias, solo se importa la primera. Si la parte options llega después de la de datos, se ignora y se usan los valores por defecto.

Opciones (options):

Parámetro	Tipo	Oblig.	Descripción
allowCreate	boolean	No	Permite crear registros que no existen. Default true.
allowUpdate	boolean	No	Permite modificar registros que ya existen. Default true.
allowRemove	boolean	No	Default false. Con true, el archivo se toma como la lista completa: los registros existentes que no vinieron en el archivo se inactivan o eliminan, según el importador. No sirve para borrar registros puntuales. Ver el detalle en cada importador.

{ "allowCreate": true, "allowUpdate": true, "allowRemove": false }

Ejemplo con curl:

curl -X POST https://<sitioweb>/data/import-export/import \
  -H "Authorization: Bearer eyJz93a...k4laUWw" \
  -F 'options={"allowCreate":true,"allowUpdate":true,"allowRemove":false}' \
  -F 'articulo.precio-costo=@costos.json;type=application/json'

Respuesta

Código	Cuándo
200 OK	La importación se procesó o fue rechazada por un problema de formato. Revisar status y generalError.
400 Bad Request	El nombre de la parte de datos no corresponde a ningún importador.
401 / 403	Ver Convenciones.

{
    "status": 2,
    "processed": 3,
    "generalError": "",
    "tables": [
        {
            "status": 2,
            "tableName": "clientes",
            "processed": 3,
            "updated": 1,
            "created": 1,
            "removed": 0,
            "withErrors": 1,
            "errors": [ "La sede S9 no existe" ]
        }
    ]
}

Campo	Tipo	Descripción
status	int	1 = aprobada (sin errores), 2 = parcial, 0 = rechazada, 3 = no procesada (solo en tablas).
processed	int	Total de registros procesados, sumando todas las tablas.
generalError	string	Error que impidió procesar el archivo (por ejemplo “Formato Incorrecto en tabla …”). Cadena vacía si no hubo.
tables	array	Resultado por tabla, en el mismo orden en que se enviaron.
tables[].tableName	string	Nombre interno de la tabla (ver cada importador).
tables[].processed / created / updated / removed	int	Registros procesados, creados, modificados y eliminados o inactivados.
tables[].withErrors	int	Registros (o lotes) con error.
tables[].errors	array[string]	Mensajes de error. Cada registro rechazado agrega un mensaje; los registros con error no se aplican y el resto sí.

Si el body no es multipart, si options no es un JSON válido o si la parte de datos no tiene Content-Type application/json, la respuesta es 200 con Status = 0 y el motivo en GeneralError (en estos casos los nombres de los campos llegan con mayúscula inicial).

Consultar el formato esperado

El esquema JSON de las tablas de cada importador se puede obtener con:

GET https://<sitioweb>/data/import-export/info?name=articulo

La respuesta trae canImport, canExport y tableSchemas (una entrada por tabla con tableName y jsonSchema).

Nota

Un error de base de datos en un lote cuenta como un solo error en withErrors, aunque el lote tenga muchos registros (los importadores de artículos, clientes y rutas procesan de a 300). En ese caso status puede decir parcial aunque no se haya aplicado ningún registro del lote: revisar siempre errors.

Tipos de importadores

Cada importador recibe una o más tablas. El JSON de la parte de datos es siempre un array de tablas, y cada tabla es un array de objetos (un objeto por registro). Las tablas se identifican por posición, no por nombre: tienen que llegar en el orden que indica cada importador.

[
    [
        { "codigo": "ART1", "descripcion": "Artículo nro 1" },
        { "codigo": "ART2", "descripcion": "Artículo nro 2" }
    ],
    [
        { "codigo": "ART1", "unidad": "Unidad", "codigoBarras": "7790001000011" }
    ]
]

• Hay que enviar todas las tablas del importador. Si una tabla no tiene datos, enviarla vacía ([]); si falta, la importación responde “Formato Incorrecto en tabla …” con status = 0, aunque las tablas anteriores ya se hayan procesado.
• Los nombres de los campos van en camelCase. Los campos que el importador no conoce se ignoran sin error.
• Cada registro se valida por separado: los que tienen errores se informan en errors y el resto se importa.

Importadores disponibles (el nombre es el name de la parte de datos):

Nombre	Tablas (en orden)	Descripción
articulo	articulos, unidades	Artículos con sus unidades y códigos de barra. Ver Artículos.
articulo.precio-costo	1 tabla	Actualización de precios de costo de artículos existentes. Ver Precios de costo.
cliente	clientes	Clientes. Ver Clientes.
ruta-preventa	rutas, asignacion	Rutas de preventa y su asignación a clientes. Ver Rutas de preventa.
proveedor	1 tabla	Proveedores. Consultar el esquema con /data/import-export/info?name=proveedor.
cliente.attr-proveedor	1 tabla	Datos del cliente según el proveedor (ramo, subramo, segmento). Consultar el esquema con /info.
familia, linea, marca, rubro, sabor, calibre	1 tabla	Tablas auxiliares de artículos. Cada registro tiene codigo (hasta 30 caracteres) y descripcion (hasta 90). Crean y actualizan; nunca eliminan, aunque se envíe allowRemove.