Saltar al contenido
Orion API

Realizar venta (TAE, Servicios, Pines)

Descripción

Realiza una venta de cualquier producto de tu catálogo: recarga de tiempo aire (TAE), pago de servicio (SERVICIO) o pin (PIN). El tipo de venta lo determina el carrier_id; el cuerpo de la petición es el mismo para los tres.

La respuesta es síncrona: Orion envía la venta al proveedor y responde con el resultado final en la misma llamada.

URL API

BASE URLhttps://api.faxil.mx/api/v1

Autenticación

HeaderRequeridoPermiso de la API Key
x-api-keySíSegún el carrier_group del producto: sales.tae, sales.services o sales.pins.
Content-TypeSíapplication/json

Parámetros de entrada

ParámetroTipoRequeridoDescripciónEjemplo
carrier_idnumber (entero)Síid del producto en tu catálogo.1
amountnumberSíMonto en MXN. Debe enviarse como número, no como texto. TAE y PIN: entero y autorizado para el producto. SERVICIO: positivo con hasta 2 decimales.50
dnstringSíNúmero celular (10 dígitos) o referencia del servicio, según el input_type del producto. Máximo 100 caracteres."5512345678"
foliostringSíIdentificador único de la venta generado por tu sistema. Máximo 100 caracteres."POS01-000123"

El folio es tu llave de idempotencia

  • Debe ser único por organización. Usa un UUID o un consecutivo propio.
  • Guárdalo en tu base de datos antes de enviar la venta.
  • Si envías un folio que ya existe, Orion no vuelve a vender: responde 409 Folio ya utilizado; consulta su estado.
  • Con ese mismo folio consultas el estado en Consultar transacción.

Ejemplo de uso

Endpoint:

POSTapi.faxil.mx/api/v1/tae/do-transaction
Ventana de terminal
curl -s -X POST "$ORION_API/api/v1/tae/do-transaction" \
  -H "x-api-key: $ORION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "carrier_id": 1,
    "amount": 50,
    "dn": "5512345678",
    "folio": "POS01-000123"
  }'

Respuestas

200 — Venta exitosa Success 

{
  "error": false,
  "message": "Venta exitosa",
  "data": {
    "transaction_id": 104233,
    "code": "00",
    "description": "TRANSACCION EXITOSA",
    "fee_amount": 0,
    "total": 50,
    "folio_carrier": "784512",
    "esim": null
  },
  "results": 1
}

400 — Venta rechazada Client Error

El proveedor rechazó la venta de forma definitiva (número inválido, servicio sin adeudo, etc.). El message contiene la descripción del rechazo. No se cobró y el saldo apartado se liberó.

{ "error": true, "message": "NUMERO NO SUSCEPTIBLE DE ABONO", "data": [], "results": 0 }

Puedes reintentar con datos corregidos usando un folio nuevo.

400 — Validación y saldo Client Error

messageCausa
carrier_id inválidoFalta carrier_id o no es un entero positivo.
Monto positivo con máximo 2 decimales requeridoamount falta, no es número (por ejemplo "50" como texto), es ≤ 0 o tiene más de 2 decimales.
Monto entero positivo requerido para TAE/PINProducto TAE o PIN con monto decimal.
Referencia inválidadn falta, está vacío o supera 100 caracteres.
Folio requerido (máximo 100 caracteres)folio falta, está vacío o supera 100 caracteres.
Operadora no disponibleEl carrier_id no existe o está inactivo.
Saldo insuficienteLa bolsa del producto no tiene saldo suficiente.
{ "error": true, "message": "Saldo insuficiente", "data": [], "results": 0 }

403 — No autorizado Client Error

messageCausa
Venta no autorizadaLa API Key no tiene el permiso de venta del grupo del producto.
Línea o canal no habilitadoTu organización no tiene habilitado ese grupo de productos o el canal API.
Operadora no habilitadaEl producto no está habilitado para tu organización.
Organización o capacidad suspendidaLa organización o la línea se suspendió durante la venta.

Además de los errores de autenticación descritos en Autenticación (API Key).

409 — Folio ya utilizado Conflict

