{ "openapi": "3.0.3", "info": { "title": "DECA ERP - FORMATO NTS alternativo", "version": "1.3.1", "description": "Disponible por defecto para empresas actuales y nuevas con acceso API vigente. Misma clave de empresa que el formato habitual. El administrador puede desactivarlo por empresa. No envia notificaciones automaticamente. Maximo 2 MB por peticion y 5 MB por PDF. Las operaciones de prueba crean documentos reales.", "contact": { "name": "NetSistemas", "email": "soporte@decaerp.com" } }, "servers": [ { "url": "https://decaerp.com" }, { "url": "https://deca.netsistemas.com" } ], "externalDocs": { "description": "Guia del FORMATO NTS alternativo", "url": "https://decaerp.com/api-nts.html" }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] }, { "UserApiKeyAuth": [] } ], "paths": { "/api_nts.php": { "post": { "operationId": "crearDocumentoNts", "summary": "Crear, actualizar, sustituir o procesar un lote NTS", "description": "Sin accion, conserva el alta anterior. accion=actualizar conserva ID, GUID, numero, URL y QR, registra historial y genera una version PDF con fecha y cambios. Sin fecha guarda como pendiente. documentoOrigenId sigue creando un sustituto con otro GUID y URL. Clave personal: respeta el alcance del usuario.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Clave nueva por operacion; misma clave y JSON para reintentar. Reutilizarla con otros datos devuelve 409. Actualizar devuelve el recibo original sin aplicar de nuevo los cambios, incluso despues de otras ediciones. Sin cabecera, actualizar compara con los datos actuales; el alta conserva su deduplicacion por JSON. En lotes se añade :INDICE." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/OperacionNts" }, { "$ref": "#/components/schemas/Lote" } ] }, "examples": { "documento": { "summary": "Alta con datos ficticios", "value": { "numeroDocumento": "EJEMPLO-2026-001", "cargador": { "nif": "DEMO-CARGADOR", "razonSocial": "Granja de ejemplo", "domicilio": "Camino de ejemplo 5, Segovia", "email": "cargador@example.com" }, "transportista": { "nif": "DEMO-TRANSPORTISTA", "razonSocial": "Transportes de ejemplo", "domicilio": "Calle de ejemplo 10, Madrid", "email": "transportista@example.com" }, "vehiculo": { "matriculaTractora": "1234BCD", "matriculaRemolque": "R5678BCD", "tipo": "Frigorifico" }, "canalNotificacion": "EMAIL", "incluirConductorPdf": true, "conductores": [ { "dni": "DEMO-CONDUCTOR-01", "nombre": "Conductor de ejemplo", "numeroTarjeta": "TARJETA-EJEMPLO", "notaDeca": "Mercancia refrigerada. Acceso por muelle 2.", "mostrarNotaDeca": true, "contactos": [ { "tipoCanal": "EMAIL", "valor": "conductor@example.com" } ] } ], "grupos": [ { "esOrigenCargadorContractual": true, "destinos": [ { "razonSocial": "Destino de ejemplo", "domicilio": "Calle de ejemplo 20, Barcelona", "lineasMercancia": [ { "descripcion": "Mercancia de ejemplo", "peso": 1200, "unidadMedida": "KG", "bultos": 24, "palets": 2 } ] } ] } ], "observaciones": "Datos ficticios para una empresa de pruebas." } }, "lote": { "summary": "Lote de documentos", "value": { "documentos": [ { "numeroDocumento": "EJEMPLO-2026-001", "cargador": { "nif": "DEMO-CARGADOR", "razonSocial": "Granja de ejemplo", "domicilio": "Camino de ejemplo 5, Segovia", "email": "cargador@example.com" }, "transportista": { "nif": "DEMO-TRANSPORTISTA", "razonSocial": "Transportes de ejemplo", "domicilio": "Calle de ejemplo 10, Madrid", "email": "transportista@example.com" }, "vehiculo": { "matriculaTractora": "1234BCD", "matriculaRemolque": "R5678BCD", "tipo": "Frigorifico" }, "canalNotificacion": "EMAIL", "incluirConductorPdf": true, "conductores": [ { "dni": "DEMO-CONDUCTOR-01", "nombre": "Conductor de ejemplo", "numeroTarjeta": "TARJETA-EJEMPLO", "notaDeca": "Mercancia refrigerada. Acceso por muelle 2.", "mostrarNotaDeca": true, "contactos": [ { "tipoCanal": "EMAIL", "valor": "conductor@example.com" } ] } ], "grupos": [ { "esOrigenCargadorContractual": true, "destinos": [ { "razonSocial": "Destino de ejemplo", "domicilio": "Calle de ejemplo 20, Barcelona", "lineasMercancia": [ { "descripcion": "Mercancia de ejemplo", "peso": 1200, "unidadMedida": "KG", "bultos": 24, "palets": 2 } ] } ] } ], "observaciones": "Datos ficticios para una empresa de pruebas." } ] } }, "actualizar": { "summary": "Modificar matricula y observaciones conservando el DeCA", "value": { "accion": "actualizar", "doc_Id": "00000000-0000-4000-8000-000000000001", "versionEsperada": 1, "vehiculo": { "matriculaTractora": "9876XYZ", "matriculaRemolque": "R5678BCD" }, "observaciones": "Datos corregidos desde el ERP" } }, "actualizarMercancias": { "summary": "Reemplazar todos los grupos y lineas de mercancia", "value": { "accion": "actualizar", "doc_Id": "00000000-0000-4000-8000-000000000001", "grupos": [ { "esOrigenCargadorContractual": true, "destinos": [ { "razonSocial": "Destino de ejemplo", "domicilio": "Calle de ejemplo 20, Barcelona", "lineasMercancia": [ { "descripcion": "Mercancia de ejemplo", "peso": 1200, "unidadMedida": "KG", "bultos": 24, "palets": 2 } ] } ] } ] } } } } } }, "responses": { "200": { "description": "Actualizacion correcta, sin cambios o reintento reconocido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Exito" } } } }, "201": { "description": "Documento creado o sustituido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Exito" } } } }, "207": { "description": "Lote procesado. Revisar http y resultado de cada elemento; no hay reversion global.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResultadoLote" } } } }, "401": { "description": "Clave no valida o empresa inactiva.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Suscripcion vencida o formato deshabilitado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Documento origen no accesible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Use POST.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto de version, sustitucion, numero o idempotencia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Maximo 2 MB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "JSON o campos invalidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error interno. Reintente con la misma clave.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "BearerAuth": { "type": "http", "scheme": "bearer" }, "UserApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-User-Api-Key", "description": "Usar sola. Se aplican los permisos del usuario." } }, "schemas": { "Tercero": { "type": "object", "required": [ "razonSocial", "domicilio" ], "properties": { "razonSocial": { "type": "string", "minLength": 1, "maxLength": 150 }, "domicilio": { "type": "string", "minLength": 1, "maxLength": 200 }, "nif": { "type": "string", "maxLength": 20, "nullable": true }, "contacto": { "type": "string", "maxLength": 150, "nullable": true }, "telefono": { "type": "string", "maxLength": 30, "nullable": true }, "email": { "type": "string", "maxLength": 150, "nullable": true, "format": "email" } } }, "Cargador": { "oneOf": [ { "type": "object", "required": [ "idCliente" ], "properties": { "idCliente": { "type": "integer", "minimum": 1, "description": "Entidad activa de la misma empresa con rol de cliente/cargador." } } }, { "type": "object", "required": [ "razonSocial", "domicilio", "nif" ], "properties": { "razonSocial": { "type": "string", "minLength": 1, "maxLength": 150 }, "domicilio": { "type": "string", "minLength": 1, "maxLength": 200 }, "nif": { "type": "string", "minLength": 1, "maxLength": 20 }, "contacto": { "type": "string", "maxLength": 150, "nullable": true }, "telefono": { "type": "string", "maxLength": 30, "nullable": true }, "email": { "type": "string", "maxLength": 150, "nullable": true, "format": "email" } } } ], "description": "Opcional. Use idCliente o datos completos. Si se omite, se mantiene la compatibilidad y la empresa titular actua como cargador contractual." }, "Transportista": { "type": "object", "required": [ "razonSocial", "domicilio", "nif" ], "properties": { "razonSocial": { "type": "string", "minLength": 1, "maxLength": 150 }, "domicilio": { "type": "string", "minLength": 1, "maxLength": 200 }, "nif": { "type": "string", "minLength": 1, "maxLength": 20 }, "contacto": { "type": "string", "maxLength": 150, "nullable": true }, "telefono": { "type": "string", "maxLength": 30, "nullable": true }, "email": { "type": "string", "maxLength": 150, "nullable": true, "format": "email" } } }, "Vehiculo": { "type": "object", "required": [ "matriculaTractora" ], "properties": { "matriculaTractora": { "type": "string", "minLength": 1, "maxLength": 30, "description": "Tras normalizar espacios y guiones: de 2 a 15 letras o digitos." }, "matriculaRemolque": { "type": "string", "maxLength": 30, "nullable": true }, "tipo": { "type": "string", "maxLength": 80, "nullable": true } } }, "Contacto": { "type": "object", "required": [ "tipoCanal", "valor" ], "properties": { "tipoCanal": { "type": "string", "enum": [ "EMAIL", "WHATSAPP", "TELEGRAM", "SMS" ] }, "valor": { "type": "string", "minLength": 1, "maxLength": 150 } } }, "Conductor": { "type": "object", "required": [ "dni", "nombre" ], "properties": { "dni": { "type": "string", "minLength": 1, "maxLength": 40 }, "nombre": { "type": "string", "minLength": 1, "maxLength": 100 }, "numeroTarjeta": { "type": "string", "maxLength": 40, "nullable": true }, "notaDeca": { "type": "string", "maxLength": 300, "nullable": true, "description": "Nota operativa que se copia al documento. No incluya DNI, telefono, email ni datos privados innecesarios." }, "mostrarNotaDeca": { "type": "boolean", "default": false, "description": "Muestra notaDeca junto al nombre si el documento incluye conductores en el PDF." }, "contactos": { "type": "array", "minItems": 0, "maxItems": 4, "items": { "$ref": "#/components/schemas/Contacto" }, "description": "Un contacto por canal. EMAIL y telefonos SMS/WHATSAPP se validan." } } }, "Mercancia": { "type": "object", "required": [ "descripcion", "peso", "unidadMedida" ], "properties": { "descripcion": { "type": "string", "minLength": 1, "maxLength": 200 }, "peso": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 9999999999.99, "multipleOf": 0.01 }, "unidadMedida": { "type": "string", "minLength": 1, "maxLength": 30, "description": "KG y T disponibles inicialmente. Por defecto, otras unidades requieren configuracion por empresa. El administrador de la empresa puede desactivar esta validacion: se aceptara cualquier codigo de hasta 30 caracteres y, si no tiene factor configurado, no se calculara PesoKg." }, "bultos": { "type": "integer", "minimum": 0, "maximum": 2147483647, "nullable": true }, "palets": { "type": "number", "minimum": 0, "maximum": 9999999999.99, "multipleOf": 0.01, "nullable": true } } }, "Destino": { "type": "object", "required": [ "razonSocial", "domicilio", "lineasMercancia" ], "properties": { "razonSocial": { "type": "string", "minLength": 1, "maxLength": 150 }, "domicilio": { "type": "string", "minLength": 1, "maxLength": 200 }, "nif": { "type": "string", "maxLength": 20, "nullable": true }, "contacto": { "type": "string", "maxLength": 150, "nullable": true }, "telefono": { "type": "string", "maxLength": 30, "nullable": true }, "email": { "type": "string", "maxLength": 150, "nullable": true, "format": "email" }, "observaciones": { "type": "string", "maxLength": 300, "nullable": true }, "lineasMercancia": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "$ref": "#/components/schemas/Mercancia" } } } }, "Grupo": { "oneOf": [ { "type": "object", "required": [ "esOrigenCargadorContractual", "destinos" ], "properties": { "esOrigenCargadorContractual": { "type": "boolean", "enum": [ true ] }, "destinos": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "$ref": "#/components/schemas/Destino" } } } }, { "type": "object", "required": [ "esOrigenCargadorContractual", "origen", "destinos" ], "properties": { "esOrigenCargadorContractual": { "type": "boolean", "enum": [ false ] }, "origen": { "$ref": "#/components/schemas/Tercero" }, "destinos": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "$ref": "#/components/schemas/Destino" } } } } ] }, "Documento": { "type": "object", "required": [ "transportista", "vehiculo", "conductores", "grupos", "canalNotificacion" ], "properties": { "documentoOrigenId": { "type": "string", "maxLength": 36, "nullable": true, "format": "uuid", "description": "GUID del documento NTS vigente de la misma empresa para sustituirlo." }, "numeroDocumento": { "type": "string", "maxLength": 40, "nullable": true, "description": "Unico vigente por empresa. Se asigna si se omite; se conserva al sustituir." }, "fechaTransporte": { "type": "string", "maxLength": 10, "nullable": true, "format": "date", "description": "Si se omite, fecha de emision en Europe/Madrid." }, "observaciones": { "type": "string", "maxLength": 500, "nullable": true }, "canalNotificacion": { "type": "string", "enum": [ "EMAIL", "WHATSAPP", "TELEGRAM", "SMS" ], "description": "Se registra; no se envian mensajes automaticamente." }, "incluirConductorPdf": { "type": "boolean", "default": true, "description": "Incluye nombre y nota autorizada de los conductores en el PDF. Nunca incorpora DNI, telefono ni email." }, "cargador": { "$ref": "#/components/schemas/Cargador" }, "transportista": { "$ref": "#/components/schemas/Transportista" }, "vehiculo": { "$ref": "#/components/schemas/Vehiculo" }, "conductores": { "type": "array", "minItems": 1, "maxItems": 2, "items": { "$ref": "#/components/schemas/Conductor" }, "description": "DNI distintos." }, "grupos": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/Grupo" }, "description": "Maximo total por documento: 200 destinos y 1000 lineas." }, "accion": { "type": "string", "enum": [ "crear" ], "default": "crear" } } }, "Lote": { "type": "object", "required": [ "documentos" ], "properties": { "documentos": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "$ref": "#/components/schemas/OperacionNts" } } } }, "Exito": { "type": "object", "required": [ "resultado", "doc_Id", "numeroDocumento", "urlAcceso", "repetido", "incluirConductorPdf", "notificacion", "avisos", "idDeca" ], "properties": { "resultado": { "type": "string", "enum": [ "OK" ] }, "doc_Id": { "type": "string", "format": "uuid" }, "numeroDocumento": { "type": "string" }, "urlAcceso": { "type": "string", "format": "uri" }, "repetido": { "type": "boolean" }, "incluirConductorPdf": { "type": "boolean" }, "notificacion": { "type": "object", "required": [ "canal", "estado" ], "properties": { "canal": { "type": "string", "enum": [ "EMAIL", "WHATSAPP", "TELEGRAM", "SMS" ] }, "estado": { "type": "string", "enum": [ "NO_CONFIGURADO" ] } } }, "avisos": { "type": "array", "items": { "type": "string" } }, "numeroEmpresa": { "type": "integer", "format": "int64", "minimum": 1, "readOnly": true, "description": "Numero de DeCA consecutivo e inmutable por empresa. Solo lectura. No sustituye al ID global utilizado en peticiones y URLs." }, "idDeca": { "type": "integer", "format": "int32", "minimum": 1, "readOnly": true, "description": "ID global del DeCA, incluido en todas las respuestas correctas: altas, reintentos, sustituciones y actualizaciones. No es el numeroEmpresa." }, "numVersion": { "type": "integer", "nullable": true, "description": "Version PDF vigente tras actualizar; null si el viaje no tiene fecha." }, "cambiado": { "type": "boolean", "description": "Indica si la operacion de actualizacion guardo cambios." }, "pdfDisponible": { "type": "boolean" } } }, "Error": { "type": "object", "required": [ "resultado", "errores" ], "properties": { "http": { "type": "integer" }, "resultado": { "type": "string" }, "errores": { "type": "array", "items": { "type": "object", "required": [ "campo", "mensaje" ], "properties": { "campo": { "type": "string" }, "mensaje": { "type": "string" } } } } } }, "ResultadoLote": { "type": "object", "required": [ "resultado", "documentos" ], "properties": { "resultado": { "type": "string", "enum": [ "LOTE_PROCESADO" ] }, "documentos": { "type": "array", "items": { "allOf": [ { "type": "object", "required": [ "indice", "http" ], "properties": { "indice": { "type": "integer", "minimum": 0 }, "http": { "type": "integer" } } }, { "oneOf": [ { "$ref": "#/components/schemas/Exito" }, { "$ref": "#/components/schemas/Error" } ] } ] } } } }, "Actualizacion": { "type": "object", "additionalProperties": false, "required": [ "accion" ], "anyOf": [ { "required": [ "doc_Id" ] }, { "required": [ "id" ] } ], "properties": { "numeroDocumento": { "type": "string", "maxLength": 40, "nullable": true, "description": "Si se envia, debe coincidir con el original. No cambia al actualizar." }, "fechaTransporte": { "type": "string", "maxLength": 10, "nullable": true, "format": "date", "description": "Omitir conserva la fecha. null deja el viaje pendiente y no genera PDF; conserva los anteriores." }, "observaciones": { "type": "string", "maxLength": 500, "nullable": true }, "canalNotificacion": { "type": "string", "enum": [ "EMAIL", "WHATSAPP", "TELEGRAM", "SMS" ], "description": "Se registra; no se envian mensajes automaticamente." }, "incluirConductorPdf": { "type": "boolean", "default": true, "description": "Incluye nombre y nota autorizada de los conductores en el PDF. Nunca incorpora DNI, telefono ni email." }, "cargador": { "oneOf": [ { "$ref": "#/components/schemas/Cargador" }, { "type": "object", "nullable": true, "enum": [ null ] } ], "description": "Bloque completo, idCliente o null para volver a la empresa titular. Omitir conserva el cargador." }, "transportista": { "$ref": "#/components/schemas/Transportista" }, "vehiculo": { "type": "object", "properties": { "matriculaTractora": { "type": "string", "maxLength": 30, "nullable": true }, "matriculaRemolque": { "type": "string", "maxLength": 30, "nullable": true }, "tipo": { "type": "string", "maxLength": 80, "nullable": true } }, "description": "Solo cambia los campos enviados. null permite vaciar las matriculas." }, "conductores": { "type": "array", "minItems": 1, "maxItems": 2, "items": { "$ref": "#/components/schemas/Conductor" }, "description": "DNI distintos." }, "grupos": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/Grupo" }, "description": "Maximo total por documento: 200 destinos y 1000 lineas." }, "accion": { "type": "string", "enum": [ "actualizar" ] }, "doc_Id": { "type": "string", "format": "uuid", "description": "GUID del documento vigente. Alternativa a id." }, "id": { "type": "integer", "minimum": 1, "maximum": 2147483647, "description": "ID global del DeCA, no numeroEmpresa. Alternativa a doc_Id; si envia ambos deben coincidir." }, "versionEsperada": { "type": "integer", "minimum": 0, "description": "Opcional. Devuelve 409 si no coincide con la ultima version PDF almacenada." } }, "description": "Campos omitidos se conservan. grupos y conductores sustituyen sus listas completas; cargador y transportista son bloques completos. No enviar documentoOrigenId. Sin cambios no se crea otra version." }, "OperacionNts": { "oneOf": [ { "$ref": "#/components/schemas/Documento" }, { "$ref": "#/components/schemas/Actualizacion" } ] } } } }