#Tu CRM gestiona clientes. Pero no factura.
Si tienes un CRM — ya sea HubSpot, Salesforce, Pipedrive o uno propio — probablemente gestiona el ciclo de vida del cliente: desde el lead hasta el cierre. Pero cuando llega el momento de facturar, empieza el trabajo manual: copiar datos del cliente, abrir otro software, crear la factura, enviarla, y luego volver al CRM a actualizar el estado.
Con la API de BeeL, puedes automatizar todo ese flujo directamente desde tu CRM. Crear clientes, validar NIFs, generar facturas conformes a VeriFactu y sincronizar estados — todo programáticamente.
ℹ️SDK oficial disponible
El SDK de TypeScript (@beel_es/sdk) simplifica la integración: tipado completo, errores tipados, reintentos automáticos y cero configuración.
#El flujo completo: CRM → BeeL → Factura
El patrón típico de integración tiene 4 pasos:
- Sincronizar cliente del CRM a BeeL (con validación de NIF)
- Crear factura cuando se cierra un deal o se genera una venta
- Emitir y enviar la factura al cliente
- Sincronizar estado de vuelta al CRM (pagada, anulada, etc.)
#Paso 1: Sincronizar clientes con validación de NIF
Antes de crear una factura, necesitas el cliente en BeeL. Lo ideal es sincronizarlo cuando se crea o actualiza en tu CRM.
import { BeeL, CustomerBuilder } from '@beel_es/sdk';
const beel = new BeeL({ apiKey: process.env.BEEL_API_KEY! });
// Primero: validar el NIF contra la AEAT
const nifResult = await beel.nif.validate(crmContact.nif);
if (!nifResult.valid) {
// Marcar en el CRM que el NIF es inválido
await crm.updateContact(crmContact.id, {
nif_status: 'INVALID',
nif_error: 'NIF no registrado en la AEAT',
});
return;
}
// Crear cliente en BeeL
const customerData = CustomerBuilder.create()
.name(crmContact.company_name)
.nif(crmContact.nif)
.email(crmContact.email)
.phone(crmContact.phone)
.address(
crmContact.street,
crmContact.number,
crmContact.postal_code,
crmContact.city,
crmContact.province,
'Spain'
)
.build();
const customer = await beel.customers.create(customerData);
// Guardar el ID de BeeL en el CRM para futuras facturas
await crm.updateContact(crmContact.id, {
beel_customer_id: customer.id,
nif_status: 'VALID',
});⚠️Valida siempre el NIF antes de facturar
Una factura con NIF inválido es una factura con problemas legales. La validación contra la AEAT tarda milisegundos y te ahorra correcciones posteriores.
#Paso 2: Crear factura al cerrar un deal
Cuando un deal se cierra en tu CRM, generas la factura automáticamente:
async function onDealClosed(deal: CrmDeal) {
const beelCustomerId = deal.contact.beel_customer_id;
if (!beelCustomerId) {
throw new Error('Cliente no sincronizado con BeeL');
}
// Mapear líneas del deal a líneas de factura
const lines = deal.products.map(product => ({
description: product.name,
quantity: product.quantity,
unit_price: product.price,
discount_percentage: product.discount || 0,
}));
const invoice = await beel.invoices.create({
type: 'STANDARD',
recipient: { customer_id: beelCustomerId },
lines,
});
// Emitir inmediatamente (asigna número + VeriFactu)
const issued = await beel.invoices.issue(invoice.id);
// Enviar por email al cliente
await beel.invoices.sendEmail(issued.id);
// Actualizar el deal en el CRM
await crm.updateDeal(deal.id, {
invoice_id: issued.id,
invoice_number: issued.invoice_number,
invoice_status: 'ISSUED',
});
}#Paso 3: Sincronizar el estado de pago
Cuando el cliente paga, puedes marcarlo desde el CRM o usar webhooks para sincronización automática:
// Opción A: Marcar como pagada desde el CRM
async function onPaymentReceived(deal: CrmDeal) {
await beel.invoices.markPaid(deal.invoice_id, {
payment_date: new Date().toISOString().split('T')[0],
});
await crm.updateDeal(deal.id, {
invoice_status: 'PAID',
});
}
// Opción B: Webhook de BeeL → actualizar CRM
// (Ver blog sobre webhooks para implementación completa)#Búsqueda y listado de facturas
Para mostrar facturas dentro de tu CRM, usa los filtros de la API:
// Facturas pendientes de un cliente
const { invoices } = await beel.invoices.list({
status: 'ISSUED',
limit: 50,
});
// Buscar clientes sincronizados
const { customers } = await beel.customers.list({
search: 'Acme',
limit: 10,
});#Gestión de errores en la integración
Los errores tipados del SDK hacen que manejar fallos sea predecible:
import { BeeLValidationError, BeeLConflictError } from '@beel_es/sdk';
try {
await beel.invoices.create(invoiceData);
} catch (error) {
if (error instanceof BeeLValidationError) {
// Campos inválidos — loguear detalles
console.error('Campos con error:', error.details);
await crm.addNote(deal.id, `Error facturación: ${JSON.stringify(error.details)}`);
} else if (error instanceof BeeLConflictError) {
// Ya existe — posible duplicado, recuperar la existente
console.warn('Posible factura duplicada');
} else {
// Error inesperado — el SDK ya reintentó 3 veces en 5xx
throw error;
}
}#Arquitectura recomendada
Para integraciones robustas, recomendamos:
| Componente | Recomendación |
|---|---|
| Sincronización | Event-driven: webhook del CRM al crear/actualizar cliente |
| Idempotencia | El SDK añade claves automáticas — seguro reintentar |
| Mapeo de IDs | Guardar beel_customer_id y beel_invoice_id en el CRM |
| Estado | Webhooks de BeeL para sync bidireccional |
| Errores | Cola de reintentos para fallos transitorios |
#Preguntas frecuentes
#¿Puedo sincronizar clientes en ambas direcciones?
Sí. La API permite crear, actualizar y listar clientes. Puedes implementar sincronización bidireccional: CRM → BeeL al crear clientes, BeeL → CRM vía webhooks cuando cambien datos.
#¿Se valida el NIF automáticamente al crear un cliente?
No se valida automáticamente al crear — eso te da control. Pero el endpoint beel.nif.validate() está disponible para validar antes de crear. Es la práctica recomendada.
#¿Funciona con CRMs que no son Node.js?
Sí. La API REST funciona con cualquier lenguaje. El SDK de TypeScript simplifica la integración en Node.js, pero puedes usar fetch, curl o cualquier cliente HTTP con los mismos endpoints.
#¿Cómo gestiono la sincronización masiva inicial?
Para migrar clientes existentes, usa un script que itere sobre los contactos del CRM, valide NIFs y cree clientes en BeeL. Las claves de idempotencia protegen contra duplicados si necesitas reiniciar el proceso.
¿Necesitas integrar facturación en tu CRM? Empieza con el SDK de TypeScript (código fuente en GitHub), consulta la documentación de la API y la página de SDKs para quickstarts en otros lenguajes.