CBus API for Developers v1

Bienvenido a la documentación oficial de la CBus API for Developers v1. CBus es una plataforma líder en la gestión de flotas y venta de boletos para empresas de autotransporte.

Esta API RESTful proporciona a los desarrolladores un conjunto de endpoints para interactuar directamente con el sistema de ventas de CBus. El objetivo es permitir la integración de sistemas de terceros, agencias de viaje en línea (OTAs) y aplicaciones personalizadas para:

• Consultar orígenes, destinos y horarios en tiempo real.
• Ver la disponibilidad y precios de asientos en corridas específicas.
• Gestionar el ciclo de vida completo de una reservación, desde el apartado temporal hasta la confirmación del pago.

Sigue esta guía para entender el flujo de autenticación, los entornos disponibles y cada uno de los endpoints.

Autenticación

Todos los endpoints requieren autenticación mediante una API Key, tanto en Sandbox como en Producción. La API Key se obtiene contactando al equipo de CBus y está asociada a la instancia del transportista.

Puedes enviar la API Key de cualquiera de estas tres formas (elige una):

Opción 1 — Header Authorization: Bearer (recomendado)

Authorization: Bearer TU_API_KEY
Accept: application/json

Opción 2 — Header X-API-Key

X-API-Key: TU_API_KEY
Accept: application/json

Opción 3 — Query parameter api_key

GET /api/dev/v1/origenes?api_key=TU_API_KEY

Modo Sandbox vs Modo Producción

Cada API Key tiene un flag is_production. Las keys en modo producción tienen una restricción adicional: el endpoint /confirmar exige que la key tenga configuradas restricciones de IP o dominio permitido en el panel de CBus. Sin esas restricciones, /confirmar responderá con 403. Las keys en modo sandbox no aplican esta restricción.

Errores de autenticación

Entorno Sandbox

Todas las URL de los endpoints listados a continuación deben usar la siguiente URL base correspondiente al entorno de pruebas:

• URL Base: https://demo.cbus.com.mx
• Prefijo: /api/dev/v1
• URL Completa de Ejemplo: https://demo.cbus.com.mx/api/dev/v1/origenes

Flujo General de Venta

El proceso de reserva y confirmación de un boleto sigue un flujo específico de varios pasos. No puedes confirmar un boleto sin antes haberlo seleccionado y reservado.

1. Búsqueda:
   • GET /api/dev/v1/origenes -> Obtiene la lista de todas las ciudades de origen.
   • GET /api/dev/v1/destinos -> Obtiene los destinos disponibles desde un origen.
   • GET /api/dev/v1/horarios -> Obtiene las corridas y horarios para una ruta y fecha.
2. Selección:
   • POST /api/dev/v1/asientos -> Muestra el mapa de asientos disponibles para un horario.
   • POST /api/dev/v1/seleccionar-asiento -> Aparta temporalmente un asiento. Devuelve una clave única.
3. Reserva:
   • POST /api/dev/v1/reservar -> Agrupa todas las claves de asientos (ida y regreso) bajo los datos de un cliente. Devuelve una clave_global.
4. Confirmación:
   • POST /api/dev/v1/confirmar -> Finaliza la compra usando la clave_global y marca los boletos como "pagados".
5. (Opcional) Cancelación:
   • POST /api/dev/v1/deseleccionar-asiento -> Libera un asiento que fue apartado temporalmente.
   • POST /api/dev/v1/boletos/cancelar -> Cancela un boleto ya pagado.
6. (Opcional) Facturación CFDI 4.0:
   • POST /api/dev/v1/facturacion/emitir -> Timbra una factura para los boletos de una clave_global.
   • POST /api/dev/v1/facturacion/cancelar -> Marca una factura como cancelada localmente.
7. (Opcional) Paquetería:
   • POST /api/dev/v1/envios/preregistrar -> Pre-registra un envío.
   • GET /api/dev/v1/envios/rastreo -> Consulta el estado y seguimiento de un envío por clave.

Planes de API y Límites de Tasa (Rate Limiting)

El acceso a la API está sujeto a límites de tasa (Rate Limiting) que dependen del plan de API adquirido para la instancia de CBus WEB. La Api_key asociada a la instancia de la empresa de transporte tendrá el límite de solicitudes por minuto (x-ratelimit-limit) correspondiente a su plan.

