Crear Organización

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

Endpoint

POST /organizations

Headers

Nombre	Tipo	Requerido	Descripción
Authorization	string	Sí	Token de autenticación Bearer (JWT).
x-idempotency	string	Sí	UUID v7 único para garantizar idempotencia.

Body Parameters

Nombre	Tipo	Requerido	Descripción
name	string	Sí	Nombre comercial de la organización.
legalName	string	No	Razón social (si es diferente al nombre).
rfc	string	Sí	Registro Federal de Contribuyentes (12 o 13 caracteres).
taxRegime	string	Sí	Clave del régimen fiscal (ej. "601").
zipCode	string	Sí	Código postal del domicilio fiscal (5 dígitos).

Ejemplos de Código

cURL

curl -X POST https://sandbox-api.lummy.com/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.

Node.js (TypeScript)

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-api.lummy.com/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('✅ Organización 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 organización:', 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.

Python

import os
import requests
from uuid import uuid4

def crear_organizacion():
    """
    Crea una nueva organización en Lummy.
    """
    api_url = "https://sandbox-api.lummy.com/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("✅ Organización creada exitosamente")
        print(f"ID: {data['id']}")
        
        return data

    except requests.exceptions.RequestException as e:
        print(f"❌ Error al crear organización: {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 (Guzzle)

<?php

require 'vendor/autoload.php';

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

function crearOrganizacion()
{
    $apiUrl = 'https://sandbox-api.lummy.com/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 "✅ Organización creada exitosamente\n";
        echo "ID: " . $data['id'] . "\n";
        
        return $data;

    } catch (RequestException $e) {
        echo "❌ Error al crear organización: " . $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

201 Created

Organización creada exitosamente.

{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

409 Conflict

Ya existe una organización con el mismo RFC.

400 Bad Request

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