Referencia de API

Crea un intent en requires_payment_method con un client_secret nuevo.

Cuerpo

Errores posibles: payment_intent.invalid_amount, payment_intent.invalid_currency, payment_intent.invalid_tip (ver Errores).

Lee un intent. Con ?expand=attempts incluye el historial de intentos de cobro.

Errores posibles: payment_intent.not_found.

Confirma el cobro: valida ruteo, crea el attempt y encola su ejecución. La respuesta HTTP siempre llega con status: "processing" — el cobro se ejecuta después, fuera del request (regla: processing solo se resuelve con evidencia del proveedor). El resultado final llega por webhook o por un GET posterior.

Cuerpo

Errores posibles: payment_intent.unauthorized, payment_intent.not_confirmable, payment_intent.no_route, payment_intent.concurrent_modification, payment_intent.invalid_tip.

Captura un intento previamente autorizado sin capturar (flujo auth/capture del POS, p. ej. tras confirmar con tok_sim_auth). Sin cuerpo. El intent no cambia de estado en la respuesta — sigue processing hasta que el proveedor confirme la captura.

Errores posibles: attempt.not_capturable (no hay intento authorized).

Cancela el intent (si la máquina de estados lo permite). Sin cuerpo. Cancelar un intent ya canceled es un no-op que devuelve 200.

Errores posibles: transición inválida si el intent ya está en un estado terminal distinto (succeeded/failed/expired).

Crea una devolución en requested sobre un intento capturado.

Cuerpo

Errores posibles: ver la tabla de refunds en Errores.

Lee una devolución por su id.

Errores posibles: refund.not_found.

Crea un cliente. Cuerpo vacío permitido.

Cuerpo

Lista o lee un cliente por su id.

Errores posibles: customer.not_found.

Guarda un método de pago tokenizado. Nace pending; el Worker lo activa fuera del request.

Cuerpo

Errores posibles: payment_method.invalid_token, payment_method.no_route, customer.not_found.

Lista los métodos guardados del cliente (incluye detached).

Transición terminal a detached. Idempotente: repetir sobre uno ya detached no falla.

Errores posibles: payment_method.not_found.

Registra un endpoint para recibir entregas. El secret solo se devuelve aquí.

Cuerpo

Lista los endpoints del tenant. Nunca incluye secretos.

Deshabilita el endpoint (baja lógica: deja de recibir entregas nuevas). No es un borrado físico — el ledger y el historial son append-only por diseño, y esta fila sigue existiendo con active: false.

Errores posibles: webhook_endpoint.not_found.

Cuerpo

Si el id no existe o el client_secret no coincide, la respuesta es siempre el mismo 404 genérico — nunca revela cuál de los dos falló (defensa contra fuerza bruta).

Query

Usado por el polling interno de winal.js cada 2 s hasta un estado terminal.

Stream de polling sobre las entregas de webhook del tenant — alternativa a recibir HTTP entrante, pensado para desarrollo local y para el CLI oficial winal listen. Solo devuelve filas si el tenant tiene al menos un webhook_endpoint activo registrado.

Query

Timbra un CFDI de ingreso, método de pago PUE, sobre un payment_intent ya succeeded. El receptor debe llevar el RFC real de tu cliente: el genérico XAXX010101000 ya no se acepta aquí (rechazo CFDI40130 del SAT) — esas ventas van por POST /v1/invoices/global.

Cuerpo

Errores posibles: invoice.invalid_body, invoice.invalid_receptor, invoice.global_required_for_publico_en_general, invoice.invalid_treatment, invoice.invalid_ieps, invoice.ieps_exceeds_importe, invoice.invalid_cantidad, invoice.cantidad_incompleta, invoice.conceptos_sum_mismatch, invoice.ieps_pac_unsupported, invoice.cfdi_field_invalid, invoice.pac_error (ver Errores). Y los dos de la regla 5: invoice.pac_unreachable y invoice.pac_unreachable_unverified, que no son un rechazo sino un desenlace INDETERMINADO (el PAC no contestó): se reintentan con la misma Idempotency-Key —nunca emitiendo de nuevo— y el segundo ni siquiera automáticamente (ver Facturación CFDI → Si el PAC no contesta).

Factura una venta ya pagada que no pasó por un cobro de Winal: el mostrador que cobró en efectivo, una transferencia recibida directo en tu banco, una terminal ajena — de un cliente que sí te dio su RFC. Emite un CFDI método de pago PUE sin payment_intent_id.