Si se excede el límite correspondiente al plan de la instancia, la API comenzará a responder con un código de error 429 Too Many Requests. Para adquirir o cambiar de plan, es necesario contactar al equipo de ventas de CBus.

Cuotas de Uso (Quotas)

Responsabilidades del Desarrollador

GET /api/dev/v1/origenes

Obtiene una lista de todas las escalas (orígenes) disponibles.

Parámetros de Query

Ninguno.

Respuesta Exitosa (200 OK)

[
    {
        "id": 5,
        "nombre": "CDMX",
        "lat": null,
        "lng": null,
        "abordajes": []
    },
    {
        "id": 1,
        "nombre": "GPE",
        "lat": null,
        "lng": null,
        "abordajes": []
    },
    {
        "id": 3,
        "nombre": "OAXACA",
        "lat": null,
        "lng": null,
        "abordajes": []
    },
    {
        "id": 4,
        "nombre": "PUEBLA",
        "lat": null,
        "lng": null,
        "abordajes": []
    },
    {
        "id": 2,
        "nombre": "TEPIC",
        "lat": null,
        "lng": null,
        "abordajes": []
    }
]

GET /api/dev/v1/destinos

Obtiene los destinos disponibles basado en un nombre de origen.

Parámetros de Query

Respuesta Exitosa (200 OK)

[
    {
        "id": 3,
        "nombre": "OAXACA",
        "lat": null,
        "lng": null,
        "abordajes": []
    },
    {
        "id": 4,
        "nombre": "PUEBLA",
        "lat": null,
        "lng": null,
        "abordajes": []
    }
]

GET /api/dev/v1/horarios

Obtiene los horarios disponibles para una ruta y fechas específicas.

Parámetros de Query

Respuesta Exitosa (200 OK)

{
    "ida": [
        {
            "id": 3,
            "corrida_id": 2,
            "ab_ba": "ba",
            "ab": 1,
            "hora_salida": "14:00:00",
            "fcomp": 0,
            "fecha": "2025-10-30",
            "minutos_trayecto": 480,
            "activo": 1,
            "aplicar_venta_linea": 1,
            "corrida": {
                "id": 2,
                "nombre": "Oaxaca-CDMX",
                "mostrar_pv": 1,
                "aplicar_en_reservaciones": 1,
                "aplicar_venta_linea": 1,
                "extraordinaria": 0,
                "fechas_deshabilitadas": [],
                "activo": 1
            },
            "origen": {
                "id": 5,
                "nombre": "CDMX",
                "hora": "2:00 pm"
            },
            "destino": {
                "id": 3,
                "nombre": "OAXACA",
                "hora": "10:00 pm"
            },
            "disponibilidad": {
                "asientos_disponibles": 20,
                "asientos_ocupados": 0,
                "total_asientos": 20,
                "ultima_actualizacion": "2025-10-29T00:00:00.000000Z"
            }
        }
    ],
    "regreso": [
        {
            "id": 3,
            "corrida_id": 2,
            "ab_ba": "ab",
            "ab": 1,
            "hora_salida": "14:00:00",
            "fcomp": 0,
            "fecha": "2025-11-01",
            "minutos_trayecto": 480,
            "...": "..."
        }
    ]
}

GET /api/dev/v1/sucursales

Obtiene el listado completo de sucursales con su información detallada.

Parámetros de Query

Ninguno.

Respuesta Exitosa (200 OK)

{
    "success": true,
    "data": [
        {
            "id": 1,
            "nombre": "Terminal Central",
            "direccion": "Av. Principal 123",
            "estado": "Jalisco",
            "colonia": "Centro",
            "localidad": "Guadalajara",
            "municipio": "Guadalajara",
            "pais": "MX",
            "codigo_postal": "44100",
            "telefono_1": "3312345678",
            "telefono_2": null,
            "telefono_3": null,
            "lat": "20.659698",
            "lng": "-103.349609",
            "descripcion": "Terminal principal de autobuses",
            "datos_ticket_id": null,
            "pais_nombre": "México"
        }
    ],
    "total": 1
}

POST /api/dev/v1/asientos

