Connecta el taller amb la resta dels teus programes
L'API REST de Programa Taller permet que la teva gestoria, el teu ERP, el gestor de flotes d'un client o la teva pròpia web llegeixin i escriguin dades del taller sense exportar fulls de càlcul. L'activa la gerència del taller, amb permisos per àrea i un registre de cada petició.
- 56endpoints a la v1
- 42esdeveniments de webhook
- 60peticions per minut i clau
curl https://el-teu-taller.example/api/v1/ping \ -H "Authorization: Bearer pt_test_9f2c…"
{
"ok": true,
"key": { "name": "CRM", "environment": "test",
"scopes": ["clients:read", "budgets:read"] },
"rate_limit": {
"per_minute": { "limit": 60, "remaining": 59 },
"per_day": { "limit": 2000, "remaining": 1999 }
},
"version": "v1"
}- RGPD: finalitat a cada clau
- Clau lligada a un sol taller
- Webhooks signats HMAC-SHA256
- Registre de peticions 90 dies
- Idempotency-Key a les escriptures
- Facturació amb la numeració i el Verifactu del programa
Per a què la fan servir els tallers
Integracions que ens demanen de debò. Si la teva no hi surt, explica-la'ns: gairebé sempre es resol amb els endpoints que ja existeixen.
Gestoria i comptabilitat
La teva assessoria descarrega cada mes les factures emeses amb el PDF i els cobraments, sense haver-te-les de demanar per correu. El teu sistema també pot facturar un pressupost aprovat i anotar el cobrament: la factura surt amb la numeració i el Verifactu del programa.
ERP del grup o del concessionari
Si el taller forma part d'un grup, sincronitza clients, vehicles i pressupostos amb el sistema central i rep un avís tan bon punt s'emet una factura.
Flotes i rènting
El taller dona a la flota una clau limitada a la seva fitxa de client: el gestor consulta en quin punt és cada cotxe i quan li caduca la ITV, demana pressupostos i cites, i rep un webhook quan entra al taller, quan és a punt i quan es lliura. Mai no veu les dades dels altres clients.
Proveïdors de recanvis
Un distribuïdor pot obrir pressupostos amb les referències de recanvi ja posades a cada partida, o llegir les partides d'una reparació per preparar la comanda.
La teva web o la teva app
La web consulta els forats lliures de l'agenda real i proposa la cita. Tu la confirmes amb un clic o, si treballes en mode reserva, entra directament en ferm.
Make, n8n o Zapier
Rep els esdeveniments per webhook i encadena el que necessitis: una tasca al CRM quan es rebutja un pressupost o una fila en un full cada vegada que entra un cobrament. I si tens el teu propi bot o IA, pot contestar els WhatsApp, SMS, xats i correus del taller.
Com funciona
De la primera clau a la integració en producció, sense tocar servidors. L'API ja és dins del teu programa.
- Crea una clau de provaA «Desenvolupadors / API», la gerència crea la clau amb un nom, la finalitat de l'ús i els permisos per àrea. La clau completa només es veu una vegada.
- Crida /pingAmb l'URL del teu taller (https://<el-seu-domini>/api/v1). Et retorna els permisos de la clau i el cupó que et queda avui.
- Desenvolupa amb dades realsLes claus pt_test_ del teu taller llegeixen les seves dades però no creen, canvien ni envien res, i no gasten quota. Per provar també escriptures, acceptacions, factures i missatges, fes servir l'entorn de proves públic.
- Passa a live i subscriu webhooksQuan tot quadra, crees una clau pt_live_ i dones d'alta l'URL que rebrà els esdeveniments. Cada canvi queda signat com a «API · nom de la clau».
curl -X POST https://el-teu-taller.example/api/v1/budgets \ -H "Authorization: Bearer pt_live_4b7e…" \ -H "Idempotency-Key: 7c1d0e52-9a3f-4f0b" \ -H "Content-Type: application/json" \ -d '{"client_id": 1204, "vehicle_id": 871, "lines": [{"description": "Canvi d’oli i filtre", "quantity": 1, "unit_price": 65, "line_type": "labor"}]}'
{
"id": 5821,
"status": "Pendiente",
"channel": "API",
"client_id": 1204,
"totals": { "base": 65, "tax": 13.65, "total": 78.65 },
"tracking_url": "…/public/seguimiento?id=…"
}Recursos disponibles
El que pot llegir i escriure una integració a la versió 1. Cada recurs té el seu permís, així cada clau veu només el que necessita.
Clients
Cerca per nom, telèfon o email, alta i edició de fitxes amb les dades de contacte.
- GET
/clients - POST
/clients - GET
/clients/{id} - PATCH
/clients/{id}
Vehicles
Cerca per matrícula o per client, alta i edició, amb quilòmetres i venciment de la ITV.
- GET
/vehicles - POST
/vehicles - GET
/vehicles/{id} - PATCH
/vehicles/{id} - +1 més
Pressupostos
Crear pressupostos amb les partides, canviar l'estat i adjuntar fotos o PDF. Acceptar-los o rebutjar-los en nom del client, amb l'evidència de qui i per quin canal.
- GET
/budgets - POST
/budgets - GET
/budgets/{id} - GET
/budgets/{id}/activity - +7 més
Factures i PDF
Factures emeses amb les línies, totals per tipus d'IVA, cobraments i el PDF original. Facturar un pressupost aprovat i anotar cobraments, amb la numeració i el Verifactu del programa.
- POST
/budgets/{id}/invoice - GET
/invoices - GET
/invoices/{id} - GET
/invoices/{id}/pdf - +1 més
Cites
Forats lliures amb la lògica de l'agenda (horaris, boxes i festius), propostes i reserves en ferm.
- GET
/appointments - POST
/appointments - GET
/appointments/availability - DELETE
/appointments/{id} - +2 més
Catàleg
Serveis i tarifes del taller, perquè la teva web o el teu configurador mostrin els mateixos preus.
- GET
/catalog/services - GET
/catalog/rates
Recanvis
Existències, referències i preu de venda de l'inventari. El cost i el proveïdor no surten mai per l'API.
- GET
/stock - GET
/stock/{id}
Comunicacions
Registre d'emails, SMS, WhatsApp i trucades. Amb el pla Business, enviament d'email i SMS.
- GET
/communications - GET
/logs - POST
/email - POST
/sms
Converses
WhatsApp, SMS, xat i correu en una llista, com la Safata d'entrada del programa: llegeix el fil i respon com el taller.
- GET
/conversations - GET
/conversations/{key}/messages - POST
/conversations/{key}/messages - GET
/messages/templates
Assistent extern
Tria en quins canals contesta el teu bot o IA en lloc de l'assistent del programa, amb reserva automàtica si no respon en 10 minuts.
- GET
/settings/assistant - PUT
/settings/assistant
Webhooks
Subscripcions per esdeveniment, amb signatura HMAC-SHA256, reintents i un enviament de prova quan vulguis.
Alguns esdeveniments
Entorn de proves
Instància pública amb dades fictícies per provar escriptures, acceptacions, factures i missatges sense risc, amb claus pt_test_ de 30 dies.
- POST
/sandbox/keys - POST
/sandbox/simulate/message
Pensada per a integracions que no fallen
Els detalls que solen donar guerra en una integració, resolts de sèrie.
Claus que crea la gerència
El responsable del taller crea cada clau amb un nom, la finalitat de l'ús i els permisos. La clau completa es mostra una sola vegada; després només se'n veu el prefix.
Permisos per àrea
Clients, vehicles, pressupostos, factures, cites, catàleg i comunicacions, amb lectura i, on té sentit, escriptura. La clau de la gestoria no necessita veure l'agenda.
Prova i producció
Les claus pt_test_ del teu taller llegeixen dades reals però no poden crear ni canviar res, i no gasten quota. Per provar escriptures, acceptacions, factures i missatges hi ha un entorn de proves públic amb dades fictícies. Quan la integració funciona, se'n crea una pt_live_.
Webhooks signats
El programa avisa la teva URL quan passa alguna cosa: més de 40 esdeveniments, de «pressupost acceptat» a «vehicle a punt». Cada enviament va signat amb HMAC-SHA256 i es reintenta fins a 5 vegades si el teu servidor no respon.
Límits a la vista
60 peticions per minut per clau (ampliable a 600) més la quota diària del pla. Cada resposta porta X-RateLimit-Remaining i, si te'n passes, un 429 amb Retry-After.
Escriptures sense duplicats
Tot POST porta Idempotency-Key: si el teu sistema reintenta la mateixa operació per un tall de xarxa, no apareix un segon client ni un segon pressupost.
Seguretat i RGPD
Una integració no hauria d'obrir més portes de les necessàries. Així està plantejada:
Cada clau és d'un sol taller
Només se'n guarda l'empremta, lligada a la instància del taller: no serveix en cap altre i ningú no la pot recuperar, tampoc nosaltres.
Finalitat obligatòria
En crear la clau s'ha d'escriure per a què es tractaran les dades, tal com demana el RGPD. Queda al costat de la clau i al registre.
El que és intern no surt
Costos, marges, notes internes i pressupostos d'ús intern no apareixen en cap resposta. Del personal del taller només se'n veu l'id i el nom.
Registre de cada petició
Quina clau, des de quina IP, a quin endpoint i amb quin resultat. Es guarda 90 dies i es consulta des de la mateixa secció.
IPs permeses i caducitat
Pots limitar una clau a les IPs del proveïdor que la fa servir i posar-li data de fi. Revocar-la té efecte immediat.
L'acceptació deixa rastre
Acceptar o rebutjar un pressupost per API exigeix un permís a part (budgets:accept) i l'evidència de qui accepta i per quin canal. Queda a l'historial com a «Acceptat per API en nom del client», amb el nom de la clau.
Plans de l'API
Van a part del pla del programa. Comences amb l'Inclòs i només puges si necessites escriure dades, rebre webhooks o més volum.
- 1 clau live
- Només lectura, totes les àrees
- 2.000 peticions al dia
- En arribar a la quota, pausa fins a les 00:00 UTC
- 5 claus live
- Lectura i escriptura
- Webhooks
- Acceptar pressupostos i facturar
- 20.000 peticions al dia
- Claus il·limitades
- Tot el que inclou Developer
- Missatges per API (email, SMS, WhatsApp i xat) i assistent extern als teus canals (els missatges es paguen a part)
- 100.000 peticions al dia
- Suport per email
- Per a empreses que connecten el seu producte amb diversos tallers
- Quota, claus i permisos a mida
- Preu per volum
Preus sense IVA. Les claus de prova no tenen cost ni compten per a la quota, igual que les proves des del tauler. Si en un mes Developer o Business superen la quota (quota diària × dies del mes), l'excés es cobra a 1 € per cada 1.000 peticions.
Preguntes freqüents
He de pagar per fer servir l'API?
No. El pla Inclòs ve amb qualsevol pla del programa: una clau de només lectura i 2.000 peticions al dia. Només pagues si necessites escriure dades, webhooks o més volum.
On trobo l'URL de l'API del meu taller?
A la secció «Desarrolladores / API» del programa. Cada taller treballa al seu propi domini, així que l'URL base té la forma https://<el-seu-domini>/api/v1.
Es poden emetre factures per l'API?
Sí, amb un permís a part (invoices:write), des del pla Developer. L'API fa servir la facturació del mateix programa: sèrie, numeració correlativa, registre Verifactu i assentament comptable. Es factura un pressupost aprovat, mai es crea una factura solta, i les rectificatives es fan des del programa.
Puc donar accés a una flota sense que vegi els meus altres clients?
Sí, amb una clau de client. En crear la clau a «Desenvolupadors / API» marca «Limitar a un client» i tria la seva fitxa: aquesta clau només veu i toca els vehicles, pressupostos, factures, cites i converses d'aquest client, i els seus webhooks només reben els seus avisos. Un id d'un altre client respon 404 i el que és de tot el taller (crear clients, facturar, enviar SMS o correus solts…) respon 403. El client es fixa en crear-la i no es canvia després.
I si la integració s'equivoca?
Amb una clau de prova no pot canviar res. Amb una live, cada canvi queda a l'historial del client o del pressupost com a «API · nom de la clau», i la clau es revoca a l'instant.
Hi ha SDK o col·lecció de Postman?
El fitxer OpenAPI 3.1 serveix per generar un client en qualsevol llenguatge. Dins del programa tens a més la col·lecció de Postman i un tauler per provar cada endpoint amb la teva clau.
Desenvolupo un programari per a tallers, em puc connectar a molts?
Sí, amb el pla Partner: cada taller crea la seva clau per al teu producte i acordem el preu per taller segons el volum. Escriu-nos i ho mirem.
Què passa si supero el límit de peticions?
Cada clau admet 60 peticions per minut. Si te'n passes, l'API respon 429 amb la capçalera Retry-After i el teu sistema només ha d'esperar aquests segons. Al pla Inclòs, quan s'esgota el cupó diari es pausa fins a les 00:00 UTC; a Developer i Business se segueix atenent i l'excés es cobra a 1 € per cada 1.000 peticions.
L'API pot acceptar un pressupost en nom del client?
Sí, amb el permís budgets:accept (pla Developer o superior) i només si indiques l'evidència: qui accepta i per quin canal (telèfon, en persona, correu, WhatsApp…). Passa per la mateixa regla d'acceptació del programa i a l'historial queda «Acceptat per API en nom del client» amb el nom de la clau. El client continua podent acceptar des del seu enllaç de seguiment; l'API no dona aquest enllaç.
Hi ha un entorn de proves?
Sí, públic i gratuït: https://demo.programa-taller.es/desarrolladores-sandbox. Et dona una clau pt_test_ de 30 dies amb escriptura habilitada sobre dades fictícies que es restauren cada 2 hores. Res no surt de debò (els enviaments es registren com a simulats) i els webhooks s'emeten igualment, així proves el cicle complet. Les teves claus i webhooks es conserven entre reinicis.
Pot el meu propi bot contestar els clients del taller?
Sí, des del pla Business. Actives l'«assistent extern» als canals que vulguis (WhatsApp, SMS, xat web o correu): cada missatge del client t'arriba pel webhook message.received i respons per l'API. Si no contestes en 10 minuts, o la teva clau o el teu webhook deixen de funcionar, l'assistent del programa respon per tu.
Tens una integració al cap?
Explica'ns què vols connectar i et diem quins endpoints fer servir i quin pla t'encaixa.