# API administrativa: sucursales de farmacia

## Modelo y migración

`pharmacy_branches` es el catálogo normalizado de sucursales. Expone UUID público, nombre visible y estado; `normalized_name` e IDs internos nunca salen en la API.

La migración crea `Principal`, asigna esa sucursal a toda farmacia histórica sin sucursal, comprueba que no queden valores nulos y vuelve obligatoria la relación. No modifica ni elimina farmacias. Si encuentra combinaciones históricas duplicadas, reporta los códigos y detiene el cambio de índices.

El seeder de `Principal` es idempotente.

## Permisos

- `pharmacy_branches.view_any`
- `pharmacy_branches.create`
- `pharmacy_branches.update`
- `pharmacy_branches.change_status`

Solo `administrator` recibe estos permisos. El selector también puede consultarse con permisos para crear o editar farmacias. La autorización se decide por permiso, no por nombre de rol.

## Endpoints

| Método | Ruta | Uso |
| --- | --- | --- |
| `GET` | `/api/v1/admin/pharmacy-branches` | catálogo |
| `POST` | `/api/v1/admin/pharmacy-branches` | crear |
| `PUT` | `/api/v1/admin/pharmacy-branches/{branch}` | renombrar |
| `PATCH` | `/api/v1/admin/pharmacy-branches/{branch}/status` | activar o desactivar |

`GET` acepta `search`, `status=active|inactive|all` y `limit`. Por defecto devuelve activas y coloca `Principal` primero.

## Resource

```json
{
  "id": "uuid-publico",
  "name": "Santiago Norte",
  "is_active": true
}
```

## Payloads

Creación y edición:

```json
{ "name": "Santiago Norte" }
```

Cambio de estado:

```json
{ "is_active": false }
```

El nombre se recorta, comprime espacios repetidos y se compara sin distinguir mayúsculas. El nombre visible conserva tildes. Una colisión concurrente responde `422 PHARMACY_BRANCH_ALREADY_EXISTS` con el error asociado a `name`.

Una sucursal inactiva permanece en datos históricos y en farmacias ya asociadas, pero no puede seleccionarse para una asociación nueva.

## Uso en el registro público

La búsqueda pública se documenta en `pharmacies-api.md`. Cuando un código identifica varias farmacias físicas, React usa la lista `pharmacies` y exige seleccionar una opción; nunca envía el nombre de la sucursal como identificación. Una sucursal inactiva excluye sus farmacias de la búsqueda y del registro nuevo.