Obtiene el mapa de asientos (layout) de un autobús para un horario específico, indicando cuáles están disponibles, ocupados o bloqueados.

Cuerpo de la Solicitud (JSON)

Ejemplo de Solicitud

{
    "ab": 1,
    "corrida": 2,
    "origen": 5,
    "destino": 3,
    "horario": 3,
    "redondo": 0,
    "fecha": "2025-10-31"
}

Respuesta Exitosa (200 OK)

{
    "escalas": {
        "origen": "CDMX",
        "destino": "OAXACA"
    },
    "precio": [ ... ],
    "hora": {
        "salida": "2:00 pm",
        "llegada": "10:00 pm"
    },
    "asientos": [
        {
            "id": 21,
            "numero": 1,
            "corrida_id": 2,
            "categoria": null,
            "categoria_abreviacion": null,
            "forma_calculo_valor": null,
            "valor": null,
            "reservaciones": [],
            "disponible": true,
            "fcomp": 0,
            "horario_id": 3,
            "origen_id": 5,
            "destino_id": 3,
            "ab": false,
            "fecha_reservacion": "2025-10-31",
            "prefix": "000"
        },
        {
            "id": 22,
            "numero": 2,
            "corrida_id": 2,
            "..." : "..."
        }
    ],
    "total_asientos": 20,
    "abordajes": [],
    "fecha_reservacion": "31-10-2025",
    "fcomp": 0
}

Nota Importante sobre la Respuesta

La respuesta de este endpoint es crucial. Cada objeto dentro del array asientos contiene los IDs exactos que necesitarás para el siguiente paso (/api/dev/v1/seleccionar-asiento).

Debes capturar y utilizar los siguientes valores del asiento que elija el usuario:

• id (Se usará como asiento)
• corrida_id (Se usará como corrida)
• horario_id (Se usará como horario)
• origen_id (Se usará como origen)
• destino_id (Se usará como destino)
• ab (Se usará tal cual, es fundamental)

GET /api/dev/v1/render

Obtiene una representación visual (HTML) del autobús con la disposición de sus asientos y su estado de disponibilidad en tiempo real.

Este endpoint es ideal para ser mostrado en un <iframe> dentro de la aplicación del socio comercial.

Parámetros de Consulta (Query Params)

Ejemplo de Uso (Iframe)

<iframe src="https://cbus.com.mx/api/dev/v1/render?api_key=TU_API_KEY&corrida=2&horario=3&origen=5&destino=3&fecha=2025-10-31" width="100%" height="600" frameborder="0"></iframe>

Respuesta

Devuelve un documento HTML completo con estilos embebidos que renderiza el mapa del autobús.

POST /api/dev/v1/seleccionar-asiento

Aparta temporalmente un asiento específico. Este asiento se bloqueará por un tiempo limitado (ej. 10 minutos) y se generará una clave única para esta selección.

Cuerpo de la Solicitud (JSON)

Ejemplo de Solicitud

{
    "corrida":"2",
    "origen":"5",
    "destino":"3",
    "horario":"3",
    "asiento":"23",
    "tipo_persona":"adulto",
    "ab": 0,
    "fecha": "2025-10-31",
    "canal_venta":"TU CANAL",
    "observaciones": "Texto que saldrá en los reportes y boleto"
}

Respuesta Exitosa (200 OK)

{
    "cliente": "N/A",
    "asiento_id": "23",
    "horario_id": "3",
    "corrida_id": "2",
    "redondo": null,
    "fecha_reservacion": "2025-10-31",
    "fcomp": 0,
    "origen_id": "5",
    "destino_id": "3",
    "estatus": "apartado",
    "tipo_persona": "adulto",
    "clave": "YGBD2D",
    "ab": false,
    "is_plt_reservacion": true,
    "canal_venta": "TU CANAL",
    "updated_at": "2025-10-30T02:29:45.000000Z",
    "created_at": "2025-10-30T02:29:45.000000Z",
    "id": 3,
    "abordajes": [],
    "expiracion": {
        "fecha_expira": "2025-10-29T20:39:45.666850Z",
        "fecha_expira_diff_h": "en 9 minutos",
        "fecha_expira_mins": 9
    },
    "observaciones": "Texto que saldrá en los reportes y boleto",
    "precio": 350.00
}

