Listar Sucursales

Obtén la lista de sucursales de una organización específica.

Endpoint

GET https://api.lummy.io/v1/branches

Entorno	URL
Producción	`https://api.lummy.io/v1/branches`
Sandbox	`https://sandbox.lummy.io/v1/branches`

Header Requerido

Este endpoint requiere el header x-organization-id para especificar de qué organización quieres obtener las sucursales.

Headers

{

"Authorization": string,requerido

↳Token de autenticación en formato Bearer. Se obtiene del endpoint de autenticación y debe incluirse en todas las peticiones para verificar la identidad del usuario.

"x-organization-id": stringrequerido

↳Identificador único de la organización. Debe ser un UUID válido de una organización a la que el usuario autenticado tenga acceso.

↳Formato: uuid

}

Query Parameters

Todos los parámetros son opcionales y permiten filtrar, paginar y ordenar los resultados.

{

"search": string,opcional

↳Término de búsqueda para filtrar sucursales por nombre. Se realiza una búsqueda parcial (contiene).

"isMain": boolean,opcional

↳Filtra las sucursales por su condición de matriz. Cuando es true retorna solo la sucursal principal, false retorna solo las secundarias.

"page": number,opcional

↳Número de página para la paginación. La numeración comienza en 1. Se usa en conjunto con limit para navegar por los resultados.

↳Valor mínimo: 1 · Valor por defecto: 1

"limit": number,opcional

↳Cantidad máxima de sucursales a retornar por página. El valor máximo permitido es 100.

↳Rango: 1 - 100 · Valor por defecto: 10

"sortBy": string,opcional

↳Campo por el cual ordenar los resultados. Puede ser por nombre de la sucursal o fecha de creación.

↳Valor por defecto: "createdAt"

↳Valores permitidos: "name""createdAt"

"sortOrder": stringopcional

↳Orden de clasificación de los resultados. "ASC" para ascendente (A-Z, más antiguo primero), "DESC" para descendente (Z-A, más reciente primero).

↳Valor por defecto: "DESC"

↳Valores permitidos: "ASC""DESC"

}

Ejemplos de Código

cURL
Node.js (TypeScript)
Python
PHP (Guzzle)

# Listar todas las sucursales
curl -X GET "https://sandbox.lummy.io/branches" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "x-organization-id: ${LUMMY_ORG_ID}"

# Con paginación y búsqueda
curl -X GET "https://sandbox.lummy.io/branches?search=norte&page=1&limit=20" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "x-organization-id: ${LUMMY_ORG_ID}"

# Filtrar solo la sucursal principal
curl -X GET "https://sandbox.lummy.io/branches?isMain=true" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "x-organization-id: ${LUMMY_ORG_ID}"

import axios from 'axios';

interface Branch {
  id: string;
  name: string;
  zipCode: string;
  isMain: boolean;
  isActive: boolean;
  createdAt: string;
  updatedAt: string;
}

interface PaginatedResponse {
  data: Branch[];
  total: number;
  page: number;
  limit: number;
  pages: number;
}

interface ListBranchesOptions {
  search?: string;
  isMain?: boolean;
  page?: number;
  limit?: number;
  sortBy?: string;
  sortOrder?: 'asc' | 'desc';
}

async function listarSucursales(
  organizationId: string,
  options: ListBranchesOptions = {}
): Promise<PaginatedResponse> {
  const API_URL = 'https://sandbox.lummy.io/branches';
  const ACCESS_TOKEN = process.env.ACCESS_TOKEN!;

  try {
    const response = await axios.get<PaginatedResponse>(API_URL, {
      headers: {
        'Authorization': `Bearer ${ACCESS_TOKEN}`,
        'x-organization-id': organizationId,
      },
      params: options,
    });

    console.log(`${response.data.total} sucursales encontradas`);
    console.log(`Pagina ${response.data.page} de ${response.data.pages}`);

    response.data.data.forEach((branch, index) => {
      const mainLabel = branch.isMain ? ' (PRINCIPAL)' : '';
      console.log(`${index + 1}. ${branch.name}${mainLabel} - CP: ${branch.zipCode} - ID: ${branch.id}`);
    });

    return response.data;
  } catch (error) {
    console.error('Error al listar sucursales:', error);
    throw error;
  }
}

// Ejecutar
listarSucursales('550e8400-e29b-41d4-a716-446655440000', { page: 1, limit: 10 });

Dependencias

npm install axios

import os
import requests
from typing import Optional, Literal

def listar_sucursales(
    organization_id: str,
    search: Optional[str] = None,
    is_main: Optional[bool] = None,
    page: int = 1,
    limit: int = 10,
    sort_by: str = 'createdAt',
    sort_order: Literal['asc', 'desc'] = 'desc'
):
    api_url = "https://sandbox.lummy.io/branches"
    access_token = os.getenv("ACCESS_TOKEN")

    if not access_token:
        raise ValueError("Debes definir ACCESS_TOKEN")

    headers = {
        "Authorization": f"Bearer {access_token}",
        "x-organization-id": organization_id
    }

    params = {
        'page': page,
        'limit': limit,
        'sortBy': sort_by,
        'sortOrder': sort_order
    }

    if search:
        params['search'] = search
    if is_main is not None:
        params['isMain'] = is_main

    try:
        response = requests.get(api_url, headers=headers, params=params, timeout=30)
        response.raise_for_status()

        result = response.json()
        print(f"{result['total']} sucursales encontradas")
        print(f"Pagina {result['page']} de {result['pages']}")

        for i, branch in enumerate(result['data'], 1):
            main_label = ' (PRINCIPAL)' if branch['isMain'] else ''
            print(f"{i}. {branch['name']}{main_label} - CP: {branch['zipCode']} - ID: {branch['id']}")

        return result

    except requests.exceptions.RequestException as e:
        print(f"Error al listar sucursales: {e}")
        if e.response:
            print(f"Detalle: {e.response.text}")
        raise

