- Las claves pt_test_ de tu taller leen los datos reales pero cualquier operación con efectos responde 403.
- Para escribir, aceptar, facturar y enviar existe un entorno de pruebas público con datos ficticios que se restauran cada 2 horas y claves gratuitas de 30 días.
- Allí los envíos se simulan pero los webhooks se emiten igual, así que se prueba el ciclo completo.
- Lo que más conviene probar es lo que pasa la segunda vez: reintentos, duplicados y caídas del servidor.
- Al pasar a producción, la gerencia crea una clave pt_live_ con los permisos mínimos, la finalidad y, si puede, las IP del proveedor.
Un entorno de pruebas (sandbox) de una API es un sitio separado de producción donde puedes hacer de todo sin consecuencias: crear clientes, aceptar presupuestos, emitir facturas o enviar mensajes, y que nada llegue a un cliente real ni toque la contabilidad de nadie. En Programa Taller hay dos niveles de prueba. Las claves pt_test_ de tu propio taller leen tus datos reales pero no pueden cambiar nada. Y para todo lo que escribe existe un entorno de pruebas público, en demo.programa-taller.es, con datos ficticios que se restauran cada 2 horas.
Esta guía va en orden, del primer minuto al paso a producción. Si eres el gerente y no programas, lee el primer apartado y el último: te dicen qué pedirle a quien te haga la integración para que no la pruebe con tus clientes.
¿Por qué no probar directamente en el programa del taller?
Porque una integración a medio hacer se equivoca, y en un taller los errores tienen cara. Un bucle mal escrito que crea el mismo cliente cuarenta veces. Una prueba de «aceptar presupuesto» que dispara el aviso a todo el equipo un martes a las once. Un SMS de prueba que le llega a un cliente de verdad diciendo «hola, esto es un test». O una factura emitida por error que luego hay que rectificar, porque la numeración correlativa no se deshace.
Por eso la regla es sencilla: en tu taller, la integración en pruebas solo lee. Todo lo que escribe, acepta, factura o envía se prueba en un sitio donde no hay nadie al otro lado.
| Clave pt_test_ de tu taller | Entorno de pruebas público | |
|---|---|---|
| Datos | Los reales de tu taller | Ficticios, se restauran cada 2 horas |
| Leer | Sí | Sí |
| Crear, cambiar, aceptar, facturar, enviar | No: responde 403 test_key_forbidden | Sí, con todos los permisos; los envíos se simulan |
| Webhooks | Pruébalos en el entorno público | Se emiten igual que en producción |
| Coste y cupo | Sin coste, no gasta cupo | Gratis; clave válida 30 días |
| Quién crea la clave | La gerencia, en «Desarrolladores / API» | El propio desarrollador, sin cuenta |
Paso 1. Pide tu clave del entorno de pruebas
Desde la página https://demo.programa-taller.es/desarrolladores-sandbox o con una sola petición, sin autenticación:
curl -X POST "https://demo.programa-taller.es/api/v1/sandbox/keys" \
-H "Content-Type: application/json" \
-d '{"email": "oscar@example.com",
"company": "Integraciones Lafuente",
"name": "Óscar Lafuente"}'Te devuelve una clave pt_test_… con todos los permisos y válida 30 días. Se muestra una sola vez: guárdala en tu gestor de contraseñas antes de cerrar la terminal. Hay un máximo de 3 claves al día por IP y por email. Si llamas a este endpoint en la instancia de un taller real, responde 404 sandbox_only: solo existe en el entorno de pruebas.
Paso 2. Comprueba la conexión con /ping
GET /api/v1/ping con la cabecera Authorization: Bearer pt_test_9f2c… responde con el nombre de la clave, su entorno, sus permisos y el cupo que queda. Si ves un 401, la clave no es válida para esa instancia (lo típico: estás apuntando a la URL equivocada). Si ves un 403, falta un permiso.
Apunta también las cabeceras de la respuesta. Cada una trae X-RateLimit-Remaining, y te conviene que tu cliente HTTP la lea desde el primer día.
Paso 3. Escribe algo y vuelve a escribirlo
Ahora sí: crea un cliente, un vehículo y un presupuesto. La prueba importante no es que funcione la primera vez, sino qué pasa la segunda.
- Repite la misma petición con la misma
Idempotency-Key. Debes recibir la respuesta guardada con la cabeceraIdempotent-Replay: true, no un segundo cliente. Es lo que te salva cuando hay un corte de red y tu sistema reintenta. - Repite con la misma clave y otro cuerpo. Debe responder
409 idempotency_conflict. Si tu código genera la clave de idempotencia mal (por ejemplo, la misma para todas las operaciones), lo descubres aquí y no en producción. - Crea un cliente con un teléfono que ya existe. Responde
409 client_exists. Prueba también?on_conflict=return_existing, que te devuelve el existente con un 200: casi siempre es lo que quieres en un formulario web. - Manda un campo que no existe. Responde
422 validation_errorcon la listafields. Los cuerpos se validan contra su esquema y cualquier campo desconocido se rechaza.
Paso 4. Recorre el ciclo completo: aceptar, facturar, cobrar
Esto es lo que una clave de prueba de tu taller nunca podría hacer, y por eso existe el entorno público. Un recorrido típico:
- Crea un presupuesto con
POST /budgets. Entra en «Pendiente». - Márcalo como enviado o usa uno que ya esté en «Enviado».
- Acéptalo en nombre del cliente con
POST /budgets/{id}/accept, indicando quién acepta y por qué canal. Comprueba que, si faltan datos fiscales, recibes422 fiscal_data_incompletecon la listamissing. - Factúralo con
POST /budgets/{id}/invoice. Repite la llamada: debe devolverte la misma factura concreated=false, nunca una segunda. - Anota un cobro con
POST /invoices/{id}/paymentsy comprueba que la factura queda saldada solo cuando los cobros suman el total.
Cada paso deja rastro en GET /budgets/{id}/activity. Léelo: es lo mismo que verá el taller en la ficha, y te dice si tu integración se está presentando como esperas.
Paso 5. Prueba los webhooks antes de depender de ellos
En el entorno de pruebas los webhooks se emiten igual que en producción, así que es el sitio para comprobar tu receptor.
- Da de alta tu URL con
POST /webhooksy los eventos que te interesen. El secreto de firma (whsec_…) solo viaja en esa respuesta: guárdalo. - Lanza una entrega de prueba con
POST /webhooks/{id}/test. Llega un eventotest.ping. - Verifica la cabecera
X-PT-Signatureen cada entrega y descarta la que no traiga una firma válida. - Responde 2xx en menos de 5 segundos. Si tu servidor tarda o falla, el programa reintenta hasta 5 veces, así que tu receptor tiene que tolerar recibir el mismo evento más de una vez.
Un consejo práctico: apaga tu servidor a propósito durante una entrega y comprueba que, al volver, procesas el reintento sin duplicar nada. Mejor descubrirlo un jueves de pruebas que el primer lunes con clientes.
Paso 6. Si haces un bot, simula al cliente
Si tu integración contesta mensajes en lugar del asistente del programa, no necesitas un móvil para probarla. POST /sandbox/simulate/message crea un mensaje entrante ficticio por WhatsApp, SMS, chat web o email, como si lo hubiera escrito un cliente:
{ "channel": "whatsapp",
"from": "+34600987654",
"text": "Buenas, ¿me podéis mirar los frenos el jueves?" }El mensaje entra en la Bandeja, se enlaza con el cliente si el teléfono coincide y dispara message.received. Tu bot responde con POST /conversations/{key}/messages y la respuesta queda como simulada. Prueba también qué pasa si tu bot no contesta: pasado el tiempo de respaldo, contesta el asistente del programa. Y prueba mensajes en otros idiomas, porque los clientes de un taller no escriben todos en español.
Paso 7. Pasa a producción con los permisos justos
Cuando todo cuadra, el cambio es pequeño en código y grande en responsabilidad:
- Cambia la URL base por la del taller (
https://<su-dominio>/api/v1, la ves en «Desarrolladores / API»). - Antes de escribir nada, prueba las lecturas con una clave
pt_test_del propio taller. Ahí verás cosas que el entorno ficticio no tiene: sus tarifas, su modo de citas, sus festivos. - Pide a la gerencia una clave
pt_live_con los permisos mínimos, la finalidad escrita y, si puede ser, limitada a tus IP y con fecha de fin. - Da de alta los webhooks en la instancia real. Los del entorno de pruebas no se trasladan.
- Vigila el registro de peticiones los primeros días. Guarda 90 días de qué clave, desde qué IP, a qué endpoint y con qué resultado.
Escribir datos, aceptar presupuestos y recibir webhooks en producción requiere el plan Developer de la API (19 € al mes sin IVA). Enviar mensajes o contestar con un bot propio, el Business (49 € al mes sin IVA). Las pruebas no cuestan nada en ningún caso.
Abre el programa, crea una clave pt_test_ y empieza a leer tus datos sin riesgo.
Prueba 3 meses por 1 €Lista para el gerente: qué pedirle a quien te hace la integración
No necesitas entender el código para saber si una integración está bien probada. Pide estas cinco cosas antes de crear la clave live:
- Que te enseñe el recorrido en el entorno de pruebas. Una captura o una videollamada de diez minutos con el ciclo completo funcionando.
- Que te diga exactamente qué permisos necesita y por qué. «Todos» no es una respuesta. Una integración de citas no necesita leer facturas.
- Que te diga qué pasa si su servidor se cae. Si usa webhooks, cómo recupera los reintentos. Si usa un bot, que el asistente del programa contesta de respaldo.
- Que te dé sus IP para limitar la clave.
- Que acuerde contigo una fecha de fin o una revisión. Las claves que nadie recuerda son las que acaban siendo un problema.
Con eso, la integración que entra en tu taller ya ha fallado todo lo que tenía que fallar en otro sitio. Tú sigues con el día a día y no te enteras de que existe, que es exactamente lo que se busca.
Lo que el entorno de pruebas no te va a enseñar
El entorno público es una instancia con datos inventados, y eso tiene límites que conviene conocer:
- No es tu taller. Sus horarios, su modo de reserva de citas («proponer» o «reservar»), sus tarifas y sus festivos no son los tuyos. Una integración de citas que funciona allí puede encontrarse en tu taller con el error
booking_mode_propose_only. Por eso el paso de leer conpt_test_en tu instancia no es opcional. - Nada sale de verdad. Un email o un SMS «enviado» se registra como simulado. Para comprobar cómo le llega el mensaje a un cliente, la única forma es en producción, con un teléfono tuyo y con cuidado.
- El volumen no es real. No uses el entorno de pruebas para medir rendimiento: su cupo y su ritmo no reflejan los de una instancia en uso.
Para profundizar, tienes los endpoints completos en la referencia de la API, una visión general en la portada para desarrolladores, y la parte de seguridad contada para gerentes en claves, permisos y RGPD. Si lo tuyo es un bot que conteste por WhatsApp, sigue con conectar tu propio asistente a los canales del taller.
Preguntas frecuentes
¿El entorno de pruebas de la API tiene algún coste?
No. Las claves del entorno de pruebas público son gratuitas y valen 30 días. Las claves pt_test_ que crea la gerencia en su propio taller tampoco tienen coste ni gastan cupo.
¿Qué diferencia hay entre una clave pt_test_ y una pt_live_?
Una pt_test_ de tu taller puede leer tus datos reales pero no crear, cambiar ni enviar nada. Una pt_live_ hace todo lo que permitan sus permisos y tu plan de API, y cada cambio queda en el historial con el nombre de la clave.
¿Se borran mis pruebas del sandbox?
Los datos ficticios se restauran cada 2 horas, así que lo que crees desaparece. Tus claves, tus webhooks y tu registro de peticiones se conservan entre reinicios.
¿Puedo probar un bot de WhatsApp sin enviar mensajes reales?
Sí. En el entorno de pruebas puedes simular que un cliente escribe por WhatsApp, SMS, chat web o email. El mensaje dispara el mismo aviso que en producción y la respuesta de tu bot se registra como simulada.
¿Cuántas claves de prueba puedo pedir?
Hasta 3 al día por IP y por email en el entorno de pruebas público. Cada una se muestra una sola vez al crearla.
¿Los webhooks configurados en el sandbox pasan a mi taller?
No. Al pasar a producción hay que dar de alta las URL y los eventos en la instancia del taller, con una clave live que tenga el permiso de gestionar webhooks.