Nota Importante sobre la clave

La clave (ej: "YGBD2D") devuelta por este endpoint es **temporal** y se usa para agrupar el asiento en el siguiente paso (/api/dev/v1/reservar).

Al ser usada en /reservar, la API generará una nueva clave final (con caracteres diferentes). Además, si se trata de un viaje redondo, las claves finales tendrán un sufijo: -1 para el viaje de ida y -2 para el viaje de regreso.

POST /api/dev/v1/deseleccionar-asiento

Libera un asiento que fue apartado (con /seleccionar-asiento) antes de que expire su tiempo. Esto cancela la pre-reserva de ese asiento individual.

Cuerpo de la Solicitud (JSON)

Ejemplo de Solicitud

{
    "clave": "YGBD2D"
}

Respuesta Exitosa (200 OK)

{
    "message": "Clave cancelada"
}

POST /api/dev/v1/reservar

Asigna los datos de un cliente a uno o más asientos apartados (claves). Esto agrupa todas las selecciones de asientos bajo una clave_global y prepara la orden para el pago.

Cuerpo de la Solicitud (JSON)

Ejemplo de Solicitud (Viaje Redondo)

{
    "cliente": {
        "nombre": "Fulanito Pérez",
        "celular": "9585846497",
        "email": "alejandro@cbus.com.mx"
    },
    "reservaciones": {
        "ida": [
            {
                "clave": "YGBD2D",
                "observaciones": "Pasajero adulto, ventana"
            }
        ],
        "regreso": [
            {
                "clave": "HJD8K1",
                "observaciones": "Pasajero adulto, pasillo"
            }
        ]
    },
    "abordajes": {
        "ida": 1,
        "regreso": 3
    }
}

Respuesta Exitosa (200 OK)

{
    "clave_global": "YBR7HRGL",
    "divisa": "MXN",
    "cliente": {
        "nombre": "Fulanito Pérez",
        "telefono": "9585846497"
    },
    "primer_viaje": false,
    "reservaciones": {
        "ida": [
            {
                "id": 3,
                "cliente": "Fulanito Pérez",
                "celular": "9585846497",
                "email": "alejandro@cbus.com.mx",
                "redondo": true,
                "clave": "YGBD2D-1",
                "observaciones": "Pasajero adulto, ventana"
            }
        ],
        "regreso": [
            {
                "id": 4,
                "cliente": "Fulanito Pérez",
                "celular": "9585846497",
                "email": "alejandro@cbus.com.mx",
                "redondo": true,
                "clave": "YGBD2D-2",
                "observaciones": "Pasajero adulto, pasillo"
            }
        ]
    },
    "expiracion": {
        "fecha_expira": "2025-10-30T06:31:37.360615Z",
        "fecha_expira_diff_h": "en 3 horas",
        "fecha_expira_mins": 120
    },
    "total": 1400.00,
    "total_original": 1552.00,
    "checkout_url": null,
    "checkout_status": null,
    "checkout_requested": false,
    "checkout_error": null,
    "enviar_link_pago": false
}

Errores Posibles (422)

POST /api/dev/v1/confirmar

Confirma la reservación y marca todos los boletos asociados a la clave_global como "pagados". Este es el último paso del flujo. La respuesta incluye detalles de los boletos confirmados, información de las sucursales/terminales relevantes al origen del viaje, y los datos fiscales de la empresa transportista.

Cuerpo de la Solicitud (JSON)

Ejemplo de Solicitud

{
    "clave_global": "YBR7HRGL",
    "tipo_pago": "TD",
    "total": 700,
    "total_original": 776
    "observaciones": "Folio de transacción MTI1MzU0Ng | Venta relizada por desarrollador independiente"
}

Respuesta Exitosa (200 OK)

La respuesta contiene un array reservaciones con los boletos confirmados, un array sucursales con la información de las terminales asociadas al origen del primer boleto (útil para mostrar dirección, teléfonos, ubicación), y un objeto empresa con los datos fiscales del transportista.

