Cuando tu negocio necesita integrar ticketing en su infraestructura existente, la calidad de la API es determinante. Si aún estás evaluando opciones, nuestra guía sobre cómo elegir plataforma de ticketing cubre los criterios clave. Una API mal diseñada significa meses de desarrollo, bugs constantes y limitaciones que descubres demasiado tarde. Esta guía te ayuda a evaluar qué buscar antes de comprometerte con una plataforma.
La buena noticia es que casi nada de lo que hay que exigir es opinión. La mayoría está escrito en especificaciones públicas: OpenAPI para el contrato, las RFC del IETF para la autenticación, los errores y el fin de vida de un endpoint, y la documentación del proveedor de pagos para la entrega de eventos. Lo que sigue es esa lista, con la referencia concreta al lado.
¿Qué indica la calidad de la documentación de una API?
La calidad de la documentación refleja la madurez de la API. Busca estos elementos:
- Especificación OpenAPI/Swagger: permite generar clientes automáticamente
- Ejemplos de código: en los lenguajes que usas (JS, Python, PHP...)
- Guías de casos de uso: no solo referencia, también tutoriales
- Changelog: historial de cambios y política de versionado
- Status page: visibilidad sobre la disponibilidad del servicio
El estándar tiene nombre y fecha. La OpenAPI Specification 3.1.0 se publicó el 15 de febrero de 2021 y exige un campo openapi con la versión de la especificación que usa el documento, distinto de la versión de la propia API. Admite JSON y YAML, y recomienda YAML 1.2 para que la conversión entre ambos no pierda información.
El contraste práctico es sencillo. Un documento OpenAPI válido se carga en un generador y produce un cliente tipado en tu lenguaje en minutos. Un PDF o una página de ejemplos sueltos no. Pide el fichero, no la captura de pantalla: si el proveedor no puede entregarte el openapi.yaml el mismo día que lo pides, la integración empieza con deuda.
¿Cómo debe autenticarse una API de ticketing segura?
La API maneja datos sensibles y transacciones económicas. La seguridad no es negociable.
- OAuth 2.0: estándar moderno para autenticación
- API keys con scopes: permisos granulares por key
- Rotación de credenciales: posibilidad de rotar sin downtime
- Rate limiting: protección contra abusos, con límites documentados
- Logs de acceso: auditoría de quién accede a qué
El marco base es la RFC 6749, que define el OAuth 2.0 Authorization Framework. Pero lo que conviene llevar a la reunión técnica es la RFC 9700, *Best Current Practice for OAuth 2.0 Security*, publicada en 2025. Tres de sus exigencias se comprueban en una tarde:
- Los servidores de autorización deben soportar PKCE, y los clientes públicos deben usarlo. Es la protección contra el robo del código de autorización.
- La validación de la *redirect URI* debe hacerse por comparación exacta de cadenas, con la única excepción de los puertos variables en
localhostpara aplicaciones nativas. Cualquier coincidencia por patrón es una puerta abierta. - Los tokens de acceso deberían estar ligados al emisor mediante mTLS o DPoP, para que un token filtrado no sirva en otras manos.
Si el proveedor solo ofrece una API key estática y eterna, no está descartado, pero el contrato debe cubrir lo que esa decisión implica: scopes reales, rotación sin cortar el servicio y registro de accesos que puedas exportar.
¿Qué endpoints esenciales debe cubrir la API?
Verifica que la API cubra todas las operaciones que necesitas.
- Eventos: crear, editar, listar, gestionar estados
- Entradas: tipos, precios, disponibilidad, reservas
- Órdenes: crear, consultar, cancelar, reembolsar
- Validación: verificar entradas, registrar accesos
- Webhooks: notificaciones de eventos (venta, acceso, etc.)
Hay una pregunta que decide más que la lista anterior: qué pasa si la misma petición llega dos veces. En ticketing, un reintento de red sobre una creación de orden puede duplicar una venta y bloquear un aforo que no existe. La respuesta correcta es una clave de idempotencia por operación de escritura, de forma que el segundo intento devuelva el resultado del primero en vez de crear un pedido nuevo. Pregúntalo por escrito y pide ver el comportamiento en sandbox.
La segunda pregunta es la paginación y los límites de lectura. Una API que no documenta cuántas órdenes devuelve por página ni cómo se recorre el histórico convierte cualquier exportación nocturna hacia tu dashboard de métricas en un problema de ingeniería propio.
¿Para qué sirven los webhooks en una integración?
Los webhooks son críticos para mantener tu sistema sincronizado sin polling constante.
- Eventos disponibles: qué acciones disparan webhooks
- Payload documentado: estructura clara de cada tipo de evento
- Reintentos: qué pasa si tu endpoint falla
- Verificación de firma: para validar que el webhook es auténtico
- Logs: historial de webhooks enviados y su estado
Cómo se verifica una firma
El procedimiento mejor documentado del sector es el de Stripe, y sirve de patrón incluso si tu proveedor es otro. Su documentación de webhooks describe una cabecera Stripe-Signature con una marca de tiempo con prefijo t= y una o varias firmas con prefijo de esquema; el único esquema válido en producción es v1. La firma se calcula como un HMAC con SHA-256 sobre la cadena formada por la marca de tiempo, un punto y el cuerpo JSON exacto de la petición, usando el secreto del endpoint como clave.
Tres detalles que rompen integraciones reales. Primero: hay que usar el cuerpo crudo; si tu framework reserializa el JSON, la verificación falla siempre. Segundo: la comparación debe hacerse en tiempo constante, para no filtrar información por el tiempo de respuesta. Tercero: las librerías oficiales aplican una tolerancia por defecto de 5 minutos entre la marca de tiempo y la hora actual, y la propia documentación advierte de no ponerla a cero, porque eso desactiva la comprobación de frescura y reabre el ataque de repetición.
Reintentos, duplicados y orden
Los números concretos importan al dimensionar tu cola. Stripe documenta reintentos automáticos durante un máximo de tres días con retroceso exponencial en modo producción, y tres reintentos en unas horas en sandbox. El reenvío manual funciona hasta 15 días desde el panel y hasta 30 días desde la CLI. Se pueden registrar hasta 16 endpoints de webhook.
Y dos advertencias que conviene copiar tal cual en tu diseño: no se garantiza el orden de entrega de los eventos, y un endpoint puede recibir el mismo evento más de una vez. La recomendación oficial es registrar los identificadores de evento ya procesados y no usar la marca de creación para deducir el orden. Además, el endpoint debe devolver un 2xx antes de la lógica pesada: cualquier respuesta 3xx se considera fallo de entrega, y un *timeout* dispara el ciclo de reintentos.
¿Cómo debe tratar la API los errores y los límites de uso?
Con formatos estándar, no con cadenas inventadas. La RFC 9457, *Problem Details for HTTP APIs*, publicada en 2023, define un cuerpo de error legible por máquina con cinco campos: type (URI que identifica el tipo de problema), title, status, detail e instance, servido como application/problem+json. Una API que lo usa te ahorra escribir un traductor de errores por cada proveedor.
Para los límites de uso, la referencia es la RFC 6585, *Additional HTTP Status Codes*, de abril de 2012, que introdujo el código 429 Too Many Requests. La propia especificación dice que la respuesta debería incluir detalles que expliquen la condición y puede incluir una cabecera Retry-After indicando cuánto esperar. Esa cabecera es la diferencia entre un reintento con criterio y un bucle que empeora la saturación.
Pregunta en la evaluación qué límites aplica la API por minuto y por clave, si son distintos en lectura y escritura, y qué ocurre en los picos de una salida a la venta, que es justo el momento en que tu integración más llama. Una plataforma que no publica sus límites te está pidiendo que los descubras en el peor día posible.
¿Por qué necesito un entorno de pruebas (sandbox)?
Desarrollar contra producción es una receta para el desastre. Exige un sandbox adecuado.
- Entorno sandbox separado: datos de prueba sin afectar producción
- Tarjetas de prueba: para simular pagos sin cargos reales
- Datos de ejemplo: eventos y entradas precargados para probar
- Paridad con producción: mismo comportamiento, mismas respuestas
Añade una prueba que casi nadie hace en la evaluación: forzar los errores. Un sandbox útil permite simular un pago rechazado, un reembolso parcial, una autenticación del banco que el comprador abandona y un webhook que llega tarde. Si solo puedes probar el camino feliz, no has probado nada.
El reloj también cuenta. Comprueba que el sandbox permite adelantar la fecha de un evento para verificar el cierre de ventas, la validación en puerta y la generación de informes posteriores sin esperar semanas.
¿Qué obligaciones legales arrastra la integración?
Dos frentes, y ninguno es opcional en la Unión Europea.
El primero son los pagos. El Reglamento Delegado (UE) 2018/389 exige en su artículo 4 que la autenticación se base en dos o más elementos de las categorías conocimiento, posesión e inherencia, y en su artículo 5 la vinculación dinámica: el código generado debe ser específico para el importe y el beneficiario aceptados por el ordenante. Su artículo 16 recoge la exención de escasa cuantía: operaciones de hasta 30 EUR, con un acumulado previo que no exceda de 100 EUR o un máximo de cinco operaciones remotas consecutivas. Tu integración tiene que saber devolver al comprador al flujo tras una autenticación, y eso se prueba en sandbox, no en la noche de la salida a la venta. Si vendes en España, conviene cruzarlo con los métodos de pago disponibles.
El segundo son los datos. El Reglamento (UE) 2016/679 obliga en su artículo 32 a aplicar medidas técnicas y organizativas apropiadas, incluidos el cifrado y la capacidad de garantizar confidencialidad e integridad, y en su artículo 33 a notificar las violaciones de seguridad a la autoridad de control sin dilación indebida y, de ser posible, en un plazo máximo de 72 horas. La API que te entrega correos y teléfonos de asistentes te convierte en responsable de lo que hagas con ellos: el contrato de encargado del tratamiento se firma antes de la primera llamada, no después. El detalle operativo está en nuestra guía de RGPD para organizadores.
¿Cómo se versiona y se deprecia una API sin romper tu integración?
Con reglas públicas. El versionado semántico 2.0.0 reserva el incremento de versión mayor para los cambios incompatibles con versiones anteriores, el menor para funcionalidad compatible y el de parche para correcciones. Aplicado a una API, significa que un cambio que rompe tu cliente no puede llegar en un despliegue silencioso de un martes.
Para el fin de vida existe una cabecera estándar. La RFC 8594, de mayo de 2019, define el campo de respuesta HTTP Sunset con una única marca temporal que indica cuándo es probable que el recurso deje de responder, y un tipo de relación de enlace sunset para apuntar a la política de retirada o migración. Preguntar si la API la emite es una forma rápida de saber si el proveedor ha pensado en el ciclo de vida o solo en el lanzamiento.
Lo mismo vale para el widget de venta embebido: si su JavaScript se sirve desde una URL sin versión, cualquier cambio del proveedor llega a tu web sin aviso.
¿Qué soporte técnico debe ofrecer el proveedor?
Cuando algo falla a las 2 de la madrugada antes de tu evento, necesitas respuestas rápidas.
- Canal técnico: acceso a desarrolladores, no solo a soporte genérico
- SLA documentado: tiempos de respuesta comprometidos
- Comunidad: foro o Slack donde resolver dudas
- Onboarding técnico: sesión de integración guiada
Pide que el SLA diga tres cosas con números: tiempo de primera respuesta por severidad, ventana horaria cubierta y qué pasa si se incumple. Un compromiso sin consecuencia es una declaración de intenciones. Y pregunta por la ventana de cambios: una plataforma que despliega en producción un viernes de salida a la venta tiene un problema de proceso, no de tecnología.
¿Cómo elijo la API de ticketing correcta?
Una buena API de ticketing acelera tu desarrollo, reduce bugs y te permite construir experiencias personalizadas. También es la base para integrar un widget de venta embebido en tu propia web o conectar tu dashboard de métricas. Una mala API te atrapa en limitaciones que descubres demasiado tarde. Invierte tiempo en evaluar antes de comprometerte: pide acceso al sandbox, prueba los endpoints críticos y habla con el equipo técnico. La decisión correcta te ahorrará meses de frustración.
Nueve comprobaciones concretas para esa evaluación:
- Pide el fichero OpenAPI, no la documentación en HTML. Si no existe, genera tú el cliente y súmalo al coste del proyecto.
- Exige PKCE y validación exacta de la redirect URI si hay OAuth 2.0, tal como pide la RFC 9700.
- Prueba la idempotencia: lanza dos veces la misma creación de orden y comprueba que solo se crea una.
- Verifica una firma de webhook a mano antes de confiar en la librería, y fija una tolerancia temporal distinta de cero.
- Haz fallar tu endpoint a propósito y mide cuántos reintentos llegan, durante cuánto tiempo y con qué cabeceras.
- Duplica un webhook y comprueba que tu sistema no vende dos veces la misma entrada.
- Pregunta los límites de uso por clave y si la API devuelve
429conRetry-After. - Comprueba el formato de error:
application/problem+jsoncontype,title,status,detaileinstanceahorra semanas. - Pregunta por la cabecera Sunset y por la política de versionado antes de firmar, no cuando llegue el aviso.
Fuentes
- OpenAPI Specification v3.1.0, 15 de febrero de 2021 (OpenAPI Initiative)
- OpenAPI/Swagger Specification (SmartBear, Swagger)
- OAuth 2.0, página oficial del estándar
- RFC 6749: The OAuth 2.0 Authorization Framework (IETF)
- RFC 9700: Best Current Practice for OAuth 2.0 Security (IETF, 2025)
- RFC 9457: Problem Details for HTTP APIs (IETF, 2023)
- RFC 6585: Additional HTTP Status Codes, abril de 2012 (IETF)
- RFC 8594: The Sunset HTTP Header Field, mayo de 2019 (IETF)
- Semantic Versioning 2.0.0, especificación en español
- Receive Stripe events in your webhook endpoint, documentación oficial de Stripe
- Reglamento Delegado (UE) 2018/389, normas técnicas de regulación para la autenticación reforzada de clientes (EUR-Lex)
- Reglamento (UE) 2016/679, Reglamento General de Protección de Datos (EUR-Lex)