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ó.
- 38endpoints a la v1
- 27esdeveniments 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
- Factures només des del programa (Verifactu)
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. Les factures es llegeixen; emetre-les continua sent cosa del programa, perquè Verifactu quadri.
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 gestor de la flota consulta en quin punt és cada cotxe i quan li caduca la ITV, i rep un webhook quan entra al taller, quan és a punt i quan es lliura.
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.
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_ llegeixen les dades del taller però no creen, canvien ni envien res, i no gasten cupó. Pots equivocar-te sense conseqüències.
- 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}
Pressupostos
Crear pressupostos amb les partides, canviar l'estat i adjuntar fotos o PDF. Acceptar, només el client des del seu enllaç.
- GET
/budgets - POST
/budgets - GET
/budgets/{id} - POST
/budgets/{id}/lines - +4 més
Factures i PDF
Factures emeses amb les línies, totals per tipus d'IVA, cobraments i el PDF original. Només lectura.
- GET
/invoices - GET
/invoices/{id} - GET
/invoices/{id}/pdf
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}
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
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
Webhooks
Subscripcions per esdeveniment, amb signatura HMAC-SHA256, reintents i un enviament de prova quan vulguis.
Alguns esdeveniments
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_ llegeixen dades reals però no poden crear ni canviar res, i no gasten quota. Quan la integració funciona, se'n crea una pt_live_.
Webhooks signats
El programa avisa la teva URL quan passa alguna cosa: 27 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.
La signatura és del client
L'acceptació d'un pressupost la dona sempre el client des del seu enllaç signat; l'API no pot aprovar en nom seu.
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
- 20.000 peticions al dia
- Claus il·limitades
- Tot el que inclou Developer
- Enviament d'email i SMS per API (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?
No. Les factures es consulten amb el PDF i els cobraments, però s'emeten des del programa perquè la numeració i el registre Verifactu siguin correctes.
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?
No. L'acceptació la signa sempre el client des del seu enllaç de seguiment. Si una integració intenta passar un pressupost a «Aprobado», rep un 403 amb l'enllaç que cal fer-li arribar.
Tens una integració al cap?
Explica'ns què vols connectar i et diem quins endpoints fer servir i quin pla t'encaixa.