Ya existe una venta con ese folio en tu organización. No se generó una venta nueva. Consulta el resultado de la original con Consultar transacción.

{ "error": true, "message": "Folio ya utilizado; consulta su estado", "data": [], "results": 0 }

502 — Resultado incierto Pendiente

El proveedor no confirmó el resultado (timeout o error de comunicación). La venta pudo haberse aplicado: el saldo queda apartado hasta que se concilie.

{ "error": true, "message": "Resultado incierto; consulta el folio antes de reintentar", "data": [], "results": 0 }

503 — Producto no disponible Server Error

No hay ruta de venta para ese producto o monto en este momento. No se cobró.

messageCausa
SKU no disponibleEl monto no está autorizado para el producto (TAE/PIN) o el producto no tiene proveedor activo.
Sin proveedor asignadoEl producto no tiene proveedor configurado.
Proveedor no disponibleEl proveedor del producto está deshabilitado temporalmente.

429 / 500

CódigomessageAcción
429Demasiadas transacciones en poco tiempo, intenta de nuevo en un momentoEspera los segundos indicados en el encabezado RateLimit (reset). No se procesó la venta.
500Error internoConsulta el folio antes de reintentar.

Parámetros de salida

CampoTipoDescripción
transaction_idnumberIdentificador interno de la transacción en Orion.
codestringCódigo de resultado. En éxito siempre "00". Ver códigos de transacción.
descriptionstringDescripción del resultado devuelta por el proveedor.
fee_amountnumberComisión cobrada al cliente final (solo SERVICIO y PIN; 0 en TAE).
totalnumberLo que debe pagar tu cliente final: amount + fee_amount.
folio_carrierstringFolio o autorización del proveedor. Es el comprobante para el cliente y para aclaraciones.
pinstringSolo PIN. Código del pin vendido. Puede no venir en otros productos.
legendstringTexto opcional del proveedor para imprimir en el ticket (instrucciones, aviso). Puede no venir.
esimobject | nullSolo en productos ESIM; null en el resto.

Venta de eSIM

Si tu catálogo incluye productos con input_type: "ESIM", la venta requiere dos campos adicionales y el dn es el teléfono de contacto del cliente:

ParámetroTipoRequeridoDescripción
dnstringSíTeléfono de contacto a 10 dígitos.
customer_namestringSíNombre completo del cliente (3 a 100 caracteres).
customer_emailstringSíCorreo del cliente. Ahí recibe el código QR de activación.

En éxito, esim trae { "iccid": "...", "msisdn": "...", "qr_link": "https://..." }.

Diagrama de flujo

flowchart TD A([POST /tae/do-transaction]) --> AUTH{¿API Key válida\ny con permiso?} AUTH -->|No| E401[401 / 403] AUTH -->|Sí| V{¿Datos válidos?} V -->|No| E400[400 - Validación] V -->|Sí| F{¿Folio nuevo?} F -->|No| E409[409 - Consulta el folio] F -->|Sí| S{¿Saldo suficiente\nen la bolsa?} S -->|No| ESAL[400 - Saldo insuficiente] S -->|Sí| R[Se aparta el saldo\ny se envía al proveedor] R --> P{Respuesta del proveedor} P -->|Exitosa| OK[200 - Venta exitosa\nse cobra] P -->|Rechazada| B{¿Hay proveedor\nde respaldo?} B -->|Sí| R B -->|No| REJ[400 - Rechazada\nsin cobro] P -->|Sin confirmar| U[502 - Resultado incierto\nsaldo apartado] U --> CHK([Consultar folio])

Resumen de acciones

HTTP¿Se cobró?Acción recomendada
200SíEntregar comprobante (folio_carrier, pin).
400 rechazo / validaciónNoCorregir y reintentar con folio nuevo.
401 / 403NoRevisar API Key, permisos y habilitación.
409—Consultar el folio original.
429NoEsperar y reintentar con el mismo folio.
502 / 500 / timeoutPuede serConsultar el folio. No generar folio nuevo.
503NoRevisar monto o reintentar más tarde.

Probar endpoint

POSThttps://api.faxil.mx/api/v1/tae/do-transaction
Realiza una venta. Usa un folio nuevo en cada intento.
Headers
Body