Como no hay cobro del cual deducirla, tú declaras la forma de pago del catálogo c_FormaPago del SAT. Si el pago aún está pendiente, ésta no es la ruta: usa POST /v1/invoices/ppd. Si el cliente NO dio su RFC, tampoco: esas ventas van por POST /v1/invoices/global.

Cuerpo

Errores posibles: invoice.invalid_body, invoice.invalid_receptor, invoice.invalid_forma_pago, invoice.forma_pago_requires_ppd, invoice.global_required_for_publico_en_general, invoice.receptor_incoherente, invoice.invalid_treatment, invoice.invalid_ieps, invoice.ieps_exceeds_importe, invoice.invalid_cantidad, invoice.cantidad_incompleta, invoice.conceptos_sum_mismatch, invoice.ieps_pac_unsupported, invoice.livemode_mismatch, invoice.cfdi_field_invalid, invoice.pac_error. Y los dos de la regla 5: invoice.pac_unreachable y invoice.pac_unreachable_unverified, que no son un rechazo sino un desenlace INDETERMINADO (el PAC no contestó): se reintentan con la misma Idempotency-Key —nunca emitiendo de nuevo— y el segundo ni siquiera automáticamente (ver Facturación CFDI → Si el PAC no contesta).

Emite un CFDI método de pago PPD por un total acordado, SIN cobro previo — se liquidará después con uno o más REP. Como en /pue, el receptor necesita el RFC real de tu cliente; el genérico no se acepta.

Cuerpo

Errores posibles: invoice.invalid_body, invoice.invalid_receptor, invoice.invalid_currency, invoice.global_required_for_publico_en_general, invoice.invalid_treatment, invoice.invalid_ieps, invoice.ppd_ieps_unsupported, invoice.ppd_mixed_rate_unsupported, invoice.ieps_exceeds_importe, invoice.invalid_cantidad, invoice.cantidad_incompleta, invoice.conceptos_sum_mismatch, invoice.ieps_pac_unsupported, invoice.cfdi_field_invalid, invoice.pac_error. Y los dos de la regla 5: invoice.pac_unreachable y invoice.pac_unreachable_unverified, que no son un rechazo sino un desenlace INDETERMINADO (el PAC no contestó): se reintentan con la misma Idempotency-Key —nunca emitiendo de nuevo— y el segundo ni siquiera automáticamente (ver Facturación CFDI → Si el PAC no contesta).

La FACTURA GLOBAL del período: un CFDI de ingreso a "PÚBLICO EN GENERAL" que agrupa todas las ventas de las que nadie pidió comprobante. Método de pago PUE siempre. No recibe receptor ni total_minor: el receptor lo arma Winal (RFC genérico + CP de tu perfil fiscal) y el total sale de sumar conceptos. Guía narrativa completa en Facturación CFDI → Factura global.

Cuerpo

Errores posibles: invoice.invalid_body, invoice.invalid_forma_pago, invoice.forma_pago_requires_ppd, invoice.invalid_concepto, invoice.invalid_treatment, invoice.invalid_ieps, invoice.ieps_exceeds_importe, invoice.invalid_cantidad, invoice.cantidad_incompleta, invoice.ieps_pac_unsupported, invoice.invalid_currency, invoice.global_periodo_invalido, invoice.livemode_mismatch, invoice.global_already_exists, invoice.invalid_sustituye_uuid, invoice.sustituida_not_found, invoice.sustitucion_periodo_distinto, invoice.cfdi_field_invalid, invoice.pac_error (ver Errores). Y los dos de la regla 5: invoice.pac_unreachable y invoice.pac_unreachable_unverified, que no son un rechazo sino un desenlace INDETERMINADO (el PAC no contestó): se reintentan con la misma Idempotency-Key —nunca emitiendo de nuevo— y el segundo ni siquiera automáticamente (ver Facturación CFDI → Si el PAC no contesta).

Registra un pago sobre una factura PPD ya stamped y timbra su complemento de pagos 2.0 (REP).

Cuerpo — dos variantes, elige una: con payment_intent_id (cobró Winal) o con amount_minor + forma_pago (cobraste tú por fuera). Mandar las dos responde invoice.invalid_body.

