# Empiece aquí — vender recargas desde su aplicación

**Para quién es esto:** para quien quiere que su negocio venda recargas y no
quiere leerse un manual para lograrlo.

Elija el camino que se parezca a su caso. Los tres funcionan hoy, contra el
ambiente de pruebas, sin pedir permiso a nadie y sin gastar un peso.

| Su situación | Vaya a | Tiempo |
|---|---|---|
| No tengo programador ni sistema propio | [Camino 1](#camino-1--no-quiero-programar-nada) | 5 minutos |
| Tengo un sistema y un programador | [Camino 2](#camino-2--tengo-mi-sistema-y-quiero-conectarlo) | 10 minutos |
| Mi programador quiere el detalle completo | [GUIA-INTEGRACION.md](GUIA-INTEGRACION.md) | 30 minutos |

---

## Camino 1 — No quiero programar nada

Hay un punto de venta completo ya hecho. Se sube a cualquier hosting con PHP
—el mismo donde tendría una página web— y ya vende.

1. Descargue la carpeta [`examples/punto-de-venta-php/`](examples/punto-de-venta-php/)
   y la carpeta [`sdk/`](sdk/).
2. Súbalas a su hosting, respetando esa estructura de carpetas.
3. Abra la página en el navegador.

Ya está vendiendo, en modo de pruebas. Verá el catálogo de servicios, el saldo
y un formulario de tres campos: servicio, número y monto.

**Para vender de verdad**, abra `config.php` y ponga las credenciales que le
entregó Recarga.do:

```php
define('RECARGADO_KEY',    'rk_...');
define('RECARGADO_SECRET', 'sk_...');
```

Eso es todo. No hay base de datos que instalar ni nada que compilar.

Ese punto de venta ya trae resuelto lo que suele costar dinero cuando se hace a
mano: si el cajero pulsa "Recargar" dos veces, o refresca una pantalla que se
quedó congelada, **no se cobra dos veces**.

---

## Camino 2 — Tengo mi sistema y quiero conectarlo

Hay una librería oficial para cada lenguaje. Es **un solo archivo**, sin nada
que instalar: se copia al proyecto y se usa.

| Lenguaje | Archivo | Cómo se usa |
|---|---|---|
| PHP 7.2+ | [`sdk/php/recargado.php`](sdk/php/recargado.php) | `require 'recargado.php';` |
| Node.js 12+ | [`sdk/node/recargado.js`](sdk/node/recargado.js) | `require('./recargado.js')` |
| Python 3.6+ | [`sdk/python/recargado.py`](sdk/python/recargado.py) | `from recargado import RecargaDo` |

Sin Composer, sin npm, sin pip. Sin dependencias de terceros.

### Su primera recarga

Copie esto y ejecútelo tal cual. Usa credenciales públicas de prueba: no cobra
nada ni recarga ningún teléfono real.

**PHP**

```php
require_once 'recargado.php';

$rd = RecargaDo::pruebas();

$venta = $rd->recargar(1, '8095551235', 50, 'MI-PRIMERA-VENTA');

if ($venta->exitosa()) {
    echo "Entregada. Autorización: {$venta->authCode}";
} elseif ($venta->pendiente()) {
    echo "En verificación. NO cobre todavía.";
} else {
    echo "Rechazada: {$venta->mensaje}";
}
```

**Node.js**

```js
const { RecargaDo } = require('./recargado.js');

const rd = RecargaDo.pruebas();

const venta = await rd.recargar(1, '8095551235', 50, 'MI-PRIMERA-VENTA');

if (venta.exitosa())        console.log('Entregada. Autorización:', venta.authCode);
else if (venta.pendiente()) console.log('En verificación. NO cobre todavía.');
else                        console.log('Rechazada:', venta.mensaje);
```

**Python**

```python
from recargado import RecargaDo

rd = RecargaDo.pruebas()

venta = rd.recargar(1, '8095551235', 50, 'MI-PRIMERA-VENTA')

if venta.exitosa():
    print('Entregada. Autorización:', venta.auth_code)
elif venta.pendiente():
    print('En verificación. NO cobre todavía.')
else:
    print('Rechazada:', venta.mensaje)
```

> **Pruebe esto ahora: ejecútelo dos veces seguidas.** Obtendrá la **misma**
> transacción y el mismo código de autorización las dos veces, no dos recargas.
> Eso es la protección contra el doble cobro funcionando, y viene de la
> referencia `MI-PRIMERA-VENTA`: mientras no cambie, Recarga.do entiende que es
> la misma venta. Cámbiela y obtendrá una recarga nueva.

**Para vender de verdad**, cambie una línea:

```php
$rd = new RecargaDo($_ENV['RECARGADO_KEY'], $_ENV['RECARGADO_SECRET']);
```

---

## Las dos cosas que hay que entender

Todo lo demás la librería lo resuelve sola. Estas dos no puede resolverlas por
usted, porque dependen de su negocio.

### 1. El cuarto parámetro es su número de factura

```php
$rd->recargar(1, '8095551235', 50, 'FACTURA-00123');
//                                  └── esto
```

Es lo que impide cobrarle dos veces al mismo cliente. Si la red se cae y su
sistema reintenta con **la misma** factura, Recarga.do reconoce la operación y
devuelve el resultado original en vez de recargar otra vez.

- Use el número de factura, ticket o venta de **su propio sistema**. Ya es único
  y ya está guardado, así que no tiene que inventar nada.
- Debe ser distinto para cada venta, y no repetirse en 24 horas.
- **Nunca** lo genere dentro de la función que reintenta: eso convierte cada
  reintento en una venta nueva, que es exactamente lo que se quiere evitar.

### 2. Los desenlaces son tres, no dos

Casi todo el mundo programa "funcionó" y "falló". Falta el del medio, y es el
que cuesta dinero.

| Desenlace | Qué significa | Qué debe hacer el cajero |
|---|---|---|
| `exitosa()` | Entregada y cobrada | Cobrar y entregar el recibo |
| `pendiente()` | **No se sabe.** El dinero está retenido, ni cobrado ni devuelto | **No cobrar y no repetir la venta.** Se resuelve sola |
| `fallida()` | Rechazada. El saldo ya volvió solo | No cobrar. Corregir y vender de nuevo |

Si su código trata `pendiente()` como un fallo y vuelve a vender, el cliente
recibe dos recargas y usted cobra una.

---

## Pruebe los tres desenlaces antes de vender de verdad

En el ambiente de pruebas, **el último dígito del número decide qué pasa**. Así
puede probar los casos difíciles cuando quiera, sin esperar a que ocurran.

| Termine el número en | Qué obtiene |
|---|---|
| `0` | Rechazada por número inválido |
| `1` | Rechazada por la telco |
| `2` | **En verificación.** Pruebe este, es el que cuesta dinero |
| cualquier otro | Entregada |

```php
$rd->recargar(1, '8095551232', 50, 'PRUEBA-PENDIENTE');  // → pendiente()
```

**No pase a producción sin haber probado el `2`.**

---

## Qué más puede hacer

```php
$rd->disponible();                  // pesos que puede gastar ahora
$rd->servicios();                   // catálogo completo
$rd->servicios('Telefonía');        // solo una categoría
$rd->transaccion(48830);            // estado de una operación
$rd->transacciones(['status' => 'SUCCESS']);   // historial
$rd->recibo(48830);                 // recibo para imprimir
$rd->enPruebas();                   // ¿sigo en pruebas? Compruébelo antes de vender
```

Los nombres son los mismos en los tres lenguajes (en Python, con guion bajo:
`en_pruebas()`, `esperar_resultado()`).

---

## Antes de su primera venta real

- [ ] Probé el número terminado en `2` y mi sistema **no** vuelve a vender.
- [ ] La referencia que paso es mi número de factura, y no se repite.
- [ ] El `api_secret` está en el servidor, **nunca** en una app móvil ni en
      JavaScript del navegador: quien lo extraiga puede gastar su saldo.
- [ ] Guardo `transactionId` y `requestId` de cada venta. Es lo que pide soporte.
- [ ] `$rd->enPruebas()` devuelve `false`.

---

## Si algo sale mal

Toda operación devuelve un `requestId`. Con ese dato soporte localiza su
operación en segundos; sin él, no. Guárdelo siempre.

| Documento | Para qué |
|---|---|
| [GUIA-INTEGRACION.md](GUIA-INTEGRACION.md) | La guía completa, con el detalle de cada decisión |
| [API.md](API.md) | Referencia de todos los endpoints y códigos de error |
| [examples/](examples/) | Ejemplos ejecutables en los tres lenguajes |
| [integracion.html](https://doc.recarga.do/integracion.html) | Manual con consola interactiva |