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.
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.
Los endpoints REST de ERPNext
Estructura idéntica para cualquier DocType del sistema: mismo patrón de URL, mismos verbos HTTP y mismo formato JSON tanto si trabajas con un Customer, una Sales Invoice o un DocType personalizado que hayas creado tú mismo desde la interfaz, sin escribir una línea de código.
| 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
Tres ejemplos reales para que veas el patrón exacto: crear un cliente nuevo con una petición POST en Python, filtrar facturas cobradas con una llamada en curl, y montar un webhook desde la propia interfaz sin escribir ningún código para el lado de ERPNext.
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: cómo se autentica una llamada a la API, qué límites de rate tiene, cómo se configuran webhooks de salida sin tocar el código fuente de ERPNext, y qué pasa cuando el volumen de peticiones crece mucho en producción.
Ver todas las preguntas¿ERPNext tiene API REST nativa o hay que construirla?+−
¿Cómo me autentico con la API REST de ERPNext?+−
¿Cómo se generan las API Keys en ERPNext?+−
¿Qué son los webhooks en ERPNext?+−
¿ERPNext se integra con Zapier, Make o n8n?+−
¿Hay rate limit en la API de ERPNext?+−
¿Puedo crear endpoints REST personalizados en ERPNext?+−
¿Cómo se monitorizan las integraciones API en producción?+−
Recursos relacionados
Sigue investigando: cómo funciona por dentro la API de VeriFactu para desarrolladores, qué es Frappe Framework y cómo funciona el motor que hay bajo ERPNext, cómo se desarrolla tu primera app paso a paso desde cero, y qué cubre exactamente nuestro servicio de desarrollo a medida.
¿Necesitas integrar ERPNext con tu stack?
Si necesitas conectar ERPNext con tu CRM externo, tu tienda online, un sistema legacy, marketplaces o cualquier otra API, cuéntanos qué sistemas hay en juego y qué datos tienen que viajar entre ellos. Diseñamos la arquitectura de integración y la implementamos con webhooks o API REST, según convenga.