{
  "openapi": "3.0.3",
  "info": {
    "title": "API DI de residuos",
    "version": "1.0.0",
    "description": "API independiente para documentos DI de residuos. Se contrata con el alcance actual: no hay integración ni presentación ante eSIR u otras plataformas de la Administración. Una integración oficial solo puede acordarse dentro del plan A medida. No comparte operaciones ni documentación con la API DeCA. Envíe una sola credencial por petición."
  },
  "servers": [{"url": "https://decaerp.com"}],
  "tags": [{"name": "DI", "description": "Documentos de Identificación de residuos"}, {"name": "Catálogos DI"}],
  "security": [{"EmpresaApiKey": []}, {"UsuarioApiKey": []}, {"BearerApiKey": []}],
  "paths": {
    "/api-di/v1/catalogos.php": {
      "get": {
        "tags": ["Catálogos DI"], "summary": "Consultar catálogos limitados de DI",
        "responses": {"200": {"description": "Articulos y codigos LER visibles para la credencial, estados, tipos de operador y operaciones R/D", "content": {"application/json": {"schema": {"type": "object"}}}}, "401": {"$ref": "#/components/responses/NoAutorizado"}, "403": {"$ref": "#/components/responses/NoDisponible"}}
      }
    },
    "/api-di/v1/documentos.php": {
      "get": {
        "tags": ["DI"], "summary": "Listar documentos o consultar uno por id",
        "description": "Sin id, devuelve una página de documentos. Con id, devuelve el documento completo. Una clave personal solo ve los DI creados por ese usuario; una clave de empresa ve todos los de su empresa.",
        "parameters": [
          {"in": "query", "name": "id", "schema": {"type": "integer", "minimum": 1}, "description": "Identificador interno de DI; si se omite, se lista la colección"},
          {"in": "query", "name": "pagina", "schema": {"type": "integer", "minimum": 1, "maximum": 1000000, "default": 1}},
          {"in": "query", "name": "limite", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20}}
        ],
        "responses": {"200": {"description": "Documento o página de documentos", "content": {"application/json": {"schema": {"type": "object"}}}}, "401": {"$ref": "#/components/responses/NoAutorizado"}, "403": {"$ref": "#/components/responses/NoDisponible"}, "404": {"description": "Documento inexistente o fuera del alcance de la clave"}}
      },
      "post": {
        "tags": ["DI"], "summary": "Crear DI",
        "description": "Se exige claveAlta única por empresa para reintentos. Reutilizarla con otro contenido devuelve 409. EN_PREPARACION admite campos incompletos; PREPARADO aplica las validaciones actuales. No se envía nada a la Administración.",
        "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CrearDI"}, "example": {"claveAlta": "e1c4d127e6177628497868da510c567930bda45570a91cbfddcce590a01dab69", "estado": "EN_PREPARACION", "datos": {"referencia": "ERP-001", "observaciones": "Pendiente de completar"}}}}},
        "responses": {"201": {"description": "DI creado o reintento idéntico", "headers": {"Location": {"schema": {"type": "string", "format": "uri"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DI"}}}}, "400": {"description": "Datos o JSON incorrectos"}, "401": {"$ref": "#/components/responses/NoAutorizado"}, "403": {"$ref": "#/components/responses/NoDisponible"}, "409": {"description": "Clave de alta reutilizada con otros datos"}}
      },
      "put": {
        "tags": ["DI"], "summary": "Actualizar DI completo por id",
        "description": "Requiere ?id=... y la versión actual. Se envía el objeto datos completo, no un parche parcial. Los DI RECIBIDO y RECHAZADO quedan cerrados.",
        "parameters": [{"in": "query", "name": "id", "required": true, "schema": {"type": "integer", "minimum": 1}}],
        "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ActualizarDI"}}}},
        "responses": {"200": {"description": "Versión vigente", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DI"}}}}, "400": {"description": "Datos o transición incorrectos"}, "401": {"$ref": "#/components/responses/NoAutorizado"}, "403": {"$ref": "#/components/responses/NoDisponible"}, "404": {"description": "Documento inexistente o fuera del alcance"}, "409": {"description": "Versión obsoleta o documento cerrado"}}
      }
    }
  },
  "components": {
    "securitySchemes": {
      "EmpresaApiKey": {"type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "Clave de empresa; 32 caracteres hexadecimales"},
      "UsuarioApiKey": {"type": "apiKey", "in": "header", "name": "X-User-Api-Key", "description": "Clave personal; prefijo du_ y 48 caracteres hexadecimales"},
      "BearerApiKey": {"type": "http", "scheme": "bearer", "description": "Alternativa para enviar una sola clave de empresa o usuario"}
    },
    "responses": {
      "NoAutorizado": {"description": "Clave ausente, incorrecta o revocada"},
      "NoDisponible": {"description": "Empresa, usuario o módulo DI sin acceso vigente"}
    },
    "schemas": {
      "DatosDI": {"type": "object", "description": "Objeto DI completo. Los campos no indicados se normalizan como vacíos al crear; al actualizar hay que reenviar todos los datos existentes. idVehiculo, idRemolque e idConductor son opcionales: si se indican, el valor de matricula, remolque o conductor debe coincidir con un maestro activo visible para la credencial. Las referencias ya guardadas conservan su copia historica.", "properties": {"idVehiculo": {"type": "string", "description": "Id del vehiculo de DeCA visible; acompanar con matricula"}, "idRemolque": {"type": "string", "description": "Id del remolque visible; acompanar con remolque"}, "idConductor": {"type": "string", "description": "Id del conductor visible; acompanar con conductor"}}, "additionalProperties": true},
      "CrearDI": {"type": "object", "required": ["claveAlta", "estado", "datos"], "properties": {"claveAlta": {"type": "string", "pattern": "^[a-f0-9]{64}$"}, "estado": {"type": "string", "enum": ["EN_PREPARACION", "PREPARADO"]}, "datos": {"$ref": "#/components/schemas/DatosDI"}}},
      "ActualizarDI": {"type": "object", "required": ["version", "estado", "datos"], "properties": {"version": {"type": "integer", "minimum": 1}, "estado": {"type": "string", "enum": ["EN_PREPARACION", "PREPARADO", "RECIBIDO", "RECHAZADO"]}, "datos": {"$ref": "#/components/schemas/DatosDI"}}},
      "DI": {"type": "object", "properties": {"id": {"type": "integer"}, "numero": {"type": "integer"}, "estado": {"type": "string"}, "version": {"type": "integer"}, "fechaAlta": {"type": "string"}, "fechaModificacion": {"type": "string"}, "datos": {"$ref": "#/components/schemas/DatosDI"}, "urlConsulta": {"type": "string", "format": "uri"}, "urlPdf": {"type": "string", "format": "uri"}, "aviso": {"type": "string"}}}
    }
  }
}