Recargas móviles, paquetes de datos, luz, agua, universidades e impuestos. Una sola integración, 59 servicios, y un ambiente de pruebas que no le cuesta un peso.
Elija el camino que se parezca a su caso. Los tres funcionan hoy contra el ambiente de pruebas, sin pedir permiso a nadie.
Un punto de venta completo, ya hecho. Se sube a cualquier hosting con PHP —el mismo donde tendría una página web— y empieza a vender en modo de pruebas.
Ver los tres caminos 30 minDe la primera recarga de prueba a la lista de comprobación para salir a producción. Paso a paso, con todo el código copiable.
Empezar a integrar 1 minUn solo archivo para pegar en ChatGPT, Claude o Copilot: reglas, contratos, errores típicos y código funcional. Para que escriba la integración correcta a la primera.
Copiar el contexto ConsultaLos 59 servicios, con lo que más dudas genera: qué se escribe en el campo
identifier de cada uno. Buscable y filtrable.
Credenciales de prueba abiertas. No generan recargas ni cargos reales.
# Guarde sus credenciales en una variable AUTH="Authorization: Bearer rk_sbx_8c4cacb52c6b8f65bf389480ce3f8891.sk_sbx_a8e4de1dbd5e135a4be191cfd8901f386e541279a6550b1d30af9fbeaa65bbd0" # 1 · ¿En qué ambiente estoy? → "sandbox": true significa pruebas curl -s https://api.recarga.do/v1/cuenta -H "$AUTH" # 2 · ¿Cuánto puedo gastar? curl -s https://api.recarga.do/v1/saldo -H "$AUTH" # 3 · Hacer una recarga de prueba curl -s -X POST https://api.recarga.do/v1/recargas \ -H "$AUTH" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"service_id":1,"identifier":"8095551235","amount":100}'
Termine el identifier en 0 y obtendrá número inválido; en
1, rechazo; en 2, resultado pendiente; cualquier otro dígito da
éxito. Así prueba todos los caminos de su código sin depender de la suerte.
Son tres ideas. Con estas tres, el resto de la documentación se lee sola.
Si su conexión falla y reintenta, envíe la misma Idempotency-Key. Una clave
nueva es una operación nueva: su cliente recibiría dos recargas y usted
cobraría una. Genere la clave una sola vez, antes del primer intento, y
guárdela junto a la orden en su base de datos.
| Campo | Qué significa |
|---|---|
saldo_disponible | Lo que puede gastar ahora mismo |
saldo_retenido | Comprometido por operaciones en curso: ni cobrado ni gastable |
saldo_actual | La suma de los dos. El dinero que aún le pertenece |
El importe se reserva antes de procesar la operación. Si se rechaza, vuelve a su saldo. Si el resultado queda en duda, permanece retenido hasta resolverse. Nunca se cobra algo que no se entregó, ni se entrega algo sin respaldo de saldo.
Las rutas están en español. Los verbos GET y POST los
define el protocolo HTTP y no se traducen: GET es consultar,
POST es ejecutar una acción.
| Acción | Verbo | Ruta | Notas |
|---|---|---|---|
| Ver si el servicio está activo | GET | /v1/estado | Público, sin credenciales |
| Ver versión y ambiente | GET | /v1/informacion | Público, sin credenciales |
| Ver mi cuenta | GET | /v1/cuenta | Indica si opera en pruebas o en producción |
| Consultar mi saldo | GET | /v1/saldo | Disponible, retenido, límites y consumo |
| Ver categorías | GET | /v1/categorias | Telefonía, electricidad, agua… |
| Ver qué puedo vender | GET | /v1/servicios | De aquí sale el service_id |
| Ver paquetes de datos | GET | /v1/servicios/{id}/paquetes | Operadoras móviles |
| Hacer una recarga | POST | /v1/recargas | Exige Idempotency-Key |
| Anular una recarga | POST | /v1/transacciones/{id}/anular | Exige Idempotency-Key |
| Ver mis ventas | GET | /v1/transacciones | Paginado y filtrable |
| Ver una venta | GET | /v1/transacciones/{id} | Detalle y estado |
| Imprimir el recibo | GET | /v1/transacciones/{id}/recibo | Solo si la venta fue exitosa |
Las equivalentes en inglés (/v1/balance, /v1/recharges…) siguen
funcionando indefinidamente y hacen exactamente lo mismo. No hay que migrar nada.
El recorrido típico en una caja, de principio a fin.
/v1/servicios. Refrésquelo cada pocas horas, no en cada venta.POST /v1/recargas
Y trata los cuatro desenlaces posibles. El 202 es el que más integraciones rompe.transaction_id y request_id. Sin ellos, soporte no puede ayudarle.SDK, ejemplos y punto de venta, todo junto en un ZIP.
DescargarCliente ya escrito en PHP, Node y Python. Un archivo, sin dependencias.
VerCódigo listo para ejecutar, incluido un punto de venta completo.
VerTodos los endpoints con el sandbox precargado y pruebas automáticas.
DescargarCada respuesta incluye un request_id, también en la cabecera
X-Request-Id. Guárdelo junto a cada venta en su sistema.
Con ese identificador localizamos cualquier operación en segundos.
Al reportar una incidencia, incluya el request_id y, si aplica, el
transaction_id.
Todo lo de esta documentación funciona ahora mismo con las credenciales de prueba. Para vender de verdad hacen falta las suyas.
No hace falta registrarse ni pedir permiso. Las credenciales de prueba están en esta documentación y funcionan al instante: no cobran nada ni recargan ningún teléfono real.
Cuando su integración funcione en pruebas, pida sus credenciales reales a su ejecutivo de cuenta de Recarga.do. Solo cambian las claves: los endpoints, los formatos y los códigos son idénticos.
El modelo es prepago: cada venta descuenta de su saldo. Compruébelo con
GET /v1/saldo y vigile el campo saldo_bajo.
request_id, y toda venta un
transaction_id. Con esos dos se localiza la operación completa en
segundos. Sin ellos, una incidencia puede tardar horas en reproducirse.