API

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 <base-url> 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.

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.

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 <api_key>:<api_secret>

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://<base-url>/api/method/frappe.auth.get_logged_user \
  -H "Authorization: token <api_key>:<api_secret>"

{ "message": "[email protected]" }

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://<base-url>/api/method/diamoerp_base.api.get_doctypes" \
  -H "Authorization: token <api_key>:<api_secret>"

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://<base-url>/api/method/diamoerp_base.api.get_doctype_fields?doctype=Customer" \
  -H "Authorization: token <api_key>:<api_secret>"

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://<base-url>/api/resource/Customer" \
  -H "Authorization: token <api_key>:<api_secret>" \
  -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://<base-url>/api/resource/Customer?fields=[\"name\",\"customer_name\"]" \
  -H "Authorization: token <api_key>:<api_secret>"

4.2 Leer un documento

curl "https://<base-url>/api/resource/Customer/CUST-0001" \
  -H "Authorization: token <api_key>:<api_secret>"

4.3 Crear un documento

curl -X POST "https://<base-url>/api/resource/Customer" \
  -H "Authorization: token <api_key>:<api_secret>" \
  -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://<base-url>/api/resource/Customer/CUST-0001" \
  -H "Authorization: token <api_key>:<api_secret>" \
  -H "Content-Type: application/json" \
  -d '{"customer_name": "Nuevo nombre"}'

4.5 Eliminar un documento

curl -X DELETE "https://<base-url>/api/resource/Customer/CUST-0001" \
  -H "Authorization: token <api_key>:<api_secret>"

5. Parámetros de consulta útiles

Todos los parámetros se pasan en la URL (codificados cuando corresponde).

Ejemplo con filtros y paginación

curl "https://<base-url>/api/resource/Sales%20Invoice?fields=[\"name\",\"customer\",\"grand_total\"]&filters=[[\"docstatus\",\"=\",1]]&order_by=creation%20desc&limit_page_length=10" \
  -H "Authorization: token <api_key>:<api_secret>"

6. Llamadas a métodos (remote methods)

Para ejecutar lógica personalizada (métodos Python marcados como whitelisted) se usa /api/method/<ruta.al.metodo>.

• 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://<base-url>/api/method/diamoerp_base.api.get_doctypes" \
  -H "Authorization: token <api_key>:<api_secret>"

7. Errores comunes

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://<base-url>/api/method/diamoerp_base.api.get_doctypes" \
  -H "Authorization: token <api_key>:<api_secret>"

# 2) Ver los campos de un Tipos de Documento
curl "https://<base-url>/api/method/diamoerp_base.api.get_doctype_fields?doctype=Customer" \
  -H "Authorization: token <api_key>:<api_secret>"

# 3) Listar clientes con un filtro
curl "https://<base-url>/api/resource/Customer?fields=[\"name\",\"customer_name\"]&filters=[[\"customer_group\",\"=\",\"Individual\"]]" \
  -H "Authorization: token <api_key>:<api_secret>"

# 4) Crear un cliente
curl -X POST "https://<base-url>/api/resource/Customer" \
  -H "Authorization: token <api_key>:<api_secret>" \
  -H "Content-Type: application/json" \
  -d '{"customer_name": "Nuevo Cliente", "customer_group": "Individual"}'