# Importación administrativa de farmacias

## Permiso y endpoints

La importación requiere `pharmacies.import`.

| Método | Ruta | Uso |
| --- | --- | --- |
| `POST` | `/api/v1/admin/pharmacies/imports/preview` | analiza un archivo Excel sin crear ni actualizar registros |
| `POST` | `/api/v1/admin/pharmacies/imports/{id}/confirm` | confirma el lote validado |
| `GET` | `/api/v1/admin/pharmacies/imports/{id}` | consulta el resumen del lote propio |
| `GET` | `/api/v1/admin/pharmacies/imports/{id}/errors` | consulta filas omitidas o con conflicto |

`{id}` es UUID público y cada lote solo puede ser consultado o confirmado por quien lo creó. Las vistas previas expiran una hora después de crearse y no pueden reutilizarse tras la confirmación.

## Archivo y columnas

Se aceptan `.xlsx` y `.xls` de hasta 10 MB. No se aceptan CSV ni otros formatos. Las cabeceras se comparan sin distinguir mayúsculas, tildes, espacios ni guiones bajos.

| Dato | Cabeceras admitidas |
| --- | --- |
| Código | `CODCliente`, `codigo`, `código`, `codigo_cliente`, `codcliente` |
| Nombre | `nombrecliente`, `nombre`, `nombre_cliente`, `farmacia`, `nombre_farmacia` |
| Zona | `Zona`, `zona` |
| Ciudad | `ciudad`, `municipio`, `pueblo`, `ciudad_pueblo` |
| Sucursal opcional | `Sucursal` |

Código, nombre y zona son obligatorios. El código se trata siempre como texto: `C01482` y `0005` conservan letras y ceros. Sin sucursal, se usa **Principal**; con sucursal, debe existir en el catálogo.

## Reglas

Zona se resuelve por nombre normalizado en el catálogo existente y no se crean zonas. Ciudad se resuelve por coincidencia exacta normalizada; si se encuentra una sola, su provincia se deriva de la ciudad. Una ciudad inexistente o ambigua importa la farmacia sin ciudad ni provincia, con advertencia, y nunca crea catálogos territoriales.

La asociación es `código + sucursal`. Si existe en esa combinación, se actualizan nombre, zona, ciudad y provincia; se conservan dirección, estado, dependientes e historial. Si no existe, se crea activa, sin dirección. Dos filas para la misma combinación dentro del archivo se omiten como duplicadas.

## Flujo

El `preview` devuelve un lote, resumen y filas con acción, estado y mensajes. No escribe farmacias. Si hay errores, confirmar requiere explícitamente `import_valid_rows_only: true`, para importar solo filas válidas. La confirmación registra las cantidades creadas, actualizadas, omitidas y fallidas en el lote de auditoría.

Los archivos se almacenan temporalmente con nombre aleatorio fuera de rutas públicas, se validan por formato y tamaño, se procesan con Maatwebsite Excel y se eliminan tras el análisis. No se almacenan IDs internos ni el contenido completo del archivo en la respuesta.