{"openapi":"3.1.0","info":{"title":"DeCA Manager API","version":"0.1.0","description":"API autenticada para gestión de documentos DeCA."},"servers":[{"url":"/"}],"components":{"schemas":{"DecaParty":{"type":"object","additionalProperties":false,"required":["name","taxId"],"properties":{"name":{"type":"string","minLength":1,"maxLength":200},"taxId":{"type":"string","minLength":1,"maxLength":32}}},"DecaContractualLoader":{"type":"object","additionalProperties":false,"required":["name","taxId","address"],"properties":{"name":{"type":"string","minLength":1,"maxLength":200},"taxId":{"type":"string","minLength":1,"maxLength":32},"address":{"type":"string","minLength":1,"maxLength":300,"description":"Domicilio del cargador contractual exigido por el artículo 6.a."}}},"DecaShipment":{"type":"object","additionalProperties":false,"required":["origin","destination","goods"],"properties":{"origin":{"type":"string","minLength":1,"maxLength":300},"destination":{"type":"string","minLength":1,"maxLength":300},"goods":{"type":"string","minLength":1,"maxLength":500},"weightKg":{"oneOf":[{"type":"number","exclusiveMinimum":0},{"type":"string","minLength":1,"maxLength":40},{"type":"null"}]},"alternativeQuantity":{"type":["string","null"],"maxLength":500}},"description":"Cada envío debe indicar peso o una cantidad alternativa adecuada."},"DecaPayload":{"type":"object","additionalProperties":false,"required":["contractualLoader","effectiveCarrier","vehicle"],"anyOf":[{"required":["shipment"]},{"required":["shipments"]}],"properties":{"contractualLoader":{"$ref":"#/components/schemas/DecaContractualLoader"},"effectiveCarrier":{"$ref":"#/components/schemas/DecaParty"},"shipment":{"$ref":"#/components/schemas/DecaShipment","deprecated":true},"shipments":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/DecaShipment"}},"vehicle":{"type":"object","additionalProperties":false,"required":["tractor"],"properties":{"tractor":{"type":"string","minLength":1,"maxLength":16},"trailer":{"type":["string","null"],"maxLength":16}}},"driver":{"type":["object","null"],"additionalProperties":false,"required":["name"],"properties":{"id":{"type":["string","null"],"format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":160},"taxId":{"type":["string","null"],"maxLength":32},"licenseNumber":{"type":["string","null"],"maxLength":64}}},"alternativeQuantity":{"type":["string","null"],"maxLength":500,"deprecated":true},"specialAuthorization":{"type":["string","null"],"minLength":1,"maxLength":500},"observations":{"type":["string","null"],"minLength":1,"maxLength":2000},"scope":{"type":["string","null"],"enum":["interior","cabotage","international",null]}}},"DecaDraftRequest":{"type":"object","additionalProperties":false,"required":["organizationId","number","legalRuleset","payload","serviceStartAt"],"properties":{"organizationId":{"type":"string","format":"uuid"},"number":{"type":"string","minLength":1,"maxLength":80},"legalRuleset":{"type":"string","minLength":1,"maxLength":80},"payload":{"$ref":"#/components/schemas/DecaPayload"},"serviceStartAt":{"type":"string","format":"date-time"}}},"IntegrationDecaDraftRequest":{"type":"object","additionalProperties":false,"required":["number","legalRuleset","payload","serviceStartAt"],"properties":{"number":{"type":"string","minLength":1,"maxLength":80},"legalRuleset":{"type":"string","minLength":1,"maxLength":80},"payload":{"$ref":"#/components/schemas/DecaPayload"},"serviceStartAt":{"type":"string","format":"date-time"}},"description":"La organización se obtiene de la API key; no se acepta organizationId en el cuerpo."},"MasterImportRequest":{"type":"object","required":["organizationId","type","csv"],"properties":{"organizationId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["drivers","vehicles","trailers","contractual_loaders","effective_carriers","shipment_locations","goods_catalog"]},"csv":{"type":"string","minLength":1,"maxLength":600000,"description":"CSV UTF-8: máximo 524288 bytes y 500 filas de datos. El separador se detecta desde la cabecera (coma o punto y coma)."}}},"MasterImportPreview":{"type":"object","required":["type","valid","totalRows","expectedHeaders","rows","errors"],"properties":{"type":{"type":"string","enum":["drivers","vehicles","trailers","contractual_loaders","effective_carriers","shipment_locations","goods_catalog"]},"valid":{"type":"boolean"},"totalRows":{"type":"integer","minimum":0,"maximum":500},"expectedHeaders":{"type":"array","items":{"type":"string"}},"rows":{"type":"array","items":{"type":"object","additionalProperties":{"type":"string"}}},"errors":{"type":"array","items":{"type":"object","required":["line","message"],"properties":{"line":{"type":"integer","minimum":1,"description":"Línea física final del registro, contando desde 1."},"field":{"type":"string"},"message":{"type":"string"}}}}}},"MasterImportResult":{"type":"object","required":["organizationId","masterType","importedCount","ids","replayed"],"properties":{"organizationId":{"type":"string","format":"uuid"},"masterType":{"type":"string","enum":["drivers","vehicles","trailers","contractual_loaders","effective_carriers","shipment_locations","goods_catalog"]},"replayed":{"type":"boolean","description":"true si se recuperó el resultado de un lote ya guardado."},"importedCount":{"type":"integer","minimum":1,"maximum":500},"ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":500}}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"apiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"}}},"paths":{"/health":{"get":{"operationId":"health","responses":{"200":{"description":"Servicio disponible"}}}},"/health/ready":{"get":{"operationId":"readiness","responses":{"200":{"description":"Servicio y Supabase preparados"},"503":{"description":"Dependencia no disponible"}}}},"/d/{publicToken}":{"get":{"operationId":"getPublicDecaPdf","parameters":[{"name":"publicToken","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"PDF DeCA vigente","content":{"application/pdf":{}}},"404":{"description":"Documento no encontrado"},"429":{"description":"Demasiadas consultas desde la misma dirección"},"503":{"description":"Storage no configurado"}}}},"/d/code/{numericCode}":{"get":{"operationId":"getPublicDecaPdfByNumericCode","parameters":[{"name":"numericCode","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{6}$"}}],"responses":{"200":{"description":"PDF DeCA por código numérico","content":{"application/pdf":{}}},"404":{"description":"Documento no encontrado"},"429":{"description":"Límite estricto de intentos para evitar enumeración"},"503":{"description":"Storage no configurado"}}}},"/r/{token}":{"get":{"operationId":"openRecipientService","responses":{"200":{"description":"Pagina movil del destinatario"},"404":{"description":"Enlace no disponible"}}}},"/r/{token}/pdf":{"get":{"operationId":"downloadRecipientPdf","responses":{"200":{"description":"PDF; registra la descarga","content":{"application/pdf":{}}},"404":{"description":"Enlace no disponible"}}}},"/r/{token}/qr":{"get":{"operationId":"downloadRecipientRoadQr","responses":{"200":{"description":"QR estable de carretera; registra la descarga","content":{"image/svg+xml":{}}},"404":{"description":"Enlace no disponible"}}}},"/r/{token}/confirm":{"post":{"operationId":"confirmRecipientReceipt","responses":{"200":{"description":"Acuse del poseedor del enlace, sin identidad verificada ni firma electronica"},"404":{"description":"Enlace no disponible"}}}},"/api/v1/organizations/{organizationId}/received-deca/analyze":{"post":{"security":[{"bearerAuth":[]}],"operationId":"analyzeReceivedDeca","parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pdfBase64":{"type":"string"},"url":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"Texto y datos sugeridos del DeCA recibido"},"400":{"description":"Falta el PDF o la URL, o la URL no está permitida"},"403":{"description":"Sin permisos"},"413":{"description":"PDF demasiado grande"},"415":{"description":"No es un PDF"},"502":{"description":"No se pudo descargar desde el QR"}}}},"/api/v1/organizations/{organizationId}/received-deca":{"post":{"security":[{"bearerAuth":[]}],"operationId":"registerReceivedDeca","parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"201":{"description":"DeCA recibido registrado"},"400":{"description":"Datos inválidos"},"403":{"description":"Sin permisos"},"409":{"description":"Ya estaba registrado"}}}},"/api/v1/deca/{id}/received-versions":{"post":{"security":[{"bearerAuth":[]}],"operationId":"addReceivedDecaVersion","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"201":{"description":"Nueva versión del DeCA recibido"},"400":{"description":"Datos inválidos"},"404":{"description":"No es un DeCA recibido"},"409":{"description":"Estado no permitido"}}}},"/api/v1/organizations/{organizationId}/deca-registry":{"get":{"security":[{"bearerAuth":[]}],"operationId":"getDecaRegistry","parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Registro de DeCA de la empresa con los datos de la versión vigente"},"400":{"description":"Rango de fechas inválido"},"403":{"description":"Sin acceso"}}}},"/api/v1/organizations/{organizationId}/operations":{"get":{"security":[{"bearerAuth":[]}],"operationId":"getOperationalDashboard","responses":{"200":{"description":"Indicadores de todos los documentos de la fecha en Europe/Madrid"},"403":{"description":"Sin acceso"}}}},"/api/v1/organizations/{organizationId}/trips":{"get":{"security":[{"bearerAuth":[]}],"operationId":"listTrips","responses":{"200":{"description":"Viajes"}}},"post":{"security":[{"bearerAuth":[]}],"operationId":"createTrip","responses":{"201":{"description":"Viaje creado"}}}},"/api/v1/trips/{tripId}/documents":{"post":{"security":[{"bearerAuth":[]}],"operationId":"attachDecaToTrip","responses":{"201":{"description":"Documento asociado tras validar fecha, vehiculo y conductor"},"422":{"description":"Documento incompatible"}}}},"/api/v1/deca/{id}/recipient-links":{"get":{"security":[{"bearerAuth":[]}],"operationId":"listRecipientLinks","responses":{"200":{"description":"Enlaces sin exponer sus tokens"}}},"post":{"security":[{"bearerAuth":[]}],"operationId":"createRecipientLink","responses":{"201":{"description":"Token mostrado una sola vez"}}}},"/api/v1/deca/{id}/recipient-links/{linkId}":{"delete":{"security":[{"bearerAuth":[]}],"operationId":"revokeRecipientLink","responses":{"200":{"description":"Enlace revocado"}}}},"/api/v1/deca/{id}/recipient-events":{"get":{"security":[{"bearerAuth":[]}],"operationId":"listRecipientEvents","responses":{"200":{"description":"Envios, descargas y acuses por version"}}}},"/api/v1/deca/{id}/confirm-receipt":{"post":{"security":[{"bearerAuth":[]}],"operationId":"confirmAuthenticatedDriverReceipt","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["versionId"],"properties":{"versionId":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Conductor asignado confirma exactamente la versión indicada"},"403":{"description":"El usuario no es el conductor asignado"},"422":{"description":"La versión fue sustituida"}}}},"/api/v1/notifications":{"get":{"security":[{"bearerAuth":[]}],"operationId":"listNotifications","responses":{"200":{"description":"Avisos del usuario"}}}},"/api/v1/notifications/{id}/read":{"patch":{"security":[{"bearerAuth":[]}],"operationId":"markNotificationRead","responses":{"200":{"description":"Aviso leido"}}}},"/api/v1/organizations/{organizationId}/deca/batch-issue":{"post":{"security":[{"bearerAuth":[]}],"operationId":"batchIssueDeca","responses":{"201":{"description":"Lote emitido"},"207":{"description":"Resultado individual con fallos parciales"},"409":{"description":"Conflicto de idempotencia"}}}},"/api/v1/organizations/{organizationId}/deca/download.zip":{"post":{"security":[{"bearerAuth":[]}],"operationId":"downloadDecaZip","responses":{"200":{"description":"ZIP con PDFs independientes","content":{"application/zip":{}}}}}},"/api/v1/deca/{id}/traceability.pdf":{"get":{"security":[{"bearerAuth":[]}],"operationId":"downloadTraceabilityReport","responses":{"200":{"description":"Informe generado por el sistema","content":{"application/pdf":{}}}}}},"/api/v1/deca/issue":{"post":{"security":[{"bearerAuth":[]}],"operationId":"issueDeca","responses":{"201":{"description":"DeCA emitido con PDF y enlace publico"},"400":{"description":"Datos invalidos"},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"503":{"description":"Storage no configurado"}}}},"/billing/signup":{"post":{"operationId":"billingSignup","description":"Alta desde la web pública: crea usuario, empresa y periodo de prueba.","responses":{"201":{"description":"Cuenta creada; se envía el enlace para crear la contraseña"},"400":{"description":"Datos inválidos"},"409":{"description":"El email ya tiene cuenta"},"429":{"description":"Demasiados intentos"},"503":{"description":"Alta no configurada"}}}},"/contact":{"post":{"operationId":"contactForm","description":"Formulario de contacto de la web pública.","responses":{"202":{"description":"Mensaje enviado"},"400":{"description":"Datos inválidos"},"429":{"description":"Demasiados intentos"},"503":{"description":"Correo no configurado"}}}},"/billing/webhook":{"post":{"operationId":"stripeWebhook","description":"Eventos de Stripe firmados (Stripe-Signature).","responses":{"200":{"description":"Evento procesado"},"400":{"description":"Firma inválida"},"503":{"description":"Stripe no configurado"}}}},"/api/v1/billing/status":{"get":{"security":[{"bearerAuth":[]}],"operationId":"getBillingStatus","parameters":[{"name":"organizationId","in":"query","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Plan, estado y uso del mes"},"403":{"description":"Sin acceso a la organización"}}}},"/api/v1/billing/checkout":{"post":{"security":[{"bearerAuth":[]}],"operationId":"createBillingCheckout","responses":{"201":{"description":"URL de pago de Stripe Checkout"},"403":{"description":"Solo propietario o administrador"},"409":{"description":"Ya existe una suscripción"},"503":{"description":"Stripe no configurado"}}}},"/api/v1/billing/portal":{"post":{"security":[{"bearerAuth":[]}],"operationId":"createBillingPortal","responses":{"201":{"description":"URL del portal de cliente de Stripe"},"403":{"description":"Solo propietario o administrador"},"409":{"description":"Sin suscripción contratada"},"503":{"description":"Stripe no configurado"}}}},"/api/v1/me":{"get":{"security":[{"bearerAuth":[]}],"operationId":"getMe","responses":{"200":{"description":"Usuario autenticado"},"401":{"description":"No autenticado"}}}},"/api/v1/legal-rulesets":{"get":{"security":[{"bearerAuth":[]}],"operationId":"listLegalRulesets","responses":{"200":{"description":"Catálogo de reglas normativas versionadas"},"401":{"description":"No autenticado"}}}},"/api/v1/organizations":{"get":{"security":[{"bearerAuth":[]}],"operationId":"listOrganizations","responses":{"200":{"description":"Organizaciones del usuario"},"401":{"description":"No autenticado"}}},"post":{"security":[{"bearerAuth":[]}],"operationId":"createOrganization","responses":{"201":{"description":"Organizacion creada"},"400":{"description":"Datos invalidos"},"401":{"description":"No autenticado"}}}},"/api/v1/organizations/{organizationId}/api-keys":{"get":{"security":[{"bearerAuth":[]}],"operationId":"listOrganizationApiKeys","parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Claves de integracion sin secretos"},"403":{"description":"Sin permisos"}}},"post":{"security":[{"bearerAuth":[]}],"operationId":"createOrganizationApiKey","parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"201":{"description":"Clave creada; el secreto se devuelve una sola vez"},"403":{"description":"Sin permisos"},"409":{"description":"Clave duplicada"}}}},"/api/v1/organizations/{organizationId}/api-keys/{keyId}":{"delete":{"security":[{"bearerAuth":[]}],"operationId":"revokeOrganizationApiKey","parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"keyId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Clave revocada"},"403":{"description":"Sin permisos"},"404":{"description":"Clave no encontrada"}}}},"/api/v1/organizations/{organizationId}/webhooks":{"get":{"security":[{"bearerAuth":[]}],"operationId":"listOrganizationWebhooks","parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Endpoints webhook sin secretos"},"403":{"description":"Sin permisos"}}},"post":{"security":[{"bearerAuth":[]}],"operationId":"createOrganizationWebhook","parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"201":{"description":"Endpoint HTTPS público creado; el secreto se devuelve una sola vez"},"400":{"description":"URL inválida, privada, reservada o no resoluble"},"403":{"description":"Sin permisos"},"503":{"description":"Cifrado de webhooks no configurado"}}}},"/api/v1/organizations/{organizationId}/webhooks/{webhookId}/status":{"patch":{"security":[{"bearerAuth":[]}],"operationId":"setOrganizationWebhookActive","parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"webhookId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Estado actualizado"},"403":{"description":"Sin permisos"},"404":{"description":"Endpoint no encontrado"}}}},"/api/v1/organizations/{organizationId}/webhooks/{webhookId}/deliveries":{"get":{"security":[{"bearerAuth":[]}],"operationId":"listOrganizationWebhookDeliveries","parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"webhookId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Estado de las entregas webhook"},"403":{"description":"Sin permisos"}}}},"/api/v1/organizations/{organizationId}/webhooks/{webhookId}/deliveries/{deliveryId}/retry":{"post":{"security":[{"bearerAuth":[]}],"operationId":"retryOrganizationWebhookDelivery","parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"webhookId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Entrega reencolada"},"403":{"description":"Sin permisos"},"404":{"description":"Entrega no encontrada"}}}},"/api/v1/organizations/{organizationId}/webhooks/{webhookId}/test":{"post":{"security":[{"bearerAuth":[]}],"operationId":"testOrganizationWebhook","parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"webhookId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"Evento de prueba encolado"},"403":{"description":"Sin permisos"},"409":{"description":"Endpoint inactivo"},"503":{"description":"Entrega webhook no configurada"}}}},"/api/v1/organizations/{organizationId}/members/{userId}":{"patch":{"security":[{"bearerAuth":[]}],"operationId":"updateOrganizationMemberRole","parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"userId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["role"],"properties":{"role":{"type":"string","enum":["admin","operator","driver","auditor"]}}}}}},"responses":{"200":{"description":"Rol actualizado"},"400":{"description":"Datos invalidos"},"403":{"description":"Sin permisos"},"404":{"description":"Miembro no encontrado"}}},"delete":{"security":[{"bearerAuth":[]}],"operationId":"removeOrganizationMember","parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"userId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Miembro revocado"},"403":{"description":"Sin permisos"},"404":{"description":"Miembro no encontrado"}}}},"/api/v1/organizations/{organizationId}/members":{"get":{"security":[{"bearerAuth":[]}],"operationId":"listOrganizationMembers","parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Miembros de la organización"},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"}}}},"/api/v1/organizations/{organizationId}/invitations":{"get":{"security":[{"bearerAuth":[]}],"operationId":"listOrganizationInvitations","parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Invitaciones de la organización"},"403":{"description":"Sin permisos"}}},"post":{"security":[{"bearerAuth":[]}],"operationId":"createOrganizationInvitation","parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"201":{"description":"Invitación creada; el token debe enviarse por un canal seguro"},"400":{"description":"Datos inválidos"},"403":{"description":"Sin permisos"},"409":{"description":"Invitación pendiente duplicada"}}}},"/api/v1/organization-invitations/accept":{"post":{"security":[{"bearerAuth":[]}],"operationId":"acceptOrganizationInvitation","responses":{"200":{"description":"Invitación aceptada"},"400":{"description":"Token inválido"},"404":{"description":"Invitación no encontrada o caducada"}}}},"/api/v1/master-imports/template":{"get":{"security":[{"bearerAuth":[]}],"operationId":"downloadMasterImportTemplate","parameters":[{"name":"type","in":"query","required":true,"schema":{"type":"string","enum":["drivers","vehicles","trailers","contractual_loaders","effective_carriers","shipment_locations","goods_catalog"]}}],"responses":{"200":{"description":"Plantilla CSV UTF-8 con cabeceras","content":{"text/csv":{}}},"400":{"description":"Tipo de maestro inválido"},"401":{"description":"No autenticado"}}}},"/api/v1/master-imports/preview":{"post":{"security":[{"bearerAuth":[]}],"operationId":"previewMasterImport","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterImportRequest"}}}},"responses":{"200":{"description":"CSV analizado; comprobar valid antes de confirmar. No escribe datos ni comprueba duplicados existentes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterImportPreview"}}}},"400":{"description":"Petición inválida"},"401":{"description":"No autenticado"},"403":{"description":"Sin acceso a la organización"},"413":{"description":"Cuerpo HTTP demasiado grande"}}}},"/api/v1/master-imports/commit":{"post":{"security":[{"bearerAuth":[]}],"operationId":"commitMasterImport","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Conservar la misma clave y datos al reintentar. Se limita al usuario y empresa actuales.","schema":{"type":"string","minLength":16,"maxLength":128,"pattern":"^[A-Za-z0-9_-]{16,128}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterImportRequest"}}}},"responses":{"200":{"description":"Resultado recuperado sin crear registros ni auditoría adicionales","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterImportResult"}}}},"201":{"description":"Maestros importados de forma atómica y auditada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterImportResult"}}}},"400":{"description":"Petición inválida o falta Idempotency-Key"},"401":{"description":"No autenticado"},"403":{"description":"Rol sin permisos"},"409":{"description":"Registro duplicado o clave reutilizada con otros datos; ninguna fila insertada"},"413":{"description":"Cuerpo HTTP demasiado grande"},"422":{"description":"CSV inválido o fallo de validación del lote"}}}},"/api/v1/deca":{"get":{"security":[{"bearerAuth":[]}],"operationId":"listDeca","responses":{"200":{"description":"DeCA recientes del usuario"},"401":{"description":"No autenticado"}}}},"/api/v1/integrations/deca":{"get":{"security":[{"apiKeyAuth":[]}],"operationId":"integrationListDeca","responses":{"200":{"description":"DeCA de la organizacion asociada a la API key"},"401":{"description":"API key invalida"},"403":{"description":"Scope insuficiente"},"503":{"description":"Integracion no configurada"}}}},"/api/v1/integrations/legal-rulesets":{"get":{"security":[{"apiKeyAuth":[]}],"operationId":"integrationListLegalRulesets","responses":{"200":{"description":"Reglas normativas disponibles para integraciones"},"401":{"description":"API key invalida"},"403":{"description":"Scope insuficiente"}}}},"/api/v1/integrations/deca/drafts":{"post":{"security":[{"apiKeyAuth":[]}],"operationId":"integrationCreateDecaDraft","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationDecaDraftRequest"}}}},"responses":{"200":{"description":"Respuesta repetida de forma idempotente"},"201":{"description":"Borrador creado"},"400":{"description":"Peticion invalida o sin idempotencia"},"403":{"description":"Scope insuficiente"},"409":{"description":"Numero de DeCA duplicado"}}}},"/api/v1/integrations/deca/drafts/{decaId}/issue":{"post":{"security":[{"apiKeyAuth":[]}],"operationId":"integrationIssueDeca","parameters":[{"name":"decaId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}}],"responses":{"200":{"description":"Respuesta repetida de forma idempotente"},"201":{"description":"DeCA emitido con PDF, QR y enlace publico"},"400":{"description":"Peticion invalida"},"403":{"description":"Scope insuficiente"},"409":{"description":"Peticion en curso o DeCA no listo"},"502":{"description":"Almacenamiento o idempotencia no disponible"}}}},"/api/v1/deca/{id}":{"get":{"security":[{"bearerAuth":[]}],"operationId":"getDecaDetail","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Detalle del DeCA y payload de la versión actual"},"401":{"description":"No autenticado"},"404":{"description":"DeCA no encontrado"}}}},"/api/v1/deca/{id}/pdf":{"get":{"security":[{"bearerAuth":[]}],"operationId":"downloadDecaPdf","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"PDF autorizado","content":{"application/pdf":{}}},"401":{"description":"No autenticado"},"404":{"description":"PDF no encontrado"},"503":{"description":"Storage no configurado"}}}},"/api/v1/deca/{id}/timeline":{"get":{"security":[{"bearerAuth":[]}],"operationId":"getDecaTimeline","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Eventos de auditoría del DeCA"},"401":{"description":"No autenticado"},"404":{"description":"DeCA no encontrado"}}}},"/api/v1/deca/{id}/status":{"post":{"security":[{"bearerAuth":[]}],"operationId":"transitionDecaStatus","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Estado cambiado; genera deca.status.changed cuando cambia"},"400":{"description":"Transicion invalida"},"403":{"description":"Sin permisos"},"422":{"description":"Estado no permitido"}}}},"/api/v1/deca/{id}/retention":{"patch":{"security":[{"bearerAuth":[]}],"operationId":"setDecaRetention","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Conservacion configurada"},"400":{"description":"Fecha invalida"},"403":{"description":"Sin permisos"}}}},"/api/v1/deca/{id}/public-link/disable":{"post":{"security":[{"bearerAuth":[]}],"operationId":"disableDecaPublicLink","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Enlace publico desactivado"},"400":{"description":"Motivo invalido"},"403":{"description":"Sin permisos"}}}},"/api/v1/deca/{id}/deliveries":{"post":{"security":[{"bearerAuth":[]}],"operationId":"recordDecaDelivery","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":128}}],"responses":{"200":{"description":"Entrega repetida de forma idempotente; el evento webhook no se duplica"},"201":{"description":"Entrega registrada y evento deca.delivery.recorded encolado"},"400":{"description":"Datos inválidos"},"403":{"description":"Sin permisos"},"404":{"description":"DeCA no encontrado"},"422":{"description":"Entrega no permitida"}}}},"/api/v1/deca/{id}/revisions":{"post":{"security":[{"bearerAuth":[]}],"operationId":"createDecaRevision","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"201":{"description":"Nueva version creada"},"400":{"description":"Datos invalidos"},"403":{"description":"Sin permisos"},"422":{"description":"Revision no permitida"}}}},"/api/v1/deca/{id}/vehicle-change":{"post":{"security":[{"bearerAuth":[]}],"operationId":"changeDecaVehicle","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tractorPlate","reason"],"properties":{"tractorPlate":{"type":"string","minLength":1,"maxLength":16},"trailerPlate":{"type":["string","null"],"maxLength":16},"reason":{"type":"string","minLength":1,"maxLength":500}}}}}},"responses":{"201":{"description":"Cambio auditado y nueva versión PDF publicada atómicamente"},"400":{"description":"Datos inválidos"},"403":{"description":"Sin permisos"},"404":{"description":"DeCA no encontrado"},"422":{"description":"Cambio no permitido o sin diferencias"}}}},"/api/v1/drivers":{"get":{"security":[{"bearerAuth":[]}],"operationId":"listDrivers","responses":{"200":{"description":"Conductores del usuario"}}},"post":{"security":[{"bearerAuth":[]}],"operationId":"createDriver","responses":{"201":{"description":"Conductor creado"},"400":{"description":"Datos invalidos"},"403":{"description":"Sin permisos"}}}},"/api/v1/drivers/{id}/status":{"patch":{"security":[{"bearerAuth":[]}],"operationId":"setDriverActive","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["active"],"properties":{"active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Estado del conductor actualizado"},"400":{"description":"Datos invalidos"},"403":{"description":"Sin permisos"},"404":{"description":"Conductor no encontrado"}}}},"/api/v1/drivers/{id}/phone":{"patch":{"security":[{"bearerAuth":[]}],"operationId":"setDriverPhone","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone"],"properties":{"phone":{"type":"string","nullable":true,"description":"Móvil; se guarda en E.164 (+34612345678). Vacío o null lo borra."}}}}}},"responses":{"200":{"description":"Teléfono del conductor actualizado"},"400":{"description":"Datos invalidos"},"403":{"description":"Sin permisos"},"404":{"description":"Conductor no encontrado"},"422":{"description":"Teléfono no válido"}}}},"/api/v1/drivers/{id}/user":{"patch":{"security":[{"bearerAuth":[]}],"operationId":"linkDriverUser","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["organizationId","userId"],"properties":{"organizationId":{"type":"string","format":"uuid"},"userId":{"type":"string","format":"uuid","nullable":true}}}}}},"responses":{"200":{"description":"Usuario del conductor actualizado"},"400":{"description":"Datos invalidos"},"403":{"description":"Sin permisos"},"404":{"description":"Conductor no encontrado"}}}},"/api/v1/vehicles":{"get":{"security":[{"bearerAuth":[]}],"operationId":"listVehicles","responses":{"200":{"description":"Vehiculos del usuario"}}},"post":{"security":[{"bearerAuth":[]}],"operationId":"createVehicle","responses":{"201":{"description":"Vehiculo creado"},"400":{"description":"Datos invalidos"},"403":{"description":"Sin permisos"}}}},"/api/v1/vehicles/{id}/status":{"patch":{"security":[{"bearerAuth":[]}],"operationId":"setVehicleActive","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["active"],"properties":{"active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Estado del vehiculo actualizado"},"400":{"description":"Datos invalidos"},"403":{"description":"Sin permisos"},"404":{"description":"Vehiculo no encontrado"}}}},"/api/v1/trailers":{"get":{"security":[{"bearerAuth":[]}],"operationId":"listTrailers","responses":{"200":{"description":"Remolques del usuario"}}},"post":{"security":[{"bearerAuth":[]}],"operationId":"createTrailer","responses":{"201":{"description":"Remolque creado"},"400":{"description":"Datos invalidos"},"403":{"description":"Sin permisos"},"409":{"description":"Matricula duplicada"}}}},"/api/v1/trailers/{id}/status":{"patch":{"security":[{"bearerAuth":[]}],"operationId":"setTrailerActive","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["active"],"properties":{"active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Estado del remolque actualizado"},"400":{"description":"Datos invalidos"},"403":{"description":"Sin permisos"},"404":{"description":"Remolque no encontrado"}}}},"/api/v1/contractual-loaders":{"get":{"security":[{"bearerAuth":[]}],"operationId":"listContractualLoaders","responses":{"200":{"description":"Cargadores contractuales de la organización"}}},"post":{"security":[{"bearerAuth":[]}],"operationId":"createContractualLoader","responses":{"201":{"description":"Cargador creado"},"400":{"description":"Datos inválidos"},"403":{"description":"Sin permisos"}}}},"/api/v1/contractual-loaders/{id}/status":{"patch":{"security":[{"bearerAuth":[]}],"operationId":"setContractualLoaderActive","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Estado actualizado"},"403":{"description":"Sin permisos"},"404":{"description":"Cargador no encontrado"}}}},"/api/v1/effective-carriers":{"get":{"security":[{"bearerAuth":[]}],"operationId":"listEffectiveCarriers","responses":{"200":{"description":"Transportistas efectivos de la organización"}}},"post":{"security":[{"bearerAuth":[]}],"operationId":"createEffectiveCarrier","responses":{"201":{"description":"Transportista creado"},"400":{"description":"Datos inválidos"},"403":{"description":"Sin permisos"}}}},"/api/v1/effective-carriers/{id}/status":{"patch":{"security":[{"bearerAuth":[]}],"operationId":"setEffectiveCarrierActive","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Estado actualizado"},"403":{"description":"Sin permisos"},"404":{"description":"Transportista no encontrado"}}}},"/api/v1/shipment-locations":{"get":{"security":[{"bearerAuth":[]}],"operationId":"listShipmentLocations","responses":{"200":{"description":"Ubicaciones de la organización"}}},"post":{"security":[{"bearerAuth":[]}],"operationId":"createShipmentLocation","responses":{"201":{"description":"Ubicación creada"},"400":{"description":"Datos inválidos"},"403":{"description":"Sin permisos"}}}},"/api/v1/shipment-locations/{id}/status":{"patch":{"security":[{"bearerAuth":[]}],"operationId":"setShipmentLocationActive","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Estado actualizado"},"403":{"description":"Sin permisos"},"404":{"description":"Ubicación no encontrada"}}}},"/api/v1/goods-catalog":{"get":{"security":[{"bearerAuth":[]}],"operationId":"listGoodsCatalog","responses":{"200":{"description":"Catálogo de mercancías"}}},"post":{"security":[{"bearerAuth":[]}],"operationId":"createGoodsCatalogItem","responses":{"201":{"description":"Mercancía creada"},"400":{"description":"Datos inválidos"},"403":{"description":"Sin permisos"}}}},"/api/v1/goods-catalog/{id}/status":{"patch":{"security":[{"bearerAuth":[]}],"operationId":"setGoodsCatalogActive","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Estado actualizado"},"403":{"description":"Sin permisos"},"404":{"description":"Mercancía no encontrada"}}}},"/api/v1/deca-templates":{"get":{"security":[{"bearerAuth":[]}],"operationId":"listDecaTemplates","responses":{"200":{"description":"Plantillas del usuario"}}},"post":{"security":[{"bearerAuth":[]}],"operationId":"createDecaTemplate","responses":{"201":{"description":"Plantilla creada"},"400":{"description":"Datos invalidos"},"403":{"description":"Sin permisos"}}}},"/api/v1/deca-templates/{id}/status":{"patch":{"security":[{"bearerAuth":[]}],"operationId":"setDecaTemplateFlags","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Favorito o estado actualizado"},"403":{"description":"Sin permisos"},"404":{"description":"Plantilla no encontrada"}}}},"/api/v1/deca/drafts":{"post":{"security":[{"bearerAuth":[]}],"operationId":"createDecaDraft","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecaDraftRequest"}}}},"responses":{"201":{"description":"Borrador creado"},"400":{"description":"Payload inválido"},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"}}}},"/api/v1/transport-document-assessments":{"get":{"security":[{"bearerAuth":[]}],"operationId":"listTransportDocumentAssessments","parameters":[{"name":"organizationId","in":"query","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Clasificaciones documentales"},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"}}},"post":{"security":[{"bearerAuth":[]}],"operationId":"createTransportDocumentAssessment","responses":{"201":{"description":"Clasificación documental registrada"},"400":{"description":"Datos inválidos"},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"422":{"description":"Clasificación incompatible"}}}},"/api/v1/transport-document-assessments/{id}/file":{"get":{"security":[{"bearerAuth":[]}],"operationId":"downloadAlternativeTransportDocument","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"PDF alternativo autenticado","content":{"application/pdf":{}}},"401":{"description":"No autenticado"},"404":{"description":"Archivo no encontrado"},"502":{"description":"Integridad incorrecta"}}},"post":{"security":[{"bearerAuth":[]}],"operationId":"uploadAlternativeTransportDocument","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/pdf":{"schema":{"type":"string","format":"binary","maxLength":5242880}}}},"responses":{"201":{"description":"PDF alternativo almacenado con hash"},"400":{"description":"Archivo vacío"},"401":{"description":"No autenticado"},"403":{"description":"Sin permisos"},"413":{"description":"Archivo demasiado grande"},"415":{"description":"No es un PDF"}}}},"/api/v1/deca/pdf-preview":{"post":{"security":[{"bearerAuth":[]}],"operationId":"previewDecaPdf","responses":{"200":{"description":"PDF generado","content":{"application/pdf":{}}},"400":{"description":"Datos inválidos"},"401":{"description":"No autenticado"}}}}}}