Pedidos por email que se cargan solos en Holded

Si vendes a otras empresas, seguramente media mañana de alguien se va en lo mismo: abrir el correo, leer el pedido del cliente (un PDF, un Excel, o tres líneas escritas desde el móvil), buscar cada referencia y teclearlo en Holded. Es trabajo que no aporta nada y donde un 8 por un 3 se convierte en un envío equivocado.

La buena noticia es que Holded tiene hoy una API pública bastante completa para pedidos de venta. La menos buena es que “conectar el email con Holded” no es un botón: hay decisiones que tomar sobre clientes, referencias, precios y revisión. En este artículo te cuento qué ofrece Holded de verdad (con enlaces a su documentación), qué atajos existen sin programar y cómo sería un flujo realista de punta a punta.

Lo que ya trae Holded (y lo que no)

Antes de pensar en desarrollo a medida, conviene saber qué hay de serie:

• Bandeja de entrada (Inbox). Holded escanea documentos que subes y extrae sus datos, pero según su documentación los convierte en documentos de compra: factura de proveedor, abono, pedido a proveedor o recibo. El tipo lo decide el escaneo, no tú (referencia de la API). Es decir, sirve para las facturas que te mandan tus proveedores, no para los pedidos que te mandan tus clientes.
• Zapier. La integración permite la acción “crear documento” (entre sus tipos figura el pedido de venta) y las de “buscar contacto” y “buscar o crear contacto”. La propia Holded avisa de dos cosas: el contacto debe coincidir con el código de contacto, que la mayoría de apps no envían, así que Holded puede crear un contacto nuevo cada vez si no añades un paso de búsqueda; y los flujos de varios pasos necesitan un plan de pago de Zapier (página de la integración).
• Make. App verificada que mantiene Make, con 38 módulos (30 acciones y 8 búsquedas). Permite crear documentos de venta (la página pone las facturas como ejemplo, así que conviene comprobar que cubre pedidos de venta) y buscar si un contacto ya existe antes de crearlo (página de la integración).
• Servidor MCP. Holded publica un servidor MCP en https://mcp.holded.com/mcp para conectar asistentes de IA a tu cuenta con OAuth 2.1 (documentación MCP). Las herramientas que escriben datos están marcadas como tales para que el asistente pida confirmación antes de cada llamada (herramientas). Está pensado para que una persona pregunte y actúe conversando, no para procesar pedidos solo a las tres de la mañana.

Ninguna de estas piezas lee el email del cliente y entiende que “10 cajas de lo de siempre” es la referencia 4471. Esa parte, la de interpretar el pedido, la tienes que poner tú, con una herramienta no-code con IA o con un desarrollo a medida.

Requisitos antes de empezar

• Plan de pago. Según el centro de ayuda de Holded, la API está disponible en todos los planes de pago y no en el gratuito (centro de ayuda).
• Inventario activado. La ayuda de Holded sobre pedidos indica que hay que activar Inventario desde la Holded Store para usar pedidos (centro de ayuda). Y el permiso de la API para pedidos de venta también cuelga de inventory.
• Una clave de API con permisos acotados. Se genera en Configuración, Desarrolladores, Credenciales (el token se muestra una sola vez). La API v2 usa autenticación Authorization: Bearer y cada clave tiene permisos propios, que no heredan los de ningún usuario; crear pedidos requiere inventory:sales-orders.write (autenticación, centro de ayuda). Dale a esa clave solo lo que necesita.
• Ojo con los tutoriales antiguos. Muchos ejemplos en internet usan la API v1, que tiene su propia clave. Holded indica que la clave v1 sigue disponible “hasta nuevo aviso” y que avisará antes de retirarla, pero la documentación actual está escrita sobre la v2, con base https://api.holded.com/api/v2/ (centro de ayuda, primeros pasos).

El límite que nadie mira: llamadas al mes

Aquí está el dato que más sorprende. Además de un límite por minuto, la API de Holded tiene una cuota mensual de llamadas según tu plan, compartida por todas las claves de la cuenta (límites de la API):

Plan	Peticiones por minuto	Llamadas al mes
Plus	60	500
Basic	60	2.000
Standard	120	7.500
Advanced	120	30.000
Premium	600	100.000 (más exceso facturado)

En los planes inferiores, al alcanzar el tope mensual la API responde con error 429. En Premium no hay corte: el exceso se factura. Ten en cuenta que el centro de ayuda habla de 100 peticiones por minuto por clave, así que las cifras no coinciden del todo entre fuentes. Comprueba el consumo de tu cuenta en Configuración, Desarrolladores, Uso de la API, o con el endpoint de uso del mes en curso (/api/v2/usage/{type}).

