Listar Organizaciones

Obtén la lista de organizaciones a las que tienes acceso. Útil para descubrir los IDs de organización disponibles.

Endpoint

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

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

Headers

{

"Authorization": stringrequerido

↳Token de autenticación en formato Bearer (JWT) que valida la identidad del usuario. Este token debe ser enviado en cada petición para acceder a los recursos protegidos de la API.

↳Ejemplo: "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

}

Query Parameters

{

"search": string,opcional

↳Término de búsqueda para filtrar organizaciones por nombre comercial o RFC. La búsqueda es case-insensitive y busca coincidencias parciales en ambos campos.

↳Ejemplo: "empresa"

"isActive": boolean,opcional

↳Filtro por estado de activación de la organización. Cuando es true retorna solo organizaciones activas, cuando es false retorna solo organizaciones inactivas. Si se omite, retorna todas las organizaciones independientemente de su estado.

↳Ejemplo: true

"page": number,opcional

↳Número de página a recuperar en el conjunto de resultados paginados. La numeración comienza en 1. Si se omite, el valor predeterminado es 1.

↳Valor mínimo: 1

↳Ejemplo: 1

"limit": number,opcional

↳Cantidad máxima de registros a retornar por página. El valor debe estar entre 1 y 100. Si se omite, el valor predeterminado es 10.

↳Rango: 1 - 100

↳Ejemplo: 10

"sortBy": string,opcional

↳Campo por el cual ordenar los resultados. Los valores permitidos son: name (nombre comercial), rfc (Registro Federal de Contribuyentes), o createdAt (fecha de creación). Si se omite, se ordena por createdAt.

↳Valores permitidos: "name""rfc""createdAt"

↳Ejemplo: "createdAt"

"sortOrder": stringopcional

↳Dirección del ordenamiento de los resultados. Los valores permitidos son: asc (ascendente, A-Z o más antiguo primero) o desc (descendente, Z-A o más reciente primero). Si se omite, el valor predeterminado es desc.

↳Valores permitidos: "asc""desc"

↳Ejemplo: "desc"

}

Ejemplos de Código

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

# Listar todas las organizaciones
curl -X GET "https://sandbox.lummy.io/organizations" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

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

# Filtrar solo activas y ordenar por nombre
curl -X GET "https://sandbox.lummy.io/organizations?isActive=true&sortBy=name&sortOrder=asc" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

import axios from 'axios';

interface Organization {
  id: string;
  name: string;
  legalName: string;
  rfc: string;
  taxRegime: string;
  zipCode: string;
  isActive: boolean;
  createdAt: string;
  updatedAt: string;
}

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

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

async function listarOrganizaciones(
  options: ListOrganizationsOptions = {}
): Promise<PaginatedResponse> {
  const API_URL = 'https://sandbox.lummy.io/organizations';
  const ACCESS_TOKEN = process.env.ACCESS_TOKEN!;

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

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

    response.data.data.forEach((org, index) => {
      console.log(`${index + 1}. ${org.name} (${org.rfc}) - ID: ${org.id}`);
    });

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

// Ejecutar
listarOrganizaciones({ page: 1, limit: 10 });

Dependencias

npm install axios

import os
import requests
from typing import Optional, Literal

def listar_organizaciones(
    search: Optional[str] = None,
    is_active: 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/organizations"
    access_token = os.getenv("ACCESS_TOKEN")

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

    headers = {
        "Authorization": f"Bearer {access_token}"
    }

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

    if search:
        params['search'] = search
    if is_active is not None:
        params['isActive'] = is_active

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

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

        for i, org in enumerate(result['data'], 1):
            print(f"{i}. {org['name']} ({org['rfc']}) - ID: {org['id']}")

        return result

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

if __name__ == "__main__":
    listar_organizaciones(page=1, limit=10)

Dependencias

pip install requests

<?php

require 'vendor/autoload.php';

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

function listarOrganizaciones(
    ?string $search = null,
    ?bool $isActive = null,
    int $page = 1,
    int $limit = 10,
    string $sortBy = 'createdAt',
    string $sortOrder = 'desc'
) {
    $apiUrl = 'https://sandbox.lummy.io/organizations';
    $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 ($isActive !== null) {
        $params['isActive'] = $isActive ? 'true' : 'false';
    }

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

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

        foreach ($data['data'] as $i => $org) {
            $num = $i + 1;
            echo "{$num}. {$org['name']} ({$org['rfc']}) - ID: {$org['id']}\n";
        }

        return $data;

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

try {
    listarOrganizaciones(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 organizaciones obtenida exitosamente.

{
  "requestId": "abc123-def456",
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Mi Empresa S.A. de C.V.",
      "legalName": "Mi Empresa Sociedad Anónima de Capital Variable",
      "rfc": "XAXX010101000",
      "taxRegime": "601",
      "zipCode": "64000",
      "isActive": true,
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Otra Empresa S.C.",
      "legalName": "Otra Empresa Sociedad Civil",
      "rfc": "YAAY020202BBB",
      "taxRegime": "612",
      "zipCode": "01000",
      "isActive": true,
      "createdAt": "2025-01-10T08:20:00.000Z",
      "updatedAt": "2025-01-10T08:20:00.000Z"
    }
  ],
  "total": 2,
  "page": 1,
  "limit": 10,
  "totalPages": 1,
  "timestamp": "2025-01-15T10:30:00.000Z",
  "path": "/organizations",
  "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": "/organizations",
  "method": "GET"
}

Casos de Uso

Descubrir Organization IDs

Este endpoint es útil para obtener los IDs de las organizaciones disponibles. Una vez que tienes el ID, puedes usarlo en el header x-organization-id para realizar operaciones específicas de esa organización.

const orgs = await listarOrganizaciones();
const firstOrgId = orgs.data[0].id;

// Usar este ID en otros endpoints
// Header: x-organization-id: 550e8400-e29b-41d4-a716-446655440000

Búsqueda y Filtrado

Busca organizaciones por nombre o RFC:

curl -X GET "https://sandbox.lummy.io/organizations?search=empresa" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Endpoint​

Headers​

Query Parameters​

Ejemplos de Código​

Respuestas​

200 OK​

401 Unauthorized​

Casos de Uso​

Descubrir Organization IDs​

Búsqueda y Filtrado​

Próximos Pasos​

Endpoint

Headers

Query Parameters

Ejemplos de Código

Respuestas

200 OK

401 Unauthorized

Casos de Uso

Descubrir Organization IDs

Búsqueda y Filtrado

Próximos Pasos