Crear Sucursal

Agrega una nueva sucursal a una organización existente.

Endpoint

POST 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 a qué organización pertenecerá la sucursal.

Headers

{

"Authorization": string,requerido

↳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..."

"x-organization-id": string,requerido

↳Identificador único en formato UUID de la organización a la cual pertenecerá la nueva sucursal. Este identificador debe corresponder a una organización existente y el usuario debe tener permisos sobre ella.

↳Formato: uuid

↳Ejemplo: "550e8400-e29b-41d4-a716-446655440000"

"x-idempotency": stringrequerido

↳Identificador único en formato UUID utilizado para garantizar la idempotencia de la operación. Si se envía el mismo UUID en una petición posterior, el sistema devolverá el resultado de la primera operación sin crear una sucursal duplicada.

↳Formato: uuid

↳Ejemplo: "01936ff8-9c6a-7b2e-8000-123456789abc"

}

Body Parameters

Request Body

{

"name": string,requerido

↳Nombre identificador de la sucursal que será utilizado para distinguirla de otras sucursales de la organización. Este campo es obligatorio y debe contener al menos un carácter. Ejemplos comunes: "Matriz", "Sucursal Norte", "Guadalajara".

↳Longitud: 1-255 caracteres

↳Ejemplo: "Sucursal Norte"

"zipCode": string,requerido

↳Código postal de la ubicación física de la sucursal. Este dato es requerido por el SAT para la emisión de CFDIs y debe ser un código postal válido de México compuesto por exactamente 5 dígitos numéricos. Este código postal aparecerá en el campo LugarExpedicion de los CFDIs emitidos desde esta sucursal.

↳Longitud exacta: 5 caracteres · Patrón: ^\d{5}$

↳Ejemplo: "64000"

"isMain": booleanopcional

↳Indica si esta sucursal es la principal o matriz de la organización. Por defecto es false. Solo puede existir una sucursal principal por organización. Si se establece en true, cualquier otra sucursal principal será automáticamente marcada como no principal.

↳Ejemplo: false

}

Ejemplos de Código

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

curl -X POST https://sandbox.lummy.io/branches \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "x-organization-id: ${LUMMY_ORG_ID}" \
  -H "x-idempotency: $(uuidgen)" \
  -d '{
    "name": "Sucursal Norte",
    "zipCode": "64000",
    "isMain": false
  }'

Variables de entorno

Define LUMMY_ORG_ID y ACCESS_TOKEN en tu shell:

export LUMMY_ORG_ID="your-organization-id"
export ACCESS_TOKEN="your-access-token"

import axios, { AxiosError } from 'axios';
import { v4 as uuidv4 } from 'uuid';

interface CreateBranchPayload {
  name: string;
  zipCode: string;
  isMain?: boolean;
}

interface BranchResponse {
  id: string;
  name: string;
  zipCode: string;
  isActive: boolean;
  createdAt: string;
}

async function crearSucursal(): Promise<BranchResponse> {
  const ORG_ID = process.env.LUMMY_ORG_ID!;
  const API_URL = 'https://sandbox.lummy.io/branches';
  const ACCESS_TOKEN = process.env.ACCESS_TOKEN!;

  const payload: CreateBranchPayload = {
    name: "Sucursal Norte",
    zipCode: "64000",
    isMain: false
  };

  try {
    const response = await axios.post<BranchResponse>(API_URL, payload, {
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${ACCESS_TOKEN}`,
        'x-organization-id': ORG_ID,
        'x-idempotency': uuidv4(),
      },
    });

    console.log('Sucursal creada exitosamente');
    console.log('ID:', response.data.id);

    return response.data;
  } catch (error) {
    if (axios.isAxiosError(error)) {
      const axiosError = error as AxiosError;
      console.error('Error al crear sucursal:', axiosError.response?.data);
      throw axiosError;
    }
    throw error;
  }
}

// Ejecutar
crearSucursal();

Dependencias

npm install axios uuid
npm install -D @types/uuid

Variables de entorno

Define LUMMY_ORG_ID y ACCESS_TOKEN en tu shell. El ACCESS_TOKEN se obtiene después de que el usuario se autentica en la plataforma Lummy.

import os
import requests
from uuid import uuid4

def crear_sucursal():
    org_id = os.getenv("LUMMY_ORG_ID")
    access_token = os.getenv("ACCESS_TOKEN")

    if not org_id or not access_token:
        raise ValueError("Debes definir LUMMY_ORG_ID y ACCESS_TOKEN")

    api_url = "https://sandbox.lummy.io/branches"

    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {access_token}",
        "x-organization-id": org_id,
        "x-idempotency": str(uuid4()),
    }

    payload = {
        "name": "Sucursal Norte",
        "zipCode": "64000",
        "isMain": False
    }

    try:
        response = requests.post(api_url, json=payload, headers=headers, timeout=30)
        response.raise_for_status()

        data = response.json()
        print("Sucursal creada exitosamente")
        print(f"ID: {data['id']}")
        return data

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

if __name__ == "__main__":
    crear_sucursal()

Dependencias

pip install requests

Variables de entorno

Define LUMMY_ORG_ID y ACCESS_TOKEN en tu shell. El ACCESS_TOKEN se obtiene después de que el usuario se autentica en la plataforma Lummy.

<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;
use Ramsey\Uuid\Uuid;

function crearSucursal()
{
    $orgId = getenv('LUMMY_ORG_ID');
    $accessToken = getenv('ACCESS_TOKEN');

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

    $apiUrl = 'https://sandbox.lummy.io/branches';

    $client = new Client([
        'timeout' => 30,
        'headers' => [
            'Content-Type' => 'application/json',
            'Authorization' => 'Bearer ' . $accessToken,
            'x-organization-id' => $orgId,
            'x-idempotency' => Uuid::uuid4()->toString(),
        ],
    ]);

    $payload = [
        "name" => "Sucursal Norte",
        "zipCode" => "64000",
        "isMain" => false
    ];

    try {
        $response = $client->post($apiUrl, ['json' => $payload]);
        $data = json_decode($response->getBody(), true);

        echo "Sucursal creada exitosamente\n";
        echo "ID: " . $data['id'] . "\n";
        return $data;

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

try {
    crearSucursal();
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
    exit(1);
}

Dependencias

composer require guzzlehttp/guzzle ramsey/uuid

Variables de entorno

Define LUMMY_ORG_ID y ACCESS_TOKEN en tu shell. El ACCESS_TOKEN se obtiene después de que el usuario se autentica en la plataforma Lummy.

Respuestas

Todas las respuestas siguen el formato estándar StandardResponse.

201 Created

Sucursal creada exitosamente.

{
  "requestId": "abc123-def456",
  "data": {
    "id": "789e8400-e29b-41d4-a716-446655449999",
    "name": "Sucursal Norte",
    "zipCode": "64000",
    "isMain": false,
    "isActive": true,
    "createdAt": "2025-01-15T10:30:00.000Z"
  },
  "timestamp": "2025-01-15T10:30:00.000Z",
  "path": "/branches",
  "method": "POST"
}

404 Not Found

La organización especificada no existe.

{
  "requestId": "abc123-def456",
  "error": {
    "message": "Organization not found",
    "code": "NotFoundException",
    "status": 404
  },
  "timestamp": "2025-01-15T10:30:00.000Z",
  "path": "/branches",
  "method": "POST"
}

Endpoint​

Headers​

Body Parameters​

Ejemplos de Código​

Respuestas​

201 Created​

404 Not Found​

Endpoint

Headers

Body Parameters

Ejemplos de Código

Respuestas

201 Created

404 Not Found