Errores posibles: invoice.invalid_body, invoice.not_found (404), invoice.not_ppd, invoice.not_stamped, invoice.intent_not_found (404), invoice.payment_intent_already_applied, invoice.payment_exceeds_saldo, invoice.payment_currency_mismatch, invoice.payment_already_exists, invoice.invalid_forma_pago, invoice.payment_fecha_invalid, invoice.invalid_currency, invoice.livemode_mismatch, invoice.mixed_rate_unsupported, invoice.ieps_breakdown_unsupported, invoice.cfdi_field_invalid, invoice.pac_error, invoice.pac_unreachable, invoice.pac_unreachable_unverified, invoice.idempotency_conflict (409, misma llave con otro pago — incluido reusarla nombrando OTRO payment_intent_id), invoice.payment_not_retryable, invoice.payment_retry_conflict (409, otro reintento del mismo REP se adelantó). La variante SIN cobro cruza el ambiente contra tu LLAVE, y las dos lo cruzan además contra el ambiente en que se timbró la factura PPD que se liquida (ver Facturación CFDI → pago sin cobro de Winal). Reintentar con la MISMA Idempotency-Key no devuelve el fallo congelado: REANUDA ese mismo complemento.

Vuelve a timbrar el MISMO complemento de pago que quedó en error. Sin cuerpo: todo lo que determina el comprobante ya está guardado en su fila, y reintentar es reenviar exactamente eso —misma fecha de expedición, mismos saldos, misma serie/folio— marcado como reintento, para que un PAC que sabe recuperar el timbre devuelva el folio anterior en vez de emitir otro. Con un PAC SIN esa recuperación (Facturama, por ejemplo) el reenvío es idéntico pero el PAC no está obligado a reconocerlo como el mismo intento.

Errores posibles: invoice.payment_not_retryable, invoice.payment_already_exists, invoice.payment_retry_conflict (409), invoice.payment_not_found (404), invoice.not_found (404), invoice.not_ppd, invoice.not_stamped, invoice.livemode_mismatch, invoice.pac_error, invoice.pac_unreachable, invoice.pac_unreachable_unverified. Reintentar uno ya stamped devuelve 200 con él, sin volver a llamar al PAC — y lo mismo recibe quien pierda una carrera contra otro reintento que sí llegó a timbrarlo. Re-timbrar exige, además, que la factura PPD siga timbrada y viva: si se canceló entretanto responde invoice.not_stamped, porque un complemento no liquida un comprobante cancelado. Y el ambiente: si el REP nace de un cobro lo dicta el cobro, no la llave con la que llamas; solo el REP del mostrador toma el de tu llave.

Lista los REP timbrados contra una factura PPD.

Descarga el CFDI ya timbrado de tu cuenta — sin importar cuál de las cuatro rutas de emisión lo generó (POST /v1/invoices, /pue, /ppd o /global). Ruta privada, con tu Authorization: no confundir con las descargas públicas de Autofactura más abajo, que son otra ruta (/public/autofactura/{slug}/invoices/{id}/xml/pdf) sin clave, pensada para que el cliente final baje su propio comprobante.

Errores posibles: invoice.not_found (404); invoice.not_stamped (400 — el CFDI existe pero aún no timbra), invoice.no_provider_ref, invoice.pac_download_error y invoice.pac_empty_file responden 400 también (ver Errores).

Cancela ante el SAT un CFDI de ingreso ya stamped (PUE, PPD o global), con los cuatro motivos del Anexo 20. Idempotente: cancelar un CFDI ya canceled devuelve éxito sin volver a llamar al PAC. Guía narrativa completa —incluida la demora real del SAT para reconocer un UUID recién timbrado— en Facturación CFDI → Cancelar un CFDI ya timbrado.

Cuerpo

Errores posibles: invoice.not_found (404); el resto —invoice.invalid_cancel_motive, invoice.cancel_substitution_required, invoice.not_stamped, invoice.cancel_requires_substitution, invoice.no_provider_ref, invoice.livemode_mismatch, invoice.cancel_pending, invoice.pac_cancel_error (incluye el "No Encontrado" por propagación del SAT — ver la guía narrativa)— responde 400, no 409 (ver Errores para el detalle de cada uno). El ambiente se cruza contra el comprobante, no solo contra tu perfil: un CFDI que se timbró en pruebas se cancela SIEMPRE en pruebas (sk_test_ y perfil en sandbox), y el de producción, en producción — aunque tu cuenta haya cambiado de ambiente entretanto.

Emite una nota de crédito (CFDI 4.0 de EGRESO) por el reembolso de una factura de ingreso ya stamped. La relación con la factura (CfdiRelacionados tipo 01) la arma Winal; el monto FISCAL sale del refund_id real, y amount_minor es solo una confirmación que debe coincidir EXACTO. Idempotente por refund_id: reintentar con el mismo devuelve la nota viva ya existente.

