Guía técnica integraciones
ERPNext API REST y webhooks: guía completa
ERPNext expone una API REST nativa autogenerada para todos los DocTypes y un sistema de webhooks built-in. Esta guía cubre autenticación (API Key + Secret, OAuth 2.0), endpoints CRUD, webhooks y ejemplos prácticos en Python, JS y curl.
tu-empresa.erpnext.com
La filosofía de la API en ERPNext
ERPNext está construido sobre Frappe Framework, donde cada entidad de negocio (Customer, Item, Sales Invoice, etc.) es un DocType. Cada DocType tiene asociado, sin que tengas que hacer nada, un conjunto completo de endpoints REST: GET para leer, POST para crear, PUT para actualizar, DELETE para borrar.
Esto es muy distinto a Django o Rails, donde para cada modelo defines manualmente Serializers, ViewSets y Routes. En ERPNext la API existe el día que defines el DocType (incluso si lo creas desde la UI sin escribir código). Para apps con muchas entidades (un ERP típico tiene 200+ DocTypes), el ahorro de boilerplate es enorme.
El formato de comunicación es JSON. La autenticación recomendada para integraciones server-to-server es API Key + API Secret en el header Authorization. Para apps de terceros que actúan en nombre de un usuario, OAuth 2.0 estándar.
Endpoints principales
Los endpoints REST de ERPNext
Estructura idéntica para cualquier DocType del sistema.
| Método | Endpoint | Para qué |
|---|---|---|
| GET | /api/resource/{doctype} | Listar registros con filtros y paginación |
| GET | /api/resource/{doctype}/{name} | Obtener un registro específico (ej: Customer/CUST-001) |
| POST | /api/resource/{doctype} | Crear un nuevo registro (Customer, Item, Sales Invoice, etc.) |
| PUT | /api/resource/{doctype}/{name} | Actualizar un registro existente |
| DELETE | /api/resource/{doctype}/{name} | Eliminar un registro |
| POST | /api/method/{module.path.to.function} | Llamar a un método personalizado expuesto con @frappe.whitelist() |
Ejemplos de integración
Crear un Customer en Python
import requests
API_URL = "https://erp.miempresa.com/api/resource/Customer"
HEADERS = {
"Authorization": "token MI_API_KEY:MI_API_SECRET",
"Content-Type": "application/json",
}
response = requests.post(API_URL, headers=HEADERS, json={
"customer_name": "Distribuciones López SL",
"customer_type": "Company",
"customer_group": "Comercial",
"territory": "España",
"tax_id": "B12345678",
})
print(response.json()) # {"data": {"name": "CUST-2026-00001", ...}}Listar facturas con filtro en curl
curl -H "Authorization: token MI_KEY:MI_SECRET" \
"https://erp.miempresa.com/api/resource/Sales Invoice?filters=[[\"status\",\"=\",\"Paid\"]]&limit_page_length=50"Crear un webhook desde la UI
Setup → Integrations → Webhook → New. Configura:
- DocType: Sales Invoice
- DocEvent: On Submit
- Request URL: https://hooks.tu-sistema.com/erpnext/sales-invoice
- Request Method: POST
- Webhook Headers: Authorization, Content-Type
- Webhook Data: campos a enviar (name, customer, total, posting_date...)
— FAQ
Preguntas frecuentes sobre ERPNext API REST
Las dudas reales del developer o arquitecto de integraciones.
Ver todas las preguntas¿ERPNext tiene API REST nativa o hay que construirla?+−
ERPNext tiene API REST nativa autogenerada para todos los DocTypes (modelos de datos). Sin necesidad de programar nada, cada DocType expone los métodos GET, POST, PUT, DELETE en /api/resource/{doctype}. Esto incluye Customer, Item, Sales Invoice, Purchase Order, Employee, Project, Stock Entry y todos los DocTypes personalizados que crees. La API devuelve y acepta JSON. Esto es uno de los mayores diferenciadores de ERPNext frente a otros ERPs: la API es de fábrica, no se compra.
¿Cómo me autentico con la API REST de ERPNext?+−
Tres métodos: 1) API Key + API Secret — generas las claves desde la ficha de usuario en ERPNext, las pasas en el header `Authorization: token API_KEY:API_SECRET`. Ideal para integraciones server-to-server. 2) OAuth 2.0 — flujo estándar para apps de terceros que necesitan acceso delegado de un usuario (ej: una app móvil que se conecta a ERPNext del usuario). 3) Token de sesión por login — la sesión web normal genera una cookie de sesión válida para llamadas desde el frontend autenticado. Para integraciones automatizadas usa siempre API Key + Secret.
¿Cómo se generan las API Keys en ERPNext?+−
1) Login en ERPNext con un usuario que tenga rol System Manager. 2) Ve a la ficha del usuario al que quieres dar acceso API (idealmente un usuario dedicado tipo `api-bot@empresa.com` con permisos limitados al dominio que necesita). 3) En la sección 'API Access' click en 'Generate Keys'. 4) Copia la API Key (visible) y la API Secret (visible solo una vez — guardar en gestor de contraseñas). 5) Usa ambas en el header Authorization de cada llamada. Si la API Secret se filtra, regenera y rota.
¿Qué son los webhooks en ERPNext?+−
Los webhooks de ERPNext son llamadas HTTP automáticas desde tu ERPNext hacia URLs externas cuando ocurre un evento en un DocType (ej: cuando se crea una Sales Invoice, cuando se actualiza el estado de un Project). Te permiten conectar ERPNext con sistemas externos sin polling: Slack te avisa cuando hay un nuevo cliente, Zapier crea un row en Google Sheets cuando facturas, n8n ejecuta un workflow cuando un proyecto cambia de estado. Se configuran en Setup → Integrations → Webhook con la URL destino, el DocType y el evento (insert, update, submit, cancel, delete).
¿ERPNext se integra con Zapier, Make o n8n?+−
Sí. Zapier tiene integración oficial parcial pero la combinación más común es: usar webhooks de ERPNext como triggers (cuando pasa X en ERPNext, mandamos POST a Zapier) y Zapier ejecuta los Zaps. Make.com y n8n.io tienen módulos ERPNext específicos que permiten flujos más sofisticados. n8n self-hosted es especialmente popular en empresas que quieren mantener los datos dentro de su infraestructura. Para integraciones complejas con muchos sistemas (CRM externo, ERP cliente, e-commerce, plataformas financieras), n8n + ERPNext es una arquitectura muy potente.
¿Hay rate limit en la API de ERPNext?+−
El producto base no tiene rate limit estricto, pero hay límites prácticos de rendimiento: una instancia ERPNext con 4 GB RAM y 2 vCPU sostiene cómodamente ~50-100 requests/segundo en consultas simples y ~10-30 r/s en escritura. Para volúmenes mayores hace falta escalar el servidor (más RAM, más vCPU) o usar batching (un solo request POST con array de registros en lugar de muchos requests individuales). Para integraciones que mueven volumen, recomendamos: usar campos `limit_page_length` en las consultas, paginación, y procesos asíncronos por colas (background jobs de Frappe).
¿Puedo crear endpoints REST personalizados en ERPNext?+−
Sí. Cualquier método Python en una app de Frappe se puede exponer como endpoint REST añadiendo el decorador `@frappe.whitelist()`. Ejemplo: defines `def calcular_precio_personalizado(client_id, qty)` con `@frappe.whitelist()` y se llama vía POST a `/api/method/mi_app.api.calcular_precio_personalizado`. Para una empresa con lógica compleja específica (cálculo de descuentos, integración con un sistema legacy, validaciones cruzadas), construir endpoints personalizados es la vía estándar y suele ser cuestión de horas, no días.
¿Cómo se monitorizan las integraciones API en producción?+−
ERPNext registra todos los requests al sistema en logs (Frappe Error Log para fallos, Activity Log para actividad). Para monitorización de webhooks específicamente: la sección Webhook Request Log muestra cada disparo con respuesta del endpoint destino (200 OK, 4xx, 5xx, timeout). Para integraciones críticas, recomendamos: 1) usar un sistema de monitoring tipo UptimeRobot o Healthchecks para los webhooks; 2) tener alertas en el log de errores; 3) tests end-to-end periódicos de los flujos críticos.
Recursos relacionados
Sigue investigando.