Empresas

Gestiona las empresas de tu espacio de trabajo. Las empresas agrupan contactos bajo una organización común y sirven como punto de referencia para negocios, cotizaciones y otras entidades comerciales.

Autenticación

Requiere header Authorization: Bearer {token}. Ver .

Permisos requeridos

Las operaciones sobre empresas requieren los permisos companies:read, companies:create, companies:update o companies:delete según corresponda.

Listar empresas

http

GET /companies

Retorna una lista paginada de empresas del espacio de trabajo. Soporta búsqueda de texto libre, filtros por responsable e industria, y ordenamiento por múltiples campos.

Parámetros de consulta

Parámetro	Tipo	Requerido	Descripción
`cursor`	`string`	No	Cursor de paginación. Usa el valor `nextCursor` de la respuesta anterior
`limit`	`integer`	No	Cantidad de resultados por página. Mínimo `1`, máximo `100`. Default: `25`
`sort`	`string`	No	Campo por el que ordenar. Valores: `created_at`, `updated_at`, `name`, `employee_count`, `annual_revenue`. Default: `created_at`
`order`	`string`	No	Dirección del ordenamiento: `asc` o `desc`. Default: `desc`
`search`	`string`	No	Búsqueda de texto libre sobre nombre, email y teléfono de la empresa
`owner_id`	`string`	No	Filtra por ID del responsable asignado
`industry`	`string`	No	Filtra por sector o industria (ej. `tecnologia`, `salud`, `retail`)

Ejemplos

bash

curl -X GET "https://api-crm.zelta.dev/public/v1/companies?limit=20&search=constructora" \
  -H "Authorization: Bearer tu-api-key-aqui"

Ejemplo JS

javascript

const params = new URLSearchParams({
  limit: '20',
  search: 'constructora',
  sort: 'name',
  order: 'asc'
});

const response = await fetch(
  `https://api-crm.zelta.dev/public/v1/companies?${params}`,
  {
    headers: {
      'Authorization': `Bearer ${process.env.ZELTA_API_KEY}`
    }
  }
);

const data = await response.json();
console.log(data.data);       // array de empresas
console.log(data.nextCursor); // cursor para la siguiente página

Ejemplo Py

python

import requests

response = requests.get(
    'https://api-crm.zelta.dev/public/v1/companies',
    params={
        'limit': 20,
        'search': 'constructora',
        'sort': 'name',
        'order': 'asc'
    },
    headers={
        'Authorization': 'Bearer tu-api-key-aqui'
    }
)

data = response.json()
companies = data['data']

Respuesta exitosa

HTTP 200 OK

json

{
  "data": [
    {
      "id": "cmp_r8v2wlnp4s",
      "name": "Constructora del Pacífico S.A.",
      "website": "https://constructorapacífico.com",
      "industry": "Construcción",
      "employeeCount": 250,
      "annualRevenue": 5000000,
      "currency": "USD",
      "phone": "+507 264-1234",
      "email": "contacto@constructorapacífico.com",
      "description": "Empresa de construcción con más de 30 años de experiencia.",
      "ownerId": "usr_b4h7czjp9e",
      "ownerName": "Carlos Rodríguez",
      "tags": [
        {
          "id": "tag_m9d3vbkp2r",
          "label": "Cliente activo",
          "handle": "cliente-activo",
          "color": "#10B981"
        }
      ],
      "customData": {},
      "addressCountryId": 171,
      "addressCountryName": "Panamá",
      "addressStateId": 1234,
      "addressStateName": "Panamá",
      "addressCityId": 56789,
      "addressCityName": "Ciudad de Panamá",
      "createdAt": "2025-01-20T09:00:00.000Z",
      "updatedAt": "2025-03-28T14:15:00.000Z"
    }
  ],
  "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI1LTAxLTIwVDA5OjAwOjAwLjAwMFoiLCJpZCI6ImNtcF9yOHYyd2xucDRzIn0=",
  "hasMore": false
}