Cuerpo

Errores posibles: invoice.credit_note_invalid_request, invoice.invalid_currency, invoice.invalid_forma_pago, invoice.not_found (404), invoice.not_stamped, invoice.refund_not_found (404), invoice.refund_not_succeeded, invoice.refund_amount_mismatch, invoice.credit_note_currency_mismatch, invoice.refund_intent_mismatch, invoice.credit_notes_exceed_total, invoice.mixed_rate_unsupported, invoice.ieps_breakdown_unsupported, invoice.cfdi_field_invalid, invoice.pac_error. Todos los demás responden 400, no 409 (mapeo por subcadena — ver Errores → Notas de crédito). Exige un cobro DE WINAL detrás de la factura (un payment_intent_id real del cual colgar el refund_id): una factura de POST /v1/invoices/pue nunca lo tiene — usa /credit-notes/pue abajo.

El equivalente de POST /v1/invoices/pue para el EGRESO: emite una nota de crédito SIN reembolso de Winal — la devolución de mostrador de una venta que Winal nunca cobró. Sin refund_id del cual leer el monto, lo declaras tú (amount_minor + forma_pago). Mismo trámite fiscal que la ruta de arriba (tope agregado, relación 01, sellador de egreso); sin idempotencia por refund (no hay refund) — la protege el Idempotency-Key de siempre.

Cuerpo

Errores posibles: invoice.credit_note_invalid_request, invoice.invalid_currency, invoice.invalid_forma_pago, invoice.not_found (404), invoice.not_stamped, invoice.credit_note_currency_mismatch, invoice.credit_notes_exceed_total, invoice.mixed_rate_unsupported, invoice.ieps_breakdown_unsupported, invoice.cfdi_field_invalid, invoice.pac_error.

Lista las notas de crédito (cualquier estado) de una factura, del más nuevo al más viejo.

Consulta una nota de crédito puntual. Debe pertenecer a la factura {id} de la ruta: una nota de OTRA factura del mismo tenant se ve como invoice.credit_note_not_found (404, no 403 — no confirma que el id exista en otro lado).

Errores posibles: invoice.credit_note_not_found (404).

Descarga el XML/PDF de una nota timbrada. A diferencia de la descarga de una factura de ingreso, aquí SÍ se puede descargar una nota ya canceled (el comprobante existió y hay que conservarlo); lo que no se descarga es una que nunca llegó a timbrarse.

Errores posibles: invoice.credit_note_not_found (404); invoice.credit_note_not_stamped, invoice.no_provider_ref, invoice.pac_download_error, invoice.pac_empty_file responden 400.

Vuelve a timbrar una nota de crédito que quedó en error — espejo de POST /v1/invoices/{id}/retry. Reenvía EL MISMO comprobante (mismos importes, mismas líneas, misma serie/folio, misma forma de pago y la misma fecha de expedición), marcado como reintento, para que un PAC que sabe recuperar el timbre devuelva el folio anterior en vez de emitir otro. Con un PAC SIN esa recuperación (Facturama, por ejemplo) el reenvío es idéntico pero el PAC no está obligado a reconocerlo como el mismo intento. Sin cuerpo. Si la nota ya está stamped o canceled, es un no-op exitoso que no llama al PAC.

Errores posibles: invoice.credit_note_not_found, invoice.not_found (404); invoice.credit_note_not_retryable, invoice.fiscal_profile_missing, invoice.livemode_mismatch, invoice.pac_error, invoice.pac_unreachable responden 400.

Cancela ante el SAT una nota de crédito ya stamped — mismo contrato que POST /v1/invoices/{id}/cancel (los cuatro motivos, motive: "01" exige substitution_uuid, idempotente). La diferencia: la respuesta aquí es el credit_note completo, no un shape recortado.

Cuerpo

Errores posibles: invoice.credit_note_not_found (404); invoice.invalid_cancel_motive, invoice.cancel_substitution_required, invoice.credit_note_not_stamped, invoice.no_provider_ref, invoice.livemode_mismatch, invoice.cancel_pending, invoice.pac_cancel_error responden 400. El ambiente se cruza contra la nota, igual que en la cancelación de la factura de ingreso.

Crea una cuenta por cobrar; internamente crea un Payment Link de un solo uso.

Cuerpo

