Guía de integración: informe de ventas

Esta guía está pensada para un canal de ventas que quiere consultar sus propias ventas realizadas a través de la API. Sigue estos pasos en orden.

Requisitos previos

Antes de empezar necesitas:

Dato	Dónde conseguirlo
`sales_channel_slug`	Te lo proporciona el equipo de beTickets al darte de alta como canal
`widget_key` (`wk_...`)	Se genera desde el dashboard de beTickets (menú Canales de venta → tu canal → Generar key)
`lang`	Código de idioma (`es`, `en`, `ca`, etc.)
URL base	Producción: `https://api.bticketing.com/api` / Preproducción: `https://api-pre.betickets.io/api`

Paso 1: Obtén un token de acceso

El único endpoint público. Intercambia tu slug + widget_key por un Bearer token.

http

POST /api/sales-channel/v1/auth/token
Content-Type: application/json

{
  "sales_channel_slug": "teatro-calderon",
  "widget_key": "wk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Respuesta:

json

{
  "success": true,
  "data": {
    "access_token": "1|abc123def456...",
    "token_type": "Bearer",
    "sales_channel_slug": "teatro-calderon"
  }
}

GUARDA ESTE TOKEN

El token anterior se revoca al pedir uno nuevo. Conserva el último token en un lugar seguro (variable de entorno, gestor de secretos, etc.).

A partir de ahora, todas las llamadas deben incluir el token en el header:

http

Authorization: Bearer 1|abc123def456...

Paso 2: Consulta tu informe de ventas

Con el token ya puedes llamar al endpoint de ventas. Este endpoint solo devuelve las órdenes asociadas a tu canal — no ves datos de otros canales.

URL

GET /api/sales-channel/v1/{salesChannelSlug}/{lang}/reports/sales

Sin filtros — todas las ventas

http

GET /api/sales-channel/v1/teatro-calderon/es/reports/sales
Authorization: Bearer 1|abc123def456...

Devuelve las últimas 500 órdenes completadas de tu canal.

Filtrar por un evento concreto

http

GET /api/sales-channel/v1/teatro-calderon/es/reports/sales?event_id=42
Authorization: Bearer 1|abc123def456...

Filtrar por varios eventos

http

GET /api/sales-channel/v1/teatro-calderon/es/reports/sales?event_ids[]=42&event_ids[]=57
Authorization: Bearer 1|abc123def456...

Filtrar por rango de fechas

http

GET /api/sales-channel/v1/teatro-calderon/es/reports/sales?date_from=2025-04-01&date_to=2025-04-30
Authorization: Bearer 1|abc123def456...

LÍMITE DE 90 DÍAS

No puedes solicitar rangos superiores a 90 días. Si lo intentas, la API responderá con un error 422.

Combinar filtros

http

GET /api/sales-channel/v1/teatro-calderon/es/reports/sales?event_ids[]=42&date_from=2025-04-01&date_to=2025-04-30
Authorization: Bearer 1|abc123def456...

Paso 3: Entiende la respuesta

json

{
  "status": 200,
  "success": true,
  "data": {
    "data": [
      {
        "id": 123,
        "order_reference": "ABC-123",
        "type": "purchase",
        "datetime": "2025-04-01T14:30:00+00:00",
        "customer_name": "Juan Pérez",
        "customer_email": "juan@ejemplo.com",
        "event_name": "Concierto de Rock",
        "session_datetime": "2025-05-15T20:00:00+00:00",
        "tickets": 2,
        "base_amount": 100.00,
        "discount_amount": -10.00,
        "fee_amount": 5.00,
        "payment_method": "card",
        "total_amount": 95.00,
        "currency": "EUR",
        "status": "completed"
      }
    ],
    "summary": {
      "transactions": 50,
      "purchases": 40,
      "refunds": 5,
      "reservations": 5,
      "tickets": 120,
      "base_amount": 3000.00,
      "discount_amount": -200.00,
      "fee_amount": 150.00,
      "total_amount": 2950.00,
      "refund_amount": 250.00,
      "net_amount": 2700.00,
      "currency": "EUR"
    }
  },
  "message": "Sales report retrieved successfully"
}

Lista de transacciones (`data[].*`)

Campo	Tipo	Descripción
`id`	`integer`	ID interno de la orden
`order_reference`	`string`	Código legible de la orden (p.ej. `ABC-123`)
`type`	`string`	`purchase` (compra), `refund` (devolución), `reservation` (reserva)
`datetime`	`string` (ISO 8601)	Fecha y hora de creación
`customer_name`	`string` o `null`	Nombre completo del comprador
`customer_email`	`string` o `null`	Email del comprador
`event_name`	`string` o `null`	Nombre del evento
`session_datetime`	`string` o `null`	Fecha/hora de la sesión
`tickets`	`integer`	Número de entradas en la orden
`base_amount`	`float`	Suma del precio base de las entradas
`discount_amount`	`float`	Suma de descuentos (valor negativo)
`fee_amount`	`float`	Suma de gastos de gestión
`payment_method`	`string` o `null`	Método de pago usado
`total_amount`	`float`	Importe total de la orden
`currency`	`string`	Código de moneda (p.ej. `EUR`)
`status`	`string`	`completed` o `cancelled`

Resumen (`summary.*`)

Campo	Descripción
`transactions`	Total de transacciones en el resultado
`purchases`	Número de compras
`refunds`	Número de devoluciones
`reservations`	Número de reservas
`tickets`	Total de entradas vendidas
`base_amount`	Suma del precio base
`discount_amount`	Suma de descuentos aplicados
`fee_amount`	Suma de gastos de gestión
`total_amount`	Importe total facturado
`refund_amount`	Importe devuelto (valor absoluto)
`net_amount`	Importe neto (total_amount - refund_amount)
`currency`	Moneda del resumen

Paso 4: Ejemplos prácticos

Ejemplo 1: Dashboard diario

Un quiosco quiere mostrar al cierre del día cuánto ha vendido:

bash

# Obtener token
TOKEN=$(curl -s -X POST "https://api.bticketing.com/api/sales-channel/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{"sales_channel_slug":"teatro-calderon","widget_key":"wk_xxxx"}' \
  | jq -r '.data.access_token')

# Ventas del día de hoy
curl -s "https://api.bticketing.com/api/sales-channel/v1/teatro-calderon/es/reports/sales?date_from=2025-04-27&date_to=2025-04-27" \
  -H "Authorization: Bearer $TOKEN" | jq '.data.summary'

Ejemplo 2: Informe mensual de un evento concreto

bash

TOKEN=$(curl -s -X POST "https://api.bticketing.com/api/sales-channel/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{"sales_channel_slug":"teatro-calderon","widget_key":"wk_xxxx"}' \
  | jq -r '.data.access_token')

curl -s "https://api.bticketing.com/api/sales-channel/v1/teatro-calderon/es/reports/sales?event_id=42&date_from=2025-03-01&date_to=2025-03-31" \
  -H "Authorization: Bearer $TOKEN" | jq '.data.summary'

Ejemplo 3: Sincronización de devoluciones

Saca todas las devoluciones de los últimos 7 días filtrando desde el código:

bash

TOKEN=$(curl -s ... | jq -r '.data.access_token')

curl -s "https://api.bticketing.com/api/sales-channel/v1/teatro-calderon/es/reports/sales?date_from=2025-04-20&date_to=2025-04-27" \
  -H "Authorization: Bearer $TOKEN" | jq '.data.data[] | select(.type == "refund")'

Buenas prácticas

Token Management: Solicita el token una vez y reutilízalo. Solo renueva cuando recibas un 401 Unauthorized.
Rangos acotados: No pidas más de 90 días de una vez. Si necesitas un histórico largo, fragmenta en ventanas de 90 días.
Cacheo: El límite es de 500 registros por llamada. Para conjuntos grandes, acota por fechas.
Frecuencia: Consulta el informe con la frecuencia que necesites (cada hora, cada día, etc.). No hay rate limiting específico para este endpoint, pero sé razonable.
Timezona: Todas las fechas se devuelven en formato ISO 8601 con offset UTC. Convierte a tu zona horaria local en el cliente.

Solución de problemas

Error	Código	Causa probable	Solución
`Unauthorized sales channel`	403	Token inválido o el slug de la URL no coincide con el canal del token	Renueva el token o verifica el slug
`The date range cannot exceed 90 days`	422	`date_from` y `date_to` distan más de 90 días	Reduce el rango a ≤ 90 días
`The given data was invalid`	422	Parámetros mal formados	Revisa el formato: `Y-m-d` para fechas, `integer` para IDs

Guía de integración: informe de ventas ​

Requisitos previos ​

Paso 1: Obtén un token de acceso ​

Paso 2: Consulta tu informe de ventas ​

URL ​

Sin filtros — todas las ventas ​

Filtrar por un evento concreto ​

Filtrar por varios eventos ​

Filtrar por rango de fechas ​

Combinar filtros ​

Paso 3: Entiende la respuesta ​

Lista de transacciones (data[].*) ​

Resumen (summary.*) ​

Paso 4: Ejemplos prácticos ​

Ejemplo 1: Dashboard diario ​

Ejemplo 2: Informe mensual de un evento concreto ​

Ejemplo 3: Sincronización de devoluciones ​

Buenas prácticas ​

Solución de problemas ​

Referencias ​

Guía de integración: informe de ventas

Requisitos previos

Paso 1: Obtén un token de acceso

Paso 2: Consulta tu informe de ventas

URL

Sin filtros — todas las ventas

Filtrar por un evento concreto

Filtrar por varios eventos

Filtrar por rango de fechas

Combinar filtros

Paso 3: Entiende la respuesta

Lista de transacciones (`data[].*`)

Resumen (`summary.*`)

Paso 4: Ejemplos prácticos

Ejemplo 1: Dashboard diario

Ejemplo 2: Informe mensual de un evento concreto

Ejemplo 3: Sincronización de devoluciones

Buenas prácticas

Solución de problemas

Referencias