{
    "reservaciones": [
        {
            "id": 3,
            "cliente": "Fulanito Pérez",
            "celular": "9585846497",
            "email": "alejandro@cbus.com.mx",
            "redondo": false,
            "costo_boleto": 700,
            "clave": "YGBD2D", // Clave final del boleto
            "fecha_reservacion": "2025-10-31",
            "fcomp": 0,
            "estatus": "pagado",
            "costo_boleto_original": 776,
            "is_plt_reservacion": 1,
            "tipo_persona": "adulto",
            "corrida_id": 2,
            "asiento_id": 23,
            "horario_id": 3,
            "origen_id": 5,
            "destino_id": 3,
            "ab": 0,
            "created_at": "2025-10-30T02:31:37.000000Z",
            "updated_at": "2025-10-30T02:31:46.000000Z",
            "abordaje_id": null,
            "canal_venta": "TU CANAL",
            "observaciones": "Folio de transacción MTI1MzU0Ng | Venta relizada por desarrollador independiente",
            "origen": {
                "id": 5,
                "nombre": "CDMX"
            },
            "destino": {
                "id": 3,
                "nombre": "OAXACA"
            },
            "abordaje": null,
            "boleto_url": "https://demo.cbus.com.mx/boleto/compartir/YGBD2D"
        }
        // ... más boletos si la clave_global agrupaba varios
    ],
    "sucursales": [ // Información de terminales/sucursales asociadas al origen
         {
            "nombre": "Terminal Central CDMX",
            "direccion": "Av. Principal 123",
            "estado": "Ciudad de México",
            "comision": null, // Campo interno, puede ignorarse
            "codigo_postal": "01234",
            "telefono_1": "5512345678",
            "telefono_2": null,
            "telefono_3": null,
            "descripcion": "Terminal principal en CDMX",
            "pais": "México",
            "colonia": "Centro",
            "localidad": null,
            "municipio": "Cuauhtémoc",
            "lat": "19.4326",
            "lng": "-99.1332"
        }
        // ... puede haber más sucursales relacionadas al origen
    ],
    "empresa": { // Datos fiscales de la empresa transportista
        "nombre": "CBus DEMO",
        "rfc": "ALEJANDRO TONATIUH BERNAL ZAMORANO",
        "razon_social": null,
        "calle": "Jilguero 57",
        "tel_1": "",
        "tel_2": "",
        "tel_3": "",
        "cp": "63170"
    },
    "clave_global": "YBR7HRGL"
}

Errores Posibles

POST /api/dev/v1/boletos/actualizar-nombre

Permite asignar el nombre del pasajero a un boleto que ya fue pagado. Este endpoint está diseñado para flujos donde el pago se confirma antes de que el nombre del pasajero esté disponible. Solo puede ejecutarse una sola vez por boleto y únicamente si la fecha de viaje aún no ha pasado.

Cuerpo de la Solicitud (JSON)

Ejemplo de Solicitud

{
    "clave": "YGBD2D",
    "nombre": "Juan Pérez García"
}

Respuesta Exitosa (200 OK)

{
    "message": "Nombre actualizado correctamente.",
    "clave": "YGBD2D",
    "nombre": "Juan Pérez García"
}

Errores Posibles (422)

POST /api/dev/v1/boletos/cancelar

Permite cancelar un boleto que ya fue pagado o confirmado. Al ejecutar este endpoint, se cambiará el estatus del boleto a cancelado, y si el pago fue realizado por tarjeta (Stripe), se procesará la cancelación en la pasarela. Además se hará la devolución pertinente de puntos premia si el pasajero contaba con ellos.

Cuerpo de la Solicitud (JSON)

Ejemplo de Solicitud

{
    "clave": "YGBD2D",
    "motivo": "Cancelación solicitada por el cliente."
}

Respuesta Exitosa (200 OK)

{
    "message": "Boleto cancelado correctamente.",
    "clave": "YGBD2D"
}

Errores Posibles (422)

POST /api/dev/v1/envios/preregistrar

Permite a socios comerciales dar de alta un envío en estado de "Pre-registro". Esta modalidad no requiere conocer escalas ni costos, ya que el sistema administrativo lo completará cuando el paquete sea entregado físicamente en una sucursal.

Nota: Este endpoint no genera ticket digital ni PDF.

Cuerpo de la Solicitud (JSON)

Ejemplo de Solicitud

