Comandes per correu electrònic que entren soles a Holded

Si vens a altres empreses, segurament algú del teu equip perd mig matí fent sempre el mateix: obrir el correu, llegir la comanda del client (un PDF, un Excel o tres línies escrites des del mòbil), buscar cada referència i picar-la a Holded. És una feina que no aporta res i on un 8 per un 3 acaba en un enviament equivocat.

La bona notícia és que avui Holded té una API pública força completa per a les comandes de venda. La no tan bona és que “connectar el correu amb Holded” no és un botó: cal prendre decisions sobre clients, referències, preus i revisió. En aquest article t’explico què ofereix Holded de debò (amb enllaços a la seva documentació), quines dreceres hi ha sense programar i com seria un flux realista de principi a fi.

El que ja porta Holded (i el que no)

Abans de pensar en un desenvolupament a mida, val la pena saber què hi ha de sèrie:

• Safata d’entrada (Inbox). Holded escaneja els documents que hi puges i n’extreu les dades, però segons la seva documentació els converteix en documents de compra: factura de proveïdor, abonament, comanda a proveïdor o rebut. El tipus el decideix l’escaneig, no tu (referència de l’API). És a dir, serveix per a les factures que t’envien els proveïdors, no per a les comandes que t’envien els clients.
• Zapier. La integració permet l’acció “crear document” (entre els tipus hi ha la comanda de venda) i les de “cercar contacte” i “cercar o crear contacte”. La mateixa Holded avisa de dues coses: el contacte ha de coincidir amb el codi de contacte, que la majoria d’aplicacions no envien, de manera que Holded pot crear un contacte nou cada vegada si no hi afegeixes un pas de cerca; i els fluxos de diversos passos necessiten un pla de pagament de Zapier (pàgina de la integració).
• Make. Aplicació verificada que manté Make, amb 38 mòduls (30 accions i 8 cerques). Permet crear documents de venda (la pàgina posa les factures com a exemple, així que convé comprovar que també cobreix les comandes de venda) i cercar si un contacte ja existeix abans de crear-lo (pàgina de la integració).
• Servidor MCP. Holded publica un servidor MCP a https://mcp.holded.com/mcp per connectar assistents d’IA al teu compte amb OAuth 2.1 (documentació MCP). Les eines que escriuen dades estan marcades com a tals perquè l’assistent demani confirmació abans de cada crida (eines). Està pensat perquè una persona pregunti i actuï conversant, no per processar comandes tot sol a les tres de la matinada.

Cap d’aquestes peces no llegeix el correu del client ni entén que “10 caixes del de sempre” vol dir la referència 4471. Aquesta part, la d’interpretar la comanda, l’has de posar tu, amb una eina sense codi amb IA o amb un desenvolupament a mida.

Requisits abans de començar

• Pla de pagament. Segons el centre d’ajuda de Holded, l’API està disponible en tots els plans de pagament i no en el gratuït (centre d’ajuda).
• Inventari activat. L’ajuda de Holded sobre comandes indica que cal activar Inventari des de la Holded Store per poder fer servir les comandes (centre d’ajuda). I el permís de l’API per a les comandes de venda també depèn d’inventory.
• Una clau d’API amb permisos limitats. Es genera a Configuració, Desenvolupadors, Credencials (el token només es mostra un cop). L’API v2 fa servir l’autenticació Authorization: Bearer i cada clau té permisos propis, que no hereten els de cap usuari; per crear comandes cal inventory:sales-orders.write (autenticació, centre d’ajuda). Dona a aquesta clau només el que necessita.
• Compte amb els tutorials antics. Molts exemples d’internet fan servir l’API v1, que té una clau pròpia. Holded indica que la clau v1 continua disponible “fins a nou avís” i que avisarà abans de retirar-la, però la documentació actual està escrita sobre la v2, amb la base https://api.holded.com/api/v2/ (centre d’ajuda, primers passos).

El límit que ningú no mira: crides al mes

Aquesta és la dada que més sorprèn. A més d’un límit per minut, l’API de Holded té una quota mensual de crides segons el teu pla, compartida per totes les claus del compte (límits de l’API):

Pla	Peticions per minut	Crides al mes
Plus	60	500
Basic	60	2.000
Standard	120	7.500
Advanced	120	30.000
Premium	600	100.000 (més l’excés, que es factura)

Als plans inferiors, quan arribes al topall mensual l’API respon amb un error 429. A Premium no hi ha tall: l’excés es factura. Tingues en compte que el centre d’ajuda parla de 100 peticions per minut per clau, així que les xifres no coincideixen del tot entre fonts. Pots comprovar el consum del teu compte a Configuració, Desenvolupadors, Ús de l’API, o amb la crida que retorna l’ús del mes en curs (/api/v2/usage/{type}).

