Skip to main content

​
Configuración básica

Puedes instalar la integración de Alegra desde nuestro Marketplace. Una vez instalada, podrás gestionar contactos, productos/servicios, crear facturas, registrar pagos y consultar catálogos directamente desde tu agente.

​
Prerrequisitos

Antes de usar esta integración, necesitas:
  1. Cuenta activa en Alegra — Regístrate en alegra.com
  2. Credenciales de API — Obtén tu email y token desde Configuración > Integraciones > API

​
Credenciales requeridas

CampoDescripciónRequerido
EmailEmail de tu cuenta de AlegraSí
API KeyToken de API de AlegraSí
Puedes generar tu API Key desde el dashboard de Alegra en Configuración > Integraciones > API > Generar token.

​
Funcionalidades

​
Buscar entidades

Búsqueda unificada para todas las entidades de Alegra: contactos, productos, facturas, cotizaciones, pagos y gastos. Inputs:
  • entity (enum: contacts | items | invoices | estimates | payments | expenses) — Tipo de entidad a buscar.
  • id (opcional, number) — Obtener un registro específico por ID.
  • query (opcional, string) — Buscar por nombre o referencia.
  • filters (opcional, objeto) — Filtros adicionales:
    • type (string) — Tipo: contact (client|provider), item (product|service|kit), payment (in|out).
    • status (string) — Estado: draft, open, closed, void.
    • clientId (number) — Filtrar por ID de cliente.
    • providerId (number) — Filtrar por ID de proveedor.
    • dateStart (string) — Fecha inicial (YYYY-MM-DD).
    • dateEnd (string) — Fecha final (YYYY-MM-DD).
  • start (opcional, number) — Offset para paginación.
  • limit (opcional, number) — Límite de resultados (máx 30).
Ejemplo: 
{
  "entity": "contacts",
  "query": "Juan",
  "filters": { "type": "client" },
  "limit": 10
}

​
Crear o actualizar contacto

Crea o actualiza un cliente o proveedor. Si se proporciona identification o email, busca coincidencias antes de crear. Inputs:
  • id (opcional, number) — ID del contacto existente (para actualizar).
  • name (string) — Nombre completo o razón social.
  • identification (opcional, string) — Número de identificación (NIT/CC/RUC).
  • email (opcional, string) — Correo electrónico.
  • phone (opcional, string) — Teléfono.
  • address (opcional, string) — Dirección.
  • city (opcional, string) — Ciudad.
  • type (opcional, array: client | provider) — Tipo de contacto (por defecto client).
Ejemplo: 
{
  "name": "Juan Pérez",
  "email": "[email protected]",
  "phone": "+57 300 123 4567",
  "identification": "1234567890",
  "type": ["client"]
}

​
Eliminar contacto

Elimina un contacto de Alegra por su ID. Inputs:
  • id (number) — ID del contacto a eliminar.
Ejemplo: 
{
  "id": 123
}

​
Crear o actualizar producto/servicio

Crea o actualiza un producto o servicio. El tipo se infiere automáticamente del nombre si no se especifica. Inputs:
  • id (opcional, number) — ID del item existente (para actualizar).
  • name (string) — Nombre del producto/servicio.
  • price (number) — Precio de venta.
  • description (opcional, string) — Descripción.
  • reference (opcional, string) — SKU o código de referencia.
  • type (opcional, enum: product | service | kit) — Tipo (auto-inferido si no se proporciona).
  • taxId (opcional, number) — ID del impuesto a aplicar.
  • categoryId (opcional, number) — ID de categoría.
  • unit (opcional, string) — Unidad de medida.
  • initialQuantity (opcional, number) — Cantidad inicial de inventario.
Ejemplo: 
{
  "name": "Servicio de consultoría",
  "price": 150000,
  "description": "Hora de consultoría especializada",
  "type": "service"
}

​
Eliminar producto/servicio

Elimina un producto o servicio de Alegra por su ID. Inputs:
  • id (number) — ID del item a eliminar.
Ejemplo: 
{
  "id": 456
}

