{"openapi":"3.1.0","info":{"title":"API del Registro de Productos Fitosanitarios","version":"1.0.0","description":"Copia del Registro de Productos Fitosanitarios del Ministerio de Agricultura, Pesca y Alimentación (MAPA), con **histórico por fecha** y **cambios entre versiones**.\n\n- Cada respuesta indica en `meta` de qué versión oficial sale el dato y su fecha.\n- `fecha=D` devuelve **lo que figuraba en la última versión publicada en o antes de D** que tengamos guardada. No dice si un producto «estaba autorizado» ese día: dice cómo figuraba en el registro publicado.\n- Los campos normalizados (fechas, plazo de seguridad, dosis) llevan siempre el valor original al lado.\n- La etiqueta autorizada del producto es la única referencia legal de uso.\n\n**Claves y planes.** Las rutas de datos necesitan una clave (`Authorization: Bearer <clave>`), que se pide gratis en `POST /v1/claves`. Plan **Gratis**: versión actual del registro y un límite diario bajo. Plan **Profesional**: además, consulta por fecha (`fecha=`), historial y cambios entre fechas, y más volumen. Cada respuesta lleva las cabeceras `X-Plan`, `X-Limite-Diario` y `X-Peticiones-Restantes`; el límite se reinicia a las 00:00 UTC.\n\nHistórico disponible desde el 28/09/2026. Entre el 06/10 y el 11/10/2026 no se comprobaron las publicaciones del MAPA: si hubo alguna versión intermedia entre la del 02/10 y la del 09/10, no está.","contact":{"name":"Nuvola Studio","email":"contacto@nuvolastudiogroup.com"}},"servers":[{"url":"/"}],"security":[{"clave":[]}],"paths":{"/v1/claves":{"post":{"summary":"Pedir una clave gratuita","description":"Crea una clave del plan Gratis. **Se muestra una sola vez**: guárdala. Como mucho 3 claves activas por correo. Solo se guardan el correo y la empresa.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["correo","acepto_condiciones"],"properties":{"correo":{"type":"string","format":"email"},"empresa":{"type":"string"},"acepto_condiciones":{"type":"boolean","const":true},"turnstile":{"type":"string","description":"Respuesta del captcha de la web (si está activado)"}}}}}},"responses":{"201":{"description":"Clave creada","content":{"application/json":{"schema":{"type":"object","properties":{"datos":{"type":"object","properties":{"clave":{"type":"string","example":"fito_Ab3dEf7h_…"},"plan":{"type":"string"},"limite_diario":{"type":"integer"},"aviso":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/v1/versiones":{"get":{"summary":"Versiones guardadas del registro","security":[],"description":"Una por cada publicación del MAPA que hemos copiado, con su fecha oficial, recuentos y enlace al original.","responses":{"200":{"description":"Versiones, de la más reciente a la más antigua","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"datos":{"type":"array","items":{"$ref":"#/components/schemas/Version"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"description":"Falta la clave o no es válida","$ref":"#/components/responses/Error"},"403":{"description":"El plan de la clave no incluye esta consulta (requiere_plan_profesional) o la clave está desactivada","$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"description":"Límite diario del plan alcanzado","$ref":"#/components/responses/Error"}}}},"/v1/productos":{"get":{"summary":"Buscar productos","parameters":[{"name":"q","in":"query","description":"Parte del nombre, otro nombre o número de registro.","schema":{"type":"string"}},{"name":"estado","in":"query","schema":{"type":"string","example":"Vigente"}},{"name":"titular","in":"query","schema":{"type":"string"}},{"name":"sustancia","in":"query","description":"Sustancia activa (nombre español o de la UE).","schema":{"type":"string"}},{"name":"cultivo","in":"query","description":"Código de cultivo o parte de su nombre.","schema":{"type":"string"}},{"name":"agente","in":"query","description":"Código de agente (plaga, enfermedad o mala hierba) o parte de su nombre.","schema":{"type":"string"}},{"name":"fecha","in":"query","required":false,"description":"Devuelve lo que figuraba en la última versión oficial publicada en o antes de esta fecha (AAAA-MM-DD). Sin ella, la última versión.","schema":{"type":"string","format":"date","example":"2026-10-02"}},{"name":"pagina","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"por_pagina","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Productos que coinciden","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"paginacion":{"$ref":"#/components/schemas/Paginacion"},"datos":{"type":"array","items":{"$ref":"#/components/schemas/ProductoResumen"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"description":"Falta la clave o no es válida","$ref":"#/components/responses/Error"},"403":{"description":"El plan de la clave no incluye esta consulta (requiere_plan_profesional) o la clave está desactivada","$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"description":"Límite diario del plan alcanzado","$ref":"#/components/responses/Error"}}}},"/v1/productos/{num_registro}":{"get":{"summary":"Ficha completa de un producto, con sus usos","parameters":[{"name":"num_registro","in":"path","required":true,"description":"Número de registro del MAPA (p. ej. «25649» o «ES-01633»; se acepta «es-1633»).","schema":{"type":"string"}},{"name":"fecha","in":"query","required":false,"description":"Devuelve lo que figuraba en la última versión oficial publicada en o antes de esta fecha (AAAA-MM-DD). Sin ella, la última versión.","schema":{"type":"string","format":"date","example":"2026-10-02"}}],"responses":{"200":{"description":"Ficha del producto","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"datos":{"allOf":[{"$ref":"#/components/schemas/Producto"},{"type":"object","properties":{"usos":{"type":"array","items":{"$ref":"#/components/schemas/Uso"}}}}]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"description":"Falta la clave o no es válida","$ref":"#/components/responses/Error"},"403":{"description":"El plan de la clave no incluye esta consulta (requiere_plan_profesional) o la clave está desactivada","$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"description":"Límite diario del plan alcanzado","$ref":"#/components/responses/Error"}}}},"/v1/productos/{num_registro}/usos":{"get":{"summary":"Usos autorizados de un producto","parameters":[{"name":"num_registro","in":"path","required":true,"description":"Número de registro del MAPA (p. ej. «25649» o «ES-01633»; se acepta «es-1633»).","schema":{"type":"string"}},{"name":"cultivo","in":"query","description":"Código de cultivo o parte de su nombre.","schema":{"type":"string"}},{"name":"agente","in":"query","description":"Código de agente (plaga, enfermedad o mala hierba) o parte de su nombre.","schema":{"type":"string"}},{"name":"fecha","in":"query","required":false,"description":"Devuelve lo que figuraba en la última versión oficial publicada en o antes de esta fecha (AAAA-MM-DD). Sin ella, la última versión.","schema":{"type":"string","format":"date","example":"2026-10-02"}}],"responses":{"200":{"description":"Usos","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"datos":{"type":"array","items":{"$ref":"#/components/schemas/Uso"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"description":"Falta la clave o no es válida","$ref":"#/components/responses/Error"},"403":{"description":"El plan de la clave no incluye esta consulta (requiere_plan_profesional) o la clave está desactivada","$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"description":"Límite diario del plan alcanzado","$ref":"#/components/responses/Error"}}}},"/v1/productos/{num_registro}/historial":{"get":{"summary":"Historial de un producto en nuestras versiones","description":"Cada estado distinto del producto con las versiones en que figuró así, y todos sus cambios (del producto y de sus usos).","parameters":[{"name":"num_registro","in":"path","required":true,"description":"Número de registro del MAPA (p. ej. «25649» o «ES-01633»; se acepta «es-1633»).","schema":{"type":"string"}}],"responses":{"200":{"description":"Historial","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"datos":{"type":"object","properties":{"num_registro":{"type":"string"},"estados":{"type":"array","items":{"$ref":"#/components/schemas/ProductoResumen"}},"cambios":{"type":"array","items":{"$ref":"#/components/schemas/Cambio"}}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"description":"Falta la clave o no es válida","$ref":"#/components/responses/Error"},"403":{"description":"El plan de la clave no incluye esta consulta (requiere_plan_profesional) o la clave está desactivada","$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"description":"Límite diario del plan alcanzado","$ref":"#/components/responses/Error"}}}},"/v1/usos":{"get":{"summary":"Productos que figuran para un cultivo o un agente","description":"Hace falta al menos `cultivo` o `agente`. Por defecto, solo productos con estado «Vigente» en esa versión.","parameters":[{"name":"cultivo","in":"query","description":"Código de cultivo o parte de su nombre.","schema":{"type":"string"}},{"name":"agente","in":"query","description":"Código de agente (plaga, enfermedad o mala hierba) o parte de su nombre.","schema":{"type":"string"}},{"name":"sustancia","in":"query","schema":{"type":"string"}},{"name":"solo_vigentes","in":"query","schema":{"type":"boolean","default":true}},{"name":"fecha","in":"query","required":false,"description":"Devuelve lo que figuraba en la última versión oficial publicada en o antes de esta fecha (AAAA-MM-DD). Sin ella, la última versión.","schema":{"type":"string","format":"date","example":"2026-10-02"}},{"name":"pagina","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"por_pagina","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Usos con su producto","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"paginacion":{"$ref":"#/components/schemas/Paginacion"},"datos":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Uso"},{"type":"object","properties":{"producto":{"type":"object"}}}]}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"description":"Falta la clave o no es válida","$ref":"#/components/responses/Error"},"403":{"description":"El plan de la clave no incluye esta consulta (requiere_plan_profesional) o la clave está desactivada","$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"description":"Límite diario del plan alcanzado","$ref":"#/components/responses/Error"}}}},"/v1/consulta-uso":{"get":{"summary":"Consulta para cuadernos de campo","description":"Estado del producto y usos que coinciden con el cultivo y el agente en la versión de esa fecha. **Sin veredicto**: decide la aplicación que consulta.","parameters":[{"name":"producto","in":"query","required":true,"schema":{"type":"string"}},{"name":"cultivo","in":"query","description":"Código de cultivo o parte de su nombre.","schema":{"type":"string"}},{"name":"agente","in":"query","description":"Código de agente (plaga, enfermedad o mala hierba) o parte de su nombre.","schema":{"type":"string"}},{"name":"fecha","in":"query","required":false,"description":"Devuelve lo que figuraba en la última versión oficial publicada en o antes de esta fecha (AAAA-MM-DD). Sin ella, la última versión.","schema":{"type":"string","format":"date","example":"2026-10-02"}}],"responses":{"200":{"description":"Producto y usos que coinciden","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"datos":{"type":"object","properties":{"producto":{"type":"object"},"usos_que_coinciden":{"type":"array","items":{"$ref":"#/components/schemas/Uso"}},"nota":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"description":"Falta la clave o no es válida","$ref":"#/components/responses/Error"},"403":{"description":"El plan de la clave no incluye esta consulta (requiere_plan_profesional) o la clave está desactivada","$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"description":"Límite diario del plan alcanzado","$ref":"#/components/responses/Error"}}}},"/v1/cambios":{"get":{"summary":"Cambios entre dos fechas","description":"Altas, bajas y modificaciones publicadas **después** de `desde` y hasta `hasta` (incluida). Para sincronizarse sin descargar todo: guarda la `meta.version` de la última llamada y úsala como `desde` en la siguiente.","parameters":[{"name":"desde","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"hasta","in":"query","schema":{"type":"string","format":"date"}},{"name":"entidad","in":"query","schema":{"type":"string","enum":["producto","uso"]}},{"name":"tipo","in":"query","schema":{"type":"string","enum":["alta","baja","modificacion"]}},{"name":"num_registro","in":"query","schema":{"type":"string"}},{"name":"pagina","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"por_pagina","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Cambios, por versión","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"paginacion":{"$ref":"#/components/schemas/Paginacion"},"datos":{"type":"array","items":{"$ref":"#/components/schemas/Cambio"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"description":"Falta la clave o no es válida","$ref":"#/components/responses/Error"},"403":{"description":"El plan de la clave no incluye esta consulta (requiere_plan_profesional) o la clave está desactivada","$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"description":"Límite diario del plan alcanzado","$ref":"#/components/responses/Error"}}}},"/v1/caducan":{"get":{"summary":"Productos que caducan o dejan de poder venderse pronto","parameters":[{"name":"dias","in":"query","schema":{"type":"integer","minimum":1,"maximum":730,"default":90}}],"responses":{"200":{"description":"Productos con caducidad o fecha límite de venta en los próximos días","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"datos":{"type":"array","items":{"$ref":"#/components/schemas/ProductoResumen"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"description":"Falta la clave o no es válida","$ref":"#/components/responses/Error"},"403":{"description":"El plan de la clave no incluye esta consulta (requiere_plan_profesional) o la clave está desactivada","$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"description":"Límite diario del plan alcanzado","$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"clave":{"type":"http","scheme":"bearer","description":"Clave de la API (`fito_…`). También vale la cabecera `X-Api-Key`. No se acepta en la dirección (`?clave=`), para que no quede en historiales ni registros."}},"responses":{"Error":{"description":"Error con código y mensaje","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"codigo":{"type":"string"},"mensaje":{"type":"string"}}}}}}}}},"schemas":{"Meta":{"type":"object","properties":{"fuente":{"type":"string"},"url_fuente":{"type":"string"},"licencia":{"type":"string"},"aviso":{"type":"string"},"version":{"type":"string","format":"date","description":"Fecha oficial de la versión del MAPA de la que sale la respuesta"},"fecha_dato_oficial":{"type":"string","format":"date"},"fecha_descarga":{"type":"string","format":"date-time"},"sha256_original":{"type":"string"}}},"Paginacion":{"type":"object","properties":{"pagina":{"type":"integer"},"por_pagina":{"type":"integer"},"total":{"type":"integer"}}},"Version":{"type":"object","properties":{"fecha_oficial":{"type":"string","format":"date"},"fecha_descarga":{"type":"string"},"productos":{"type":"integer"},"usos":{"type":"integer"},"sha256_original":{"type":"string"},"original":{"type":["string","null"],"description":"Descarga del JSON original del MAPA"}}},"Fechas":{"type":"object","properties":{"registro":{"type":["string","null"],"format":"date"},"caducidad":{"type":["string","null"],"format":"date"},"cancelacion":{"type":["string","null"],"format":"date"},"limite_venta":{"type":["string","null"],"format":"date"}}},"ProductoResumen":{"type":"object","properties":{"num_registro":{"type":"string"},"nombre":{"type":"string"},"titular":{"type":"string"},"formulado":{"type":"string"},"estado":{"type":"string"},"fechas":{"$ref":"#/components/schemas/Fechas"},"sustancias":{"type":"array","items":{"type":"string"}},"avisos":{"type":"array","items":{"type":"string"},"description":"Avisos de calidad del dato oficial (no se corrige)"}}},"Producto":{"type":"object","properties":{"num_registro":{"type":"string"},"nombre":{"type":"string"},"titular":{"type":"string"},"fabricante":{"type":"string"},"fabrica":{"type":"string"},"formulado":{"type":"string"},"estado":{"type":"string"},"fechas":{"$ref":"#/components/schemas/Fechas"},"composicion":{"type":"array","items":{"type":"object","properties":{"sustancia":{"type":"string"},"nombre_ue":{"type":"string"},"concentracion":{"type":"number"},"unidad":{"type":"string"}}}},"condicionamiento":{"type":["string","null"]},"otras_denominaciones":{"type":"array"},"otros_nombres":{"type":"array"},"importaciones_paralelas":{"type":"array"},"avisos":{"type":"array","items":{"type":"string"}}}},"Uso":{"type":"object","properties":{"uso_id":{"type":"string","description":"Identificador estable del uso entre versiones"},"num_registro":{"type":"string"},"cultivo":{"type":"object","properties":{"codigo":{"type":"string"},"nombre":{"type":"string"}}},"agente":{"type":"object","properties":{"codigo":{"type":"string"},"nombre":{"type":"string"}}},"ambito":{"type":["string","null"]},"tipo_usuario":{"type":["string","null"]},"sistema_cultivo":{"type":["string","null"]},"metodo_aplicacion":{"type":["string","null"]},"dosis":{"type":"object","properties":{"min":{"type":["number","null"]},"max":{"type":["number","null"]},"unidad":{"type":["string","null"]},"tipo":{"type":"string","enum":["valor","ver_nota","sin_dato","otra_unidad"]},"unidad_original":{"type":["string","null"]}}},"plazo_seguridad":{"type":"object","properties":{"dias":{"type":["integer","null"]},"tipo":{"type":"string","enum":["dias","no_procede","no_aplica","sin_dato","por_ambiente","ver_condicionamiento"]},"por_ambiente":{"type":["object","null"],"example":{"aire_libre":10,"invernadero":3}},"original":{"type":["string","null"]}}},"volumen_caldo":{"type":"object"},"aplicaciones":{"type":["string","null"]},"intervalo_aplicaciones":{"type":["string","null"]},"bbch":{"type":["string","null"]},"condicionamiento_especifico":{"type":["string","null"]},"repeticiones_en_fuente":{"type":"integer"},"avisos":{"type":"array","items":{"type":"string"}}}},"Cambio":{"type":"object","properties":{"fecha_oficial":{"type":"string","format":"date","description":"Versión en la que aparece el cambio"},"entidad":{"type":"string","enum":["producto","uso"]},"clave":{"type":"string","description":"num_registro o uso_id"},"num_registro":{"type":"string"},"nombre_producto":{"type":["string","null"],"description":"Nombre del producto en esa versión (en una baja, el último que tuvo)"},"tipo":{"type":"string","enum":["alta","baja","modificacion"]},"campos":{"type":["array","null"],"items":{"type":"object","properties":{"campo":{"type":"string"},"antes":{},"despues":{}}}}}}}}}