Errores posibles: receivable.missing_fields, receivable.invalid_amount, receivable.invalid_currency, receivable.invalid_date, receivable.incomplete_fiscal_receptor.

Lista o lee una cuenta por cobrar. status es derivado: open | paid | overdue | canceled.

Errores posibles: receivable.not_found.

Arma la URL https://wa.me/... con el mensaje de cobro pre-redactado.

Errores posibles: receivable.no_phone (sin customer_phone capturado).

Estado de cuenta agregado de un cliente: sus cuentas y los totales abierto/vencido/pagado.

Antigüedad de saldos por cliente, en 4 cubos contables estándar.

Importa el CSV del estado de cuenta bancario. Multipart (file) o cuerpo crudo. Sin Idempotency-Key — su idempotencia real es el hash del archivo.

Campos (multipart o query)

Errores posibles: ver la tabla completa en Conciliación bancaria.

Lista los estados de cuenta importados, o las líneas de uno (filtro opcional matched/unmatched/partial).

Errores posibles: bank_statement.invalid_match_status.

Sin Authorization — la llave es receipt_code + rfc.

Cuerpo

Errores posibles: autofactura.invalid_body, autofactura.invalid_rfc, autofactura.generic_rfc_not_allowed (el RFC genérico XAXX010101000, bien formado pero ya no admitido — se rechaza antes de resolver slug o receipt_code), autofactura.not_available (404), autofactura.receipt_not_found (404), más los errores de invoice.* del PAC reenviados tal cual.

Descarga del CFDI ya timbrado; ambos parámetros deben coincidir con el CFDI.

Errores posibles: invoice.not_stamped, autofactura.receipt_not_found.

Cobrado, ticket promedio, reembolsado, disputas (con su holdback) y tasa de aprobación del período.

Query

Errores posibles: reports.invalid_period, reports.invalid_currency.

El mismo período de summary, desglosado día por día.

Query

Errores posibles: reports.invalid_period, reports.invalid_currency.

El período agrupado por método de pago o por conector ganador del ruteo, cada fila con su propio approval_rate.

Query

Errores posibles: reports.invalid_period, reports.invalid_currency.

Operaciones recientes, más nuevas primero — paginado por cursor opaco, sin from/to.

Query

Errores posibles: reports.invalid_cursor.

El asiento contable del ledger, línea por línea, sin agregar: cargo/abono en centavos ya separados en dos columnas. text/csv, streaming.

Query

Errores posibles: reports.invalid_period.

Informe de retenciones ISR/IVA del régimen de plataformas digitales por vendedor, base del DIOT. Período mensual, requerido — from/to no aplican aquí.

Query

Errores posibles: reports.invalid_period.

Cuánto le ahorró/recuperó Winal al tenant en el período: ruteo consciente de costo, retry cross-conector y dunning de suscripciones.

Query

Errores posibles: reports.invalid_period.

Pólizas contables del período, formato CONTPAQi o Aspel-COI, listas para importar.

Query

Errores posibles: reports.invalid_period, reports.invalid_format.

Corte de caja del turno: desglose por método/conector (cobrado, propinas, operaciones), totales y devoluciones. Ver Reportes → Multisucursal para el detalle narrativo.

Query

Errores posibles: reports.invalid_period, reports.invalid_currency.

Alta mínima de una solicitud, en draft.

Cuerpo

Errores posibles: onboarding_application.invalid_legal_name, invalid_person_type, invalid_contact_email.

Patch parcial (campos null/omitidos no se tocan), solo mientras la solicitud sea editable (draft/needs_info). Mismo cuerpo que POST, más documents[] (ver Onboarding para los 4 tipos requeridos).

Errores posibles: onboarding_application.not_found, onboarding_application.transition_conflict, onboarding_application.invalid_document.

Dispara la verificación (síncrona en fase 0): completitud → formato de RFC/CLABE → check de listas (simulado). Resuelve a approved, needs_info o rejected en la misma llamada.

Errores posibles: onboarding_application.missing_fields, missing_documents, transition_conflict.

Lista (?status=, ?limit= opcionales; sin documents) o lee una solicitud por id (con documents[]).

Errores posibles: onboarding_application.not_found.

Liga un sub-comercio con una solicitud de Onboarding ya approved.

Cuerpo

Errores posibles: connect.invalid_application_id, connect.application_not_found, connect.application_not_approved, connect.account_conflict.

Lista (?limit=) o lee una cuenta Connect. La CLABE del sub nunca se expone completa.