Obtener una empresa

http

GET /companies/:id

Retorna los datos completos de una empresa específica por su ID.

Ejemplos

bash

curl -X GET "https://api-crm.zelta.dev/public/v1/companies/cmp_r8v2wlnp4s" \
  -H "Authorization: Bearer tu-api-key-aqui"

Ejemplo JS

javascript

const companyId = 'cmp_r8v2wlnp4s';
const response = await fetch(
  `https://api-crm.zelta.dev/public/v1/companies/${companyId}`,
  {
    headers: {
      'Authorization': `Bearer ${process.env.ZELTA_API_KEY}`
    }
  }
);

const company = await response.json();

Ejemplo Py

python

import requests

company_id = 'cmp_r8v2wlnp4s'
response = requests.get(
    f'https://api-crm.zelta.dev/public/v1/companies/{company_id}',
    headers={'Authorization': 'Bearer tu-api-key-aqui'}
)

company = response.json()

Respuesta exitosa

HTTP 200 OK

Retorna el objeto completo de la empresa con todos sus campos. Ver .

Crear una empresa

http

POST /companies

Crea una nueva empresa en el espacio de trabajo.

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
`name`	`string`	Sí	Nombre de la empresa. Máximo 200 caracteres
`website`	`string`	No	Sitio web de la empresa. Debe ser una URL válida (ej. `https://empresa.com`)
`industry`	`string`	No	Sector o industria a la que pertenece la empresa
`employeeCount`	`integer`	No	Número aproximado de empleados
`annualRevenue`	`integer`	No	Ingresos anuales estimados en la moneda indicada
`currency`	`string`	No	Código ISO 4217 de la moneda para `annualRevenue`. Máximo 3 caracteres (ej. `USD`, `MXN`, `PAB`)
`phone`	`string`	No	Teléfono principal de la empresa
`email`	`string`	No	Correo electrónico de contacto de la empresa
`description`	`string`	No	Descripción o notas generales sobre la empresa
`ownerId`	`string`	No	ID del usuario responsable. Si se omite, se asigna al usuario que realiza la solicitud
`tags`	`string[]`	No	Array de IDs de etiquetas a asignar a la empresa
`customData`	`object`	No	Datos de campos personalizados definidos en el espacio de trabajo
`addressCountryId`	`integer`	No	ID del país (tabla de referencia geográfica)
`addressStateId`	`integer`	No	ID del estado o provincia
`addressCityId`	`integer`	No	ID de la ciudad

Ejemplos

bash

curl -X POST "https://api-crm.zelta.dev/public/v1/companies" \
  -H "Authorization: Bearer tu-api-key-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Constructora del Pacífico S.A.",
    "website": "https://constructorapacifico.com",
    "industry": "Construcción",
    "employeeCount": 250,
    "annualRevenue": 5000000,
    "currency": "USD",
    "phone": "+507 264-1234",
    "email": "[email protected]",
    "addressCountryId": 171,
    "addressStateId": 1234,
    "addressCityId": 56789
  }'

Ejemplo JS

javascript

const response = await fetch('https://api-crm.zelta.dev/public/v1/companies', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ZELTA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Constructora del Pacífico S.A.',
    website: 'https://constructorapacifico.com',
    industry: 'Construcción',
    employeeCount: 250,
    annualRevenue: 5000000,
    currency: 'USD',
    phone: '+507 264-1234',
    email: '[email protected]',
    addressCountryId: 171,
    addressStateId: 1234,
    addressCityId: 56789
  })
});

const company = await response.json();
console.log(company.id); // ID de la nueva empresa

Ejemplo Py

python

import requests

