{"openapi":"3.0.3","info":{"title":"Servicio Crédito Móvil SBN — API","version":"1.5.0","description":"API multiempresa de recargas electrónicas, pago de servicios y gift cards.\n\n**Autenticación:** token Bearer (`sb_live_…` producción · `sb_test_…` sandbox).\n\n**Envelope:** todas las respuestas usan `{ success, ... }`. Los errores añaden `code` y `message`.\n\n**Idempotencia:** `external_reference` es único por empresa. Reintentar con la MISMA referencia devuelve la transacción existente con `duplicated: true` — nunca cobra dos veces.\n\n**Estabilidad:** dentro de `v1` sólo se hacen cambios aditivos. Ver `CHANGELOG.md`.","contact":{"name":"Soporte a integradores SBN","url":"https://docs-recargas.sbn.mx"}},"servers":[{"url":"https://api-recargas.sbn.mx","description":"Producción (tokens sb_live_)"},{"url":"https://sandbox-api-recargas.sbn.mx","description":"Sandbox (tokens sb_test_)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"sb_live_… / sb_test_…","description":"Token de empresa. Se envía como `Authorization: Bearer sb_live_…`. Sólo desde su servidor — NUNCA en el navegador o app móvil."}},"schemas":{"Error":{"type":"object","required":["success","code","message"],"properties":{"success":{"type":"boolean","example":false},"code":{"type":"string","description":"Código estable. Programe contra este valor, no contra `message`.","enum":["AUTH_MISSING_TOKEN","AUTH_INVALID_TOKEN","AUTH_TOKEN_DISABLED","SCOPE_FORBIDDEN","COMPANY_DISABLED","INSUFFICIENT_BALANCE","DUPLICATE_EXTERNAL_REFERENCE","VALIDATION_ERROR","INVALID_PHONE","INVALID_AMOUNT","AMOUNT_REQUIRED","AMOUNT_OUT_OF_RANGE","INVALID_REFERENCE","INVALID_REFERENCE_FORMAT","INVALID_REFERENCE_LENGTH","INVALID_DATE_RANGE","PRODUCT_NOT_FOUND","INVALID_PRODUCT","PRODUCT_DISABLED","INVALID_CARRIER","INVALID_BILLER","PROVIDER_REJECTED","PROVIDER_ERROR","TRANSACTION_PENDING_RECONCILIATION","PRODUCTION_CREDENTIALS_INACTIVE","TRANSACTION_NOT_FOUND","REPORT_NOT_FOUND","REPORT_PROCESSING","RECEIPT_PROCESSING","EXPORT_PROCESSING","RATE_LIMIT_EXCEEDED","INTERNAL_ERROR"],"example":"INSUFFICIENT_BALANCE"},"message":{"type":"string","example":"Saldo insuficiente para realizar la operación."},"status":{"type":"string","example":"failed"}}},"TransactionStatus":{"type":"string","enum":["received","validated","balance_held","sent_to_provider","success","failed","pending_reconciliation","manual_review","cancelled"],"description":"`success` y `failed` son finales. `pending_reconciliation` la resuelve la conciliación (~2 min): NUNCA reintente la venta, consulte el estado."},"ServiceType":{"type":"string","enum":["recharge","service","giftcard","package"]},"Pagination":{"type":"object","properties":{"page":{"type":"integer","example":1},"limit":{"type":"integer","example":20,"description":"Máximo 100."},"total":{"type":"integer","example":137},"pages":{"type":"integer","example":7}}},"Desglose":{"type":"object","description":"Reparto económico de la operación. Es lo que necesita para su ticket y su corte de caja.","properties":{"valor":{"type":"number","format":"double","example":100,"description":"Valor facial (la recarga de $100)."},"cargo_al_saldo":{"type":"number","format":"double","example":94.34,"description":"Lo que realmente se descuenta de su saldo."},"descuento":{"type":"number","format":"double","example":5.66,"description":"Ahorro respecto al valor facial."},"comision_cliente":{"type":"number","format":"double","example":2,"description":"La ÚNICA comisión que ve el cliente final."},"ahorro_negocio":{"type":"number","format":"double","example":1.42,"description":"Parte del margen que SBN le cede: se le cobró MENOS de su saldo. Sólo en recargas y paquetes. Es su ganancia por operar con SBN, además de su comisión."},"ganancia_negocio":{"type":"number","format":"double","example":3.42,"description":"Su comisión de mostrador MÁS el ahorro. Lo que gana en total."},"total_cliente_final":{"type":"number","format":"double","example":105.66,"description":"Lo que cobra al cliente."},"saldo_antes":{"type":"number","format":"double","example":5000},"saldo_despues":{"type":"number","format":"double","example":4905.66},"moneda":{"type":"string","example":"MXN"}}},"Me":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"company_id":{"type":"integer","example":7},"name":{"type":"string","example":"Abarrotes La Esquina"},"environment":{"type":"string","enum":["production","sandbox"]},"scopes":{"type":"array","items":{"type":"string","enum":["balance:read","catalog:read","recharge:create","transaction:read"]}},"limits":{"type":"object","properties":{"hourly":{"type":"integer","example":300},"daily":{"type":"integer","example":3000}}}}}}},"Balance":{"type":"object","properties":{"success":{"type":"boolean","example":true},"available_balance":{"type":"number","format":"double","example":4905.66,"description":"Disponible para operar."},"held_balance":{"type":"number","format":"double","example":100,"description":"Retenido por operaciones en curso o pendientes de conciliar."},"currency":{"type":"string","example":"MXN"}}},"Carrier":{"type":"object","properties":{"carrier":{"type":"string","example":"TELCEL"},"service_type":{"$ref":"#/components/schemas/ServiceType"},"product_count":{"type":"integer","example":12}}},"Product":{"type":"object","properties":{"product_code":{"type":"string","example":"TEL100"},"product_name":{"type":"string","example":"Telcel $100"},"carrier":{"type":"string","example":"TELCEL"},"service_type":{"$ref":"#/components/schemas/ServiceType"},"amount":{"type":"number","format":"double","example":100}}},"Biller":{"type":"object","description":"Emisor de pago de servicios. `campos` describe qué debe capturar el usuario.","properties":{"biller":{"type":"string","example":"CFE - Codigo de Barras"},"tipo":{"type":"string","enum":["monto_libre","catalogo"]},"campos":{"type":"array","description":"Campos requeridos: longitud, formato, si admite ceros a la izquierda, si exige confirmación.","items":{"type":"object","additionalProperties":true}},"productos":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"reglas":{"type":"string","nullable":true,"description":"Texto del emisor que DEBE mostrarse al usuario."}}},"PosType":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ServiceType"},"label":{"type":"string","example":"Recargas"},"icon":{"type":"string","nullable":true},"product_count":{"type":"integer","example":393}}},"PosBrand":{"type":"object","properties":{"carrier":{"type":"string","example":"TELCEL"},"icon":{"type":"string","nullable":true,"description":"Logotipo del carrier."},"categoria":{"type":"string","nullable":true},"product_count":{"type":"integer","example":12}}},"PosAmount":{"type":"object","description":"Monto vendible. En productos de MONTO LIBRE (`free_amount: true`) hay que cotizar.","properties":{"product_code":{"type":"string","example":"TEL100"},"product_name":{"type":"string","example":"Telcel $100"},"service_type":{"$ref":"#/components/schemas/ServiceType"},"carrier":{"type":"string","example":"TELCEL"},"amount":{"type":"number","format":"double","example":100,"nullable":true,"description":"null si es monto libre."},"cost_to_client":{"type":"number","format":"double","example":105.66,"nullable":true,"description":"Lo que pagaría el cliente final."},"comision_cliente":{"type":"number","format":"double","example":5.66,"nullable":true},"free_amount":{"type":"boolean","example":false},"min":{"type":"number","format":"double","example":10,"nullable":true},"max":{"type":"number","format":"double","example":5000,"nullable":true},"formato":{"type":"string","nullable":true},"currency":{"type":"string","example":"MXN"},"available":{"type":"boolean","example":true,"description":"false si el pricing falló; vea `reason`."},"reason":{"type":"string","nullable":true,"example":"PRICING_ERROR"},"note":{"type":"string","nullable":true}}},"Quote":{"type":"object","description":"Cotización SIN cobrar. No mueve saldo ni crea transacción.","properties":{"success":{"type":"boolean","example":true},"product_code":{"type":"string","example":"TEL100"},"product_name":{"type":"string","example":"Telcel $100"},"carrier":{"type":"string","example":"TELCEL"},"service_type":{"$ref":"#/components/schemas/ServiceType"},"desglose":{"$ref":"#/components/schemas/Desglose"},"alcanza_saldo":{"type":"boolean","nullable":true,"example":true,"description":"Si su saldo cubre la operación."}}},"RechargeRequest":{"type":"object","required":["external_reference","phone"],"description":"Identifique el producto con `product_code` **o** con `carrier`. Uno de los dos es obligatorio; `product_code` es el que devuelve la cotización.","properties":{"external_reference":{"type":"string","maxLength":100,"example":"SBNPOS-S1-004512","description":"Único por empresa. Es su llave de idempotencia: reintente SIEMPRE con la misma."},"product_code":{"type":"string","example":"TEL100","description":"Código exacto del catálogo — el mismo que usó para cotizar. Alternativa a `carrier`."},"carrier":{"type":"string","example":"TELCEL","description":"Compañía. El producto se resuelve por compañía + monto. Alternativa a `product_code`."},"phone":{"type":"string","example":"5512345678","description":"10 dígitos."},"amount":{"type":"number","format":"double","example":100,"description":"Opcional si manda `product_code` de precio fijo: el monto sale del catálogo. Obligatorio con `carrier` (es lo que permite elegir producto) y en carriers de Monto Libre. Si lo manda junto a un `product_code` de precio fijo, debe coincidir."}},"anyOf":[{"required":["product_code"]},{"required":["carrier","amount"]}]},"ServicePaymentRequest":{"type":"object","required":["reference","external_reference"],"properties":{"biller":{"type":"string","example":"CFE - Codigo de Barras","description":"Emisor (ver /v1/catalog/billers). Alternativa: product_code."},"product_code":{"type":"string","example":"CFE000","description":"Código exacto del producto (alternativa a biller)."},"reference":{"type":"string","example":"001234567890123456789012345678","description":"SIEMPRE string: puede iniciar con ceros. Longitud y formato según los campos del emisor."},"amount":{"type":"number","format":"double","example":200,"description":"En emisores de Monto Libre (CFE, agua, predial) lo define quien paga, dentro del rango, y es OBLIGATORIO. En servicios de precio fijo puede omitirse si manda `product_code`: sale del catálogo."},"external_reference":{"type":"string","maxLength":100,"example":"PAGO-000001"}},"anyOf":[{"required":["product_code"]},{"required":["biller","amount"]}]},"OperationResult":{"type":"object","description":"Resultado de una recarga o pago. `status` determina qué hacer.","properties":{"success":{"type":"boolean","example":true},"code":{"type":"string","example":"RECHARGE_SUCCESS"},"message":{"type":"string","example":"Recarga aplicada."},"transaction_id":{"type":"string","example":"SB-RCG-20260726-000123"},"external_reference":{"type":"string","example":"SBNPOS-S1-004512"},"status":{"$ref":"#/components/schemas/TransactionStatus"},"duplicated":{"type":"boolean","example":false,"description":"true si la referencia ya existía: se devuelve la transacción original."},"amount":{"type":"number","format":"double","example":100},"charged_amount":{"type":"number","format":"double","example":94.34},"comision_visible":{"type":"number","format":"double","example":5.66},"total_cliente_final":{"type":"number","format":"double","example":105.66},"currency":{"type":"string","example":"MXN"},"provider_mode":{"type":"string","enum":["taecel"],"description":"Proveedor que ejecutó la operación. Siempre `taecel`: el modo simulado se eliminó. Se conserva por compatibilidad."},"producto":{"type":"object","description":"Qué se compró. Evita cruzar contra su propio catálogo.","properties":{"product_code":{"type":"string","nullable":true,"example":"MOV020"},"product_name":{"type":"string","nullable":true,"example":"Movistar $20"},"carrier":{"type":"string","nullable":true,"example":"Movistar"},"service_type":{"type":"string","example":"recharge"},"bolsa":{"type":"string","nullable":true,"example":"1","description":"\"1\" tiempo aire (hay reparto de margen) · \"2\" servicios (no hay)."},"referencia":{"type":"string","nullable":true,"description":"Teléfono recargado o referencia del recibo."}}},"comisiones":{"type":"object","description":"De dónde sale cada peso. `comision_cliente = traslado_costo + comision_negocio` · `ganancia_negocio = comision_negocio + ahorro_negocio`.","properties":{"comision_negocio":{"type":"number","format":"double","example":2,"description":"Lo que el negocio configuró cobrar en mostrador."},"traslado_costo":{"type":"number","format":"double","example":0,"description":"Costo del proveedor trasladado al consumidor. 0 en recargas."},"comision_cliente":{"type":"number","format":"double","example":2,"description":"La ÚNICA comisión que ve el consumidor."},"ahorro_negocio":{"type":"number","format":"double","example":0.28,"description":"Parte del margen que SBN le devolvió."},"ganancia_negocio":{"type":"number","format":"double","example":2.28,"description":"Lo que el negocio ganó EN TOTAL."},"moneda":{"type":"string","example":"MXN"}}},"saldo":{"type":"object","description":"Cómo quedó el saldo. Sale del ledger, no de un cálculo.","properties":{"disponible_antes":{"type":"number","format":"double","example":100,"nullable":true},"disponible_despues":{"type":"number","format":"double","example":80.28,"nullable":true},"retenido_antes":{"type":"number","format":"double","example":0,"nullable":true},"retenido_despues":{"type":"number","format":"double","example":0,"nullable":true},"movimiento":{"type":"number","format":"double","example":-19.72,"description":"Negativo = salió saldo. 0 si la operación falló."},"moneda":{"type":"string","example":"MXN"}}},"tiempos":{"type":"object","properties":{"creada_en":{"type":"string","format":"date-time"},"completada_en":{"type":"string","format":"date-time","nullable":true},"duracion_ms":{"type":"integer","nullable":true,"example":1746}}},"taecel":{"type":"object","description":"Los 18 campos de `StatusTXN` **con los nombres de TAECEL**, sin traducir. Es lo que se cita en una aclaración con ellos. `TransID` y `Folio` son SUS identificadores.","properties":{"TransID":{"type":"string","nullable":true,"example":"260801048262"},"Folio":{"type":"string","nullable":true,"example":"732513"},"Status":{"type":"string","nullable":true,"example":"Exitosa"},"Nota":{"type":"string","nullable":true},"Fecha":{"type":"string","nullable":true},"Carrier":{"type":"string","nullable":true},"Telefono":{"type":"string","nullable":true},"Monto":{"type":"string","nullable":true},"Cargo":{"type":"string","nullable":true},"Abono":{"type":"string","nullable":true},"Via":{"type":"string","nullable":true},"Región":{"type":"string","nullable":true},"Timeout":{"type":"string","nullable":true},"IP":{"type":"string","nullable":true},"Bolsa":{"type":"string","nullable":true},"Comision":{"type":"string","nullable":true},"pin":{"type":"string","nullable":true,"description":"GiftCards. Si se pierde, el cliente pagó y no recibió nada."},"Saldo Final":{"type":"string","nullable":true}}},"provider_environment":{"type":"string","enum":["test","live"],"example":"test","description":"**Ambiente de TAECEL que ejecutó la operación.** `test` = llega a TAECEL pero NO es dinero real: no debe entrar a un corte de caja. `live` = dinero real."},"desglose":{"$ref":"#/components/schemas/Desglose"}}},"Transaction":{"type":"object","properties":{"transaction_id":{"type":"string","example":"SB-RCG-20260726-000123"},"external_reference":{"type":"string","example":"SBNPOS-S1-004512"},"status":{"$ref":"#/components/schemas/TransactionStatus"},"service_type":{"$ref":"#/components/schemas/ServiceType"},"amount":{"type":"number","format":"double","example":100},"charged_amount":{"type":"number","format":"double","example":94.34,"nullable":true},"reference":{"type":"string","nullable":true,"example":"5512345678","description":"Teléfono o referencia de servicio."},"provider_reference":{"type":"string","nullable":true,"example":"260800669705","description":"Número de transacción del proveedor (TransID). Es el identificador con el que se localiza la operación ante él; consérvelo si va a levantar una aclaración."},"provider_folio":{"type":"string","nullable":true,"example":"987654","description":"Folio de autorización del carrier. Sólo existe cuando la operación se completó; es el que se imprime en el ticket."},"provider_status":{"type":"string","nullable":true,"example":"Exitosa","description":"Estatus tal como lo reportó el proveedor."},"provider_message":{"type":"string","nullable":true,"example":"El número telefónico no es válido.","description":"Motivo del resultado, con las palabras del proveedor. En los rechazos es la explicación que conviene mostrar al usuario final."},"provider_code":{"type":"integer","nullable":true,"example":1,"description":"Código numérico del proveedor. 0 = exitosa."},"ahorro_negocio":{"type":"number","format":"double","example":1.42,"description":"Parte del margen que SBN le cedió en esta operación. Se congela por transacción."},"gana_negocio":{"type":"number","format":"double","example":3.42,"description":"Comisión de mostrador + ahorro."},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true}}},"Cursor":{"type":"object","description":"Paginación estable. Pase `next` como parámetro `cursor` para la página siguiente.","properties":{"next":{"type":"string","nullable":true,"example":"10482"},"has_more":{"type":"boolean","example":true},"limit":{"type":"integer","example":20}}},"TransactionList":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}},"pagination":{"$ref":"#/components/schemas/Pagination","description":"Sólo cuando se pagina por `page`."},"cursor":{"$ref":"#/components/schemas/Cursor"}}},"Ticket":{"type":"object","description":"Datos para armar el ticket. Con `format=escpos` la respuesta es texto plano, no JSON.","properties":{"success":{"type":"boolean","example":true},"transaction_id":{"type":"string","example":"SB-RCG-20260726-000123"},"data":{"type":"object","additionalProperties":true,"description":"Encabezado, líneas, folio, pin (gift cards) y desglose."}}},"SignedUrl":{"type":"object","description":"URL de descarga directa, firmada y con caducidad. No requiere token: la firma ES la autorización, y sólo es válida durante `expires_in`.","properties":{"success":{"type":"boolean","example":true},"url":{"type":"string","format":"uri","example":"https://dbs3.sbn.mx/sbn-credito-operaciones/…","description":"URL firmada y temporal."},"expires_in":{"type":"integer","example":600,"description":"Segundos de validez."}}},"Report":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"module":{"type":"string","example":"reporte_transacciones"},"original_name":{"type":"string","example":"transacciones-2026-07.pdf"},"size":{"type":"integer","example":148223},"created_at":{"type":"string","format":"date-time"}}},"Dependency":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded","down"]},"latency_ms":{"type":"integer","nullable":true,"example":3},"detail":{"type":"string","nullable":true}}},"Status":{"type":"object","properties":{"success":{"type":"boolean","example":true},"service":{"type":"string","example":"Servicio Credito Movil SBN"},"environment":{"type":"string","enum":["production","sandbox"]},"provider_mode":{"type":"string","enum":["taecel"],"description":"Proveedor que ejecutó la operación. Siempre `taecel`: el modo simulado se eliminó. Se conserva por compatibilidad."},"provider_environment":{"type":"string","enum":["test","live"],"example":"test","description":"**Ambiente de TAECEL que ejecutó la operación.** `test` = llega a TAECEL pero NO es dinero real: no debe entrar a un corte de caja. `live` = dinero real."},"status":{"type":"string","enum":["ok","degraded","down"],"description":"`down` responde HTTP 503."},"dependencies":{"type":"object","properties":{"database":{"$ref":"#/components/schemas/Dependency"},"cache":{"$ref":"#/components/schemas/Dependency"},"queue":{"$ref":"#/components/schemas/Dependency"},"provider":{"$ref":"#/components/schemas/Dependency"}}},"checked_at":{"type":"string","format":"date-time"}}},"WebhookEventCatalog":{"type":"object","properties":{"success":{"type":"boolean","example":true},"events":{"type":"array","items":{"type":"string","enum":["transaction.succeeded","transaction.failed","transaction.pending_resolved","balance.low","balance.topup","webhook.test"]}},"wildcard":{"type":"string","example":"*"},"signature_header":{"type":"string","example":"X-SBN-Signature"},"docs":{"type":"string","example":"/docs#webhooks"}}}}},"paths":{"/v1/status":{"get":{"summary":"Estado del servicio y sus dependencias","tags":["Estado"],"security":[],"description":"Público, sin token. Úselo como sonda de disponibilidad antes de operar.","responses":{"200":{"description":"Operativo o degradado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Status"}}}},"503":{"description":"Base de datos inalcanzable: el servicio no puede operar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Status"}}}}}}},"/v1/webhooks/events":{"get":{"summary":"Catálogo de eventos de webhook","tags":["Webhooks"],"security":[],"description":"Eventos que puede recibir. Configuración y verificación de firma: guía 09 de la documentación de integración.","responses":{"200":{"description":"Catálogo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEventCatalog"}}}}}}},"/v1/me":{"get":{"summary":"Identidad, scopes y límites de la empresa autenticada","tags":["Empresa"],"description":"Primer llamado recomendado: confirma que el token funciona y con qué permisos.","responses":{"200":{"description":"Empresa autenticada.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"401":{"description":"Token ausente, inválido o revocado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"El token no tiene el scope requerido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite por hora o por día excedido.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."},"Retry-After":{"schema":{"type":"integer","example":1800},"description":"Segundos hasta que se libere la ventana."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno. El detalle técnico NUNCA se expone; queda en error_logs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/balance":{"get":{"summary":"Saldo disponible y retenido","tags":["Saldo"],"description":"Requiere scope `balance:read`. `held_balance` incluye operaciones pendientes de conciliar.","responses":{"200":{"description":"Saldo actual.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Balance"}}}},"401":{"description":"Token ausente, inválido o revocado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"El token no tiene el scope requerido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite por hora o por día excedido.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."},"Retry-After":{"schema":{"type":"integer","example":1800},"description":"Segundos hasta que se libere la ventana."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno. El detalle técnico NUNCA se expone; queda en error_logs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/carriers":{"get":{"summary":"Compañías disponibles","tags":["Catálogo"],"description":"Requiere scope `catalog:read`.","responses":{"200":{"description":"Listado de compañías.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Carrier"}}}}}}},"401":{"description":"Token ausente, inválido o revocado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"El token no tiene el scope requerido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite por hora o por día excedido.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."},"Retry-After":{"schema":{"type":"integer","example":1800},"description":"Segundos hasta que se libere la ventana."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno. El detalle técnico NUNCA se expone; queda en error_logs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/products":{"get":{"summary":"Productos disponibles","tags":["Catálogo"],"parameters":[{"name":"carrier","in":"query","schema":{"type":"string"},"example":"TELCEL","description":"Filtra por compañía."}],"responses":{"200":{"description":"Listado de productos.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}}}}}},"401":{"description":"Token ausente, inválido o revocado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"El token no tiene el scope requerido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite por hora o por día excedido.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."},"Retry-After":{"schema":{"type":"integer","example":1800},"description":"Segundos hasta que se libere la ventana."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno. El detalle técnico NUNCA se expone; queda en error_logs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/billers":{"get":{"summary":"Emisores de pago de servicios","tags":["Servicios"],"description":"Cada emisor trae su tipo (monto libre o catálogo), los campos que debe capturar el usuario, sus productos de precio fijo y las reglas que hay que mostrarle.","responses":{"200":{"description":"Listado de emisores.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Biller"}}}}}}},"401":{"description":"Token ausente, inválido o revocado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"El token no tiene el scope requerido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite por hora o por día excedido.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."},"Retry-After":{"schema":{"type":"integer","example":1800},"description":"Segundos hasta que se libere la ventana."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno. El detalle técnico NUNCA se expone; queda en error_logs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/pos/catalog/types":{"get":{"summary":"Pantalla 1 — tipos de operación","tags":["Catálogo POS"],"description":"Recargas, servicios, gift cards y paquetes, con ícono y conteo.","responses":{"200":{"description":"Tipos disponibles.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/PosType"}}}}}}},"401":{"description":"Token ausente, inválido o revocado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"El token no tiene el scope requerido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite por hora o por día excedido.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."},"Retry-After":{"schema":{"type":"integer","example":1800},"description":"Segundos hasta que se libere la ventana."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno. El detalle técnico NUNCA se expone; queda en error_logs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/pos/catalog/brands":{"get":{"summary":"Pantalla 2 — marcas de un tipo","tags":["Catálogo POS"],"parameters":[{"name":"type","in":"query","required":true,"schema":{"$ref":"#/components/schemas/ServiceType"}},{"name":"q","in":"query","schema":{"type":"string"},"description":"Búsqueda por nombre de marca."}],"responses":{"200":{"description":"Marcas del tipo indicado.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/PosBrand"}}}}}}},"401":{"description":"Token ausente, inválido o revocado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"El token no tiene el scope requerido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite por hora o por día excedido.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."},"Retry-After":{"schema":{"type":"integer","example":1800},"description":"Segundos hasta que se libere la ventana."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno. El detalle técnico NUNCA se expone; queda en error_logs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/pos/catalog/amounts":{"get":{"summary":"Pantalla 3 — montos de una marca, con precio real","tags":["Catálogo POS"],"description":"Incluye `cost_to_client` ya con su comisión aplicada. Si `free_amount` es true, cotice con `/v1/pos/catalog/quote`.","parameters":[{"name":"type","in":"query","required":true,"schema":{"$ref":"#/components/schemas/ServiceType"}},{"name":"carrier","in":"query","required":true,"schema":{"type":"string"},"example":"TELCEL"}],"responses":{"200":{"description":"Montos vendibles.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/PosAmount"}}}}}}},"401":{"description":"Token ausente, inválido o revocado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"El token no tiene el scope requerido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite por hora o por día excedido.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."},"Retry-After":{"schema":{"type":"integer","example":1800},"description":"Segundos hasta que se libere la ventana."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno. El detalle técnico NUNCA se expone; queda en error_logs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/pos/catalog/quote":{"get":{"summary":"Pantalla 4 — cotización SIN cobrar","tags":["Catálogo POS"],"description":"Devuelve el desglose completo y si su saldo alcanza. No mueve saldo ni crea transacción: es seguro llamarlo las veces que haga falta.","parameters":[{"name":"product_code","in":"query","required":true,"schema":{"type":"string"},"example":"TEL100"},{"name":"amount","in":"query","required":true,"schema":{"type":"number"},"example":100}],"responses":{"200":{"description":"Cotización.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quote"}}}},"401":{"description":"Token ausente, inválido o revocado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"El token no tiene el scope requerido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Producto inexistente o monto fuera del rango permitido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite por hora o por día excedido.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."},"Retry-After":{"schema":{"type":"integer","example":1800},"description":"Segundos hasta que se libere la ventana."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno. El detalle técnico NUNCA se expone; queda en error_logs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/recharges":{"post":{"summary":"Crear recarga (idempotente)","tags":["Recargas"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":100},"description":"Alias estándar de `external_reference`. Envíe una u otra; si envía ambas deben coincidir."}],"description":"Requiere scope `recharge:create`.\n\n**Reintentos:** use SIEMPRE el mismo `external_reference`. Cambiarlo para \"reintentar\" provoca un segundo cobro.\n\n**`pending_reconciliation`:** el saldo queda retenido y la conciliación resuelve en ~2 min. NO revenda; consulte el estado o espere el webhook `transaction.pending_resolved`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RechargeRequest"}}}},"responses":{"200":{"description":"Resultado de la operación (éxito, fallo, pendiente o duplicada).","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationResult"}}}},"401":{"description":"Token ausente, inválido o revocado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"El token no tiene el scope requerido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validación, saldo insuficiente o rechazo del proveedor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite por hora o por día excedido.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."},"Retry-After":{"schema":{"type":"integer","example":1800},"description":"Segundos hasta que se libere la ventana."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno. El detalle técnico NUNCA se expone; queda en error_logs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/services/payments":{"post":{"summary":"Pago de servicio o gift card (idempotente)","tags":["Servicios"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":100},"description":"Alias estándar de `external_reference`. Envíe una u otra; si envía ambas deben coincidir."}],"description":"La referencia se valida contra los campos del emisor. Mismas reglas de idempotencia y conciliación que `/v1/recharges`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServicePaymentRequest"}}}},"responses":{"200":{"description":"Resultado de la operación.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationResult"}}}},"401":{"description":"Token ausente, inválido o revocado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"El token no tiene el scope requerido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Referencia, monto o emisor inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite por hora o por día excedido.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."},"Retry-After":{"schema":{"type":"integer","example":1800},"description":"Segundos hasta que se libere la ventana."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno. El detalle técnico NUNCA se expone; queda en error_logs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/transactions":{"get":{"summary":"Historial de transacciones","tags":["Recargas"],"description":"Requiere scope `transaction:read`. Paginado.","parameters":[{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/TransactionStatus"}},{"name":"from","in":"query","schema":{"type":"string","format":"date"},"example":"2026-07-01"},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"example":"2026-07-31"},{"name":"service_type","in":"query","schema":{"$ref":"#/components/schemas/ServiceType"}},{"name":"carrier","in":"query","schema":{"type":"string"},"example":"TELCEL"},{"name":"external_reference","in":"query","schema":{"type":"string"},"description":"Coincidencia exacta con SU referencia."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Paginación estable (recomendada). Use `cursor.next` de la respuesta anterior. Con `page` las filas se desplazan si entran ventas mientras pagina."},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1},"description":"Alternativa a `cursor`."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Listado paginado.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionList"}}}},"401":{"description":"Token ausente, inválido o revocado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"El token no tiene el scope requerido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite por hora o por día excedido.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."},"Retry-After":{"schema":{"type":"integer","example":1800},"description":"Segundos hasta que se libere la ventana."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno. El detalle técnico NUNCA se expone; queda en error_logs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/transactions/by-reference/{externalReference}":{"get":{"summary":"Buscar por SU referencia (external_reference)","tags":["Recargas"],"description":"Resuelve el caso crítico del mostrador: **«se me cayó la red, ¿se cobró?»**.\n\nAntes de reintentar tras un error de red, consulte aquí con la misma referencia que envió. Si existe, la operación se creó: NO la repita.","parameters":[{"name":"externalReference","in":"path","required":true,"schema":{"type":"string"},"example":"SBNPOS-S1-004512"}],"responses":{"200":{"description":"Detalle de la operación.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Transaction"}}}}}},"401":{"description":"Token ausente, inválido o revocado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"El token no tiene el scope requerido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No existe una operación con esa referencia: puede reintentar con ella.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite por hora o por día excedido.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."},"Retry-After":{"schema":{"type":"integer","example":1800},"description":"Segundos hasta que se libere la ventana."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno. El detalle técnico NUNCA se expone; queda en error_logs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/reports/transactions/csv":{"post":{"summary":"Export CSV para conciliación contable","tags":["Reportes"],"description":"Acepta los mismos filtros que `/v1/transactions`. Trabajo asíncrono: responde 202 y el archivo aparece en `GET /v1/reports`. Incluye BOM UTF-8 para que Excel respete los acentos.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string","format":"date","example":"2026-07-01"},"to":{"type":"string","format":"date","example":"2026-07-31"},"status":{"$ref":"#/components/schemas/TransactionStatus"},"service_type":{"$ref":"#/components/schemas/ServiceType"},"carrier":{"type":"string","example":"TELCEL"}}}}}},"responses":{"202":{"description":"Encolado.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"job_id":{"type":"string"}}}}}},"401":{"description":"Token ausente, inválido o revocado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"El token no tiene el scope requerido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite por hora o por día excedido.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."},"Retry-After":{"schema":{"type":"integer","example":1800},"description":"Segundos hasta que se libere la ventana."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno. El detalle técnico NUNCA se expone; queda en error_logs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/transactions/{id}":{"get":{"summary":"Detalle de una transacción","tags":["Recargas"],"description":"Fuente de verdad del estado. Ante cualquier duda tras un timeout, consulte aquí — nunca reintente a ciegas.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"SB-RCG-20260726-000123"}],"responses":{"200":{"description":"Detalle.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Transaction"}}}}}},"401":{"description":"Token ausente, inválido o revocado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"El token no tiene el scope requerido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No encontrada (o no pertenece a su empresa).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite por hora o por día excedido.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."},"Retry-After":{"schema":{"type":"integer","example":1800},"description":"Segundos hasta que se libere la ventana."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno. El detalle técnico NUNCA se expone; queda en error_logs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/transactions/{id}/receipt":{"get":{"summary":"Comprobante PDF","tags":["Recargas"],"description":"Si aún no se ha generado, responde 202 y lo encola: reintente en unos segundos.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"URL firmada del comprobante.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignedUrl"}}}},"202":{"description":"En proceso de generación.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."}}},"401":{"description":"Token ausente, inválido o revocado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"El token no tiene el scope requerido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Transacción no encontrada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite por hora o por día excedido.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."},"Retry-After":{"schema":{"type":"integer","example":1800},"description":"Segundos hasta que se libere la ventana."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno. El detalle técnico NUNCA se expone; queda en error_logs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/transactions/{id}/ticket":{"get":{"summary":"Ticket de venta: JSON, ESC/POS térmico o PDF","tags":["Servicios"],"description":"Siempre disponible (reimpresión), independiente del ticket automático.\n\n`json` → datos para armar su propio ticket · `escpos` → texto listo para impresora térmica (`text/plain`) · `pdf` → URL firmada.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","escpos","pdf"],"default":"json"}},{"name":"paper","in":"query","schema":{"type":"string","enum":["58","80"]},"description":"Ancho en mm, sólo para `escpos`."}],"responses":{"200":{"description":"Ticket en el formato solicitado.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ticket"}},"text/plain":{"schema":{"type":"string","description":"ESC/POS listo para enviar a la impresora."}}}},"401":{"description":"Token ausente, inválido o revocado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"El token no tiene el scope requerido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Transacción no encontrada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite por hora o por día excedido.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."},"Retry-After":{"schema":{"type":"integer","example":1800},"description":"Segundos hasta que se libere la ventana."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno. El detalle técnico NUNCA se expone; queda en error_logs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/reports/transactions":{"post":{"summary":"Generar reporte PDF por rango de fechas","tags":["Reportes"],"description":"Trabajo asíncrono: responde 202 y el reporte aparece en `GET /v1/reports`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["from","to"],"properties":{"from":{"type":"string","format":"date","example":"2026-07-01"},"to":{"type":"string","format":"date","example":"2026-07-31"}}}}}},"responses":{"202":{"description":"Encolado.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"job_id":{"type":"string"}}}}}},"401":{"description":"Token ausente, inválido o revocado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"El token no tiene el scope requerido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite por hora o por día excedido.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."},"Retry-After":{"schema":{"type":"integer","example":1800},"description":"Segundos hasta que se libere la ventana."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno. El detalle técnico NUNCA se expone; queda en error_logs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/reports":{"get":{"summary":"Reportes y exports generados","tags":["Reportes"],"responses":{"200":{"description":"Listado de reportes disponibles.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Report"}}}}}}},"401":{"description":"Token ausente, inválido o revocado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"El token no tiene el scope requerido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite por hora o por día excedido.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."},"Retry-After":{"schema":{"type":"integer","example":1800},"description":"Segundos hasta que se libere la ventana."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno. El detalle técnico NUNCA se expone; queda en error_logs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/reports/{uuid}/download":{"get":{"summary":"URL firmada de descarga de un reporte","tags":["Reportes"],"parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"URL firmada temporal.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignedUrl"}}}},"401":{"description":"Token ausente, inválido o revocado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"El token no tiene el scope requerido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Reporte no encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite por hora o por día excedido.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":300},"description":"Operaciones permitidas por hora."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":287},"description":"Disponibles en la hora actual."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1753491600},"description":"Epoch (s) en que se reinicia la ventana horaria."},"X-RateLimit-Limit-Day":{"schema":{"type":"integer","example":3000},"description":"Operaciones permitidas por día."},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer","example":2954},"description":"Disponibles en el día actual."},"X-RateLimit-Reset-Day":{"schema":{"type":"integer","example":1753574400},"description":"Epoch (s) en que se reinicia la ventana diaria."},"X-Request-Id":{"schema":{"type":"string","example":"5f3c…"},"description":"Eco del enviado, o generado. Cítelo al reportar una incidencia."},"Retry-After":{"schema":{"type":"integer","example":1800},"description":"Segundos hasta que se libere la ventana."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno. El detalle técnico NUNCA se expone; queda en error_logs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"tags":[{"name":"Estado","description":"Disponibilidad del servicio."},{"name":"Empresa","description":"Identidad, scopes y límites."},{"name":"Saldo","description":"Saldo disponible y retenido."},{"name":"Catálogo POS","description":"Flujo de venta en 4 pantallas: tipo → marca → monto → cotización."},{"name":"Catálogo","description":"Catálogo clásico por compañía y producto."},{"name":"Recargas","description":"Recargas de tiempo aire y consulta de transacciones."},{"name":"Servicios","description":"Pago de servicios, gift cards y tickets."},{"name":"Reportes","description":"Generación y descarga de reportes."},{"name":"Webhooks","description":"Eventos en tiempo real. Ver guía 09 de integración."}]}