Errores posibles: connect.account_not_found.

Split manual post-cobro (multi sub-comercio). application_fee_minor + Σ splits[].amount_minor debe ser exactamente charge_amount_minor.

Cuerpo

Errores posibles: connect.invalid_charge, connect.missing_allocations, connect.invalid_allocation, connect.split_mismatch, connect.account_not_found.

Lista (?limit=) o lee un transfer, con sus splits[].

Errores posibles: connect.transfer_not_found.

Ordena una dispersión SPEI a una CLABE. Sin custodia (ADR-0001): sale de la cuenta del propio comercio.

Cuerpo

Errores posibles: payout.missing_fields, payout.invalid_amount, payout.invalid_clabe, payout.unsupported_currency.

Lista (?limit=, default 100, máx. 500) o lee un payout — provider_ref/tracking_key/failure_reason aparecen cuando el Worker ya ejecutó la orden.

Errores posibles: payout.not_found.

Catálogo global (sin variación por tenant). ?category= opcional.

Consulta de adeudo — NO mueve dinero, no exige Idempotency-Key.

Cuerpo: { "reference": "string, requerido" }

Errores posibles: biller.missing_reference, biller.invalid_code, biller.not_found, biller.invalid_reference, biller.reference_not_found, biller.livemode_unsupported.

⚠️ amount_due_minor es SIMULADO hoy (hash determinista de reference, sin llamada real al biller) y esta ruta de consulta está bloqueada en producción (sk_live_ recibe 400 biller.livemode_unsupported, no un adeudo): el simulador no puede devolver una cifra real, y devolverla igual sería tan peligroso como fabricar el pago mismo — ver Pago de servicios.

Confirma el pago del servicio ante el biller.

Cuerpo

Errores posibles: service_payment.missing_fields, service_payment.amount_mismatch, service_payment.idempotency_conflict, service_payment.livemode_unsupported (llave sk_live_ sin agregador real conectado).

Lista o lee un pago de servicio.

Query (solo en el listado)

Devuelve has_more y next_cursor junto a data, y cada pago trae confirm_requested_at: cuándo se pidió la confirmación al biller (null si nunca se llegó a pedir).

Errores posibles: service_payment.not_found, service_payment.invalid_period, service_payment.invalid_cursor.

Catálogo de operadoras (Telcel, AT&T, CFE…) para tu tenant, con la regla de validación de referencia de cada una y su disponibilidad reciente.

Activa o desactiva una operadora para tu tenant (por default TODAS están activas; solo hace falta llamarlo para apagar una).

Cuerpo: { "active": "bool, opcional (default true)" }

Errores posibles: recharge.invalid_carrier, recharge.carrier_not_found.

Catálogo de productos (montos/paquetes/servicios) por tenant, con el nombre y categoría de su operadora ya resueltos.

Ejecuta una recarga o pago vía recarga. Irreversible una vez entregada — ver El desenlace.

Cuerpo

Errores posibles: recharge.missing_fields, recharge.invalid_phone, recharge.invalid_reference, recharge.carrier_not_enabled, recharge.carrier_not_found, recharge.livemode_unsupported, recharge.product_not_found, recharge.product_not_supported_by_provider, recharge.catalog_not_synced, recharge.amount_required, recharge.amount_not_allowed, recharge.idempotency_conflict, recharge.payment_intent_not_found, recharge.payment_intent_not_succeeded, recharge.payment_intent_amount_mismatch, recharge.allowance_exhausted.

Última foto conocida (no en vivo) del saldo prefondeado de la bolsa que consume tu cuenta. Nunca es base contable — solo para saber si alcanza para la siguiente venta.

uses_own_credentials es true cuando la bolsa es de la cuenta (sus credenciales, o una bolsa de la que es dueña) y false cuando es la de quien la administra. El bloque refresh —solo cuando la bolsa se puede leer al momento— dice qué pasó con la última lectura pedida con POST /v1/recharge-balance/refresh y desde cuándo una nueva llega al agregador (next_available_at).

Lista o lee una recarga. Es tu ÚNICA forma de saber si una recarga processing ya se resolvió — ver Cómo entrega Winal una recarga.

Query (solo en el listado)

El listado devuelve has_more y next_cursor junto a data. Sin fechas ni cursor se comporta como siempre. Cada recarga trae además provider_cost_minor (el costo REAL descontado, puede ser null), client_reference, provider_transaction_id, connector_key, livemode y requested_at — los del intento que entregó, o del último.

