Programa Taller
API

Entorno de pruebas de la API (sandbox): probar una integración sin riesgo

Una prueba de «aceptar presupuesto» puede hacer sonar la alarma de todo el equipo, y una factura emitida por error no se deshace. Así se prueba una integración sin tocar nada real.

Por el equipo de Programa Taller · 16 nov 2026 · Lectura: 9 min
Ilustración de una ventana de código dentro de una caja de arena con una pala y un escudo con una marca de verificación, sobre fondo azul oscuro e índigo
En pocas palabras
  • 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 tallerEntorno de pruebas público
DatosLos reales de tu tallerFicticios, se restauran cada 2 horas
LeerSíSí
Crear, cambiar, aceptar, facturar, enviarNo: responde 403 test_key_forbiddenSí, con todos los permisos; los envíos se simulan
WebhooksPruébalos en el entorno públicoSe emiten igual que en producción
Coste y cupoSin coste, no gasta cupoGratis; clave válida 30 días
Quién crea la claveLa 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.

  1. Repite la misma petición con la misma Idempotency-Key. Debes recibir la respuesta guardada con la cabecera Idempotent-Replay: true, no un segundo cliente. Es lo que te salva cuando hay un corte de red y tu sistema reintenta.
  2. 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.
  3. 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.
  4. Manda un campo que no existe. Responde 422 validation_error con la lista fields. Los cuerpos se validan contra su esquema y cualquier campo desconocido se rechaza.
Los datos se restauran cada 2 horas, pero tus claves, tus webhooks y tu registro de peticiones se conservan. No guardes ids de clientes o presupuestos de una sesión a otra: el cliente 1204 de esta mañana puede no existir esta tarde. Búscalos o créalos al empezar cada prueba.

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:

  1. Crea un presupuesto con POST /budgets. Entra en «Pendiente».
  2. Márcalo como enviado o usa uno que ya esté en «Enviado».
  3. 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, recibes 422 fiscal_data_incomplete con la lista missing.
  4. Factúralo con POST /budgets/{id}/invoice. Repite la llamada: debe devolverte la misma factura con created=false, nunca una segunda.
  5. Anota un cobro con POST /invoices/{id}/payments y 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.

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:

  1. Cambia la URL base por la del taller (https://<su-dominio>/api/v1, la ves en «Desarrolladores / API»).
  2. 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.
  3. 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.
  4. Da de alta los webhooks en la instancia real. Los del entorno de pruebas no se trasladan.
  5. 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.

Prueba con datos ficticios, conecta con los tuyos

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:

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:

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.

Sigue leyendo

API

Seguridad de la API del taller: claves, permisos y RGPD antes de dar acceso

13 nov 2026 · 9 min
API

Webhooks: qué son, con ejemplos reales de un taller mecánico

29 oct 2026 · 11 min
API

Conectar tu propio chatbot al WhatsApp del taller por API: guía

10 nov 2026 · 10 min
3 meses por 1 €