Documentación de la API

Esta sección contiene la documentación técnica de la API REST de Planograma para integradores y socios: endpoints, métodos HTTP, parámetros, estructuras de datos y ejemplos de solicitudes y respuestas. La API la utilizan los sistemas externos (ERP, plataformas de comercio electrónico).

Note

Los nombres de los campos, los parámetros, las rutas y los ejemplos JSON se presentan exactamente tal como aparecen en la aplicación. El texto explicativo está en español, pero las denominaciones técnicas permanecen sin cambios.

Autenticación

Todas las solicitudes a /api/** requieren la cabecera Authorization; su ausencia devuelve 401 Unauthorized con el mensaje Invalid API KEY.

Los endpoints de integración (productos, stock, pedidos, NIR, etc.) usan las credenciales de usuario de Planograma enviadas en la cabecera Authorization, con el formato usuario:contraseña:

Authorization: Bearer <utilizator>:<parola>

El sistema divide el valor por el carácter : y autentica al usuario dentro del tenant actual (determinado a partir del subdominio/host). Si el formato no es correcto o las credenciales son inválidas, la respuesta es 401 Unauthorized.

Warning

Usa una cuenta dedicada de integración con los permisos mínimos necesarios. Las credenciales se transmiten únicamente por HTTPS.

Formato de las respuestas

La mayoría de los endpoints de integración devuelven un sobre estándar BaseApiResponse:

Campo	Tipo	Descripción
error	Boolean	true si la solicitud ha fallado
errorMessage	String?	el mensaje de error (cuando error=true)
status	Int?	el código de estado
data	T?	los datos útiles (lista u objeto, según el endpoint)

Los endpoints de tipo "read" devuelven en data una lista de objetos info (por ejemplo ProductInfo, OrderInfo).

Note

Las claves de identificación externa (thirdPartyReference, externalReference, externalOrderId, externalLineId) permiten a los integradores vincular los documentos de Planograma con sus propios registros, sin depender de los ID internos de Planograma.

---

API de integración

Productos

Recurso base: /api/product.

Método	Ruta	Descripción
POST	/api/product/read	listar productos con filtros
PUT	/api/product/add	añadir producto
POST	/api/product/update	actualizar productos
DELETE	/api/product/delete	eliminar productos
GET	/api/product/third-party-reference/{thirdPartyReference}/check	comprueba la existencia de un producto por referencia externa (devuelve Boolean)

La lectura (POST /api/product/read) recibe ReadProductsFilterRequest (paginación mediante page por defecto 1 y limit por defecto 100, más filtros: productIds, models, categoryIds, thirdPartyReferenceIds, active, etc.) y devuelve ProductApiResponse con una lista de ProductInfo.

Campos principales de ProductInfo:

productId, productName, productCode, sku, thirdPartyReference,
categoryId, categoryName, vatId, vatPercentage,
purchasePrice, sellingPrice, minimumStock,
totalQuantityInStock, totalReservedQuantity, totalFreeQuantity, stockInfo,
requiresSerialNumber, requiresBatchCode, requiresBatchDetails,
requiresProductionDate, requiresExpirationDate,
width, height, length, weight, volume, diameter, material, color, active

La adición (PUT /api/product/add) recibe AddProductApiRequest (campo obligatorio name, code; la categoría se indica mediante categoryId o categoryExternalReference; más los atributos de trazabilidad requiresSerialNumber, requiresBatchCode, etc.). La actualización (EditProductApiRequest) apunta a los productos mediante productIds, y la eliminación (DeleteProductApiRequest) mediante productIds o productModels.

Stock

Recurso base: api/stock.

Método	Ruta	Descripción
POST	api/stock/remaining-stock/{productId}	el stock disponible de un producto
POST	api/stock/all	listado paginado de los stocks
POST	api/stock/detailed-report	informe detallado de stock

POST api/stock/remaining-stock/{productId} recibe CheckStockClientRequest (source, includeReservations, location). Si location=true, el stock se desglosa por ubicaciones; de lo contrario se devuelve el total agregado.

POST api/stock/all acepta los parámetros de paginación page (por defecto 0) y size (por defecto 10) y el cuerpo GetStocksRequest:

{
  "includeReservations": false,
  "isActive": true,
  "location": false
}

Respuesta PagedStockResponse:

content: [ StockResponse ], totalElements, totalPages, size, number

donde StockResponse tiene: productId, productName, productCode, remainingQuantity y, cuando location=true, locationCode y locationName.

POST api/stock/detailed-report acepta los parámetros page (0), size (50), sortBy (productName), sortDirection (asc) y devuelve un informe detallado.

Pedidos

Recurso base: /api/order.

Método	Ruta	Descripción
POST	/api/order/read	listar pedidos con filtros
PUT	/api/order/add	añadir pedido
POST	/api/order/update	actualizar pedidos
POST	/api/order/order-ready	comprueba si un pedido está listo
DELETE	/api/order/delete	eliminar pedidos
PUT	/api/order/print-document	imprimir documento de pedido
POST	/api/order/picking-info	información de picking
POST	/api/order/start-picking	iniciar picking
PATCH	/api/order/update-status	actualizar estado del pedido
PATCH	/api/order/update-awb-link	actualizar enlace AWB externo
POST	/api/order/check-orders-in-waiting-for-supply	reverificación de pedidos en espera de stock

La lectura (ReadOrdersFilterRequest) filtra por orderIds, externalOrderIds, companyExternalReferences, warehouseIds, statuses, orderType, thirdPartyReferenceIds y devuelve OrderApiResponse con una lista de OrderInfo.

Campos principales de OrderInfo:

orderId, externalOrderId, thirdPartyReference,
warehouseId, warehouseName, warehouseCode, status, orderType,
requiresValidation, dateAdded, isReady, picked, comment,
awbExternalLink, invoiceExternalLink,
numberOfEnvelopes, numberOfPackages, totalWeight, fulfilledWeight,
orderProducts, orderRequirements,
companyThirdPartyReference, companyExternalReference

La adición (PUT /api/order/add) recibe CreateOrderApiRequest. Ejemplo simplificado:

{
  "externalOrderId": "WEB-1001",
  "warehouseId": 1,
  "orderType": 1,
  "validationRequired": 1,
  "company": { "name": "Client SRL", "cui": "RO123" },
  "orderProducts": [
    { "productModel": "ABC-123", "quantity": 2, "externalLineId": "L1", "locationCode": "A-01" }
  ]
}

externalOrderId es obligatorio y debe ser único. Las líneas (CreateOrderProductApiRequest) identifican el producto mediante productModel (o productId); locationCode reserva el stock de una ubicación determinada.

La actualización (UpdateOrderApiRequest) apunta a los pedidos mediante orderIds, externalOrderIds o thirdPartyReferenceIds, y los campos nuevos se indican en updateFields. PATCH /api/order/update-status (UpdateOrderStatusRequest: orderId, status, awbExternalLink) cambia el estado de un pedido.

POST /api/order/picking-info responde con PickingInfoApiResponse: picked, numberOfPackages, numberOfEnvelopes, totalWeight, pickerId, pickerUsername.

Entradas (NIR)

Recurso base: /api/nir.

Método	Ruta	Descripción
PUT	/api/nir/add	añadir NIR
PATCH	/api/nir/update	actualizar NIR
POST	/api/nir/read	listar NIR con filtros
POST	/api/nir/validation-info	información de validación
DELETE	/api/nir/delete	eliminar NIR
PATCH	/api/nir/update-external-reference	actualizar referencia externa
PATCH	/api/nir/update-packaging-type	actualizar tipo de embalaje

La adición (CreateNirApiRequest) requiere externalReference (obligatorio), warehouseId, supplierId, la lista nirProducts (NirProductApiInfo: code y quantity obligatorios, externalLineId) y validationRequired (por defecto true).

La lectura (ReadNirsFilterRequest) filtra por nirIds, externalOrderIds, externalClientIds, warehouseIds, thirdPartyReferenceIds y devuelve NirApiResponse con la lista de NirInfo (nirId, externalReference, warehouseId, validated, status, nirProducts, thirdPartyReference, purchaseOrders).

POST /api/nir/validation-info (NirValidationInfoApiRequest: nirId o externalReference) devuelve NirValidationInfoApiResponse con validated, scanInfoList, userUsername, etc.

Devoluciones

Recurso base: /api/return.

Método	Ruta	Descripción
PUT	/api/return/add	añadir devolución
POST	/api/return/read	listar devoluciones con filtros
POST	/api/return/validation-info	información de validación de devolución

PUT /api/return/add recibe CreateReturnApiRequest: externalReference y externalClientId (obligatorios), warehouseId, initialExternalOrderId, la lista returnedProducts (ReturnProductApiInfo: code, quantity).

Transferencias

Recursos: /api/transfer y /api/transfer-product.

Método	Ruta	Descripción
POST	/api/transfer/validate-transfer/{transferId}	validar transferencia
POST	/api/transfer/change-transfer-status/{transferId}/{transferStatus}	cambiar estado de la transferencia
DELETE	/api/transfer/delete-transfer/{transferId}	eliminar transferencia
POST	/api/transfer-product/add-transfer-product	añadir producto a la transferencia
DELETE	/api/transfer-product/delete-transfer-product/{transferProductId}	eliminar producto de la transferencia

La adición de un producto (ScanClientRequest) incluye: documentId, productId, quantity, sourceLocationCode, destinationLocationCode, batchCode, sn, ssccCode, etc. La respuesta es ClientBaseResponse (message, status).

Inventario

Recurso base: /api/inventory.

Método	Ruta	Descripción
POST	/api/inventory/stock-adjustment	ajuste de stock
GET	/api/inventory/{id}	información de inventario
GET	/api/inventory/{id}/delta	las diferencias (delta) del inventario

POST /api/inventory/stock-adjustment recibe StockAdjustmentRequest: locationCode, inventoryId, model, quantity, recordedQuantity, stockBatchId, snList, stockBatchCode, expirationDate, productionDate, validate.

Órdenes de compra

Recurso base: /api/purchase-order (requiere el permiso PURCHASE_ORDER).

Método	Ruta	Descripción
POST	/api/purchase-order/add	añadir orden de compra
GET	/api/purchase-order/{purchaseOrderId}	detalles de la orden de compra
PATCH	/api/purchase-order/update	actualizar
PATCH	/api/purchase-order/{purchaseOrderId}/status/{status}	cambiar estado
PATCH	/api/purchase-order/{purchaseOrderId}/close	cerrar
DELETE	/api/purchase-order/{purchaseOrderId}	eliminar
POST	/api/purchase-order/add-product	añadir producto
DELETE	/api/purchase-order/remove-product/{id}	eliminar producto

CreatePurchaseOrderDTO: date (obligatorio, formato dd.MM.yyyy), arrivalDate, supplier (obligatorio), warehouseId, nirs, comment, documentNumber.

Producción

Recurso base: /api/production.

Método	Ruta	Descripción
POST	/api/production/read	listar órdenes de producción con filtros
PUT	/api/production/add	añadir orden de producción
POST	/api/production/close-simplified-production/order/{orderId}	cerrar producción simplificada

La adición (AddProductionOrderRequest) requiere productId, quantity y thirdPartyReference. La respuesta (ProductionOrderApiResponse) contiene una lista de ProductionOrderInfo.

Nomencladores

Categorías (/api/category)

Método	Ruta	Descripción
POST	/api/category/read	listar categorías
PUT	/api/category/add	añadir
POST	/api/category/update	actualizar
DELETE	/api/category/delete	eliminar

CategoryInfo: categoryId, externalReference, categoryName, categoryDetails, thirdPartyReference, active.

Unidades de medida (/api/measurement-unit)

Método	Ruta	Descripción
PUT	/api/measurement-unit/add	añadir
POST	/api/measurement-unit/read	listar
POST	/api/measurement-unit/update	actualizar
DELETE	/api/measurement-unit/delete	eliminar

MeasurementUnitInfo: muId, name, code, details, status, thirdPartyReference.

Empresas (/api/company)

Método	Ruta	Descripción
POST	/api/company/read	listar empresas (clientes/proveedores)
PUT	/api/company/add	añadir
POST	/api/company/update	actualizar
DELETE	/api/company/delete	eliminar
GET	/api/company/third-party-reference/{thirdPartyReference}/check	comprueba la existencia por referencia externa

CompanyInfo: companyId, externalReference, name, cui, regNo, bank, iban, address, phone, email, website, type, active, thirdPartyReference.

Metadatos

Recurso base: /api/metadata. Endpoints ligeros para verificar la existencia/mapeo de los registros, antes de una sincronización completa.

Método	Ruta	Descripción
POST	/api/metadata/category	metadatos de categorías
POST	/api/metadata/product	metadatos de productos
POST	/api/metadata/product/by_model	metadatos de productos por modelo
POST	/api/metadata/order	metadatos de pedidos

Todos reciben ReadMetadataApiRequest (active, thirdPartyReferenceIds, models).

Notificaciones, documentos y disparadores

Método	Ruta	Descripción
POST	/api/notifies	envía una notificación interna (ExternalNotifyRequest: title, message, recipientId)
POST	/api/printable-document/notice/{orderId}	genera el albarán del pedido en formato PDF (application/pdf)
GET	/softone/trigger/order/{id}	dispara la sincronización de un pedido
GET	/softone/trigger/nir/{id}	dispara la sincronización de un NIR
GET	/softone/trigger/delete/order/{id}	dispara la eliminación de un pedido

---

Note

Esta documentación cubre la estructura actual de la API. Para nuevas integraciones, contacta con el equipo de Planograma para obtener una cuenta de integración y para el mapeo de los estados específicos de tu sistema.