response = requests.post(
    'https://api-crm.zelta.dev/public/v1/companies',
    headers={
        'Authorization': 'Bearer tu-api-key-aqui',
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Constructora del Pacífico S.A.',
        'website': 'https://constructorapacifico.com',
        'industry': 'Construcción',
        'employeeCount': 250,
        'annualRevenue': 5000000,
        'currency': 'USD',
        'phone': '+507 264-1234',
        'email': '[email protected]',
        'addressCountryId': 171,
        'addressStateId': 1234,
        'addressCityId': 56789
    }
)

company = response.json()
print(company['id'])

Respuesta exitosa

HTTP 201 Created

Retorna el objeto completo de la empresa recién creada.

Actualizar una empresa

http

PUT /companies/:id

Actualiza los datos de una empresa existente. Solo se actualizan los campos incluidos en el cuerpo — los campos omitidos conservan su valor actual.

Cuerpo de la solicitud

Todos los campos son opcionales. Ver la tabla de para las definiciones de cada campo.

Ejemplos

bash

curl -X PUT "https://api-crm.zelta.dev/public/v1/companies/cmp_r8v2wlnp4s" \
  -H "Authorization: Bearer tu-api-key-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "employeeCount": 320,
    "annualRevenue": 7500000,
    "description": "Empresa líder en infraestructura civil en la región."
  }'

Ejemplo JS

javascript

const companyId = 'cmp_r8v2wlnp4s';
const response = await fetch(
  `https://api-crm.zelta.dev/public/v1/companies/${companyId}`,
  {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.ZELTA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      employeeCount: 320,
      annualRevenue: 7500000,
      description: 'Empresa líder en infraestructura civil en la región.'
    })
  }
);

const updated = await response.json();

Ejemplo Py

python

import requests

company_id = 'cmp_r8v2wlnp4s'
response = requests.put(
    f'https://api-crm.zelta.dev/public/v1/companies/{company_id}',
    headers={
        'Authorization': 'Bearer tu-api-key-aqui',
        'Content-Type': 'application/json'
    },
    json={
        'employeeCount': 320,
        'annualRevenue': 7500000,
        'description': 'Empresa líder en infraestructura civil en la región.'
    }
)

updated = response.json()

Respuesta exitosa

HTTP 200 OK

Retorna el objeto completo de la empresa con los campos actualizados.

Eliminar una empresa

http

DELETE /companies/:id

Elimina una empresa de forma lógica (soft delete). La empresa queda inaccesible desde la API y la interfaz, pero sus datos no se borran permanentemente.

Contactos asociados

Eliminar una empresa no elimina sus contactos asociados. Los contactos mantienen la referencia al companyId pero la empresa aparecerá como no disponible al consultar el contacto. Considera desvincular los contactos antes de eliminar la empresa si esto es relevante para tu integración.

Ejemplos

bash

curl -X DELETE "https://api-crm.zelta.dev/public/v1/companies/cmp_r8v2wlnp4s" \
  -H "Authorization: Bearer tu-api-key-aqui"

Ejemplo JS

javascript

const companyId = 'cmp_r8v2wlnp4s';
const response = await fetch(
  `https://api-crm.zelta.dev/public/v1/companies/${companyId}`,
  {
    method: 'DELETE',
    headers: {
      'Authorization': `Bearer ${process.env.ZELTA_API_KEY}`
    }
  }
);

const result = await response.json();
// { "success": true }

Ejemplo Py

python

import requests

company_id = 'cmp_r8v2wlnp4s'
response = requests.delete(
    f'https://api-crm.zelta.dev/public/v1/companies/{company_id}',
    headers={'Authorization': 'Bearer tu-api-key-aqui'}
)

result = response.json()
# {'success': True}

Respuesta exitosa

HTTP 200 OK

json

{
  "success": true
}

Campos de la respuesta

