Developer Hub

Guía de Integración API

Integra el poder de Bircat en tu sistema de manera segura. Realiza solicitudes de compra de servicios o tiempo aire y dales seguimiento en tiempo real.

Descargar PDF

Dos Formas de Integrar

Hemos diseñado nuestra API para ser flexible según las capacidades de tu arquitectura. Tienes dos flujos principales disponibles:

Flujo 1: Con Inicio de Sesión (JWT)Ideal si tu app puede guardar el token y usarlo en múltiples peticiones.
Flujo 2: Credenciales en cada PeticiónPerfecto para microservicios y sistemas servidor a servidor que no desean persistir sesiones.

Autenticación

Transacción

Prueba rápida con cURL

Ingresa tus datos para generar comandos listos para copiar y pegar en tu terminal.Nota: No compartir capturas con credenciales reales.

URL Base

ID Cedis

Username

Password

Flujo 1: Obtener Token (POST /auth/login)

curl -X POST 'https://api.bircat.com/auth/login' \ -H 'Content-Type: application/json' \ -d '{ "idCedis": 10, "username": "su_usuario", "password": "su_contraseña" }'

Flujo 1: Comprar con Token (POST /transactions/purchase)

curl -X POST 'https://api.bircat.com/transactions/purchase' \ -H 'Authorization: Bearer <TU_TOKEN>' \ -H 'Content-Type: application/json' \ -d '{ "reference": "5551234567", "sku": "TA-TELCEL-100", "externalId": "req-987654", "externalDate": "20260413150000" }'

Flujo 1: Consultar Estado (GET /transactions/purchase)

curl -X GET 'https://api.bircat.com/transactions/purchase?externalId=req-987654' \ -H 'Authorization: Bearer <TU_TOKEN>'

Flujo 2: Comprar con Credenciales (POST /transactions/purchase/byCredentials)

curl -X POST 'https://api.bircat.com/transactions/purchase/byCredentials' \ -H 'Content-Type: application/json' \ -d '{ "idCedis": 10, "username": "su_usuario", "password": "su_contraseña", "reference": "5551234567", "sku": "TA-TELCEL-100", "externalId": "req-987654", "externalDate": "20260413150000" }'

Flujo 2: Consultar Estado (POST /transactions/purchase/byCredentials/query)

curl -X POST 'https://api.bircat.com/transactions/purchase/byCredentials/query' \ -H 'Content-Type: application/json' \ -d '{ "idCedis": 10, "username": "su_usuario", "password": "su_contraseña", "externalId": "req-987654" }'

Flujo 1: Integración con Token JWT

Cargando diagrama...

1. Obteniendo el Token

Ruta: POST /auth/login

Envía tus credenciales para recibir un Token JWT válido temporalmente.

{
  "idCedis": 10,
  "username": "su_usuario",
  "password": "su_contraseña"
}

2. Solicitud de Compra

Ruta: POST /transactions/purchase

No olvides enviar el Bearer <token> en los headers.

{
  "reference": "5551234567",
  "sku": "TA-TELCEL-100",
  "externalId": "req-987654",
  "externalDate": "20260413150000"
}

Reglas de Seguimiento (Polling)

Es vital que consultes el estado hasta saber el estatus final de la compra para evitar transacciones duplicadas.

Máximo 60 Segundos

El reloj cuenta desde el instante en que enviaste la primera solicitud. Después de 60s, considera timeout.

Espera 5 Segundos

Entre cada consulta de estado `GET ...?externalId` haz pausas de 5s para no saturar al proveedor.

No Duplicar Compra

Nunca repetir la petición de POST de compra en este bucle. Consulta siempre con el mismo `externalId`.

Checklist Operativo de Polling

1
Iniciar cronómetro al enviar la solicitud de compra.
2
Esperar 5s entre consultas de estado.
3
Repetir solo consulta (nunca recompra en el bucle).
4
Cortar a los 60s asumiendo tiempo agotado.
5
Si 404 en consulta, detener y evaluar nueva compra.

Flujo 2: Credenciales en cada Petición

Cargando diagrama...

Cuerpo unificado para Flujo 2

Ruta: POST /transactions/purchase/byCredentials

Envías simultáneamente los datos de autenticación y los campos propios de la compra.

{
  "idCedis": 10,
  "username": "su_usuario",
  "password": "su_contraseña",
  "reference": "5551234567",
  "sku": "TA-TELCEL-100",
  "externalId": "req-987654",
  "externalDate": "20260413150000"
}

Consultas (POST .../query)

Para este endpoint, envía solo tus credenciales y el externalId:

{
  "idCedis": 10,
  "username": "su_usuario",
  "password": "su_contraseña",
  "externalId": "req-987654"
}

* Las reglas de tiempo y ruteo aplican igual que en el Flujo 1 (60 seg. máx).

Ejemplos de Respuesta

Estado Pendiente

Aún procesando. Sigue consultando.

{
  "header": {
    "code": 200,
    "message": "OK"
  },
  "data": {
    "idTransaction": "txn-12345",
    "externalId": "req-987654",
    "message": "En proceso...",
    "isCompleted": false
  }
}

Estado Final

Transacción completada exitosamente.

{
  "header": {
    "code": 200,
    "message": "OK"
  },
  "data": {
    "idTransaction": "txn-12345",
    "externalId": "req-987654",
    "response": "00",
    "message": "Transacción exitosa",
    "authNumber": "98765",
    "isCompleted": true,
    "isSuccess": true
  }
}