if __name__ == "__main__":
    listar_sucursales('550e8400-e29b-41d4-a716-446655440000', page=1, limit=10)

Dependencias

pip install requests

<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

function listarSucursales(
    string $organizationId,
    ?string $search = null,
    ?bool $isMain = null,
    int $page = 1,
    int $limit = 10,
    string $sortBy = 'createdAt',
    string $sortOrder = 'desc'
) {
    $apiUrl = 'https://sandbox.lummy.io/branches';
    $accessToken = getenv('ACCESS_TOKEN');

    if (!$accessToken) {
        throw new Exception('Debes definir ACCESS_TOKEN');
    }

    $client = new Client(['timeout' => 30]);

    $params = [
        'page' => $page,
        'limit' => $limit,
        'sortBy' => $sortBy,
        'sortOrder' => $sortOrder
    ];

    if ($search !== null) {
        $params['search'] = $search;
    }
    if ($isMain !== null) {
        $params['isMain'] = $isMain ? 'true' : 'false';
    }

    try {
        $response = $client->get($apiUrl, [
            'headers' => [
                'Authorization' => 'Bearer ' . $accessToken,
                'x-organization-id' => $organizationId
            ],
            'query' => $params
        ]);

        $data = json_decode($response->getBody(), true);
        echo "{$data['total']} sucursales encontradas\n";
        echo "Pagina {$data['page']} de {$data['pages']}\n";

        foreach ($data['data'] as $i => $branch) {
            $num = $i + 1;
            $mainLabel = $branch['isMain'] ? ' (PRINCIPAL)' : '';
            echo "{$num}. {$branch['name']}{$mainLabel} - CP: {$branch['zipCode']} - ID: {$branch['id']}\n";
        }

        return $data;

    } catch (RequestException $e) {
        echo "Error al listar sucursales: " . $e->getMessage() . "\n";
        if ($e->getResponse()) {
            echo "Detalle: " . $e->getResponse()->getBody() . "\n";
        }
        throw $e;
    }
}

try {
    listarSucursales('550e8400-e29b-41d4-a716-446655440000', page: 1, limit: 10);
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
    exit(1);
}

Dependencias

composer require guzzlehttp/guzzle

Respuestas

Todas las respuestas siguen el formato estándar StandardResponse. Para endpoints paginados se usa PaginatedResponse.

200 OK

Lista de sucursales obtenida exitosamente.

{

"type": ,opcional

"properties": opcional

}

{
  "requestId": "abc123-def456",
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Matriz",
      "zipCode": "64000",
      "isMain": true,
      "isActive": true,
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "name": "Sucursal Norte",
      "zipCode": "64100",
      "isMain": false,
      "isActive": true,
      "createdAt": "2025-01-16T14:20:00.000Z",
      "updatedAt": "2025-01-16T14:20:00.000Z"
    }
  ],
  "total": 2,
  "page": 1,
  "limit": 10,
  "totalPages": 1,
  "timestamp": "2025-01-15T10:30:00.000Z",
  "path": "/branches",
  "method": "GET"
}

400 Bad Request

Falta el header x-organization-id.

{
  "requestId": "abc123-def456",
  "error": {
    "message": "Header requerido: x-organization-id. El contexto organizacional es obligatorio.",
    "code": "ValidationError",
    "status": 400
  },
  "timestamp": "2025-01-15T10:30:00.000Z",
  "path": "/branches",
  "method": "GET"
}

401 Unauthorized

Token inválido o expirado.

{
  "requestId": "abc123-def456",
  "error": {
    "message": "Unauthorized",
    "code": "UnauthorizedException",
    "status": 401
  },
  "timestamp": "2025-01-15T10:30:00.000Z",
  "path": "/branches",
  "method": "GET"
}

403 Forbidden

No tienes acceso a la organización especificada.

{
  "requestId": "abc123-def456",
  "error": {
    "message": "Usuario no autorizado para la organización: 550e8400-e29b-41d4-a716-446655440000.",
    "code": "ForbiddenException",
    "status": 403
  },
  "timestamp": "2025-01-15T10:30:00.000Z",
  "path": "/branches",
  "method": "GET"
}

Endpoint​

Headers​

Query Parameters​

Ejemplos de Código​

Respuestas​

200 OK​

400 Bad Request​

401 Unauthorized​

403 Forbidden​

Próximos Pasos​

Endpoint

Headers

Query Parameters

Ejemplos de Código

Respuestas

200 OK

400 Bad Request

401 Unauthorized

403 Forbidden

Próximos Pasos