{ "openapi": "3.0.3", "info": { "title": "DeCAfacil API", "version": "1.2.0", "description": "API REST para integrar DeCAfacil con ERP, facturación, expediciones y gestores de flota. Permite sincronizar clientes, vehículos y conductores, crear viajes planificados o sin fecha, actualizar documentos, consultar su estado y recuperar la URL pública.\n\nLa autenticación se envía siempre en la cabecera `X-Api-Key`. Las llamadas de prueba actúan sobre la empresa asociada a esa clave.", "contact": { "name": "Soporte DeCAfacil", "email": "nts@netsistemas.com", "url": "https://deca.netsistemas.com/integracion-erp.html" }, "license": { "name": "Uso sujeto a las condiciones del servicio", "url": "https://deca.netsistemas.com/legal.php" } }, "externalDocs": { "description": "Guía de integración ERP, ejemplos y proyecto demostrativo", "url": "https://deca.netsistemas.com/integracion-erp.html" }, "servers": [ { "url": "https://deca.netsistemas.com", "description": "Servidor de DeCAfacil" } ], "tags": [ { "name": "Escritura", "description": "Alta y modificación de documentos DeCA. El campo `accion` del JSON selecciona la operación." }, { "name": "Consulta", "description": "Consulta individual, búsqueda por referencia del ERP y listados filtrados." }, { "name": "Maestros ERP", "description": "Sincronización idempotente de clientes, vehículos y conductores mediante `origenRegistro` e `idExterno`." } ], "security": [ { "ApiKeyAuth": [] } ], "paths": { "/api.php": { "post": { "tags": [ "Escritura" ], "operationId": "escribirDeca", "summary": "Crear o actualizar un DeCA", "description": "Use `accion=crear` para un alta y `accion=actualizar` junto con `id` para modificar un documento. La actualización funciona como un PATCH: conserva los campos que no se envían. Si se incluye `lineas`, sustituye todas las líneas de mercancía existentes.\n\nUn alta sin `fechaTransporte` queda no planificada y todavía no genera PDF. Al asignarle fecha mediante una actualización se validan los campos obligatorios y se genera la primera versión.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DecaCreateRequest" }, { "$ref": "#/components/schemas/DecaUpdateRequest" } ], "discriminator": { "propertyName": "accion", "mapping": { "crear": "#/components/schemas/DecaCreateRequest", "actualizar": "#/components/schemas/DecaUpdateRequest" } } }, "examples": { "crearPlanificado": { "summary": "Crear un viaje con fecha y mercancías", "value": { "accion": "crear", "cargadorNombre": "Harinas Leonesas SL", "cargadorNif": "B24010101", "cargadorDomicilio": "Pol. Ind. León Oeste 12, León", "transportistaNombre": "Transportes del Norte SL", "transportistaNif": "B00000001", "origen": "León", "destino": "Valladolid", "fechaTransporte": "2026-08-20", "matriculaTractora": "1234 KLM", "matriculaRemolque": "R 1234 ABC", "numAlbaran": "ALB-2026-001", "origenRegistro": "ERP_CLIENTE", "idExterno": "EXP-12345", "lineas": [ { "descripcion": "Harina de trigo", "cantidad": 40, "unidad": "sacos", "pesoKg": 1000 }, { "descripcion": "Sémola de trigo", "cantidad": 10, "unidad": "sacos", "pesoKg": 250 } ] } }, "crearNoPlanificado": { "summary": "Crear un viaje pendiente de fecha", "value": { "accion": "crear", "cargadorNombre": "Cerámicas Levante SA", "cargadorNif": "A46020202", "origen": "Valencia", "destino": "Burgos", "origenRegistro": "ERP_CLIENTE", "idExterno": "PRE-2026-0042", "observaciones": "Pendiente de planificación" } }, "asignarFecha": { "summary": "Asignar fecha a un viaje no planificado", "value": { "accion": "actualizar", "id": 125, "fechaTransporte": "2026-08-21", "cargadorDomicilio": "Av. Mediterráneo 18, Valencia", "matriculaTractora": "7350 LPD", "lineas": [ { "descripcion": "Azulejo cerámico paletizado", "cantidad": 18, "unidad": "palets", "pesoKg": 12600 } ] } }, "actualizarVehiculo": { "summary": "Cambiar vehículo sin alterar el resto", "value": { "accion": "actualizar", "id": 125, "matriculaTractora": "7350 LPD", "matriculaRemolque": "R 8841 LHG", "observaciones": "Cambio de tractora comunicado desde el ERP" } } } } } }, "responses": { "200": { "description": "Documento creado o actualizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecaWriteResponse" }, "examples": { "conPdf": { "summary": "Viaje con fecha", "value": { "ok": true, "idDeca": 125, "token": "7f4ef35861d34c748be6d12058741b96", "url": "https://deca.netsistemas.com/deca.php?t=7f4ef35861d34c748be6d12058741b96", "numVersion": 1, "pdf": true } }, "sinPdf": { "summary": "Viaje pendiente de fecha", "value": { "ok": true, "idDeca": 126, "token": "98d49c58694f4ccf8dd6585726127454", "url": "https://deca.netsistemas.com/deca.php?t=98d49c58694f4ccf8dd6585726127454", "numVersion": null, "pdf": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "tags": [ "Consulta" ], "operationId": "consultarDeca", "summary": "Consultar, buscar o listar DeCAs", "description": "El parámetro `accion` selecciona la consulta:\n\n- `consultar`: recupera un documento por `id`.\n- `buscar`: localiza el documento enlazado al ERP por `origen` e `idExterno`.\n- `listar`: devuelve una página de resultados y admite fechas opcionales.\n\nPara listar viajes no planificados use `noPlanificados=1`. En ese caso no filtre por fecha de transporte, ya que esos viajes no tienen ese valor.", "parameters": [ { "name": "accion", "in": "query", "required": true, "description": "Tipo de consulta que se va a ejecutar.", "schema": { "type": "string", "enum": [ "consultar", "buscar", "listar" ] }, "example": "listar" }, { "name": "id", "in": "query", "description": "Identificador DeCA. Obligatorio cuando `accion=consultar`.", "schema": { "type": "integer", "minimum": 1 }, "example": 125 }, { "name": "origen", "in": "query", "description": "Código estable del sistema origen. Obligatorio cuando `accion=buscar`.", "schema": { "type": "string" }, "example": "ERP_CLIENTE" }, { "name": "idExterno", "in": "query", "description": "Identificador del envío, expedición o albarán en el ERP. Obligatorio cuando `accion=buscar`.", "schema": { "type": "string" }, "example": "EXP-12345" }, { "name": "limit", "in": "query", "description": "Número máximo de registros. Solo para `accion=listar`.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "offset", "in": "query", "description": "Primer registro de la página. Solo para `accion=listar`.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "fechaCampo", "in": "query", "description": "Fecha sobre la que se aplican `fechaDesde` y `fechaHasta`. Solo para `accion=listar`.", "schema": { "type": "string", "enum": [ "creacion", "modificacion", "registro", "transporte" ], "default": "creacion" } }, { "name": "fechaDesde", "in": "query", "description": "Inicio inclusivo del filtro. Es opcional y puede usarse sin fecha final.", "schema": { "type": "string", "format": "date" }, "example": "2026-08-01" }, { "name": "fechaHasta", "in": "query", "description": "Fin inclusivo del filtro. Es opcional y puede usarse sin fecha inicial.", "schema": { "type": "string", "format": "date" }, "example": "2026-08-31" }, { "name": "noPlanificados", "in": "query", "description": "Use `1` para devolver únicamente viajes sin `fechaTransporte`. Solo para `accion=listar`.", "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0 } } ], "responses": { "200": { "description": "Consulta correcta. La estructura depende del valor de `accion`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DecaConsultaResponse" }, { "$ref": "#/components/schemas/DecaBusquedaResponse" }, { "$ref": "#/components/schemas/DecaListadoResponse" } ] }, "examples": { "consulta": { "summary": "Resultado de consultar por id", "value": { "ok": true, "idDeca": 125, "url": "https://deca.netsistemas.com/deca.php?t=7f4ef35861d34c748be6d12058741b96", "numVersion": 2, "fechaTransporte": "2026-08-21", "estado": { "anulado": false, "terminado": false, "albaranado": true, "numAlbaran": "ALB-2026-001" }, "origenRegistro": "ERP_CLIENTE", "idExterno": "EXP-12345", "lineas": [ { "descripcion": "Harina de trigo", "cantidad": 40, "unidad": "sacos", "pesoKg": 1000 } ] } }, "busquedaNoEncontrada": { "summary": "La referencia del ERP no existe", "value": { "ok": true, "encontrado": false } }, "listado": { "summary": "Página de resultados", "value": { "ok": true, "total": 1, "limit": 100, "offset": 0, "fechaCampo": "creacion", "items": [ { "idDeca": 125, "fechaTransporte": "2026-08-21", "cargadorNombre": "Harinas Leonesas SL", "origen": "León", "destino": "Valladolid", "mercancia": "Harina de trigo", "numVersion": 2, "url": "https://deca.netsistemas.com/deca.php?t=7f4ef35861d34c748be6d12058741b96", "fechaCreacion": "2026-08-20 09:30", "fechaModificacion": "2026-08-20 10:15", "fechaRegistro": "2026-08-20", "origenRegistro": "ERP_CLIENTE", "idExterno": "EXP-12345", "estado": { "anulado": false, "terminado": false, "albaranado": true, "numAlbaran": "ALB-2026-001" } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api_clientes.php": { "get": { "tags": [ "Maestros ERP" ], "operationId": "consultarClientes", "summary": "Consultar o listar clientes", "description": "Sin parametros de identificacion devuelve un listado paginado. Para obtener un registro concreto use `id` o la pareja `origen` + `idExterno`.", "parameters": [ { "name": "id", "in": "query", "description": "Identificador interno del cliente.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "origen", "in": "query", "description": "Sistema que asigno la referencia externa. Debe enviarse junto a idExterno.", "schema": { "type": "string", "maxLength": 50 } }, { "name": "idExterno", "in": "query", "description": "Identificador estable del registro en el ERP. Debe enviarse junto a origen.", "schema": { "type": "string", "maxLength": 80 } }, { "name": "activo", "in": "query", "description": "Filtra por estado. El valor predeterminado devuelve activos e inactivos.", "schema": { "type": "string", "enum": [ "todos", "1", "0" ], "default": "todos" } }, { "name": "q", "in": "query", "description": "Busqueda libre en los campos principales y la referencia externa.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "limit", "in": "query", "description": "Numero maximo de elementos de la pagina.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "description": "Primer elemento de la pagina.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Consulta correcta.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ClienteItemResponse" }, { "$ref": "#/components/schemas/ClienteListResponse" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "Maestros ERP" ], "operationId": "guardarCliente", "summary": "Crear, actualizar, activar o desactivar un cliente", "description": "Use `accion=guardar` para sincronizar de forma idempotente. Si ya existe la pareja `origenRegistro` + `idExterno`, el registro se actualiza; si no existe, se crea. `actualizar`, `activar` y `desactivar` admiten `id` o referencia externa. No se realiza borrado fisico.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClienteWriteRequest" }, "examples": { "sincronizar": { "summary": "Crear o actualizar cliente desde el ERP", "value": { "accion": "guardar", "nombre": "Harinas Leonesas SL", "nif": "B24010101", "domicilio": "Pol. Ind. Leon Oeste 12, Leon", "activo": true, "origenRegistro": "ERP_EMPRESA", "idExterno": "CLI-00428" } }, "desactivar": { "summary": "Desactivar por referencia del ERP", "value": { "accion": "desactivar", "origenRegistro": "ERP_EMPRESA", "idExterno": "CLI-00428" } } } } } }, "responses": { "200": { "description": "Registro actualizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClienteItemWriteResponse" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClienteItemWriteResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api_vehiculos.php": { "get": { "tags": [ "Maestros ERP" ], "operationId": "consultarVehiculos", "summary": "Consultar o listar vehículos", "description": "Sin parametros de identificacion devuelve un listado paginado. Para obtener un registro concreto use `id` o la pareja `origen` + `idExterno`.", "parameters": [ { "name": "id", "in": "query", "description": "Identificador interno del vehiculo.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "origen", "in": "query", "description": "Sistema que asigno la referencia externa. Debe enviarse junto a idExterno.", "schema": { "type": "string", "maxLength": 50 } }, { "name": "idExterno", "in": "query", "description": "Identificador estable del registro en el ERP. Debe enviarse junto a origen.", "schema": { "type": "string", "maxLength": 80 } }, { "name": "activo", "in": "query", "description": "Filtra por estado. El valor predeterminado devuelve activos e inactivos.", "schema": { "type": "string", "enum": [ "todos", "1", "0" ], "default": "todos" } }, { "name": "q", "in": "query", "description": "Busqueda libre en los campos principales y la referencia externa.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "limit", "in": "query", "description": "Numero maximo de elementos de la pagina.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "description": "Primer elemento de la pagina.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Consulta correcta.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/VehiculoItemResponse" }, { "$ref": "#/components/schemas/VehiculoListResponse" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "Maestros ERP" ], "operationId": "guardarVehiculo", "summary": "Crear, actualizar, activar o desactivar un vehículo", "description": "Use `accion=guardar` para sincronizar de forma idempotente. Si ya existe la pareja `origenRegistro` + `idExterno`, el registro se actualiza; si no existe, se crea. `actualizar`, `activar` y `desactivar` admiten `id` o referencia externa. No se realiza borrado fisico.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehiculoWriteRequest" }, "examples": { "sincronizar": { "summary": "Crear o actualizar vehiculo desde el ERP", "value": { "accion": "guardar", "matricula": "1234 KLM", "tipo": "tractora", "marca": "Volvo", "modelo": "FH 460", "activo": true, "origenRegistro": "ERP_EMPRESA", "idExterno": "VEH-00117" } }, "desactivar": { "summary": "Desactivar por referencia del ERP", "value": { "accion": "desactivar", "origenRegistro": "ERP_EMPRESA", "idExterno": "VEH-00117" } } } } } }, "responses": { "200": { "description": "Registro actualizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehiculoItemWriteResponse" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehiculoItemWriteResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api_conductores.php": { "get": { "tags": [ "Maestros ERP" ], "operationId": "consultarConductores", "summary": "Consultar o listar conductores", "description": "Sin parametros de identificacion devuelve un listado paginado. Para obtener un registro concreto use `id` o la pareja `origen` + `idExterno`.", "parameters": [ { "name": "id", "in": "query", "description": "Identificador interno del conductor.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "origen", "in": "query", "description": "Sistema que asigno la referencia externa. Debe enviarse junto a idExterno.", "schema": { "type": "string", "maxLength": 50 } }, { "name": "idExterno", "in": "query", "description": "Identificador estable del registro en el ERP. Debe enviarse junto a origen.", "schema": { "type": "string", "maxLength": 80 } }, { "name": "activo", "in": "query", "description": "Filtra por estado. El valor predeterminado devuelve activos e inactivos.", "schema": { "type": "string", "enum": [ "todos", "1", "0" ], "default": "todos" } }, { "name": "q", "in": "query", "description": "Busqueda libre en los campos principales y la referencia externa.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "limit", "in": "query", "description": "Numero maximo de elementos de la pagina.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "description": "Primer elemento de la pagina.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Consulta correcta.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ConductorItemResponse" }, { "$ref": "#/components/schemas/ConductorListResponse" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "Maestros ERP" ], "operationId": "guardarConductor", "summary": "Crear, actualizar, activar o desactivar un conductor", "description": "Use `accion=guardar` para sincronizar de forma idempotente. Si ya existe la pareja `origenRegistro` + `idExterno`, el registro se actualiza; si no existe, se crea. `actualizar`, `activar` y `desactivar` admiten `id` o referencia externa. No se realiza borrado fisico.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConductorWriteRequest" }, "examples": { "sincronizar": { "summary": "Crear o actualizar conductor desde el ERP", "value": { "accion": "guardar", "nombre": "Carlos Martin Gomez", "telefono": "34600111222", "activo": true, "origenRegistro": "ERP_EMPRESA", "idExterno": "CON-00032" } }, "desactivar": { "summary": "Desactivar por referencia del ERP", "value": { "accion": "desactivar", "origenRegistro": "ERP_EMPRESA", "idExterno": "CON-00032" } } } } } }, "responses": { "200": { "description": "Registro actualizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConductorItemWriteResponse" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConductorItemWriteResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "Clave de 32 caracteres asignada a la empresa. Trátela como una contraseña y no la incluya en URLs ni registros de diagnóstico." } }, "responses": { "BadRequest": { "description": "Petición incorrecta o datos incompletos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": "fechaTransporte debe ser YYYY-MM-DD." } } } }, "Unauthorized": { "description": "Clave API ausente o no válida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": "Clave API no válida." } } } }, "Forbidden": { "description": "La empresa no tiene la API disponible o la suscripción ha caducado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": "Suscripción caducada." } } } }, "NotFound": { "description": "Registro no encontrado para la empresa autenticada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": "DeCA no encontrado." } } } }, "Conflict": { "description": "Ya existe un registro con los mismos datos o referencia externa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": "Ya existe un DeCA para origen 'ERP_CLIENTE' / idExterno 'EXP-12345'. Use 'actualizar'." } } } }, "ServerError": { "description": "No se pudo completar la operación", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": "No se pudo completar la operación." } } } } }, "schemas": { "LineaMercancia": { "type": "object", "description": "Línea de mercancía transportada.", "properties": { "descripcion": { "type": "string", "maxLength": 200, "description": "Naturaleza de la mercancía." }, "cantidad": { "type": "number", "minimum": 0, "nullable": true, "description": "Cantidad en la unidad indicada." }, "unidad": { "type": "string", "maxLength": 30, "nullable": true, "description": "Unidad de medida: palets, bultos, sacos, m3, etc." }, "pesoKg": { "type": "number", "minimum": 0, "nullable": true, "description": "Peso de la línea en kilogramos." } } }, "DecaInputFields": { "type": "object", "properties": { "cargadorNombre": { "type": "string", "description": "Nombre o razón social del cargador contractual. Obligatorio cuando hay fecha de transporte." }, "cargadorNif": { "type": "string", "description": "NIF/CIF del cargador contractual. Obligatorio cuando hay fecha de transporte." }, "cargadorDomicilio": { "type": "string", "description": "Domicilio del cargador contractual. Obligatorio cuando hay fecha de transporte." }, "transportistaNombre": { "type": "string", "description": "Si se omite, se usa el nombre configurado para la empresa." }, "transportistaNif": { "type": "string", "description": "Si se omite, se usa el NIF configurado para la empresa." }, "origen": { "type": "string", "description": "Lugar de origen. Obligatorio cuando hay fecha de transporte." }, "destino": { "type": "string", "description": "Lugar de destino. Obligatorio cuando hay fecha de transporte." }, "fechaTransporte": { "type": "string", "format": "date", "nullable": true, "description": "Fecha del viaje en formato YYYY-MM-DD. Omítala o envíe una cadena vacía para dejar el viaje no planificado." }, "matriculaTractora": { "type": "string", "description": "Matrícula del vehículo principal. Obligatoria cuando hay fecha de transporte." }, "matriculaRemolque": { "type": "string", "nullable": true, "description": "Matrícula del remolque, si existe. En una actualización puede enviarse vacía para eliminarla." }, "observaciones": { "type": "string", "nullable": true }, "numAlbaran": { "type": "string", "nullable": true, "description": "Número de albarán. En un alta, si se informa, el documento queda marcado como albaranado." }, "anulado": { "type": "boolean", "description": "Estado opcional, utilizado principalmente en actualizaciones." }, "terminado": { "type": "boolean", "description": "Estado opcional, utilizado principalmente en actualizaciones." }, "albaranado": { "type": "boolean", "description": "Estado opcional, utilizado principalmente en actualizaciones." }, "origenRegistro": { "type": "string", "nullable": true, "description": "Código estable del sistema que origina el registro, por ejemplo `ERP_CLIENTE`." }, "idExterno": { "type": "string", "nullable": true, "description": "Identificador del envío o expedición en el ERP. La pareja `origenRegistro` + `idExterno` debe ser única por empresa." }, "lineas": { "type": "array", "description": "Mercancías del viaje. Con fecha debe existir al menos una línea con descripción y, en alguna línea, `pesoKg` o `cantidad` + `unidad`. En una actualización, enviar esta propiedad sustituye todas las líneas anteriores.", "items": { "$ref": "#/components/schemas/LineaMercancia" } }, "mercancia": { "type": "string", "deprecated": true, "description": "Campo de compatibilidad para crear una sola línea. En integraciones nuevas use `lineas`." }, "pesoKg": { "type": "number", "minimum": 0, "deprecated": true, "description": "Campo de compatibilidad asociado a `mercancia`." }, "otraMagnitud": { "type": "string", "deprecated": true, "description": "Campo de compatibilidad asociado a `mercancia`." } } }, "DecaCreateRequest": { "allOf": [ { "$ref": "#/components/schemas/DecaInputFields" }, { "type": "object", "required": [ "accion" ], "properties": { "accion": { "type": "string", "enum": [ "crear" ] } } } ] }, "DecaUpdateRequest": { "allOf": [ { "$ref": "#/components/schemas/DecaInputFields" }, { "type": "object", "required": [ "accion", "id" ], "properties": { "accion": { "type": "string", "enum": [ "actualizar" ] }, "id": { "type": "integer", "minimum": 1, "description": "Identificador `idDeca` que se va a modificar." } } } ] }, "EstadoDeca": { "type": "object", "properties": { "anulado": { "type": "boolean" }, "terminado": { "type": "boolean" }, "albaranado": { "type": "boolean" }, "numAlbaran": { "type": "string", "nullable": true } } }, "DecaWriteResponse": { "type": "object", "required": [ "ok", "idDeca", "token", "url", "pdf" ], "properties": { "ok": { "type": "boolean" }, "idDeca": { "type": "integer" }, "token": { "type": "string", "description": "Token de la URL pública. Normalmente basta con conservar `url` e `idDeca`." }, "url": { "type": "string", "format": "uri", "description": "Dirección pública estable que puede enviarse al conductor." }, "numVersion": { "type": "integer", "nullable": true, "description": "Es nulo mientras el viaje no tenga fecha ni PDF." }, "pdf": { "type": "boolean", "description": "Indica si se generó una versión PDF en esta operación." } } }, "DecaConsultaResponse": { "type": "object", "required": [ "ok", "idDeca", "url", "estado", "lineas" ], "properties": { "ok": { "type": "boolean" }, "idDeca": { "type": "integer" }, "url": { "type": "string", "format": "uri" }, "numVersion": { "type": "integer", "nullable": true }, "fechaTransporte": { "type": "string", "format": "date", "nullable": true }, "estado": { "$ref": "#/components/schemas/EstadoDeca" }, "origenRegistro": { "type": "string", "nullable": true }, "idExterno": { "type": "string", "nullable": true }, "lineas": { "type": "array", "items": { "$ref": "#/components/schemas/LineaMercancia" } } } }, "DecaBusquedaResponse": { "type": "object", "required": [ "ok", "encontrado" ], "properties": { "ok": { "type": "boolean" }, "encontrado": { "type": "boolean" }, "idDeca": { "type": "integer", "nullable": true }, "url": { "type": "string", "format": "uri", "nullable": true }, "numVersion": { "type": "integer", "nullable": true }, "fechaTransporte": { "type": "string", "format": "date", "nullable": true } } }, "DecaListadoItem": { "type": "object", "properties": { "idDeca": { "type": "integer" }, "fechaTransporte": { "type": "string", "format": "date", "nullable": true }, "cargadorNombre": { "type": "string", "nullable": true }, "origen": { "type": "string", "nullable": true }, "destino": { "type": "string", "nullable": true }, "mercancia": { "type": "string", "nullable": true }, "numVersion": { "type": "integer", "nullable": true }, "url": { "type": "string", "format": "uri" }, "fechaCreacion": { "type": "string", "nullable": true, "example": "2026-08-20 09:30" }, "fechaModificacion": { "type": "string", "nullable": true, "example": "2026-08-20 10:15" }, "fechaRegistro": { "type": "string", "format": "date", "nullable": true }, "origenRegistro": { "type": "string", "nullable": true }, "idExterno": { "type": "string", "nullable": true }, "estado": { "$ref": "#/components/schemas/EstadoDeca" } } }, "DecaListadoResponse": { "type": "object", "required": [ "ok", "total", "limit", "offset", "fechaCampo", "items" ], "properties": { "ok": { "type": "boolean" }, "total": { "type": "integer", "description": "Total de registros que cumplen el filtro." }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "fechaCampo": { "type": "string", "enum": [ "creacion", "modificacion", "registro", "transporte" ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/DecaListadoItem" } } } }, "ErrorResponse": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Mensaje legible que indica la causa del error." } } }, "ClienteWriteRequest": { "type": "object", "required": [ "accion" ], "properties": { "accion": { "type": "string", "enum": [ "crear", "actualizar", "guardar", "activar", "desactivar" ], "default": "guardar", "description": "`guardar` es la opcion recomendada para sincronizacion ERP porque crea o actualiza por referencia externa." }, "id": { "type": "integer", "minimum": 1, "description": "Id interno, necesario si no se usa referencia externa." }, "nombre": { "type": "string", "maxLength": 150 }, "nif": { "type": "string", "maxLength": 20 }, "domicilio": { "type": "string", "maxLength": 200, "nullable": true }, "activo": { "type": "boolean" }, "origenRegistro": { "type": "string", "maxLength": 50, "nullable": true, "description": "Codigo estable del sistema origen. Debe enviarse junto a idExterno." }, "idExterno": { "type": "string", "maxLength": 80, "nullable": true, "description": "Identificador estable en el ERP. Debe enviarse junto a origenRegistro." } } }, "VehiculoWriteRequest": { "type": "object", "required": [ "accion" ], "properties": { "accion": { "type": "string", "enum": [ "crear", "actualizar", "guardar", "activar", "desactivar" ], "default": "guardar", "description": "`guardar` es la opcion recomendada para sincronizacion ERP porque crea o actualiza por referencia externa." }, "id": { "type": "integer", "minimum": 1 }, "matricula": { "type": "string", "maxLength": 15 }, "tipo": { "type": "string", "enum": [ "tractora", "remolque", "rigido", "otro" ], "default": "tractora" }, "marca": { "type": "string", "maxLength": 60, "nullable": true }, "modelo": { "type": "string", "maxLength": 80, "nullable": true }, "activo": { "type": "boolean" }, "origenRegistro": { "type": "string", "maxLength": 50, "nullable": true, "description": "Codigo estable del sistema origen. Debe enviarse junto a idExterno." }, "idExterno": { "type": "string", "maxLength": 80, "nullable": true, "description": "Identificador estable en el ERP. Debe enviarse junto a origenRegistro." } } }, "ConductorWriteRequest": { "type": "object", "required": [ "accion" ], "properties": { "accion": { "type": "string", "enum": [ "crear", "actualizar", "guardar", "activar", "desactivar" ], "default": "guardar", "description": "`guardar` es la opcion recomendada para sincronizacion ERP porque crea o actualiza por referencia externa." }, "id": { "type": "integer", "minimum": 1 }, "nombre": { "type": "string", "maxLength": 150 }, "telefono": { "type": "string", "description": "Solo digitos. Si se envian 9 cifras se anade automaticamente el prefijo 34." }, "activo": { "type": "boolean" }, "origenRegistro": { "type": "string", "maxLength": 50, "nullable": true, "description": "Codigo estable del sistema origen. Debe enviarse junto a idExterno." }, "idExterno": { "type": "string", "maxLength": 80, "nullable": true, "description": "Identificador estable en el ERP. Debe enviarse junto a origenRegistro." } } }, "ClienteItem": { "type": "object", "properties": { "idCliente": { "type": "integer" }, "nombre": { "type": "string" }, "nif": { "type": "string" }, "domicilio": { "type": "string", "nullable": true }, "activo": { "type": "boolean" }, "origenRegistro": { "type": "string", "maxLength": 50, "nullable": true, "description": "Codigo estable del sistema origen. Debe enviarse junto a idExterno." }, "idExterno": { "type": "string", "maxLength": 80, "nullable": true, "description": "Identificador estable en el ERP. Debe enviarse junto a origenRegistro." }, "fechaAlta": { "type": "string", "format": "date-time" }, "fechaModificacion": { "type": "string", "format": "date-time" } } }, "VehiculoItem": { "type": "object", "properties": { "idVehiculo": { "type": "integer" }, "matricula": { "type": "string" }, "tipo": { "type": "string", "enum": [ "tractora", "remolque", "rigido", "otro" ] }, "marca": { "type": "string", "nullable": true }, "modelo": { "type": "string", "nullable": true }, "activo": { "type": "boolean" }, "origenRegistro": { "type": "string", "maxLength": 50, "nullable": true, "description": "Codigo estable del sistema origen. Debe enviarse junto a idExterno." }, "idExterno": { "type": "string", "maxLength": 80, "nullable": true, "description": "Identificador estable en el ERP. Debe enviarse junto a origenRegistro." }, "fechaAlta": { "type": "string", "format": "date-time" }, "fechaModificacion": { "type": "string", "format": "date-time" } } }, "ConductorItem": { "type": "object", "properties": { "idConductor": { "type": "integer" }, "nombre": { "type": "string" }, "telefono": { "type": "string" }, "activo": { "type": "boolean" }, "origenRegistro": { "type": "string", "maxLength": 50, "nullable": true, "description": "Codigo estable del sistema origen. Debe enviarse junto a idExterno." }, "idExterno": { "type": "string", "maxLength": 80, "nullable": true, "description": "Identificador estable en el ERP. Debe enviarse junto a origenRegistro." }, "fechaAlta": { "type": "string", "format": "date-time" }, "fechaModificacion": { "type": "string", "format": "date-time" } } }, "ClienteItemResponse": { "type": "object", "required": [ "ok", "item" ], "properties": { "ok": { "type": "boolean" }, "item": { "$ref": "#/components/schemas/ClienteItem" } } }, "ClienteWriteResponse": { "type": "object", "required": [ "ok", "creado", "item" ], "properties": { "ok": { "type": "boolean" }, "creado": { "type": "boolean", "description": "true si se creo; false si se actualizo." }, "item": { "$ref": "#/components/schemas/ClienteItem" } } }, "ClienteListResponse": { "type": "object", "required": [ "ok", "total", "limit", "offset", "items" ], "properties": { "ok": { "type": "boolean" }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ClienteItem" } } } }, "VehiculoItemResponse": { "type": "object", "required": [ "ok", "item" ], "properties": { "ok": { "type": "boolean" }, "item": { "$ref": "#/components/schemas/VehiculoItem" } } }, "VehiculoWriteResponse": { "type": "object", "required": [ "ok", "creado", "item" ], "properties": { "ok": { "type": "boolean" }, "creado": { "type": "boolean", "description": "true si se creo; false si se actualizo." }, "item": { "$ref": "#/components/schemas/VehiculoItem" } } }, "VehiculoListResponse": { "type": "object", "required": [ "ok", "total", "limit", "offset", "items" ], "properties": { "ok": { "type": "boolean" }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/VehiculoItem" } } } }, "ConductorItemResponse": { "type": "object", "required": [ "ok", "item" ], "properties": { "ok": { "type": "boolean" }, "item": { "$ref": "#/components/schemas/ConductorItem" } } }, "ConductorWriteResponse": { "type": "object", "required": [ "ok", "creado", "item" ], "properties": { "ok": { "type": "boolean" }, "creado": { "type": "boolean", "description": "true si se creo; false si se actualizo." }, "item": { "$ref": "#/components/schemas/ConductorItem" } } }, "ConductorListResponse": { "type": "object", "required": [ "ok", "total", "limit", "offset", "items" ], "properties": { "ok": { "type": "boolean" }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ConductorItem" } } } } } } }