Sucursales

¿Qué es una sucursal y por qué la necesitas?

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.

{info} También encuentras el id de tus sucursales en el panel, en Documentación → API key.

Listar tus sucursales

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.

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

{success} Respuesta satisfactoria code: 200

[
{
"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

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']

{warning} 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.

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:

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'

{success} Respuesta satisfactoria code: 200

{
"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 code: 422

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