--- title: "API" space: "DiamoERP" url: "https://diamo.com.ar/diamoerp/api" updated: "2026-09-28" --- Esta guía explica, de forma práctica, cómo consumir la API de DiamoERP desde cualquier sistema externo (un script, una integración, un ERP, etc.). DiamoERP genera automáticamente una API REST para todos sus tipos de documento. > **Base URL**: en todos los ejemplos usamos `` como el dominio de tu sitio, por ejemplo `https://demo.diamo.com.ar`. La API se expone bajo el prefijo `/api`. --- ## **1. Solicitar un usuario API dedicado** Para consumir la API necesitás un usuario marcado como **Usuario API dedicado**. Estas cuentas utilizan una licencia reservada y no pueden iniciar sesión en Desk o portal. La asignación no es de autoservicio. Deben realizarla desde Diamo, o un usuario con rol `Administrador del sistema`, siempre que la suscripción tenga cupo `api_users` disponible. El cupo ERP es `users - api_users`. Por ejemplo, 10 usuarios ERP y 2 usuarios API requieren 12 licencias totales. ![](/files/Captura de pantalla 2026-09-28 a la(s) 2.23.40 p. m..webp) ### **1.1 Generar las credenciales** 1. Un administrador abre el usuario API dedicado. 2. En la sección **Acceso por API**, pulsa **Generar Llaves**. 3. Copiá el **API Secret** que aparece en el diálogo y guardalo en un lugar seguro (un gestor de contraseñas). El **API Key** queda visible en el campo *API Key*. ![](/files/Captura de pantalla 2026-09-28 a la(s) 2.22.48 p. m..webp) > El **API Secret** sólo se muestra una vez. La **API Key** no se puede regenerar; si perdés el secret, generá keys nuevas (se crea un secret nuevo para la misma key). --- ## **2. Autenticación** La forma recomendada es la **autenticación por token**. El token es la concatenación de `api_key` y `api_secret` separadas por `:`, y se envía en la cabecera `Authorization` con el prefijo `token`: ``` Authorization: token : ``` Cada petición hecha con ese token se registra contra el usuario que generó las keys, y **los permisos se evalúan contra ese usuario** (roles, permisos por documento, etc.). ### **Ejemplo** ``` curl https:///api/method/frappe.auth.get_logged_user \ -H "Authorization: token :" ``` ``` { "message": "usuario@ejemplo.com" } ``` --- ## **3. Descubrir la API** Se incluyen dos endpoints que los Tipos de Documentos y campos que tu usuario puede leer. ### **3.1 Listar los Tipos de Documentos disponibles** Devuelve la lista de Tipos de Documentos que podés leer, con su módulo y su etiqueta. ``` curl "https:///api/method/diamoerp_base.api.get_doctypes" \ -H "Authorization: token :" ``` Respuesta (fragmento): ``` { "message": [ { "name": "Customer", "module": "Selling", "issingle": 0, "label": "Cliente" }, { "name": "Sales Invoice", "module": "Accounts", "issingle": 0, "label": "Factura de venta" }, { "name": "System Settings", "module": "Setup", "issingle": 1, "label": "Configuración del sistema" } ] } ``` ### **3.2 Listar los campos de un Tipos de Documento** Dado un Tipos de Documento, devuelve sus campos (nombre, etiqueta, tipo, opciones, si es obligatorio, si es de solo lectura, etc.). Los campos de tipo **tabla** (*Table*) se incluyen, y en `options` indican el Tipos de Documento hijo. ``` curl "https:///api/method/diamoerp_base.api.get_doctype_fields?doctype=Customer" \ -H "Authorization: token :" ``` Respuesta (fragmento): ``` { "message": [ { "fieldname": "customer_name", "label": "Customer Name", "fieldtype": "Data", "options": null, "reqd": 1, "read_only": 0 }, { "fieldname": "customer_group", "label": "Customer Group", "fieldtype": "Link", "options": "Customer Group", "reqd": 0, "read_only": 0 } ] } ``` > **Tip**: combiná los dos endpoints para armar integraciones. Primero listá los Tipos de Documentos, elegí el que te interesa, y después consultá sus campos para saber qué enviar en cada operación. --- ## **4. Operaciones CRUD sobre documentos** La API genera los endpoints CRUD para cada Tipos de Documento automáticamente. > Enviá siempre estas cabeceras para recibir/entregar JSON correctamente: `Accept: application/json` y `Content-Type: application/json`. ### **4.1 Listar documentos** ``` curl "https:///api/resource/Customer" \ -H "Authorization: token :" \ -H "Accept: application/json" ``` Por defecto devuelve 20 registros y sólo el campo `name`. Para pedir campos específicos usá `fields` (un array JSON): ``` curl "https:///api/resource/Customer?fields=[\"name\",\"customer_name\"]" \ -H "Authorization: token :" ``` ### **4.2 Leer un documento** ``` curl "https:///api/resource/Customer/CUST-0001" \ -H "Authorization: token :" ``` ### **4.3 Crear un documento** ``` curl -X POST "https:///api/resource/Customer" \ -H "Authorization: token :" \ -H "Content-Type: application/json" \ -d '{"customer_name": "Cliente de Ejemplo", "customer_group": "Individual"}' ``` ### **4.4 Actualizar un documento** Sólo enviá los campos que querés cambiar: ``` curl -X PUT "https:///api/resource/Customer/CUST-0001" \ -H "Authorization: token :" \ -H "Content-Type: application/json" \ -d '{"customer_name": "Nuevo nombre"}' ``` ### **4.5 Eliminar un documento** ``` curl -X DELETE "https:///api/resource/Customer/CUST-0001" \ -H "Authorization: token :" ``` --- ## **5. Parámetros de consulta útiles** Todos los parámetros se pasan en la URL (codificados cuando corresponde). | **Parámetro** | **Descripción** | **Ejemplo** | | ------------------- | -------------------------------------------------------------- | ----------------------------------------------- | | `fields` | Array JSON de campos a devolver | `fields=["name","customer_name"]` | | `filters` | Array de filtros `[campo, operador, valor]` (unidos con `AND`) | `filters=[["customer_group","=","Individual"]]` | | `or_filters` | Igual que `filters` pero unidos con `OR` | `or_filters=[["status","=","Enabled"]]` | | `order_by` | Campo y orden (`campo desc`) | `order_by=creation%20desc` | | `limit_start` | Registro desde el que empezar | `limit_start=20` | | `limit_page_length` | Cantidad de registros (máx. por página) | `limit_page_length=50` | ### **Ejemplo con filtros y paginación** ``` curl "https:///api/resource/Sales%20Invoice?fields=[\"name\",\"customer\",\"grand_total\"]&filters=[[\"docstatus\",\"=\",1]]&order_by=creation%20desc&limit_page_length=10" \ -H "Authorization: token :" ``` --- ## **6. Llamadas a métodos (remote methods)** Para ejecutar lógica personalizada (métodos Python marcados como *whitelisted*) se usa `/api/method/`. - Si el método **sólo devuelve datos**, usá `GET`. - Si el método **modifica la base de datos**, usá `POST`. La respuesta exitosa viene en la clave `message`: ``` curl "https:///api/method/diamoerp_base.api.get_doctypes" \ -H "Authorization: token :" ``` --- ## **7. Errores comunes** | **Código / tipo** | **Significado** | **Solución** | | --------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | `401` | Token inválido o mal formado | Verificá `Authorization: token api_key:api_secret` | | `403` | El usuario no tiene permiso para el DocType / campo | Usá los endpoints de descubrimiento para ver qué podés leer | | `404` | Endpoint o documento inexistente | Verificá la URL y el nombre del DocType/documento | | `417` | Error de validación (p. ej. campo obligatorio faltante) | Revisá el mensaje y los campos obligatorios (`reqd`) | | `429` | Superaste el límite de peticiones (rate limit) | Esperá el valor de `Retry-After` y reintentá; espaciá tus llamadas o pedí ampliar el límite | | `503` | El control de rate limit no está disponible | Reintentá más tarde; el ERP no ejecuta la petición sin esa protección | | `exc` en la respuesta | Excepción del servidor | Mirá `exc_type` y `exc` para el detalle | ### **7.1 Rate limiting (límite de peticiones)** Para proteger el rendimiento del ERP y de los demás clientes, las peticiones autenticadas con una API key (`Authorization: token ...` o `Basic ...`) están limitadas por **API key**. Si se supera el máximo de peticiones permitido en la ventana de tiempo, la API responde `429 Too Many Requests` con el header `Retry-After` en segundos. Las credenciales pertenecen a un **usuario API dedicado**. Estas cuentas no pueden iniciar sesión interactiva; para sumar 2 cuentas API a 10 usuarios ERP, la suscripción debe tener 12 licencias totales (`users: 12`, `api_users: 2`). --- ## **8. Ejemplo completo** Un flujo típico de integración: ``` # 1) Descubrir qué Tipos de Documentos puedo leer curl "https:///api/method/diamoerp_base.api.get_doctypes" \ -H "Authorization: token :" # 2) Ver los campos de un Tipos de Documento curl "https:///api/method/diamoerp_base.api.get_doctype_fields?doctype=Customer" \ -H "Authorization: token :" # 3) Listar clientes con un filtro curl "https:///api/resource/Customer?fields=[\"name\",\"customer_name\"]&filters=[[\"customer_group\",\"=\",\"Individual\"]]" \ -H "Authorization: token :" # 4) Crear un cliente curl -X POST "https:///api/resource/Customer" \ -H "Authorization: token :" \ -H "Content-Type: application/json" \ -d '{"customer_name": "Nuevo Cliente", "customer_group": "Individual"}' ```