​
Crear factura

Crea una nueva factura. Por defecto se crea como borrador. Inputs:
  • clientId (number) — ID del cliente.
  • date (opcional, string) — Fecha de la factura (YYYY-MM-DD).
  • dueDate (opcional, string) — Fecha de vencimiento (YYYY-MM-DD).
  • items (array de objeto) — Líneas de la factura:
    • id (opcional, number) — ID del producto del catálogo.
    • name (opcional, string) — Nombre del item.
    • description (opcional, string) — Descripción.
    • price (number) — Precio unitario.
    • quantity (number) — Cantidad.
    • discount (opcional, number) — Porcentaje de descuento (0-100).
    • taxId (opcional, number) — ID del impuesto.
  • observations (opcional, string) — Notas internas.
  • termsConditions (opcional, string) — Términos y condiciones.
  • asDraft (opcional, boolean) — Crear como borrador (por defecto true).
Ejemplo: 
{
  "clientId": 123,
  "date": "2025-01-15",
  "dueDate": "2025-02-15",
  "items": [
    {
      "name": "Servicio de desarrollo",
      "price": 500000,
      "quantity": 1
    }
  ],
  "asDraft": true
}

​
Activar factura

Activa una factura en borrador para que esté lista para cobro. Inputs:
  • invoiceId (number) — ID de la factura a activar.
Ejemplo: 
{
  "invoiceId": 789
}

​
Enviar factura por email

Envía una factura por correo electrónico. Requiere confirmación en dos pasos. Inputs:
  • invoiceId (number) — ID de la factura a enviar.
  • emails (array de string) — Direcciones de correo destinatarias.
  • subject (opcional, string) — Asunto del correo.
  • message (opcional, string) — Mensaje del cuerpo del correo.
  • confirmationToken (opcional, string) — Token de confirmación (segundo paso).
Ejemplo (paso 1 - preview): 
{
  "invoiceId": 789,
  "emails": ["[email protected]"]
}
Ejemplo (paso 2 - enviar): 
{
  "invoiceId": 789,
  "emails": ["[email protected]"],
  "confirmationToken": "abc123..."
}

​
Anular factura

Anula una factura. Requiere confirmación en dos pasos.
Esta acción no se puede deshacer.
Inputs:
  • invoiceId (number) — ID de la factura a anular.
  • confirmationToken (opcional, string) — Token de confirmación (segundo paso).
Ejemplo: 
{
  "invoiceId": 789
}

​
Registrar pago

Registra un pago y lo aplica a una factura. Requiere confirmación en dos pasos. Inputs:
  • invoiceId (number) — ID de la factura.
  • amount (number) — Monto del pago.
  • date (opcional, string) — Fecha del pago (YYYY-MM-DD).
  • bankAccountId (opcional, number) — ID de la cuenta bancaria.
  • paymentMethod (opcional, string) — Método de pago.
  • observations (opcional, string) — Notas o referencia.
  • confirmationToken (opcional, string) — Token de confirmación (segundo paso).
Ejemplo (paso 1 - preview): 
{
  "invoiceId": 789,
  "amount": 500000
}
Ejemplo (paso 2 - confirmar): 
{
  "invoiceId": 789,
  "amount": 500000,
  "confirmationToken": "xyz789..."
}

​
Obtener catálogos

Obtiene datos de referencia de Alegra: impuestos, métodos de pago, cuentas bancarias, categorías, etc. Inputs:
  • catalog (enum) — Catálogo a consultar:
    • taxes — Impuestos configurados.
    • payment_methods — Métodos de pago.
    • bank_accounts — Cuentas bancarias.
    • terms — Términos de pago.
    • categories — Categorías de productos.
    • numbering_templates — Plantillas de numeración.
    • price_lists — Listas de precios.
    • company — Información de la empresa.
  • documentType (opcional, enum) — Tipo de documento para numbering_templates: invoice, creditNote, debitNote, estimate, remission, bill.
Ejemplo: 
{
  "catalog": "taxes"
}