Una recarga es un pedido con uno o más intentos contra un agregador (Cuando un agregador falla). Campos del pedido: attempt_count; failure_code (solo con status: "failed", catálogo cerrado de seis valores: not_requested, rejected, failed, absent_from_report, exhausted, unfunded); needs_review (true SOLO con absent_from_report: ahí outcome es undetermined y safe_to_retry es false — ver Cuando un agregador falla); y attempts[], uno por intento y en orden, cada uno con id, attempt_no, connector_key, status, provider_ref, provider_transaction_id, provider_cost_minor, client_reference, requested_at, resolved_at, failure_code, failure_reason y routing (reason legible; excluded: los agregadores no considerados por haberse intentado ya; y evaluated[]: cada agregador evaluado con provider_key, eligible y su reason —salud, saldo, prioridad o costo—, ver Cómo elige Winal el agregador). El id del intento 1 es el del pedido; los siguientes tienen el suyo y no resuelven por GET /v1/recharges/{id}.

Errores posibles: recharge.not_found, recharge.invalid_period, recharge.invalid_cursor, recharge.connector_key_unknown.

Estado de cuenta del período de la cuenta EFECTIVA: entregado con su costo real, en vuelo, rechazado, pagos de servicio, abonos recibidos, cupo y —solo si la cuenta es DUEÑA de la bolsa— su saldo. La variante .csv devuelve el mismo período con una línea por movimiento. Los totales y las líneas son por intento contra un agregador (el costo real es del intento): un pedido surtido por respaldo suma una rechazada y una entregada, y en el CSV son dos líneas con el mismo pedido_id — las dos últimas columnas, pedido_id e intento_no, van al final para no mover ninguna de las anteriores.

No incluye un «saldo de la cuenta»: el dinero vive en el agregador a nombre de quien fondeó la bolsa (Winal no custodia fondos) y una bolsa se comparte entre las cuentas que su dueño apuntó a ella. Lo de una cuenta administrada son sus movimientos y su cupo. Ver Recargas de tiempo aire.

Query

Por agregador. Sin filtro, la respuesta trae by_connector[]: el mismo período por agregador (connector_key, charges, in_flight, failed, deposits y allowance), y cada cifra del total es la suma de la misma cifra en los agregadores. Con filtro, connector_key aparece en la respuesta como eco (sin filtro no aparece) y by_connector tiene una sola entrada. Los pagos de servicio no se acotan y su note lo dice. Ver Cuadrar por agregador.

Errores posibles: recharge.invalid_period, recharge.connector_key_unknown, y en el CSV recharge.pouch_id_not_applicable si mandas pouch_id.

El HISTORIAL de movimientos de tu bolsa —ventas, cargos y ABONOS (depósitos)— tal como los reportó el agregador, cacheado por Winal. Sirve para conciliar un comprobante de depósito contra lo que el agregador dice haber recibido; no sustituye /statement, que sigue siendo la única prueba de que el TOTAL entró — esto es el detalle día a día para encontrar UN movimiento concreto. Ver Recargas de tiempo aire → Conciliar un depósito.

Solo tu bolsa PROPIA. Si tu cuenta consume la bolsa de quien te administra, esta ruta devuelve una página vacía: el detalle crudo de una bolsa compartida mezcla el consumo de todas las cuentas que la apuntan (y movimientos ajenos a tiempo aire, como Timbres CFDI), así que solo su dueño lo ve. Sigues viendo lo tuyo en /statement.

Vigencia declarada, nunca en vivo. Lo que devuelve esta ruta es lo que un ciclo periódico sincronizó del agregador (cada ~15 minutos, hoy y ayer); synced_through dice hasta cuándo se sabe con certeza que no faltan filas y coverage_from desde cuándo hay historial. Un array vacío con coverage_from: null significa "todavía no se ha sincronizado", no "no hubo movimientos". Y truncated_at con fecha significa que ese día se leyó A MEDIAS (el reporte del agregador viene paginado y se alcanzó el tope de páginas): el listado está incompleto aunque synced_through tenga valor, así que la ausencia de un movimiento no prueba nada. Los tres campos juntos son los que permiten distinguir "no lo hubo" de "no lo sabemos todavía".

Query

Errores posibles: recharge.invalid_period.

Ordena un traspaso. Irreversible una vez aplicado —el agregador no lo cancela ni lo reversa— y no delegable: no admite Winal-Account-Key (ordenar un traspaso mueve tu propia tesorería, no la de una cuenta que administras) y si la mandas responde 403 account.delegation_not_allowed.