{
    "remitente": "Juan Pérez",
    "telefono_remitente": "9511234567",
    "destinatario": "María López",
    "telefono_destinatario": "9519876543",
    "descripcion": "Caja con 5kg de café",
    "modalidad_pago": "por_pagar"
}

Respuesta Exitosa (201 Created)

{
    "success": true,
    "clave": "ENV-784521",
    "mensaje": "Pre-registro guardado. Use esta clave al entregar el paquete en sucursal."
}

GET /api/dev/v1/envios/rastreo

Consulta el estado actual y el historial de seguimiento de un envío (paquetería) a partir de su clave única. Devuelve los datos del envío, las sucursales de origen y destino, y todos los eventos de rastreo registrados en orden cronológico.

Parámetros de Query

Ejemplo de Solicitud

GET /api/dev/v1/envios/rastreo?clave=PAQ-784521
Authorization: X-API-KEY tu_api_key

Respuesta Exitosa (200 OK)

{
    "clave": "PAQ-784521",
    "estatus": "en_transito",
    "remitente": "Juan Pérez",
    "destinatario": "María López",
    "sucursal_origen": "Terminal Oaxaca Centro",
    "sucursal_destino": "Terminal Ciudad de México",
    "fecha_envio": "2026-06-01",
    "fecha_entrega": null,
    "seguimiento": [
        {
            "descripcion": "Paquete registrado en sucursal origen",
            "fecha": "2026-06-01 09:15:00"
        },
        {
            "descripcion": "En viaje a sucursal destino PAQ-784521",
            "fecha": "2026-06-01 14:30:00"
        },
        {
            "descripcion": "Recepción en sucursal destino PAQ-784521",
            "fecha": "2026-06-02 08:45:00"
        }
    ]
}

Valores posibles de estatus

Errores Posibles

POST /api/dev/v1/facturacion/emitir

Genera y timbra una factura CFDI 4.0 para un grupo de boletos ya pagados, identificados por su clave_global. El CFDI se emite ante el SAT en tiempo real a través de Soicont y devuelve las URLs del PDF y XML firmados.

Cuerpo de la Solicitud (JSON)

Ejemplo de Solicitud

{
    "clave_global": "YBR7HRGL",
    "rfc": "BAZO900101ABC",
    "nombre": "Juan Pérez García",
    "email": "juan.perez@ejemplo.com",
    "uso_cfdi": "G03",
    "forma_pago": "03",
    "regimen_fiscal": "626",
    "domicilio_fiscal": "63170"
}

Respuesta Exitosa (200 OK)

{
    "uuid": "6128a3f1-4e2c-4d1a-9b3e-7c8d2f1e0a45",
    "folio": "1042",
    "pdf": "https://storage.cbus.com.mx/reservaciones/YBR7HRGL/factura.pdf",
    "xml": "https://storage.cbus.com.mx/reservaciones/YBR7HRGL/factura.xml"
}

Errores Posibles (422)

POST /api/dev/v1/facturacion/cancelar

Marca una factura como cancelada en el sistema y libera los boletos asociados para que puedan refacturarse. La cancelación fiscal ante el SAT debe completarse manualmente desde el panel de Soicont (soicont.com.mx), ya que el proveedor no expone un endpoint de cancelación por API.

Cuerpo de la Solicitud (JSON)

Ejemplo de Solicitud

{
    "uuid": "6128a3f1-4e2c-4d1a-9b3e-7c8d2f1e0a45"
}

Respuesta Exitosa (200 OK)

{
    "message": "Factura marcada como cancelada localmente. Completa la cancelación fiscal desde el panel de Soicont (soicont.com.mx) usando el UUID proporcionado.",
    "uuid": "6128a3f1-4e2c-4d1a-9b3e-7c8d2f1e0a45"
}

Errores Posibles

{
    "message": "The given data was invalid.",
    "errors": {
        "corrida": [
            "El campo corrida es obligatorio."
        ],
        "horario": [
            "El campo horario es obligatorio."
        ],
        "fecha": [
            "El campo fecha debe ser una fecha posterior o igual a hoy."
        ]
    }
}

{
    "message": "El asiento ya no está disponible"
}

{
    "errors": {
        "message": "Has execedido el tiempo de reservación o las claves no existen, inicia de nuevo."
    }
}

{
    "message": "Not Found"
}

{
    "message": "Server Error"
}