# Sucursales

<!-- Fuente: https://docs.efipay.co/commercio -->

---

- [Sucursales](#sucursales)
  - [¿Qué es una sucursal y por qué la necesitas?](#overview)
  - [Listar tus sucursales](#get)
  - [Crear una sucursal](#create)

## ¿Qué es una sucursal y por qué la necesitas? [#overview]

Una **sucursal** (`office`) es un punto de venta de tu comercio. Puede ser una tienda
física, una línea de negocio o simplemente una forma de separar la operación.

**Es lo primero que necesitas para integrarte.** Casi todos los endpoints que crean
algo —cobros, planes, suscriptores, cupones, reservas de cupo— piden un campo `office`
con el id de una de tus sucursales. Si estás empezando, llama a
`GET /api/v1/offices/get`, toma el `id` de la sucursal que corresponda y guárdalo en tu
configuración.

Todo comercio tiene al menos una sucursal creada desde el registro, así que
normalmente no necesitas crear ninguna.

:::note
También encuentras el id de tus sucursales en el panel, en
[Documentación → API key](https://sag.efipay.co/documentacion/api-key).
:::

## Listar tus sucursales [#get]

`GET /api/v1/offices/get`

**Descripción:** Devuelve las sucursales a las que tiene acceso el usuario de tu token.
Si tu token solo alcanza una sucursal, verás una.

`GET /api/v1/offices/get`

```bash
curl -X GET \
'/api/v1/offices/get' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H "Content-type: application/json"
```

:::tip
Respuesta satisfactoria
:::

Código de respuesta: 200

```json
[
    {
        "id": 1,
        "name": "Sede principal",
        "description": "Punto de venta principal",
        "email": "principal@mi-comercio.com",
        "area_code": "+57",
        "number_phone": "3001234567",
        "website": "https://mi-comercio.com",
        "voucher_information": true,
        "independent_billing": false,
        "main": true,
        "active": true,
        "commerce_id": 42
    }
]
```

## Crear una sucursal [#create]

`POST /api/v1/offices`

**Descripción:** Crea una sucursal. Solo `name` es obligatorio; el resto sirve para que
el comprobante de pago muestre los datos de esa sucursal en lugar de los del comercio.

| Nombre del campo | Descripción | Reglas |
| - | - | - |
| name | Nombre de la sucursal. Solo letras, números y espacios. Único dentro de tu comercio | `['required', 'max:50', 'regex:/^[\pL\pN\s]+$/u', 'unique:offices,name']` |
| description | Para qué es la sucursal. Uso interno | `['nullable', 'string', 'max:250']` |
| image | Logo de la sucursal. JPG, PNG, GIF o SVG, hasta 5 MB | `['nullable', 'image', 'max:5120']` |
| email | Correo de contacto de la sucursal | `['nullable', 'required_if:independent_billing,1,true', 'email', 'max:190']` |
| area_code | Indicativo telefónico con `+` (por ejemplo `+57`) | `['nullable', 'required_with:number_phone', 'string', 'max:6', 'regex:/^\+\d{1,3}$/i']` |
| number_phone | Teléfono de la sucursal. Se valida como número real del país de `iso_code` | `['nullable', 'required_with:area_code', 'numeric', 'digits_between:6,15', 'phone']` |
| iso_code | País del teléfono en ISO2. `CO` por defecto | `['nullable', 'string', 'size:2', 'in:CO,US,MX,...']` |
| website | Sitio web de la sucursal | `['nullable', 'string', 'url', 'max:190']` |
| voucher_information | `true` para que el comprobante muestre los datos de esta sucursal en vez de los del comercio | `['nullable', 'boolean']` |
| independent_billing | `true` si esta sucursal factura por su cuenta. **Activa cinco campos obligatorios**: `email`, `nit`, `verification_code`, `city`, `address` y `rut` | `['nullable', 'boolean']` |
| nit | NIT de la sucursal | `['nullable', 'required_if:independent_billing,1,true', 'numeric', 'max_digits:9']` |
| verification_code | Dígito de verificación del NIT | `['nullable', 'required_if:independent_billing,1,true', 'digits:1']` |
| city | Ciudad de la sucursal | `['nullable', 'required_if:independent_billing,1,true', 'string', 'max:255']` |
| address | Dirección de la sucursal | `['nullable', 'required_if:independent_billing,1,true', 'string', 'max:255']` |
| rut | RUT de la sucursal, como archivo. Solo obligatorio con `independent_billing` en `true` | `['required', 'file', 'mimes:pdf,doc,docx,xls,xlsx,csv', 'max:5120']` |

:::caution
Si envías `image` o `rut`, la petición completa va como
`multipart/form-data`, no como JSON. Es el único endpoint de esta documentación que
recibe archivos.
:::

`POST /api/v1/offices`

Cuerpo de ejemplo:

```json
{
    "name": "Sede norte",
    "description": "Punto de venta calle 140",
    "email": "norte@mi-comercio.com",
    "area_code": "+57",
    "number_phone": "3001234567",
    "voucher_information": true
  }
```

```bash
curl -X POST \
'/api/v1/offices' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H "Content-type: application/json" \
-d '{
    "name": "Sede norte",
    "description": "Punto de venta calle 140",
    "email": "norte@mi-comercio.com",
    "area_code": "+57",
    "number_phone": "3001234567",
    "voucher_information": true
}'
```

Con logo, en `multipart/form-data`:

```bash
curl -X POST \
'/api/v1/offices' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-F 'name=Sede norte' \
-F 'description=Punto de venta calle 140' \
-F 'image=@logo-sede-norte.png'
```

:::tip
Respuesta satisfactoria
:::

Código de respuesta: 200

```json
{
    "saved": true,
    "office": {
        "id": 7,
        "name": "Sede norte",
        "description": "Punto de venta calle 140",
        "email": "norte@mi-comercio.com",
        "area_code": "+57",
        "number_phone": "3001234567",
        "voucher_information": true,
        "independent_billing": false,
        "commerce_id": 42,
        "active": true
    }
}
```

:::danger
Nombre repetido dentro de tu comercio
:::

Código de respuesta: 422

```json
{
    "message": "El campo name ya ha sido tomado.",
    "errors": {
        "name": ["El campo name ya ha sido tomado."]
    }
}
```