API REST de TapTime

Cada petición necesita una clave de API de la empresa (Integraciones → Webhooks y API en el panel) enviada como Authorization: Bearer tt_live_…. Las respuestas y los errores son JSON.

curl "https://api.tapti.me/v1/company/reservations?status=confirmed&updatedSince=2026-09-01T00:00:00Z" \
  -H "Authorization: Bearer tt_live_…"

Autenticación

Cada petición lleva una clave de API de la empresa como token bearer. Créala desde el panel, en Integraciones → Webhooks y API → Claves de la API REST, donde se muestra una sola vez y se guarda en el servidor únicamente como hash SHA-256; una clave perdida se revoca y se sustituye, no se recupera. Una empresa puede tener hasta 10 claves activas.

• Las claves de solo lectura pueden llamar a todos los endpoints GET y suscribir y cancelar webhooks: una suscripción no envía nada que la clave no pudiera leer ya.
• Las claves de lectura y escritura también pueden hacer POST para cambiar el estado de una reserva; una clave de solo lectura recibe 403 Forbidden en esas rutas.
• Una clave pertenece a una sola empresa: cada listado y consulta ya está limitado a ella, no existe un parámetro companyId.

Límites de peticiones

50 peticiones por minuto y por clave, en ventana deslizante, compartidas por todos los endpoints. Si te pasas, recibes 429 Too Many Requests; espera y vuelve a intentarlo en lugar de consultar más rápido, o suscribe un webhook y deja de consultar.

Endpoints

El objeto reserva

Una reserva de mesa y una cita salen con una misma estructura compartida: kind, id, status, source, guestInitiated, startsAt/endsAt/timezone (la zona horaria del propio local), currency, company, branch, guest, attribution, conversionId, createdAt/updatedAt, más partySize y table en una reserva, y service y specialist en una cita. Es exactamente lo que entrega un webhook, así que un receptor que gestiona una gestiona las dos.

{
  "data": {
    "kind": "reservation",
    "id": 4821,
    "status": "confirmed",
    "source": "online",
    "guestInitiated": true,
    "startsAt": "2026-09-12T20:00:00+03:00",
    "endsAt": "2026-09-12T21:30:00+03:00",
    "timezone": "Asia/Baku",
    "currency": "AZN",
    "company": { "id": 12, "name": "Cafe Aroma", "slug": "cafe-aroma", "country": "AZ" },
    "branch": { "id": 3, "name": "Nizami st." },
    "partySize": 4,
    "table": { "id": 9, "label": "T3" },
    "guest": { "name": "Maria K.", "phone": "…", "email": "…" },
    "locale": "en",
    "note": null,
    "conversionId": "tt3f9c…",
    "createdAt": "2026-09-10T08:12:04+00:00",
    "updatedAt": "2026-09-12T20:00:03+00:00",
    "attribution": { "channel": "widget", "utmSource": "instagram", "gclid": null, "fbclid": "IwAR2…" }
  }
}

El objeto pedido

Un pedido tiene la misma estructura dondequiera que lo encuentres (la API REST, los webhooks de pedidos, el feed de eventos): kind ("order"), id, number (el número que canta el personal), status (open o paid), source (customer o staff), guestInitiated, fulfilment, table, label, deliveryAddress, note, currency, timezone, company, branch, customer (el miembro de fidelización, cuando el personal lo identificó), items (name, variant, quantity, unitPriceCents, subtotalCents), itemCount, subtotalCents, discountCents, deliveryFeeCents, tipCents, totalCents, valueCents (lo que vale el pedido sin la propina: la cifra que reportan las conversiones), paymentMethod, servedBy, conversionId, createdAt, paidAt y attribution. Los importes siempre van en unidades menores.

{
  "data": {
    "kind": "order",
    "id": 9170,
    "number": 42,
    "status": "paid",
    "source": "customer",
    "guestInitiated": true,
    "fulfilment": "takeaway",
    "table": null,
    "label": "Ana",
    "currency": "EUR",
    "branch": { "id": 3, "name": "Vitosha Blvd" },
    "customer": { "id": 311, "name": "Ana", "phone": "…" },
    "items": [
      { "menuItemId": 88, "name": "Flat white", "variant": "Large",
        "quantity": 2, "unitPriceCents": 450, "subtotalCents": 900 }
    ],
    "itemCount": 2,
    "subtotalCents": 900,
    "discountCents": 0,
    "deliveryFeeCents": 0,
    "tipCents": 100,
    "totalCents": 1000,
    "valueCents": 900,
    "paymentMethod": "online",
    "conversionId": "tt81ad…",
    "createdAt": "2026-09-12T12:04:10+03:00",
    "paidAt": "2026-09-12T12:05:02+03:00",
    "attribution": { "channel": "web", "utmSource": "google", "gclid": "Cj0K…" }
  }
}

El objeto fidelización

