Cómo mapear tu ERP
Esta página es una tabla de equivalencias entre los conceptos habituales de un ERP de logística o agroindustria y los campos del esquema DigiAnt. Su objetivo es reducir el tiempo de análisis previo a la integración.
Tabla de equivalencias
| Concepto habitual en el ERP | Campo DigiAnt | Notas |
|---|---|---|
| ID de orden de transporte, albarán, CMR | externalId (texto) | Obligatorio. El ID del documento en el ERP. DigiAnt lo usa para idempotencia — reintentar con el mismo externalId no crea duplicados. |
| Toneladas, kg, litros, m³ | quantity (número decimal) | Unidad libre — DigiAnt no la valida. Acuerda la unidad con el equipo DigiAnt durante el onboarding. |
| Producto, mercancía, grano, cereal | productId (UUID) | UUID del producto del catálogo DigiAnt. Consulta el catálogo con GET /partner/products. La respuesta devuelve el nombre como product. |
| Lote, partida, campaña | batch (texto) | Opcional — texto libre. |
| Formato de embalaje, envase | format (texto) | Opcional — texto libre. |
| Cliente, shipper, propietario del cargamento | productOwnerName / productOwnerCif / productOwnerPhone / productOwnerEmail | Todos obligatorios. |
| Punto de carga / expedidor | operationType: "loading" + partnerName / partnerCif / partnerPhone / partnerAddress / partnerWarehouseCode | Todos los campos partner* obligatorios. |
| Punto de descarga / destinatario / receptor | operationType: "unloading" + partnerName / partnerCif / … | Mismos campos partner*. |
| Empresa transportista | carrierTaxId (NIF/CIF, texto) | DigiAnt resuelve el NIF/CIF al UUID interno. El transportista debe estar registrado en DigiAnt; si no existe devuelve 422. |
| Conductor, chófer (en creación) | driverNif (NIF, texto) | Opcional en el push. DigiAnt lo resuelve al UUID interno. |
| Conductor, chófer (en actualización) | driverNif (NIF, texto) vía PATCH /authorizations/{id} | Mismo formato que en la creación. DigiAnt lo resuelve al UUID interno. |
| Matrícula del tractor / cabeza tractora | tractorPlate (texto) | Opcional — 1 a 8 caracteres alfanuméricos, se normaliza a mayúsculas. |
| Matrículas de remolques, semirremolques | trailerPlates (array de texto) | Opcional — array vacío por defecto. |
| Instalación, silo, planta, centro logístico | totemGroupId (UUID) | El "dónde" físico en DigiAnt — consultar con GET /partner/totem-groups. |
| Nave, silo, referencia interna del almacén | warehouseId (UUID) | UUID del almacén del catálogo DigiAnt. Consulta el catálogo con GET /partner/warehouses. La respuesta devuelve la referencia como warehouse. |
| Fecha prevista de carga/descarga | scheduledDate (datetime ISO) | Omitir en autorizaciones por peso sin fecha fija. |
| Fecha de vencimiento / fin de vigencia | endDate (datetime ISO) | Opcional. |
Patrones de transformación habituales
Unidades de cantidad
Acuerda con el equipo DigiAnt qué unidad usarás (toneladas métricas es lo más habitual en granel seco). La unidad no se valida ni se almacena junto al valor — un error de escala (kg en lugar de toneladas) se almacena sin error y afecta los informes de pesada.
Identificación de transportista
El Partner API acepta directamente el NIF/CIF del transportista en el campo carrierTaxId. DigiAnt lo resuelve al UUID interno en el momento de la creación. El transportista debe estar registrado previamente en DigiAnt; si el NIF/CIF no existe, la llamada devuelve 422.
Identificación del conductor
En la creación de la autorización, usa el NIF del conductor en driverNif. DigiAnt lo resuelve al UUID interno.
Si necesitas actualizar el conductor después, usa PATCH /authorizations/{id} con driverNif (NIF). El mismo formato que en la creación — DigiAnt lo resuelve al UUID interno.
Estado de la autorización
Las autorizaciones creadas vía Partner API nacen siempre en estado Active. No se puede fijar el estado en la creación. Para finalizarlas usa POST /authorizations/{id}/cancel, que las marca como Finished. El campo status en las respuestas devuelve "Active" o "Finished" (con mayúscula inicial).
Matrículas
DigiAnt normaliza las matrículas a mayúsculas automáticamente. Puedes enviarlas en cualquier capitalización. Los caracteres permitidos son alfanuméricos (A-Z, 0-9); cualquier carácter especial — guiones, espacios — produce un error 400.