Exemple amb supòsits (no és un cas real): 20 comandes per dia laborable, 21 dies al mes i tres crides per comanda (cercar el client, crear la comanda i adjuntar el correu original). Són 1.260 crides. Si a més actualitzes cada dia laborable un catàleg de 8.000 productes a 200 per pàgina (el màxim que permet el llistat), són 40 crides diàries, unes 840 més al mes. Total aproximat: 2.100. No hi cap al pla Plus, queda just per sobre del pla Basic i entra amb marge al pla Standard. Per això el disseny importa: guardar una còpia local del catàleg i actualitzar-la amb webhooks en lloc de tornar-la a llegir sencera ho canvia tot. La mateixa Holded recomana desar a la memòria cau les dades de referència i fer servir webhooks per no gastar el pressupost de crides.

Un flux realista, del correu a la comanda

1. Una bústia només per a comandes

El més net és una adreça dedicada (per exemple, comandes@latevaempresa.cat) o una regla que hi reenviï els correus dels clients coneguts. El sistema llegeix aquesta bústia a través de l’API de Gmail o de Microsoft 365, mai el correu general de ningú.

2. Llegir la comanda, arribi com arribi

Un model d’IA extreu del cos del missatge i dels adjunts (PDF, Excel, foto) una estructura fixa: client, referències, quantitats, data de lliurament desitjada i observacions. La IA llegeix bé, però no coneix el teu negoci: per això no escriu directament a Holded.

3. Contrastar-ho amb les teves dades

Aquesta és la part que porta més feina, i convé saber què fa i què no fa l’API:

• Client. La cerca de contactes de l’API només funciona per nom i per prefix (com la funció d’autocompleció) (cercar contactes). Per identificar el client pel correu del remitent o pel NIF, el més raonable és tenir una còpia local dels contactes.
• Productes. El llistat de productes només permet filtrar per nom (llistar productes). Si els teus clients demanen amb el seu propi codi, necessites una taula d’equivalències entre el seu codi i el teu.
• Preus. Aquest detall és clau: quan crees una comanda, Holded desa el preu i els impostos de cada línia tal com els envies; enllaçar el producte no fa que els agafi de la fitxa (crear una comanda de venda). La teva integració ha d’aplicar la tarifa correcta d’aquell client. Si no hi poses els impostos, s’aplica l’impost per defecte del contacte.

Tot el que no quadri (un client nou, una referència desconeguda, una quantitat estranya) va a una cua de revisió en lloc d’entrar a cegues.

4. Crear la comanda a Holded

Amb les dades validades, n’hi ha prou amb una crida a POST /api/v2/sales-orders amb el contact_id, les línies a items i, si cal, el warehouse_id (és opcional). La data de lliurament que vol el client té el seu lloc a due_date, que Holded descriu com la data de lliurament prevista. Per a la numeració, fes servir number_line_id (la sèrie de Holded) i no t’inventis números: la documentació avisa que un número manual amb el format d’una sèrie activa acaba trencant la correlativitat (i que, si envies number, s’ignora number_line_id). Després, adjunta el correu o el PDF original a la comanda (adjuntar un fitxer) perquè qualsevol pugui comprovar d’on ha sortit (màxim 10 MB per fitxer).

5. Revisió humana on aporta valor

L’API té una crida a part per aprovar la comanda, que en fixa la data d’aprovació (aprovar una comanda). Al principi té sentit que una persona revisi i aprovi; quan el sistema porti setmanes sense errors amb un client, també es pot automatitzar aquest pas per a aquell client.

6. El que ve després

Holded emet webhooks signats quan es creen, es modifiquen o s’esborren comandes de venda (salesorder.create, salesorder.update, salesorder.delete), amb un identificador únic que serveix per no processar dues vegades el mateix esdeveniment (webhooks). Hi ha esdeveniments equivalents per a productes, contactes i estoc, útils per mantenir al dia la còpia local. Amb això pots avisar el magatzem o confirmar la comanda al client per correu. I després la comanda es pot convertir en un altre document, com ara un albarà (és l’exemple de la mateixa documentació), amb la crida de conversió; no s’admeten totes les combinacions de documents i depèn de la configuració del teu compte (convertir un document).

Zapier, Make o a mida?

• Zapier o Make encaixen si les comandes arriben sempre amb el mateix format, de pocs clients i amb referències que coincideixen amb les teves. Pots muntar el flux tu mateix i el pot mantenir algú del teu equip.
• A mida encaixa quan cada client demana a la seva manera, hi ha tarifes per client, un catàleg gran o necessites una cua d’excepcions com cal. En aquests casos, l’aparellament de productes és el que decideix si l’automatització funciona o no.

Si dubtes, comença per mesurar: quantes comandes al dia, de quants clients i en quins formats. Això és just el que es mira en una diagnosi de processos.