Campo	Tipo	Descripción
`id`	`string`	Identificador único de la empresa
`name`	`string`	Nombre de la empresa
`website`	`string \| null`	Sitio web
`industry`	`string \| null`	Sector o industria
`employeeCount`	`integer \| null`	Número de empleados
`annualRevenue`	`integer \| null`	Ingresos anuales estimados
`currency`	`string \| null`	Código ISO 4217 de la moneda de `annualRevenue`
`phone`	`string \| null`	Teléfono principal
`email`	`string \| null`	Correo electrónico de contacto
`description`	`string \| null`	Descripción o notas generales
`ownerId`	`string \| null`	ID del responsable asignado
`ownerName`	`string \| null`	Nombre completo del responsable (resuelto por JOIN)
`tags`	`array`	Etiquetas asignadas a la empresa
`tags[].id`	`string`	ID de la etiqueta
`tags[].label`	`string`	Nombre visible de la etiqueta
`tags[].handle`	`string`	Identificador slug de la etiqueta
`tags[].color`	`string`	Color hex de la etiqueta
`customData`	`object`	Valores de campos personalizados
`addressCountryId`	`integer \| null`	ID del país
`addressCountryName`	`string \| null`	Nombre del país
`addressStateId`	`integer \| null`	ID del estado o provincia
`addressStateName`	`string \| null`	Nombre del estado o provincia
`addressCityId`	`integer \| null`	ID de la ciudad
`addressCityName`	`string \| null`	Nombre de la ciudad
`createdAt`	`string`	Fecha de creación en formato ISO 8601
`updatedAt`	`string`	Fecha de última actualización en formato ISO 8601

Problemas comunes

Error	Causa	Solución
`401 Unauthorized`	API Key inválida o ausente	Verifica que el header `Authorization` incluya un token válido
`403 Forbidden`	Sin permisos suficientes	El rol asociado a tu API Key no tiene el permiso `companies:read` o `companies:create`
`404 Not Found`	Empresa no encontrada	Verifica que el ID sea correcto y pertenezca al espacio de trabajo del token
`422 Unprocessable Entity`	Error de validación	Revisa que el campo `name` esté presente y que `website` sea una URL válida
`400` — `website` inválido	URL malformada	El campo `website` debe incluir el protocolo (`https://`)
`400` — `currency` inválido	Código de moneda no reconocido	Usa un código ISO 4217 de 3 letras válido (ej. `USD`, `MXN`, `EUR`)
`400` — `ownerId` inválido	El usuario no pertenece al workspace	Usa solo IDs de miembros activos del espacio de trabajo

Datos geográficos

Los IDs de país, estado y ciudad provienen de la tabla de referencia geográfica de Zelta CRM. Puedes consultarlos mediante los endpoints públicos de geo (/geo/countries, /geo/states/:countryId, /geo/cities/:stateId) sin necesidad de autenticación.

Siguientes pasos

— Asocia personas a una empresa
— Vincula negocios a una empresa
— Cómo generar y usar tu API Key

Empresas ​

Autenticación ​

Listar empresas ​

Parámetros de consulta ​

Ejemplos ​

Respuesta exitosa ​

Obtener una empresa ​

Ejemplos ​

Respuesta exitosa ​

Crear una empresa ​

Cuerpo de la solicitud ​

Ejemplos ​

Respuesta exitosa ​

Actualizar una empresa ​

Cuerpo de la solicitud ​

Ejemplos ​

Respuesta exitosa ​

Eliminar una empresa ​

Ejemplos ​

Respuesta exitosa ​

Campos de la respuesta ​

Problemas comunes ​

Siguientes pasos ​

Empresas

Autenticación

Listar empresas

Parámetros de consulta

Ejemplos

Respuesta exitosa

Obtener una empresa

Ejemplos

Respuesta exitosa

Crear una empresa

Cuerpo de la solicitud

Ejemplos

Respuesta exitosa

Actualizar una empresa

Cuerpo de la solicitud

Ejemplos

Respuesta exitosa

Eliminar una empresa

Ejemplos

Respuesta exitosa

Campos de la respuesta

Problemas comunes

Siguientes pasos