{
    "openapi": "3.1.0",
    "info": {
        "title": "API de DeCA gratis",
        "version": "1.0.0",
        "description": "Documento de control del transporte (DeCA) por API. Documentación: https://deca.transportistastop10.com/api/docs"
    },
    "servers": [
        {
            "url": "https://deca.transportistastop10.com/api/v1",
            "description": "Producción"
        },
        {
            "url": "https://deca-demo.transportistastop10.com/api/v1",
            "description": "Pruebas (claves dg_test_)"
        }
    ],
    "security": [
        {
            "bearer": []
        },
        {
            "apikey": []
        }
    ],
    "components": {
        "securitySchemes": {
            "bearer": {
                "type": "http",
                "scheme": "bearer"
            },
            "apikey": {
                "type": "apiKey",
                "in": "header",
                "name": "X-API-Key"
            }
        },
        "schemas": {
            "Error": {
                "type": "object",
                "properties": {
                    "error": {
                        "type": "object",
                        "properties": {
                            "codigo": {
                                "type": "string"
                            },
                            "mensaje": {
                                "type": "string"
                            },
                            "campos": {
                                "type": "object",
                                "additionalProperties": {
                                    "type": "string"
                                }
                            },
                            "request_id": {
                                "type": "string"
                            }
                        }
                    }
                }
            },
            "DecaEntrada": {
                "type": "object",
                "properties": {
                    "ref_externa": {
                        "type": "string",
                        "maxLength": 100,
                        "description": "Tu referencia (pedido, expedición). Única por cuenta: reenviar con la misma no duplica."
                    },
                    "emisor_rol": {
                        "type": "string",
                        "enum": [
                            "transportista",
                            "cargador"
                        ],
                        "description": "Qué lado eres. Por defecto, el de tu cuenta. Tu lado se rellena con tu empresa si lo dejas vacío."
                    },
                    "cargador_nombre": {
                        "type": "string",
                        "description": "Cargador contractual · nombre o razón social"
                    },
                    "cargador_nif": {
                        "type": "string",
                        "description": "Cargador contractual · NIF"
                    },
                    "cargador_domicilio": {
                        "type": "string",
                        "description": "Cargador contractual · domicilio"
                    },
                    "transp_nombre": {
                        "type": "string",
                        "description": "Transportista efectivo · nombre o razón social"
                    },
                    "transp_nif": {
                        "type": "string",
                        "description": "Transportista efectivo · NIF"
                    },
                    "fecha_transporte": {
                        "type": "string",
                        "description": "Fecha del transporte",
                        "format": "date"
                    },
                    "tipo_vehiculo": {
                        "type": "string",
                        "description": "Tipo de vehículo",
                        "enum": [
                            "rigido",
                            "articulado"
                        ]
                    },
                    "matricula": {
                        "type": "string",
                        "description": "Matrícula (tractora o rígido)"
                    },
                    "matricula_remolque": {
                        "type": "string",
                        "description": "Matrícula del remolque o semirremolque"
                    },
                    "autorizacion_especial": {
                        "type": "string",
                        "description": "Autorización especial de circulación"
                    },
                    "observaciones": {
                        "type": "string",
                        "description": "Observaciones"
                    },
                    "conductor_nombre": {
                        "type": "string",
                        "description": "Conductor"
                    },
                    "conductor_tel": {
                        "type": "string",
                        "description": "Teléfono del conductor"
                    },
                    "referencia": {
                        "type": "string",
                        "description": "Referencia interna"
                    },
                    "envios": {
                        "type": "array",
                        "maxItems": 48,
                        "items": {
                            "type": "object",
                            "required": [
                                "origen",
                                "destino",
                                "naturaleza",
                                "peso"
                            ],
                            "properties": {
                                "origen": {
                                    "type": "string"
                                },
                                "destino": {
                                    "type": "string"
                                },
                                "naturaleza": {
                                    "type": "string",
                                    "description": "Naturaleza de la mercancía"
                                },
                                "peso": {
                                    "type": [
                                        "number",
                                        "string"
                                    ]
                                },
                                "unidad": {
                                    "type": "string",
                                    "enum": [
                                        "kg",
                                        "t",
                                        "m3",
                                        "l",
                                        "palets",
                                        "bultos",
                                        "unidades",
                                        "contenedores"
                                    ],
                                    "default": "kg"
                                },
                                "nota": {
                                    "type": "string"
                                }
                            }
                        },
                        "description": "Uno o varios envíos (misma pareja cargador-transportista)"
                    },
                    "emitir": {
                        "type": "boolean",
                        "default": true,
                        "description": "false: queda pendiente y devuelve el enlace para que el otro lado complete sus datos"
                    },
                    "solo_validar": {
                        "type": "boolean",
                        "default": false
                    },
                    "pedir_datos_email": {
                        "type": "string",
                        "format": "email"
                    }
                }
            }
        }
    },
    "paths": {
        "/cuenta": {
            "get": {
                "summary": "Tu empresa, tu plan y el cupo del mes.",
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "401": {
                        "description": "Sin clave o clave no válida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Datos que faltan o no son válidos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Límite de peticiones o del plan"
                    }
                }
            }
        },
        "/decas": {
            "get": {
                "summary": "Lista de DeCA, del más nuevo al más viejo. Filtros: estado, desde, hasta (fecha del transporte), ref_externa, matricula, modificado_desde. Paginación: limite (máx. 100) y despues_de (el valor «siguiente» de la respuesta anterior).",
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "401": {
                        "description": "Sin clave o clave no válida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Datos que faltan o no son válidos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Límite de peticiones o del plan"
                    }
                }
            },
            "post": {
                "summary": "Crea un DeCA y, por defecto, lo emite (PDF, QR y URL). Con \"emitir\": false queda pendiente de los datos del otro lado y te devolvemos el enlace para que los complete (con \"pedir_datos_email\" se lo mandamos nosotros). Con \"solo_validar\": true no se guarda nada.",
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "401": {
                        "description": "Sin clave o clave no válida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Datos que faltan o no son válidos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Límite de peticiones o del plan"
                    },
                    "201": {
                        "description": "Creado"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "ref_externa": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "description": "Tu referencia (pedido, expedición). Única por cuenta: reenviar con la misma no duplica."
                                    },
                                    "emisor_rol": {
                                        "type": "string",
                                        "enum": [
                                            "transportista",
                                            "cargador"
                                        ],
                                        "description": "Qué lado eres. Por defecto, el de tu cuenta. Tu lado se rellena con tu empresa si lo dejas vacío."
                                    },
                                    "cargador_nombre": {
                                        "type": "string",
                                        "description": "Cargador contractual · nombre o razón social"
                                    },
                                    "cargador_nif": {
                                        "type": "string",
                                        "description": "Cargador contractual · NIF"
                                    },
                                    "cargador_domicilio": {
                                        "type": "string",
                                        "description": "Cargador contractual · domicilio"
                                    },
                                    "transp_nombre": {
                                        "type": "string",
                                        "description": "Transportista efectivo · nombre o razón social"
                                    },
                                    "transp_nif": {
                                        "type": "string",
                                        "description": "Transportista efectivo · NIF"
                                    },
                                    "fecha_transporte": {
                                        "type": "string",
                                        "description": "Fecha del transporte",
                                        "format": "date"
                                    },
                                    "tipo_vehiculo": {
                                        "type": "string",
                                        "description": "Tipo de vehículo",
                                        "enum": [
                                            "rigido",
                                            "articulado"
                                        ]
                                    },
                                    "matricula": {
                                        "type": "string",
                                        "description": "Matrícula (tractora o rígido)"
                                    },
                                    "matricula_remolque": {
                                        "type": "string",
                                        "description": "Matrícula del remolque o semirremolque"
                                    },
                                    "autorizacion_especial": {
                                        "type": "string",
                                        "description": "Autorización especial de circulación"
                                    },
                                    "observaciones": {
                                        "type": "string",
                                        "description": "Observaciones"
                                    },
                                    "conductor_nombre": {
                                        "type": "string",
                                        "description": "Conductor"
                                    },
                                    "conductor_tel": {
                                        "type": "string",
                                        "description": "Teléfono del conductor"
                                    },
                                    "referencia": {
                                        "type": "string",
                                        "description": "Referencia interna"
                                    },
                                    "envios": {
                                        "type": "array",
                                        "maxItems": 48,
                                        "items": {
                                            "type": "object",
                                            "required": [
                                                "origen",
                                                "destino",
                                                "naturaleza",
                                                "peso"
                                            ],
                                            "properties": {
                                                "origen": {
                                                    "type": "string"
                                                },
                                                "destino": {
                                                    "type": "string"
                                                },
                                                "naturaleza": {
                                                    "type": "string",
                                                    "description": "Naturaleza de la mercancía"
                                                },
                                                "peso": {
                                                    "type": [
                                                        "number",
                                                        "string"
                                                    ]
                                                },
                                                "unidad": {
                                                    "type": "string",
                                                    "enum": [
                                                        "kg",
                                                        "t",
                                                        "m3",
                                                        "l",
                                                        "palets",
                                                        "bultos",
                                                        "unidades",
                                                        "contenedores"
                                                    ],
                                                    "default": "kg"
                                                },
                                                "nota": {
                                                    "type": "string"
                                                }
                                            }
                                        },
                                        "description": "Uno o varios envíos (misma pareja cargador-transportista)"
                                    },
                                    "emitir": {
                                        "type": "boolean",
                                        "default": true,
                                        "description": "false: queda pendiente y devuelve el enlace para que el otro lado complete sus datos"
                                    },
                                    "solo_validar": {
                                        "type": "boolean",
                                        "default": false
                                    },
                                    "pedir_datos_email": {
                                        "type": "string",
                                        "format": "email"
                                    }
                                }
                            },
                            "example": {
                                "ref_externa": "PED-1001",
                                "referencia": "Albarán 1001",
                                "fecha_transporte": "2026-10-07",
                                "cargador_nombre": "Frutas Huerta S.L.",
                                "cargador_nif": "B12345674",
                                "cargador_domicilio": "Calle Mayor 1, 03001 Alicante",
                                "matricula": "1234BCD",
                                "matricula_remolque": "R5678BCF",
                                "conductor_nombre": "Juan Pérez",
                                "conductor_tel": "600123456",
                                "envios": [
                                    {
                                        "origen": "Alicante",
                                        "destino": "Valencia",
                                        "naturaleza": "Fruta en cajas",
                                        "peso": 12000,
                                        "unidad": "kg"
                                    }
                                ]
                            }
                        }
                    }
                }
            }
        },
        "/decas/{id}": {
            "get": {
                "summary": "Un DeCA con sus envíos y sus URL.",
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "401": {
                        "description": "Sin clave o clave no válida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Datos que faltan o no son válidos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Límite de peticiones o del plan"
                    }
                },
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "id numérico o número del DeCA (2026-000123)"
                    }
                ]
            },
            "patch": {
                "summary": "Pendiente: cambia los datos (y con \"emitir\": true, lo emite). Emitido: modificación por el método 1 (misma URL y mismo QR); exige \"motivo\".",
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "401": {
                        "description": "Sin clave o clave no válida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Datos que faltan o no son válidos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Límite de peticiones o del plan"
                    }
                },
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "id numérico o número del DeCA (2026-000123)"
                    }
                ]
            },
            "delete": {
                "summary": "Borra un DeCA PENDIENTE. Los emitidos no se borran: se conservan un año.",
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "401": {
                        "description": "Sin clave o clave no válida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Datos que faltan o no son válidos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Límite de peticiones o del plan"
                    }
                },
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "id numérico o número del DeCA (2026-000123)"
                    }
                ]
            }
        },
        "/decas/{id}/emitir": {
            "post": {
                "summary": "Emite un DeCA pendiente.",
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "401": {
                        "description": "Sin clave o clave no válida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Datos que faltan o no son válidos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Límite de peticiones o del plan"
                    }
                },
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "id numérico o número del DeCA (2026-000123)"
                    }
                ]
            }
        },
        "/decas/{id}/sustituir": {
            "post": {
                "summary": "Método 2: crea un DeCA nuevo (URL y QR nuevos) con los cambios y deja este como sustituido. Exige \"motivo\".",
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "401": {
                        "description": "Sin clave o clave no válida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Datos que faltan o no son válidos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Límite de peticiones o del plan"
                    }
                },
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "id numérico o número del DeCA (2026-000123)"
                    }
                ]
            }
        },
        "/decas/{id}/pedir-datos": {
            "post": {
                "summary": "Devuelve el enlace para que el otro lado complete sus datos sin registrarse; con \"email\", se lo mandamos.",
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "401": {
                        "description": "Sin clave o clave no válida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Datos que faltan o no son válidos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Límite de peticiones o del plan"
                    }
                },
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "id numérico o número del DeCA (2026-000123)"
                    }
                ]
            }
        },
        "/decas/{id}/enviar": {
            "post": {
                "summary": "Manda el DeCA por email (\"email\") y te devuelve el texto para WhatsApp del conductor.",
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "401": {
                        "description": "Sin clave o clave no válida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Datos que faltan o no son válidos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Límite de peticiones o del plan"
                    }
                },
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "id numérico o número del DeCA (2026-000123)"
                    }
                ]
            }
        },
        "/decas/{id}/fin": {
            "post": {
                "summary": "Marca el fin del servicio.",
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "401": {
                        "description": "Sin clave o clave no válida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Datos que faltan o no son válidos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Límite de peticiones o del plan"
                    }
                },
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "id numérico o número del DeCA (2026-000123)"
                    }
                ]
            }
        },
        "/decas/{id}/archivar": {
            "post": {
                "summary": "Archiva (\"archivado\": true) o saca del archivo (false).",
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "401": {
                        "description": "Sin clave o clave no válida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Datos que faltan o no son válidos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Límite de peticiones o del plan"
                    }
                },
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "id numérico o número del DeCA (2026-000123)"
                    }
                ]
            }
        },
        "/decas/{id}/pdf": {
            "get": {
                "summary": "El PDF (no cuenta como descarga pública).",
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "401": {
                        "description": "Sin clave o clave no válida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Datos que faltan o no son válidos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Límite de peticiones o del plan"
                    }
                },
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "id numérico o número del DeCA (2026-000123)"
                    }
                ]
            }
        },
        "/decas/{id}/qr.png": {
            "get": {
                "summary": "El QR en PNG.",
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "401": {
                        "description": "Sin clave o clave no válida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Datos que faltan o no son válidos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Límite de peticiones o del plan"
                    }
                },
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "id numérico o número del DeCA (2026-000123)"
                    }
                ]
            }
        },
        "/decas/{id}/cambios": {
            "get": {
                "summary": "Historial de modificaciones: versión, motivo, quién y qué cambió.",
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "401": {
                        "description": "Sin clave o clave no válida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Datos que faltan o no son válidos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Límite de peticiones o del plan"
                    }
                },
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "id numérico o número del DeCA (2026-000123)"
                    }
                ]
            }
        },
        "/decas/{id}/descargas": {
            "get": {
                "summary": "Cada vez que alguien abrió la URL pública o el QR (fecha, IP y navegador).",
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "401": {
                        "description": "Sin clave o clave no válida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Datos que faltan o no son válidos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Límite de peticiones o del plan"
                    }
                },
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "id numérico o número del DeCA (2026-000123)"
                    }
                ]
            }
        },
        "/agenda/empresas": {
            "get": {
                "summary": "Tu agenda (se aprende sola de cada DeCA). Filtro: q.",
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "401": {
                        "description": "Sin clave o clave no válida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Datos que faltan o no son válidos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Límite de peticiones o del plan"
                    }
                }
            },
            "post": {
                "summary": "Da de alta (o actualiza) una empresa, un vehículo o un lugar. No hace falta para crear DeCA.",
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "401": {
                        "description": "Sin clave o clave no válida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Datos que faltan o no son válidos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Límite de peticiones o del plan"
                    }
                }
            }
        },
        "/agenda/vehiculos": {
            "get": {
                "summary": "Tu agenda (se aprende sola de cada DeCA). Filtro: q.",
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "401": {
                        "description": "Sin clave o clave no válida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Datos que faltan o no son válidos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Límite de peticiones o del plan"
                    }
                }
            },
            "post": {
                "summary": "Da de alta (o actualiza) una empresa, un vehículo o un lugar. No hace falta para crear DeCA.",
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "401": {
                        "description": "Sin clave o clave no válida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Datos que faltan o no son válidos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Límite de peticiones o del plan"
                    }
                }
            }
        },
        "/agenda/lugares": {
            "get": {
                "summary": "Tu agenda (se aprende sola de cada DeCA). Filtro: q.",
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "401": {
                        "description": "Sin clave o clave no válida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Datos que faltan o no son válidos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Límite de peticiones o del plan"
                    }
                }
            },
            "post": {
                "summary": "Da de alta (o actualiza) una empresa, un vehículo o un lugar. No hace falta para crear DeCA.",
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "401": {
                        "description": "Sin clave o clave no válida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Datos que faltan o no son válidos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Límite de peticiones o del plan"
                    }
                }
            }
        },
        "/fotos": {
            "post": {
                "summary": "Lee con IA la foto de un albarán, pedido o carta de porte (multipart «foto» o JSON «imagen_base64») y devuelve los datos del DeCA para revisarlos. No crea nada: después, POST /decas. Gasta una lectura del cupo de fotos (20 al mes en el plan gratis; ilimitadas en Pro). Tamaño máximo: 2 MB como fichero o unos 6 MB en base64; con 1.800 px de lado basta.",
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "401": {
                        "description": "Sin clave o clave no válida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Datos que faltan o no son válidos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Límite de peticiones o del plan"
                    }
                }
            }
        },
        "/importar": {
            "post": {
                "summary": "Importa un CSV (cuerpo text/csv o multipart con el campo «csv»). ?validar=1 lo comprueba sin generar nada; ?emitir=0 los deja pendientes.",
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "401": {
                        "description": "Sin clave o clave no válida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Datos que faltan o no son válidos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Límite de peticiones o del plan"
                    }
                }
            }
        },
        "/webhooks": {
            "get": {
                "summary": "Tus webhooks.",
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "401": {
                        "description": "Sin clave o clave no válida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Datos que faltan o no son válidos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Límite de peticiones o del plan"
                    }
                }
            },
            "post": {
                "summary": "Crea un webhook: \"url\" (https), \"eventos\" (lista o [\"*\"]) y \"descripcion\". Devuelve el secreto UNA vez.",
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "401": {
                        "description": "Sin clave o clave no válida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Datos que faltan o no son válidos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Límite de peticiones o del plan"
                    }
                }
            }
        },
        "/webhooks/{id}": {
            "patch": {
                "summary": "Activa o pausa (\"activo\").",
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "401": {
                        "description": "Sin clave o clave no válida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Datos que faltan o no son válidos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Límite de peticiones o del plan"
                    }
                },
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "id numérico o número del DeCA (2026-000123)"
                    }
                ]
            },
            "delete": {
                "summary": "Borra el webhook.",
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "401": {
                        "description": "Sin clave o clave no válida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Datos que faltan o no son válidos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Límite de peticiones o del plan"
                    }
                },
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "id numérico o número del DeCA (2026-000123)"
                    }
                ]
            }
        },
        "/webhooks/{id}/entregas": {
            "get": {
                "summary": "Las últimas 100 entregas con su resultado.",
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "401": {
                        "description": "Sin clave o clave no válida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Datos que faltan o no son válidos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Límite de peticiones o del plan"
                    }
                },
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "id numérico o número del DeCA (2026-000123)"
                    }
                ]
            }
        },
        "/webhooks/{id}/probar": {
            "post": {
                "summary": "Manda un evento «ping» ahora mismo.",
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "401": {
                        "description": "Sin clave o clave no válida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Datos que faltan o no son válidos",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Límite de peticiones o del plan"
                    }
                },
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "id numérico o número del DeCA (2026-000123)"
                    }
                ]
            }
        }
    }
}