Webhooks, postbacks servidor a servidor y la API REST

Tres formas de conectar TapTime con otros sistemas, todas en el mismo apartado. Solo el propietario de la empresa puede gestionarlas. Para los avisos en chats y para Zapier, Make, n8n o Pipedream, consulta sus propias guías: usan los mismos eventos.

Panel Integraciones Webhooks y API

Usa	Cuándo
Webhook	Tu propio sistema o un CRM debe enterarse de cada cambio en reservas, pedidos o fidelización, con todos los detalles.
Postback	Una red publicitaria, un afiliado o un tracker te ha dado una URL de postback a la que llamar en cada conversión.
API REST	Tu sistema quiere consultar las reservas cuando le convenga, o confirmarlas y cancelarlas.

Eventos que puedes enviar

Evento	Cuándo
booking.requested	Un cliente ha solicitado una reserva que espera tu confirmación
booking.confirmed	Se confirma una reserva
booking.cancelled	El cliente o el negocio la ha cancelado
booking.no_show	El cliente no se ha presentado
booking.completed	La visita ha terminado
order.placed	Te ha llegado el pedido de un cliente (desde tu página o desde el código QR de una mesa)
order.paid	Se ha pagado cualquier pedido, también en caja
loyalty.member_joined	Un cliente ha recibido su primer sello en un programa
loyalty.stamp_added	Se ha añadido un sello
loyalty.reward_issued	Se ha completado una tarjeta y se ha emitido su recompensa
loyalty.reward_redeemed	Se ha entregado una recompensa

Webhooks

1
Añadir webhook
Pega la dirección https de tu endpoint y elige los eventos: reservas, pedidos, fidelización o todos.
2
Enviar prueba
Se envía al instante un evento de ejemplo y se muestra la respuesta de tu endpoint.
3
Verifica la firma
Cada solicitud lleva una cabecera TapTime-Signature: t=<time>,v1=<HMAC-SHA256 de «t.body» con tu secreto de firma>. Compárala antes de fiarte de la solicitud.

El cuerpo es JSON: el ID, el tipo y la hora del evento, y la reserva, el pedido o la tarjeta de fidelización completos en data.booking, data.order o data.loyalty, con el cliente, la hora, la mesa, el servicio o los artículos, el estado y de dónde vino (etiquetas UTM e identificadores de clic).

Responde con cualquier estado 2xx. Cualquier otra respuesta se reintenta 8 veces durante aproximadamente un día.
Cada evento tiene un ID: si lo recibes dos veces, ignora el segundo.
Responde 410 Gone y TapTime dejará de reintentar ese evento.
No se siguen las redirecciones y se rechazan las direcciones de redes privadas.

Postbacks servidor a servidor

Pega la URL de postback que te dio tu tracker y haz clic en los marcadores para insertar datos de la reserva, por ejemplo https://tracker.example/postback?cid={click_id}&payout={value}&status={status}. Entre los marcadores disponibles están {click_id}, {event}, {booking_id}, {value}, {currency}, {party_size}, {utm_source}, {utm_campaign}, {gclid} y {fbclid}. El identificador de clic del tracker llega a la reserva cuando tu enlace de reserva lleva click_id, clickid o subid.

API REST

1
Crear clave de API
Ponle un nombre y elige solo lectura, o lectura y escritura para permitir confirmar, cancelar y marcar no presentados.
2
Cópiala ahora
La clave se muestra una sola vez. Guárdala en tu servidor, nunca en una página web ni en una app.
3
Llama a la API
Envíala como Authorization: Bearer <key> a https://api.tapti.me/v1/company.

Solicitud	Devuelve
GET /v1/company	La empresa a la que pertenece la clave
GET /v1/company/reservations, /appointments	Reservas, filtradas por status, branchId, from, to o updatedSince, 100 por página
GET /v1/company/reservations/{id}	Una reserva
POST /v1/company/reservations/{id}/status	Cambia el estado (claves de escritura)
GET /v1/company/orders, /orders/{id}	Pedidos con sus artículos y totales, filtrados por status, source, fulfilment, from, to o paidSince
GET /v1/company/loyalty/programs, /cards, /rewards	Programas de fidelización, tarjetas de los miembros y las recompensas que han conseguido
GET /v1/company/events?after={cursor}	Todos los eventos de reservas, pedidos y fidelización en orden; consúltalo periódicamente para mantenerte sincronizado; añade type=order,loyalty para recibir solo algunos
POST /v1/company/webhooks, DELETE /v1/company/webhooks/{id}	Suscribe una URL a eventos y la da de baja; es lo que usan las apps de Zapier, Make, n8n y Pipedream

Cuando algo falla

El Registro de envíos de cada endpoint muestra sus últimos 25 envíos con el código de estado y la respuesta de tu sistema. Los envíos fallidos se reintentan solos; «Volver a enviar» reintenta uno ahora.

Preguntas frecuentes

¿Puede un webhook ir a Zapier o Make?

Sí: usa Integraciones → Automatización, que comprueba que la dirección pertenece a la plataforma y muestra sus propios pasos. Crea un «Catch Hook» (Zapier), un «Custom webhook» (Make), un nodo Webhook (n8n) o un disparador HTTP (Pipedream), pega su dirección y pulsa Enviar prueba para que la herramienta aprenda los campos.

He perdido mi secreto de firma.

El propietario puede volver a mostrarlo desde el endpoint o rotarlo. Al rotarlo se genera uno nuevo al instante y el anterior deja de funcionar.

¿Te ha resultado útil este artículo?

¿No ha resuelto tu duda?

Escríbenos e indica la página en la que estabas. Una persona lee cada mensaje y responde en el idioma en que nos escribas.

Escríbenos