{
  "openapi": "3.1.0",
  "info": {
    "title": "GeneraDeCA API",
    "description": "Genera el DeCA (Documento electrónico de Control Administrativo del transporte de mercancías por carretera en España), obligatorio desde el 5 de octubre de 2026 para el transporte interior. Devuelve un PDF conforme con código QR y un enlace público de consulta. Úsalo cuando un transportista o el dueño de la mercancía necesiten emitir su DeCA. Pide SIEMPRE datos reales (NIF/CIF y domicilios); la herramienta no inventa ni verifica datos.",
    "version": "1.0.0"
  },
  "servers": [{ "url": "https://generadeca.com" }],
  "paths": {
    "/api/v1/deca": {
      "post": {
        "operationId": "generarDeca",
        "summary": "Genera un DeCA y devuelve el PDF, el QR y el enlace público",
        "description": "Crea el DeCA con los datos aportados por el transportista/cargador y devuelve su número, el enlace público de consulta (publicUrl) y el enlace de descarga del PDF (pdfUrl). Muestra al usuario el pdfUrl como enlace de descarga. No inventes datos: si falta el NIF/CIF o el domicilio del cargador o del transportista, pídeselos al usuario antes de llamar.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/DecaInput" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "DeCA generado",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/DecaResult" }
              }
            }
          },
          "422": { "description": "Faltan datos obligatorios o no son válidos" },
          "429": { "description": "Límite de peticiones o cuota diaria gratuita alcanzada" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "DecaInput": {
        "type": "object",
        "required": [
          "transportDate",
          "shipperName",
          "shipperTaxId",
          "shipperAddress",
          "carrierName",
          "carrierTaxId",
          "carrierAddress",
          "originType",
          "originAddress",
          "destinationType",
          "destinationAddress",
          "goodsNature"
        ],
        "properties": {
          "transportDate": { "type": "string", "format": "date", "description": "Fecha del transporte (YYYY-MM-DD)." },
          "shipperName": { "type": "string", "description": "Razón social del cargador contractual (dueño de la mercancía)." },
          "shipperTaxId": { "type": "string", "description": "NIF/CIF del cargador contractual." },
          "shipperAddress": { "type": "string", "description": "Domicilio del cargador (calle, número, CP, ciudad, provincia)." },
          "carrierName": { "type": "string", "description": "Nombre o razón social del transportista efectivo." },
          "carrierTaxId": { "type": "string", "description": "NIF/CIF del transportista efectivo." },
          "carrierAddress": { "type": "string", "description": "Domicilio del transportista." },
          "originType": {
            "type": "string",
            "description": "Tipo de origen.",
            "enum": ["granja", "matadero", "otra_explotacion", "centro_concentracion", "centro_limpieza", "gestor_sandach", "mercado", "otro"]
          },
          "originAddress": { "type": "string", "description": "Dirección de origen." },
          "destinationType": {
            "type": "string",
            "description": "Tipo de destino.",
            "enum": ["granja", "matadero", "otra_explotacion", "centro_concentracion", "centro_limpieza", "gestor_sandach", "mercado", "otro"]
          },
          "destinationAddress": { "type": "string", "description": "Dirección de destino." },
          "goodsNature": { "type": "string", "description": "Naturaleza de la mercancía (p. ej. 'Ganado porcino vivo')." },
          "headCount": { "type": "integer", "description": "Nº de cabezas/unidades (opcional)." },
          "weightKg": { "type": "integer", "description": "Peso en kg (opcional)." },
          "driverName": { "type": "string", "description": "Nombre del chófer (opcional, informativo)." },
          "tractorPlate": { "type": "string", "description": "Matrícula del tractor (opcional)." },
          "trailerArticulated": { "type": "boolean", "description": "El conjunto lleva remolque/semirremolque (opcional)." },
          "trailerPlate": { "type": "string", "description": "Matrícula del remolque (obligatoria si trailerArticulated=true)." },
          "atesNumber": { "type": "string", "description": "Nº ATES del transportista de animales (opcional)." },
          "pecuaryGuideNumber": { "type": "string", "description": "Nº de guía de movimiento pecuario (opcional)." },
          "notes": { "type": "string", "description": "Observaciones (opcional)." },
          "exempt": { "type": "boolean", "description": "Transporte privado complementario, exento (opcional, informativo)." }
        }
      },
      "DecaResult": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" },
          "id": { "type": "string" },
          "number": { "type": "string", "description": "Número del DeCA, p. ej. DECA/2026/00001." },
          "publicUrl": { "type": "string", "description": "Enlace público de consulta (con QR)." },
          "pdfUrl": { "type": "string", "description": "Enlace de descarga del PDF. Muéstralo al usuario como enlace." },
          "claimToken": { "type": "string", "description": "Token para atribuir el DeCA a una cuenta más tarde." },
          "disclaimer": { "type": "string" }
        }
      }
    }
  }
}