Crear empresa

Registra la empresa emisora automáticamente desde tu plataforma para que tus usuarios puedan emitir documentos tributarios electrónicos

Método: POST

Nota

Es necesario el envío del token de acceso <access_token> para hacer uso de este endpoint. Para ver cómo generar el token, vea Cómo generar un token de acceso.

Recuerde: El token de acceso caduca cada hora.

Endpoint

Sandbox

https://api-sandbox.lumendte.com/v1/companies

Producción

https://api.lumendte.com/v1/companies

---

Payload

Campo	Tipo	Descripción
legalName	string	Razón social de la empresa o nombre de la persona natural
tradeName	string	Nombre comercial
taxIdentityNumber	string	NIT o DUI si es una persona natural
taxRegistrationNumber	string	NRC
economicActivityCode	string	Código de actividad económica
taxpayerType	string	SMALL, MEDIUM o LARGE

Significados de taxpayerType (categoría de contribuyente):

Valor	Significado
SMALL	Pequeño Contribuyente
MEDIUM	Mediano Contribuyente
LARGE	Gran Contribuyente

Tras crear la empresa, registra sus establecimientos como la casa matriz o sucursales con sus respectivos códigos de departamento, municipio y distrito: Departamentos, Municipios y Distritos. Ver Crear establecimiento.

Ejemplo de Solicitud

cURL

curl -X POST https://api-sandbox.lumendte.com/v1/companies \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tu_access_token" \
  -d '{
    "legalName": "Distribuidora El Sol, S.A. de C.V.",
    "tradeName": "El Sol",
    "taxIdentityNumber": "0614-090590-123-4",
    "taxRegistrationNumber": "123456-7",
    "economicActivityCode": "46900",
    "taxpayerType": "SMALL"
  }'

Node.js

const axios = require("axios");

const config = {
  method: "post",
  url: "https://api-sandbox.lumendte.com/v1/companies",
  headers: {
    Accept: "application/json",
    "Content-Type": "application/json",
    Authorization: "Bearer tu_access_token",
  },
  data: {
    legalName: "Distribuidora El Sol, S.A. de C.V.",
    tradeName: "El Sol",
    taxIdentityNumber: "0614-090590-123-4",
    taxRegistrationNumber: "123456-7",
    economicActivityCode: "46900",
    taxpayerType: "SMALL",
  },
};

axios(config)
  .then((response) => {
    console.log("Empresa creada:", response.data.id);
  })
  .catch((error) => {
    console.error(
      "Error en la solicitud:",
      error.response ? error.response.data : error.message,
    );
  });

Python

import requests

response = requests.post(
    'https://api-sandbox.lumendte.com/v1/companies',
    headers={
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer tu_access_token',
    },
    json={
        'legalName': 'Distribuidora El Sol, S.A. de C.V.',
        'tradeName': 'El Sol',
        'taxIdentityNumber': '0614-090590-123-4',
        'taxRegistrationNumber': '123456-7',
        'economicActivityCode': '46900',
        'taxpayerType': 'SMALL',
    },
)

if response.ok:
    data = response.json()
    print('Empresa creada:', data['id'])
else:
    print('Error en la solicitud:', response.text)

Response Success

Status: 201 Created

La API utilizará el taxIdentityNumber para identificar la empresa emisora.

{
  "legalName": "Distribuidora El Sol, S.A. de C.V.",
  "tradeName": "El Sol",
  "taxIdentityNumber": "0614-090590-123-4",
  "taxRegistrationNumber": "123456-7",
  "economicActivityCode": "46900",
  "taxpayerType": "SMALL"
}

---

Ejemplo de errores

400 — Payload inválido

Campo vacío o taxpayerType fuera de SMALL | MEDIUM | LARGE.

{
  "errorCode": "INVALID_PARAMETERS",
  "statusCode": 400,
  "message": [
    "legalName must not be empty",
    "taxIdentityNumber must be at least 9 characters long",
    "taxpayerType must be one of: SMALL, MEDIUM, LARGE"
  ],
  "error": "Bad Request"
}

Fix: Revisa el valor de taxpayerType y vuelve a enviar el JSON completo.

409 — Empresa duplicada

Ya existe una empresa con el mismo NIT o NRC. Recuerda que esos datos son únicos para cada empresa o contribuyente y Lumen identifica cuando estan bajo tu cuenta registrada.

Si el NIT ya existe:

{
  "errorCode": "COMPANY_ALREADY_EXISTS",
  "statusCode": 409,
  "message": "A company with the same taxIdentityNumber already exists",
  "error": "Conflict"
}

Si el NRC ya existe:

{
  "errorCode": "COMPANY_ALREADY_EXISTS",
  "statusCode": 409,
  "message": "A company with the same taxRegistrationNumber already exists for tenant 42",
  "error": "Conflict"
}