Crear Organización

Registra una nueva organización en Lummy para comenzar a emitir facturas.

Endpoint

POST 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": 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-idempotency": stringrequerido

↳Identificador único en formato UUID v7 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 un registro duplicado.

↳Formato: uuid

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

}

Body Parameters

Request Body

{

"name": string,requerido

↳Nombre comercial de la organización con el cual será identificada en el sistema. Este campo es obligatorio y debe contener al menos un carácter.

↳Longitud: 1-255 caracteres

↳Ejemplo: "Mi Empresa S.A. de C.V."

"legalName": string,opcional

↳Razón social completa de la organización según conste en el Registro Federal de Contribuyentes del SAT. Este campo es opcional y se utiliza cuando la razón social difiere del nombre comercial.

↳Longitud máxima: 255 caracteres

↳Ejemplo: "Mi Empresa Sociedad Anónima de Capital Variable"

"rfc": string,requerido

↳Registro Federal de Contribuyentes asignado por el SAT. Debe ser un RFC válido con formato de 12 caracteres para personas morales (3 letras, 6 dígitos, 3 caracteres alfanuméricos) o 13 caracteres para personas físicas (4 letras, 6 dígitos, 3 caracteres alfanuméricos).

↳Longitud: 12-13 caracteres · Patrón: ^[A-ZÑ&]{3,4}\d{6}[A-Z0-9]{3}$

↳Ejemplo: "XAXX010101000"

"taxRegime": string,requerido

↳Clave del régimen fiscal al que está sujeta la organización según el catálogo c_RegimenFiscal del SAT. Este valor debe corresponder a un régimen fiscal válido y vigente.

↳Catálogo SAT: c_RegimenFiscal

↳Ejemplo: "601"

"zipCode": stringrequerido

↳Código postal del domicilio fiscal de la organización registrado ante el SAT. Debe ser un código postal válido de México compuesto por exactamente 5 dígitos numéricos.

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

↳Ejemplo: "12345"

}

Ejemplos de Código

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

curl -X POST https://sandbox.lummy.io/organizations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "x-idempotency: $(uuidgen)" \
  -d '{
    "name": "Mi Empresa S.A. de C.V.",
    "legalName": "Mi Empresa S.A. de C.V.",
    "rfc": "XAXX010101000",
    "taxRegime": "601",
    "zipCode": "12345"
  }'

Variables de entorno

Define ACCESS_TOKEN en tu shell:

export ACCESS_TOKEN="your-access-token"

El ACCESS_TOKEN se obtiene después de que el usuario se autentica en la plataforma Lummy.

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

interface CreateOrganizationPayload {
  name: string;
  legalName?: string;
  rfc: string;
  taxRegime: string;
  zipCode: string;
}

interface OrganizationResponse {
  id: string;
  name: string;
  rfc: string;
  isActive: boolean;
  createdAt: string;
}

async function crearOrganizacion(): Promise<OrganizationResponse> {
  const API_URL = 'https://sandbox.lummy.io/organizations';
  const ACCESS_TOKEN = process.env.ACCESS_TOKEN!;

  const payload: CreateOrganizationPayload = {
    name: "Mi Empresa S.A. de C.V.",
    legalName: "Mi Empresa S.A. de C.V.",
    rfc: "XAXX010101000",
    taxRegime: "601", // General de Ley Personas Morales
    zipCode: "12345"
  };

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

    console.log('Organizacion 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 organizacion:', axiosError.response?.data);
      throw axiosError;
    }
    throw error;
  }
}

// Ejecutar
crearOrganizacion();

Dependencias

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

Variables de entorno

Define 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_organizacion():
    """
    Crea una nueva organización en Lummy.
    """
    api_url = "https://sandbox.lummy.io/organizations"
    access_token = os.getenv("ACCESS_TOKEN")

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

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

    payload = {
        "name": "Mi Empresa S.A. de C.V.",
        "legalName": "Mi Empresa S.A. de C.V.",
        "rfc": "XAXX010101000",
        "taxRegime": "601", # General de Ley Personas Morales
        "zipCode": "12345"
    }

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

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

        return data

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

if __name__ == "__main__":
    crear_organizacion()

Dependencias

pip install requests

Variables de entorno

Define 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 crearOrganizacion()
{
    $apiUrl = 'https://sandbox.lummy.io/organizations';
    $accessToken = getenv('ACCESS_TOKEN');

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

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

    $payload = [
        "name" => "Mi Empresa S.A. de C.V.",
        "legalName" => "Mi Empresa S.A. de C.V.",
        "rfc" => "XAXX010101000",
        "taxRegime" => "601",
        "zipCode" => "12345"
    ];

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

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

        return $data;

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

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

Dependencias

composer require guzzlehttp/guzzle ramsey/uuid

Variables de entorno

Define 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

Organización creada exitosamente.

{
  "requestId": "abc123-def456",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Mi Empresa S.A. de C.V.",
    "legalName": "Mi Empresa S.A. de C.V.",
    "rfc": "XAXX010101000",
    "taxRegime": "601",
    "zipCode": "12345",
    "isActive": true,
    "createdAt": "2025-01-15T10:30:00.000Z"
  },
  "timestamp": "2025-01-15T10:30:00.000Z",
  "path": "/organizations",
  "method": "POST"
}

409 Conflict

Ya existe una organización con el mismo RFC.

{
  "requestId": "abc123-def456",
  "error": {
    "message": "Ya existe una organización con el RFC: XAXX010101000",
    "code": "ConflictException",
    "status": 409
  },
  "timestamp": "2025-01-15T10:30:00.000Z",
  "path": "/organizations",
  "method": "POST"
}

400 Bad Request

Datos inválidos (RFC mal formado, CP incorrecto, etc).

{
  "requestId": "abc123-def456",
  "error": {
    "message": "RFC inválido: debe tener 12 o 13 caracteres",
    "code": "ValidationError",
    "status": 400
  },
  "timestamp": "2025-01-15T10:30:00.000Z",
  "path": "/organizations",
  "method": "POST"
}

Endpoint​

Headers​

Body Parameters​

Ejemplos de Código​

Respuestas​

201 Created​

409 Conflict​

400 Bad Request​

Endpoint

Headers

Body Parameters

Ejemplos de Código

Respuestas

201 Created

409 Conflict

400 Bad Request