Ejemplo con supuestos (no es un caso real): 20 pedidos por día laborable, 21 días al mes, y tres llamadas por pedido (buscar cliente, crear pedido, adjuntar el email original). Son 1.260 llamadas. Si además refrescas cada día laborable un catálogo de 8.000 productos a 200 por página (el máximo que permite el listado), son 40 llamadas diarias, unas 840 más al mes. Total aproximado: 2.100. No cabe en Plus, se queda justo por encima de Basic y entra con holgura en Standard. Por eso el diseño importa: guardar una copia local del catálogo y actualizarla con webhooks en lugar de releerla entera cambia la factura: la propia Holded recomienda cachear los datos de referencia y usar webhooks para no gastar presupuesto de llamadas.

Un flujo realista, del email al pedido

1. Un buzón solo para pedidos

Lo más limpio es una dirección dedicada (por ejemplo, pedidos@tuempresa.es) o una regla que reenvíe allí los correos de clientes conocidos. El sistema lee ese buzón a través de la API de Gmail o de Microsoft 365, nunca el correo general de nadie.

2. Leer el pedido, venga como venga

Un modelo de IA extrae del cuerpo y de los adjuntos (PDF, Excel, foto) una estructura fija: cliente, referencias, cantidades, fecha de entrega deseada y observaciones. La IA lee bien, pero no sabe tu negocio: por eso no escribe directamente en Holded.

3. Validar contra tus datos

Aquí está la parte que más trabajo lleva, y conviene saber qué hace y qué no hace la API:

• Cliente. La búsqueda de contactos de la API es solo por nombre y por prefijo (tipo autocompletar) (buscar contactos). Para emparejar por email del remitente o por NIF, lo razonable es tener una copia local de los contactos.
• Productos. El listado de productos solo permite filtrar por nombre (listar productos). Si tus clientes piden con su propio código, necesitas una tabla de equivalencias entre su código y el tuyo.
• Precios. Este detalle es clave: al crear un pedido, Holded guarda el precio y los impuestos de cada línea tal como se los envías; enlazar el producto no hace que los lea de la ficha (crear pedido de venta). Tu integración tiene que aplicar la tarifa correcta de ese cliente. Si omites los impuestos, se aplica el impuesto por defecto del contacto.

Todo lo que no cuadre (cliente nuevo, referencia desconocida, cantidad rara) va a una cola de revisión en lugar de entrar a ciegas.

4. Crear el pedido en Holded

Con los datos validados, una llamada a POST /api/v2/sales-orders con el contact_id, las líneas en items y, si lo necesitas, el warehouse_id (es opcional). La fecha de entrega deseada del cliente tiene su sitio en due_date, que Holded describe como fecha de entrega prevista. Para la numeración, usa number_line_id (la serie de Holded) y no inventes números: la documentación avisa de que un número manual con el formato de una serie activa acaba rompiendo la correlatividad (y que si envías number, ignora number_line_id). Después, adjunta el email o PDF original al pedido (adjuntar archivo) para que cualquiera pueda comprobar de dónde salió (máximo 10 MB por archivo).

5. Revisión humana donde aporta

La API tiene una llamada aparte para aprobar el pedido, que fija su fecha de aprobación (aprobar pedido). Al principio tiene sentido que una persona revise y apruebe; cuando el sistema lleve semanas sin fallos con un cliente, se puede automatizar también ese paso para él.

6. Lo que pasa después

Holded emite webhooks firmados al crear, modificar o borrar pedidos de venta (salesorder.create, salesorder.update, salesorder.delete), con un identificador único que sirve para no procesar dos veces el mismo evento (webhooks). Hay eventos equivalentes para productos, contactos y stock, útiles para mantener la copia local. Con eso puedes avisar al almacén o confirmar al cliente por email. Y el pedido se puede convertir después en otro documento, como un albarán (es el ejemplo de la propia documentación), con el endpoint de conversión; no todas las parejas de documentos están soportadas y depende de la configuración de tu cuenta (convertir documento).

¿Zapier, Make o a medida?

• Zapier o Make encajan si los pedidos llegan siempre con el mismo formato, de pocos clientes y con referencias que coinciden con las tuyas. Puedes montar el flujo tú mismo y lo mantiene alguien de tu equipo.
• A medida encaja cuando cada cliente pide a su manera, hay tarifas por cliente, catálogo grande o necesitas una cola de excepciones decente. En esos casos, el emparejamiento de productos es lo que decide si la automatización funciona.

Si dudas, empieza por medir: cuántos pedidos al día, de cuántos clientes, en qué formatos. Eso es justo lo que se mira en un diagnóstico de procesos.