Cuerpo

Errores posibles: idempotency_key_required, recharge_transfer.missing_fields, recharge_transfer.idempotency_key_required, recharge_transfer.invalid_amount, recharge_transfer.invalid_note, recharge_transfer.invalid_pouch, recharge_transfer.livemode_unsupported, recharge_transfer.idempotency_conflict, recharge_transfer.source_not_found, recharge_transfer.destination_not_managed, recharge_transfer.destination_not_found, recharge_transfer.same_bag, recharge_transfer.destination_account_ref_missing, recharge_transfer.insufficient_bag_balance, recharge_transfer.provider_unavailable, recharge_transfer.provider_rejected, recharge_transfer.not_found (defensivo: es la guarda interna del servicio, en la práctica no se alcanza por esta ruta), y account.delegation_not_allowed si mandas Winal-Account-Key.

Lista o lee un traspaso, acotado al ambiente de la llave que pregunta. Es tu única forma de saber si uno en requesting o processing ya se resolvió — no lo reordenes mientras esperas.

Query (solo en el listado)

Errores posibles: recharge_transfer.not_found.

Las cuentas propias de la cuenta efectiva en cada agregador: con tu llave sola, las tuyas; actuando sobre un cliente (Winal-Account-Key), las de ese cliente — nunca las de otro. No lleva parámetros: devuelve una por agregador, vivas (en curso, sin desenlace, esperando credenciales o dadas de alta). Solo lectura: dar de alta la cuenta vive en la consola.

Campos de cada elemento

Nunca viajan credenciales ni los datos del titular.

Por cada bolsa que la cuenta efectiva posee en un agregador con formulario de reporte (su cuenta propia, o la cuenta madre del integrador), su referencia de depósito y el enlace del formulario, con la hora en que se leyó. Nunca el de una bolsa ajena: una farmacia que vende de la bolsa de su integrador recibe una lista vacía. No le pregunta nada al agregador. Sin parámetros.

Campos de cada elemento

Vuelve a leer el enlace del agregador (TAECEL: urlReporteCompra) con las credenciales de cada bolsa propia de la cuenta, o de una sola. Solo con llave de PRODUCCIÓN: pedirlo con sk_test_ llamaría al agregador con las credenciales REALES de la bolsa, así que se rechaza antes de tocar nada. Detrás del freno del enlace —DOS ventanas: 24 horas de frescura desde la última lectura EXITOSA, y 5 minutos de reintento desde el último intento, tenga o no éxito— dentro de él contesta con el que ya hay, sin llamar a nadie. Espera hasta wait_ms al desenlace: 200 si ya no hay nada en vuelo, 202 si alguna lectura sigue en camino (mira el GET, que no exige ambiente). Sin Idempotency-Key: repetirla no duplica nada.

Cuerpo (opcional)

Errores posibles: recharge.report_link_unavailable, recharge.report_link_source_not_found, recharge.report_link_requires_live_key (llave de prueba).

Lee ahora el saldo de la bolsa de la que vende la cuenta efectiva (TAECEL: getBalance) —la misma de GET /v1/recharges/balance, y escrita en la misma foto que su monitor—. Freno de 10 minutos por bolsa, contados desde su última lectura de CUALQUIER origen: dentro de él contesta 200 con la última foto y su observed_at, sin llamar al agregador. Fuera, pide la lectura y espera hasta wait_ms: 200 con la foto fresca, o 202 con la anterior y refresh.status: "pending". Responde el mismo recurso que GET /v1/recharges/balance con el bloque refresh.

Cuerpo (opcional)

Errores posibles: recharge.balance_refresh_unavailable (llave de prueba, o ninguna bolsa legible).

Webhook a la cuenta dueña de la bolsa la primera vez que Winal ve un abono nuevo en su reporte de movimientos (TAECEL: getReports, leído cada ~15 minutos, hoy y ayer). Exactamente uno por movimiento de cada bolsa; el event_id se deriva del movimiento. Solo abonos, nunca cargos. Llega en los dos ambientes: comprueba livemode antes de acreditar nada. data es el movimiento con los mismos campos de GET /v1/recharges/bag-movements, más account_id, provider_key, source_id, pouch_id y observed_at (cuándo lo vio Winal). No está medido que el reporte traiga el abono de un depósito validado desde el formulario: si no llega, confirma con POST /v1/recharge-balance/refresh (arriba).