Cada evento, tarjeta y recompensa de fidelización comparte una estructura: kind ("loyalty"), id (la tarjeta), timezone, company, branch (dónde ocurrió, cuando lo hay), program (id, name, stampsRequired, rewardTitle), customer (id, name, phone, locale), card (id, status, stampsCount, stampsRequired, stampsToReward, createdAt), stamp (en un sello: source, issuedBy, createdAt) y reward (en una recompensa: code, title, status, expiresAt, redeemedAt, redeemedBy), más conversionId, el id con el que se reporta un alta en fidelización.

{
  "kind": "loyalty",
  "id": 5120,
  "program": { "id": 4, "name": "Coffee card", "stampsRequired": 8, "rewardTitle": "Free coffee" },
  "customer": { "id": 311, "name": "Ana", "phone": "…", "locale": "bg" },
  "card": { "id": 5120, "status": "active", "stampsCount": 5,
            "stampsRequired": 8, "stampsToReward": 3 },
  "branch": { "id": 3, "name": "Vitosha Blvd" },
  "stamp": { "source": "qr_scan", "issuedBy": "Ivan", "createdAt": "…" },
  "reward": null,
  "conversionId": "tt5c02…"
}

Feed de eventos

Cada fila es { id, cursor, type, createdAt, previousStatus, data }. data contiene el objeto bajo la clave que indica el prefijo del evento: data.booking, data.order o data.loyalty. Guarda el cursor más alto que hayas procesado y devuélvelo como after: nunca se salta ni repite una fila, así que es seguro reanudar tras un fallo. Ignora los tipos que no gestiones: pueden añadirse otros nuevos.

curl "https://api.tapti.me/v1/company/events?after=998&limit=100" \
  -H "Authorization: Bearer tt_live_…"

Webhooks

Crea un endpoint en Integraciones → Webhooks y API (o conecta Zapier, Make, n8n o Pipedream en Integraciones → Automatización) para que TapTime envíe por POST un evento JSON firmado en el momento en que cambia una reserva, un pedido o una tarjeta de fidelización. Tú eliges los eventos de cada endpoint. Una empresa puede tener hasta 50 webhooks, postbacks, chats y conexiones de automatización en total.

• Cualquier respuesta 2xx se considera entregada; una respuesta que no sea 2xx o un tiempo de espera agotado se reintenta con espera progresiva (1 min, 5 min, 15 min, 1 h, 3 h, 6 h, 12 h) hasta 8 intentos; un 410 detiene los reintentos.
• No se siguen las redirecciones.
• La URL debe ser HTTPS en producción y no puede apuntar a una dirección privada o de loopback.
• La entrega es al menos una vez: verifica siempre la firma y descarta duplicados por TapTime-Event-Id.

{
  "id": "evt_9f3c2a7e1b",
  "type": "booking.confirmed",
  "createdAt": "2026-09-12T19:02:11+03:00",
  "test": false,
  "data": { "booking": { "kind": "reservation", "id": 4821, "status": "confirmed", "…": "…" } }
}

const [t, v1] = req.headers["taptime-signature"]
  .split(",").map(part => part.split("=")[1]);
const expected = crypto
  .createHmac("sha256", process.env.TAPTIME_WEBHOOK_SECRET)
  .update(`${t}.${rawBody}`)
  .digest("hex");
const valid = crypto.timingSafeEqual(
  Buffer.from(expected), Buffer.from(v1));

Suscripciones de webhooks

Las plataformas de automatización activan y desactivan disparadores a través de la API en lugar de pedir al usuario que pegue una URL («REST hooks»): haz POST con la URL propia de la plataforma y los eventos que quiere, guarda el id devuelto y haz DELETE cuando se desactive el disparador. Una suscripción es un webhook firmado normal: aparece en el panel, marcada con la clave que la creó.

• Una clave solo ve y elimina las suscripciones que creó; revocar la clave las elimina todas.
• Las direcciones de hooks.zapier.com, make.com y pipedream.net se reconocen y se muestran con el nombre de la plataforma; cualquier otra dirección https es un webhook normal.
• El secreto de firma se devuelve una sola vez, en la respuesta al POST; el propietario puede volver a verlo en el panel.

curl -X POST "https://api.tapti.me/v1/company/webhooks" \
  -H "Authorization: Bearer tt_live_…" -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.zapier.com/hooks/catch/123/abc/", "events": ["order.placed"]}'

Postbacks

Un GET o POST a la URL propia de tu tracker con las macros rellenadas, para plataformas que trabajan con postbacks por query string en lugar de webhooks JSON. En un pedido, {value} es el valor del pedido sin la propina y {order_id} su id.

https://tracker.example/postback
  ?cid={click_id}&event={event}&status={status}
  &payout={value}&cur={currency}

Marcadores disponibles

• {event}
• {event_id}
• {status}
• {booking_id}
• {booking_type}
• {order_id}
• {customer_id}
• {conversion_id}
• {value}
• {currency}
• {party_size}
• {branch_id}
• {timestamp}
• {utm_source}
• {utm_medium}
• {utm_campaign}
• {utm_term}
• {utm_content}
• {gclid}
• {fbclid}
• {msclkid}
• {ttclid}
• {click_id}

Errores

Todos los errores son JSON: { "error": "<code>", "message": "<texto legible>" }.