Skip to main content
All analytics endpoints are public — no authentication is required. Events are accepted asynchronously and processed in the background. The API returns 202 Accepted or 201 Created to avoid blocking the caller.

​
POST /api/v1/analytics/track

Track a generic analytics event for a specific tenant and interaction type. Middleware: throttle:api
Authentication: Not required

​
Request body

​
tenant_id
string
required
UUID or string ID of the tenant to associate the event with.
​
type
string
required
Interaction type. Must be one of the InteractionType enum values: whatsapp_click, call, location_view, cart_add, social_share, conversion, purchase.
​
product_id
integer
Optional. If provided, must exist in the products table. The product ID is also merged into metadata.
​
metadata
object
Arbitrary key-value metadata to attach to the event.

​
Response 202 Accepted

​
success
boolean
true
​
message
string
Event accepted for processing

​
Response 404 Not Found

Returned when the tenant_id does not correspond to a public (active) tenant.
​
success
boolean
false
​
message
string
Tenant not found or not available
curl -X POST https://yourdomain.com/api/v1/analytics/track \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "tenant_id": "a1b2c3d4-...",
    "type": "whatsapp_click",
    "product_id": 101,
    "metadata": {"source": "catalog_page"}
  }'

​
Error responses

StatusCause
404Tenant not found or not public
422tenant_id or type missing, invalid interaction type

​
POST /api/v1/analytics/conversion

Record a purchase/conversion beacon event. Designed to be called from a client-side beacon (e.g. after a payment confirmation). Failures are swallowed silently to avoid disrupting the user flow. Middleware: throttle:api
Authentication: Not required

​
Request body

​
tenant_slug
string
required
URL slug of the tenant. Used to resolve the tenant without exposing internal IDs.
​
transaction_id
string
Unique transaction identifier from the payment system.
​
value
number
Order/transaction value. Defaults to 0.0.
​
currency
string
ISO 4217 currency code. Defaults to HNL.
​
event
string
Event type. Defaults to the purchase interaction type.
​
timestamp
string
ISO 8601 timestamp of the original event. Defaults to server time when omitted.

​
Response 200 OK

​
status
string
ok on success, skipped when tenant not found or slug missing.
​
transaction_id
string
Echoed back from the request.
curl -X POST https://yourdomain.com/api/v1/analytics/conversion \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "tenant_slug": "mi-negocio",
    "transaction_id": "txn_abc123",
    "value": 150.00,
    "currency": "HNL"
  }'

​
POST /api/v1/interactions

Record a low-level interaction event (view, WhatsApp click, call, maps click). This endpoint uses the tenant-aware throttle group rather than the general api group. Middleware: throttle:tenant-aware
Authentication: Not required
Do not use this endpoint to enumerate tenants. Invalid tenant IDs are silently accepted with a 202 response — no tenant existence feedback is given.

​
Request body

​
tenant_id
integer
required
Numeric tenant ID.
​
type
string
required
Event type. Allowed values: view, whatsapp_click, call_click, maps_click.
​
product_id
integer
Optional product ID associated with the interaction.
​
metadata
object
Arbitrary metadata object.

​
Response 201 Created / 202 Accepted

201 when the interaction is successfully recorded. 202 when the tenant does not exist (silent acceptance) or on processing errors.
​
status
string
success, accepted.
curl -X POST https://yourdomain.com/api/v1/interactions \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"tenant_id": 1, "type": "view"}'

​
Error responses

StatusCause
422Missing tenant_id or type, or type not in the allowed list

Build docs developers (and LLMs) love

Get started for freeTalk to us