- Una clave por cada tercero, con nombre, finalidad escrita, permisos mínimos, IPs permitidas y fecha de fin.
- Las claves pt_test_ leen pero no cambian nada; las escrituras se prueban en el entorno público con datos ficticios.
- Costes, márgenes, notas internas y datos del personal no salen por ninguna clave.
- Cada petición queda registrada 90 días con clave, IP, endpoint y resultado, y cada cambio firmado con el nombre de la clave.
- La API no cubre lo que el tercero haga con los datos: para eso está el contrato de encargo del tratamiento.
La seguridad de una API se juega en tres decisiones: quién tiene la clave, qué permisos lleva y qué rastro deja lo que hace con ella. Para un taller, la regla de oro es sencilla: una clave por cada tercero, con los permisos mínimos para su tarea, la finalidad escrita y una fecha de fin. Si algo se tuerce, la revocas y deja de funcionar en el acto, sin cambiar la contraseña de nadie ni tocar las demás integraciones.
Lo contrario, dar a la gestoría o a la agencia de la web el usuario y la contraseña del programa, es lo que todavía se hace en muchos talleres. Esta guía es una lista de comprobación para el gerente antes de dar acceso a un tercero, con lo que hace Programa Taller en cada punto y lo que sigue dependiendo de ti.
Lidia Fuster, gerente de un taller, recibe un correo de su nueva asesoría: «Para descargar las facturas cada mes, mándanos el usuario y la contraseña del programa». Con ese usuario, la asesoría vería también la agenda, los mensajes de los clientes, los márgenes y las notas internas. Y si dentro de un año cambia de asesoría, nadie se acordará de cambiar la contraseña.
Con una clave de API, la asesoría recibe solo lo que necesita: facturas y cobros, en lectura, con su nombre y su finalidad escritos. Escena inventada para ilustrar el caso.
Antes de crear la clave: cinco preguntas al tercero
Haz estas preguntas a quien te pida acceso. Las respuestas te dicen qué clave crear, o si no deberías crear ninguna.
- ¿Para qué vas a usar los datos, exactamente? «Para la contabilidad mensual» es una respuesta. «Para la integración» no lo es. El programa pide escribir la finalidad al crear la clave, como exige el RGPD, y queda junto a la clave y en el registro.
- ¿Qué datos necesitas leer y cuáles tienes que escribir? La mayoría de terceros solo leen. Si alguien quiere escribir, pregúntale qué y por qué.
- ¿Desde qué direcciones IP te conectarás? Un proveedor serio te da una lista fija de sus servidores. Si no lo sabe, apúntalo como señal.
- ¿Hasta cuándo? Un proyecto de seis meses no necesita una clave sin fecha de fin.
- ¿Me firmas un contrato de encargo del tratamiento? Si va a tratar datos de tus clientes por tu cuenta, el artículo 28 del RGPD exige que la relación esté regulada por contrato. No es un trámite de la API: es tuyo, como responsable de esos datos.
¿Qué permisos le doy a cada uno?
Cada área tiene su permiso de lectura y, donde tiene sentido, de escritura. Los que tienen efectos están marcados aparte, y el plan de API decide cuáles se pueden usar: el Incluido es solo lectura. Estas combinaciones cubren los casos más habituales:
| Quién pide acceso | Permisos que necesita | Lo que no debería tener |
|---|---|---|
| Gestoría o asesoría | invoices:read | Clientes completos, comunicaciones, agenda |
| Web con cita online | appointments:read, appointments:write, clients:write, vehicles:write, budgets:write | Facturas, comunicaciones |
| Integración para el gestor de flotas de un cliente | vehicles:read, budgets:read, webhooks:manage | La clave en manos del propio cliente (ver el aviso de abajo) |
| Distribuidor de recambios | budgets:read o budgets:write, stock:read | Comunicaciones, facturas |
| Cuadro de mando del grupo | reports:read | Cualquier escritura |
vehicles:read ve todos los vehículos del taller, no solo los de una flota, y una con budgets:read, todos los presupuestos. Si quien pide acceso es un cliente o un proveedor que solo debería ver una parte, no le entregues la clave: que la use tu informático o tu agencia en un sistema intermedio que le pase solo lo suyo. Si tu caso no encaja, escríbenos y lo valoramos.Hay permisos que merecen una pausa antes de concederlos:
communications:readda acceso al registro de emails, SMS, WhatsApp y llamadas con su contenido completo. Es de lo más sensible que guarda un taller.budgets:acceptpermite aceptar o rechazar presupuestos en nombre del cliente. Exige indicar quién acepta y por qué canal, y queda en el historial como «Aceptado por API en nombre del cliente» con el nombre de la clave. Solo para integraciones que de verdad reciben esa confirmación.invoices:writeemite facturas con la numeración y el registro Verifactu del programa. Una factura emitida no se borra; se rectifica desde el programa.messages:sendycommunications:sendescriben a tus clientes en nombre del taller y consumen saldo.
Si la clave pide algo que no tiene, la API responde 403 insufficient_scope. Es mejor recibir esa llamada del proveedor («nos falta tal permiso, ¿nos lo das?») que haber concedido de más desde el principio. Es el principio de minimización del artículo 5 del RGPD aplicado a una integración.
¿Por qué empezar con una clave de prueba?
Las claves tienen dos entornos, y el prefijo lo dice: pt_test_ y pt_live_.
- Una
pt_test_de tu taller lee tus datos reales pero no puede crear, cambiar ni enviar nada: cualquier operación con efectos responde403 test_key_forbidden. Tampoco gasta cupo. Sirve para que el proveedor construya y compruebe que lee bien. - Para probar escrituras, aceptaciones, facturas y mensajes, hay un entorno de pruebas público con datos ficticios que se restauran cada 2 horas. Allí nada sale de verdad y los webhooks se emiten igual. Sus claves duran 30 días.
- Solo cuando todo funciona, se crea una
pt_live_con los permisos mínimos.
Para el gerente, la consecuencia práctica es que el proveedor puede trabajar semanas sin que su código pueda estropear nada en tu taller. Si te pide una clave live el primer día, pregúntale por qué.
Al crear la clave: lo que configuras tú
La clave la crea la gerencia en «Desarrolladores / API». Estos son los campos y lo que conviene poner:
- Nombre reconocible. «Asesoría · facturas mensuales», no «clave 2». Ese nombre aparece en el historial de todo lo que haga.
- Finalidad. La que te dieron en la pregunta 1, con sus palabras.
- Permisos. Los de la tabla, ni uno más.
- IPs permitidas. Si el proveedor te dio su lista, limita la clave a ella. Desde cualquier otra dirección, la API responde
403 ip_not_allowed, aunque alguien haya copiado la clave. - Fecha de fin. Al llegar, la clave deja de funcionar sola (
401 expired_api_key).
La clave completa se enseña una sola vez. Después, en la pantalla solo se ve su prefijo. El programa guarda únicamente una huella atada a tu taller: no sirve en ningún otro y nadie puede recuperarla, tampoco nosotros. Entrégala por un canal seguro (un gestor de contraseñas compartido, por ejemplo) y no por WhatsApp ni en el cuerpo de un email. Si se pierde, se crea otra.
¿Qué datos no salen nunca por la API?
Hay información que ninguna clave puede leer, tenga los permisos que tenga:
- Costes, márgenes y proveedores de los recambios: el inventario sale con existencias, referencias y precio de venta.
- Notas internas y presupuestos de uso interno.
- Del personal del taller, solo el identificador y el nombre.
Y si un cliente ejerció su derecho de supresión, su ficha no admite cambios ni altas asociadas: la API responde 409 client_erased. Una integración no puede volver a dar de alta por la puerta de atrás a quien pidió que le borraran.
Con el programa a prueba puedes crear una clave de solo lectura, ver el registro y revocarla cuando quieras.
Probar 3 meses por 1 €Mientras la clave está en uso: cómo vigilarla
Una clave que nadie mira es una puerta abierta que nadie recuerda. El programa guarda un registro de cada petición durante 90 días: qué clave, desde qué IP, a qué endpoint y con qué resultado. Se consulta en la misma sección. Una revisión de cinco minutos al mes basta:
- ¿Hay claves que no se han usado en semanas? Revócalas.
- ¿Alguna llama a endpoints que no esperabas para su finalidad?
- ¿Aparecen IPs nuevas? Si la clave tiene lista de IPs, no deberían.
- ¿Hay muchos errores
403? El proveedor está intentando algo para lo que no le diste permiso: pregúntale.
Cada cambio que hace una clave live queda firmado en el historial del cliente o del presupuesto como «API · nombre de la clave». Si un presupuesto aparece modificado sin que nadie del equipo lo tocara, el historial te dice qué integración fue.
Hay dos protecciones más que trabajan solas. Los límites de peticiones (60 por minuto y clave, ampliable a 600, más el cupo diario del plan) evitan que un fallo en el código del proveedor sature tu taller: al pasarse recibe un 429 con el tiempo de espera. Y la cabecera Idempotency-Key, obligatoria en todo POST, impide que un reintento por un corte de red cree un segundo cliente o un segundo presupuesto.
Los avisos que salen del taller también se protegen
Si la integración recibe webhooks, el tráfico va en sentido contrario: es tu taller el que envía datos a la dirección del tercero. Cada entrega va firmada con HMAC-SHA256 en la cabecera X-PT-Signature, con un secreto que solo se muestra al crear la suscripción. Pide al proveedor que compruebe esa firma; si no lo hace, cualquiera que adivine su dirección podría colarle avisos falsos. Y suscríbelo solo a los eventos que necesita: el gestor de flotas no tiene por qué enterarse de los cobros.
Cuando la relación termina
Cambias de asesoría, la agencia entrega la web, el cliente de flota deja de trabajar contigo. Ese día:
- Revoca la clave. Tiene efecto inmediato: la siguiente petición recibe
401 revoked_api_key. - Borra sus webhooks, si los tenía.
- Pide al tercero que confirme por escrito que ha devuelto o borrado los datos, como prevé el contrato de encargo.
Comparado con cambiar la contraseña de un usuario compartido y avisar a todo el equipo, es un clic. Por eso merece la pena que cada tercero tenga su propia clave: cortar con uno no afecta a los demás.
Lo que la API no puede proteger por ti
La API controla qué sale del programa. Lo que el tercero haga después con esos datos, en sus servidores, queda fuera de su alcance. Una gestoría con la clave bien configurada puede tener luego las facturas en un portátil sin contraseña. Esa parte se cubre con el contrato, con las preguntas del principio y eligiendo bien con quién trabajas.
Tampoco sustituye a tu asesor de protección de datos. Si una integración trata datos de muchos clientes o datos especialmente sensibles, valora con él si hace falta algo más que esta lista. Y ninguna configuración resiste una clave pegada en un grupo de WhatsApp.
Bien hecho, el resultado es que puedes abrir el taller a más herramientas (la gestoría, la web, un cliente con veinte furgonetas) sin multiplicar el riesgo con cada una, y sin que el gerente tenga que estar vigilando contraseñas compartidas. Para ver qué integraciones existen, empieza por la página de la API para talleres; para cómo se protege la atención con IA frente a mensajes manipulados, el artículo sobre riesgos de un chatbot de atención al cliente. Y los planes de API están detallados en la propia página de desarrolladores, aparte de los precios del programa.
Preguntas frecuentes
¿Es seguro dar a la gestoría acceso al programa del taller?
Es más seguro darle una clave de API de solo lectura de facturas que el usuario y la contraseña del programa. La clave limita lo que ve, se puede atar a sus IPs, tiene fecha de fin y se revoca al momento sin afectar a nadie más.
¿Qué pasa si alguien copia mi clave de API?
Si la clave está limitada a las IPs del proveedor, no le sirve desde otro sitio. En cualquier caso, revócala desde «Desarrolladores / API»: tiene efecto inmediato. El registro de peticiones te dice qué se hizo con ella.
¿Puede el proveedor recuperar una clave si la pierde?
No. La clave completa se muestra una sola vez y el programa solo guarda una huella, así que nadie puede recuperarla. Se crea una nueva y se revoca la anterior.
¿Cuánto tiempo se guarda el registro de peticiones de la API?
90 días. Incluye qué clave hizo la petición, desde qué IP, a qué endpoint y con qué resultado, y se consulta desde la misma sección del programa.
¿Necesito un contrato con quien usa la API de mi taller?
Si trata datos personales de tus clientes por tu cuenta, el artículo 28 del RGPD exige regular la relación por contrato de encargo del tratamiento. La API te ayuda a limitar el acceso, pero el contrato lo firmas tú; consúltalo con tu asesor.
¿Una integración puede ver lo que gano en cada reparación?
No. Los costes, los márgenes, el proveedor de los recambios, las notas internas y los presupuestos de uso interno no aparecen en ninguna respuesta de la API, tenga la clave los permisos que tenga.