Conecta el taller con el resto de tus programas
La API REST de Programa Taller permite que tu gestoría, tu ERP, el gestor de flotas de un cliente o tu propia web lean y escriban datos del taller sin exportar hojas de cálculo. La activa la gerencia del taller, con permisos por área y un registro de cada petición.
- 56endpoints en la v1
- 42eventos de webhook
- 60peticiones por minuto y clave
curl https://tu-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: finalidad en cada clave
- Clave atada a un solo taller
- Webhooks firmados HMAC-SHA256
- Registro de peticiones 90 días
- Idempotency-Key en escrituras
- Facturación con la numeración y el Verifactu del programa
Para qué la usan los talleres
Integraciones que nos piden de verdad. Si la tuya no aparece, cuéntanosla: casi siempre se resuelve con los endpoints que ya existen.
Gestoría y contabilidad
Tu asesoría descarga cada mes las facturas emitidas con su PDF y los cobros, sin pedirte nada por email. Tu sistema también puede facturar un presupuesto aprobado y anotar el cobro: la factura sale con la numeración y el Verifactu del programa.
ERP del grupo o concesionario
Si el taller forma parte de un grupo, sincroniza clientes, vehículos y presupuestos con el sistema central y recibe un aviso en cuanto se emite una factura.
Flotas y renting
El taller le da a la flota una clave limitada a su ficha de cliente: el gestor consulta en qué punto está cada coche y cuándo le vence la ITV, pide presupuestos y citas, y recibe un webhook cuando entra en el taller, cuando está listo y cuando se entrega. Nunca ve los datos de los demás clientes.
Proveedores de recambios
Un distribuidor puede abrir presupuestos con las referencias de recambio ya puestas en cada partida, o leer las partidas de una reparación para preparar el pedido.
Tu web o tu app
Tu web consulta los huecos libres de la agenda real y propone la cita. Tú la confirmas con un clic o, si trabajas en modo reserva, entra directamente en firme.
Make, n8n o Zapier
Recibe los eventos por webhook y encadena lo que necesites: una tarea en tu CRM cuando se rechaza un presupuesto o una fila en una hoja cada vez que entra un cobro. Y si tienes tu propio bot o IA, puede contestar los WhatsApp, SMS, chats y emails del taller.
Cómo funciona
De la primera clave a la integración en producción, sin tocar servidores. La API ya está en tu programa.
- Crea una clave de pruebaEn «Desarrolladores / API», la gerencia crea la clave con un nombre, la finalidad del uso y los permisos por área. La clave completa se ve una sola vez.
- Llama a /pingCon la URL de tu taller (https://<su-dominio>/api/v1). Te devuelve los permisos de la clave y el cupo que te queda hoy.
- Desarrolla con datos realesLas claves pt_test_ de tu taller leen sus datos pero no crean, cambian ni envían nada, y no gastan cupo. Para probar también escrituras, aceptaciones, facturas y mensajes, usa el entorno de pruebas público.
- Pasa a live y suscribe webhooksCuando todo cuadra, creas una clave pt_live_ y das de alta la URL que recibirá los eventos. Cada cambio queda firmado como «API · nombre de la clave».
curl -X POST https://tu-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": "Cambio de aceite y filtro", "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
Lo que puede leer y escribir una integración en la versión 1. Cada recurso tiene su permiso, así que cada clave ve solo lo que necesita.
Clientes
Búsqueda por nombre, teléfono o email, alta y edición de fichas con sus datos de contacto.
- GET
/clients - POST
/clients - GET
/clients/{id} - PATCH
/clients/{id}
Vehículos
Búsqueda por matrícula o por cliente, alta y edición, con kilómetros y vencimiento de la ITV.
- GET
/vehicles - POST
/vehicles - GET
/vehicles/{id} - PATCH
/vehicles/{id} - +1 más
Presupuestos
Crear presupuestos con sus partidas, cambiar el estado y adjuntar fotos o PDF. Aceptarlos o rechazarlos en nombre del cliente, con la evidencia de quién y por qué canal.
- GET
/budgets - POST
/budgets - GET
/budgets/{id} - GET
/budgets/{id}/activity - +7 más
Facturas y PDF
Facturas emitidas con sus líneas, totales por tipo de IVA, cobros y el PDF original. Facturar un presupuesto aprobado y anotar cobros, con la numeración y el Verifactu del programa.
- POST
/budgets/{id}/invoice - GET
/invoices - GET
/invoices/{id} - GET
/invoices/{id}/pdf - +1 más
Citas
Huecos libres con la lógica de la agenda (horarios, boxes y festivos), propuestas y reservas en firme.
- GET
/appointments - POST
/appointments - GET
/appointments/availability - DELETE
/appointments/{id} - +2 más
Catálogo
Servicios y tarifas del taller, para que tu web o tu configurador enseñen los mismos precios.
- GET
/catalog/services - GET
/catalog/rates
Recambios
Existencias, referencias y precio de venta del inventario. El coste y el proveedor nunca salen por la API.
- GET
/stock - GET
/stock/{id}
Comunicaciones
Registro de emails, SMS, WhatsApp y llamadas. Con el plan Business, envío de email y SMS.
- GET
/communications - GET
/logs - POST
/email - POST
/sms
Conversaciones
WhatsApp, SMS, chat y email en una lista, como la Bandeja del programa: lee el hilo y responde como el taller.
- GET
/conversations - GET
/conversations/{key}/messages - POST
/conversations/{key}/messages - GET
/messages/templates
Asistente externo
Elige en qué canales contesta tu bot o IA en lugar del asistente del programa, con respaldo automático si no responde en 10 minutos.
- GET
/settings/assistant - PUT
/settings/assistant
Webhooks
Suscripciones por evento, con firma HMAC-SHA256, reintentos y una entrega de prueba a demanda.
Algunos eventos
Entorno de pruebas
Instancia pública con datos ficticios para probar escrituras, aceptaciones, facturas y mensajes sin riesgo, con claves pt_test_ de 30 días.
- POST
/sandbox/keys - POST
/sandbox/simulate/message
Pensada para integraciones que no fallan
Los detalles que suelen dar guerra en una integración, resueltos de serie.
Claves que crea la gerencia
El responsable del taller crea cada clave con un nombre, la finalidad del uso y sus permisos. La clave completa se enseña una sola vez; después solo se ve su prefijo.
Permisos por área
Clientes, vehículos, presupuestos, facturas, citas, catálogo y comunicaciones, con lectura y, donde tiene sentido, escritura. La clave de la gestoría no necesita ver la agenda.
Prueba y producción
Las claves pt_test_ de tu taller leen datos reales pero no pueden crear ni cambiar nada, y no gastan cupo. Para probar escrituras, aceptaciones, facturas y mensajes hay un entorno de pruebas público con datos ficticios. Cuando la integración funciona, se crea una pt_live_.
Webhooks firmados
El programa avisa a tu URL cuando pasa algo: más de 40 eventos, de «presupuesto aceptado» a «vehículo listo». Cada envío va firmado con HMAC-SHA256 y se reintenta hasta 5 veces si tu servidor no contesta.
Límites a la vista
60 peticiones por minuto por clave (ampliable a 600) más el cupo diario del plan. Cada respuesta trae X-RateLimit-Remaining y, si te pasas, un 429 con Retry-After.
Escrituras sin duplicados
Todo POST lleva Idempotency-Key: si tu sistema reintenta la misma operación por un corte de red, no aparece un segundo cliente ni un segundo presupuesto.
Seguridad y RGPD
Una integración no debería abrir más puertas de las necesarias. Así está planteada:
Cada clave es de un solo taller
Solo se guarda su huella, atada a la instancia del taller: no sirve en ningún otro y nadie puede recuperarla, tampoco nosotros.
Finalidad obligatoria
Al crear la clave hay que escribir para qué se van a tratar los datos, como pide el RGPD. Queda junto a la clave y en el registro.
Lo interno no sale
Costes, márgenes, notas internas y presupuestos de uso interno no aparecen en ninguna respuesta. Del personal del taller solo se ve el id y el nombre.
Registro de cada petición
Qué clave, desde qué IP, a qué endpoint y con qué resultado. Se guarda 90 días y se consulta desde la misma sección.
IPs permitidas y caducidad
Puedes limitar una clave a las IPs del proveedor que la usa y ponerle fecha de fin. Revocarla tiene efecto inmediato.
La aceptación deja rastro
Aceptar o rechazar un presupuesto por API exige un permiso aparte (budgets:accept) y la evidencia de quién acepta y por qué canal. Queda en el historial como «Aceptado por API en nombre del cliente», con el nombre de la clave.
Planes de la API
Van aparte del plan del programa. Empiezas con el Incluido y subes solo si necesitas escribir datos, recibir webhooks o más volumen.
- 1 clave live
- Solo lectura, todas las áreas
- 2.000 peticiones al día
- Al llegar al cupo, pausa hasta las 00:00 UTC
- 5 claves live
- Lectura y escritura
- Webhooks
- Aceptar presupuestos y facturar
- 20.000 peticiones al día
- Claves ilimitadas
- Todo lo de Developer
- Mensajes por API (email, SMS, WhatsApp y chat) y asistente externo en tus canales (los mensajes se pagan aparte)
- 100.000 peticiones al día
- Soporte por email
- Para empresas que conectan su producto con varios talleres
- Cupo, claves y permisos a medida
- Precio por volumen
Precios sin IVA. Las claves de prueba no tienen coste ni cuentan para el cupo, igual que las pruebas desde el panel. Si en un mes Developer o Business superan su cupo (cupo diario × días del mes), el exceso se cobra a 1 € por cada 1.000 peticiones.
Preguntas frecuentes
¿Tengo que pagar para usar la API?
No. El plan Incluido viene con cualquier plan del programa: una clave de solo lectura y 2.000 peticiones al día. Solo pagas si necesitas escribir datos, webhooks o más volumen.
¿Dónde encuentro la URL de la API de mi taller?
En la sección «Desarrolladores / API» del programa. Cada taller trabaja en su propio dominio, así que la URL base tiene la forma https://<su-dominio>/api/v1.
¿Se pueden emitir facturas por la API?
Sí, con un permiso aparte (invoices:write), desde el plan Developer. La API usa la facturación del propio programa: serie, numeración correlativa, registro Verifactu y asiento contable. Se factura un presupuesto aprobado, nunca se crea una factura suelta, y las rectificativas se hacen desde el programa.
¿Puedo dar acceso a una flota sin que vea a mis otros clientes?
Sí, con una clave de cliente. Al crear la clave en «Desarrolladores / API» marca «Limitar a un cliente» y elige su ficha: esa clave solo ve y toca los vehículos, presupuestos, facturas, citas y conversaciones de ese cliente, y sus webhooks solo reciben sus avisos. Un id de otro cliente responde 404 y lo que es de todo el taller (crear clientes, facturar, enviar SMS o email sueltos…) responde 403. El cliente se fija al crearla y no se cambia después.
¿Y si la integración se equivoca?
Con una clave de prueba no puede cambiar nada. Con una live, cada cambio queda en el historial del cliente o del presupuesto como «API · nombre de la clave», y la clave se revoca al momento.
¿Hay SDK o colección de Postman?
El fichero OpenAPI 3.1 sirve para generar un cliente en cualquier lenguaje. Dentro del programa tienes además la colección de Postman y un panel para probar cada endpoint con tu clave.
Desarrollo un software para talleres, ¿puedo conectarme a muchos?
Sí, con el plan Partner: cada taller crea su clave para tu producto y acordamos el precio por taller según el volumen. Escríbenos y lo vemos.
¿Qué pasa si supero el límite de peticiones?
Cada clave admite 60 peticiones por minuto. Si te pasas, la API responde 429 con la cabecera Retry-After y tu sistema solo tiene que esperar esos segundos. En el plan Incluido, al agotar el cupo diario se pausa hasta las 00:00 UTC; en Developer y Business se sigue atendiendo y el exceso se cobra a 1 € por cada 1.000 peticiones.
¿La API puede aceptar un presupuesto en nombre del cliente?
Sí, con el permiso budgets:accept (plan Developer o superior) y solo si indicas la evidencia: quién acepta y por qué canal (teléfono, en persona, email, WhatsApp…). Pasa por la misma regla de aceptación del programa y en el historial queda «Aceptado por API en nombre del cliente» con el nombre de la clave. El cliente sigue pudiendo aceptar desde su enlace de seguimiento; la API no da ese enlace.
¿Hay un entorno de pruebas?
Sí, público y gratuito: https://demo.programa-taller.es/desarrolladores-sandbox. Te da una clave pt_test_ de 30 días con escritura habilitada sobre datos ficticios que se restauran cada 2 horas. Nada sale de verdad (los envíos se registran como simulados) y los webhooks se emiten igual, así pruebas el ciclo completo. Tus claves y webhooks se conservan entre reinicios.
¿Puede mi propio bot contestar a los clientes del taller?
Sí, desde el plan Business. Activas el «asistente externo» en los canales que quieras (WhatsApp, SMS, chat web o email): cada mensaje del cliente te llega por el webhook message.received y respondes por la API. Si no contestas en 10 minutos, o tu clave o tu webhook dejan de funcionar, el asistente del programa responde por ti.
¿Tienes una integración en mente?
Cuéntanos qué quieres conectar y te decimos qué endpoints usar y qué plan te encaja.