# API Recarga.do v1 — Referencia para clientes

**Base URL:** `https://api.recarga.do`
**Versión:** `v1` · **Moneda:** DOP · **Zona horaria:** America/Santo_Domingo

---

## MODELO DE INTEGRACIÓN

API REST de **consulta directa**. El cliente llama por HTTPS y recibe JSON.

- **No** se incrusta ningún `<iframe>`: la API no sirve HTML y responde
  `X-Frame-Options: DENY`.
- **No** hay redirecciones ni *callbacks* hacia pantallas de Recarga.do.
- **No** hay SDK, ni sesiones, ni cookies. Un par de credenciales fijas en un header.
- `Access-Control-Allow-Origin: *`, de modo que un navegador puede llamarla desde
  cualquier origen. Aun así, el `api_secret` debe permanecer en el servidor del
  integrador, nunca dentro de una aplicación distribuida.

La interfaz de usuario es íntegramente del integrador. Guía paso a paso en
[GUIA-INTEGRACION.md](GUIA-INTEGRACION.md).

> El `<iframe src="index.php?token=JWT">` que aparece en `SYSTEM_ANALYSIS.md` pertenece al
> **portal interno del sistema legado**, no a la API v1 ni a las integraciones de terceros.

---

## AUTENTICACIÓN

Cada comercio recibe un par `api_key` / `api_secret`. Se admiten dos formas equivalentes:

```http
Authorization: Bearer <api_key>.<api_secret>
```

```http
X-Api-Key: <api_key>
X-Api-Secret: <api_secret>
```

El `api_key` determina la empresa. **Nunca envíe `empresa_id` en el cuerpo**: si lo hace y
no coincide con el de su token, la petición se rechaza con `403`.

Condiciones para operar: token `activo` y no expirado, empresa con API habilitada y en
estado `activa` o `vip`.

---

## FORMATO DE RESPUESTA

Éxito:

```json
{
  "success": true,
  "data": { },
  "message": "Operación realizada correctamente",
  "request_id": "req_9f2c1ab34de5f6a7b8c9d0e1"
}
```

Error:

```json
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Balance insuficiente para procesar la operación.",
    "details": { "saldo_disponible": 120.00, "monto_requerido": 500.00 }
  },
  "request_id": "req_9f2c1ab34de5f6a7b8c9d0e1"
}
```

`request_id` viaja también en el header `X-Request-Id`. **Guárdelo**: es la referencia
para cualquier consulta de soporte.

---

## CÓDIGOS HTTP

| Código | Cuándo |
|---|---|
| 200 | Consulta correcta |
| 201 | Recarga procesada |
| 202 | Operación en curso — resultado aún desconocido |
| 400 / 422 | Datos inválidos |
| 401 | Credenciales ausentes o inválidas |
| 403 | Token sin permiso, empresa suspendida, o `empresa_id` ajeno |
| 404 | Recurso inexistente (o de otra empresa) |
| 409 | Conflicto de idempotencia |
| 429 | Límite de peticiones excedido |
| 500 | Error interno |
| 502 | El proveedor rechazó o no está disponible |

---

## CÓDIGOS DE ERROR

| Código | HTTP | Significado |
|---|---|---|
| `UNAUTHENTICATED` | 401 | Credenciales ausentes o inválidas |
| `FORBIDDEN` | 403 | Sin permiso para la operación |
| `NOT_FOUND` | 404 | Recurso inexistente |
| `VALIDATION_ERROR` | 422 | Parámetros inválidos |
| `INSUFFICIENT_BALANCE` | 422 | Saldo disponible insuficiente |
| `LIMIT_EXCEEDED` | 422 | Límite diario/semanal/mensual superado |
| `IDEMPOTENT_REQUEST_IN_PROGRESS` | 409 | Operación en curso con la misma clave |
| `IDEMPOTENCY_CONFLICT` | 409 | Clave irresoluble; use una nueva |
| `RATE_LIMIT_EXCEEDED` | 429 | Demasiadas peticiones |
| `TRANSACTION_PENDING` | 202 | Resultado desconocido; consulte el estado |
| `INVALID_PHONE` | 502 | Número inválido según el proveedor |
| `INVALID_PRODUCT` | 502 | Servicio no válido |
| `INVALID_AMOUNT` | 502 | Monto no admitido |
| `DUPLICATE_TRANSACTION` | 502 | El proveedor la considera duplicada |
| `TRANSACTION_REJECTED` | 502 | Rechazo genérico del proveedor |
| `PROVIDER_TIMEOUT` | 502 | El proveedor no respondió a tiempo |
| `PROVIDER_UNAVAILABLE` | 502 | Sin comunicación con el proveedor |
| `INTERNAL_ERROR` | 500 | Error interno |

---

## IDEMPOTENCIA — LEA ESTO ANTES DE INTEGRAR

`POST /v1/recharges` **exige** el header `Idempotency-Key`: una cadena única por
operación (se recomienda un UUID v4), de hasta 128 caracteres.

```http
Idempotency-Key: 8fe9d681-a99e-4fda-b610-3c0a1f7e42bd
```

- Reintentar con la **misma clave y el mismo cuerpo** devuelve la respuesta original,
  con el header `Idempotent-Replay: true`. **No se ejecuta una segunda recarga.**
- Si la operación original sigue en curso: `409 IDEMPOTENT_REQUEST_IN_PROGRESS`.
  Espere y consulte el estado; **no genere una clave nueva para el mismo cobro.**
- Reutilizar la clave con **otro** cuerpo: `422`.
- Las claves se conservan 24 horas.

### Qué hacer ante un timeout de red

**Nunca** reintente con una clave nueva. Reintente con la **misma** clave, o consulte
`GET /v1/transactions?identifier=<número>`. Una clave nueva es una operación nueva y
puede recargar dos veces al mismo cliente final.

---

## PERMISOS DEL TOKEN

Un token puede limitarse a un subconjunto de operaciones. El modelo es compatible hacia atrás:

| Estado del token | Comportamiento |
|---|---|
| **Sin permisos declarados** | Se permite toda operación. Es el estado por defecto de los tokens existentes. |
| **Con al menos un permiso declarado** | Modo estricto: solo se admite lo declarado; el resto responde `403`. |

Así, restringir un token concreto no exige coordinación con el resto de clientes.

| Permiso | Concede |
|---|---|
| `recharges.create` | Ejecutar recargas |
| `recharges.read` | Consultar recargas |
| `transactions.read` | Consultar historial, detalle y recibos |
| `balance.read` | Consultar saldo y límites |
| `account.read` | Consultar los datos de la cuenta |
| `catalog.read` | Consultar servicios, categorías y paquetes |
| `*` | Todos los permisos |

Consulte los permisos vigentes de su token en `GET /v1/account`, campo `token.permisos`.
Una lista vacía significa que no hay restricción.

**Recomendación:** si su integración solo consulta y nunca recarga, pida un token limitado a
`balance.read`, `catalog.read` y `transactions.read`. Un token filtrado sin `recharges.create`
no puede gastar su saldo.

---

## LISTA BLANCA DE IPs

Opcionalmente, un token puede restringirse a un conjunto de direcciones IP. Si el token tiene
al menos una IP declarada, cualquier petición desde otro origen responde `403`, aunque las
credenciales sean correctas.

Es la defensa que convierte un secreto filtrado en algo inservible fuera de su servidor.
Solicítela a soporte indicando las IPs de salida de su infraestructura.

---

## RATE LIMITING

Por defecto 120 peticiones/minuto por token (configurable por comercio). Toda respuesta
incluye:

```http
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1786568460
```

---

## ENDPOINTS

### `GET /v1/health` — público
Estado del servicio. `{"status":"ok"}`

### `GET /v1/info` — público
Nombre, versión y entorno de la API.

### `GET /v1/account`
Datos de la empresa asociada al token y su ambiente (`production` / `development`).

### `GET /v1/balance`
```json
{
  "saldo_actual": 15400.00,
  "saldo_disponible": 15150.00,
  "saldo_retenido": 250.00,
  "tipo_credito": "prepago",
  "alerta_saldo_bajo": 5000.00,
  "limites": { "diario": 50000.00, "semanal": 250000.00, "mensual": 1000000.00 },
  "consumo_periodo": { "diario": 3200.00, "semanal": 18400.00, "mensual": 61200.00 },
  "saldo_bajo": false,
  "moneda": "DOP",
  "actualizado_en": "2026-08-12 20:31:04"
}
```

`saldo_retenido` es dinero comprometido por operaciones en curso: ni gastable ni cobrado.

### `GET /v1/categories`
Categorías con al menos un servicio activo.

### `GET /v1/services`
Parámetros opcionales: `categoria`, `q`.

```json
[{
  "id": 12, "nombre": "Claro Recarga", "tipo": "standard",
  "categoria": "Telefonía", "categoria_id": 1,
  "monto_minimo": 20.00, "monto_maximo": 5000.00,
  "acepta_anulacion": true
}]
```

### `GET /v1/services/{id}/packages`
Paquetes de datos del servicio (operadoras móviles).

### `POST /v1/recharges`

```http
POST /v1/recharges
Authorization: Bearer <api_key>.<api_secret>
Idempotency-Key: 8fe9d681-a99e-4fda-b610-3c0a1f7e42bd
Content-Type: application/json

{
  "service_id": 12,
  "identifier": "8095551234",
  "amount": 100,
  "terminal_id": "CAJA-01"
}
```

| Campo | Tipo | Obligatorio | Notas |
|---|---|---|---|
| `service_id` | entero | sí | De `GET /v1/services` |
| `identifier` | cadena | sí | Teléfono, contrato o NIC según el servicio |
| `amount` | decimal | sí | > 0, máximo 2 decimales, dentro del rango del servicio |
| `terminal_id` | cadena | no | Referencia de caja/terminal, hasta 50 caracteres |

**201:**
```json
{
  "success": true,
  "data": {
    "transaction_id": 48830,
    "status": "SUCCESS",
    "xid": "RD-3f9a2c8e1b7d4a6f0c5e2b91",
    "auth_code": "884213",
    "service": { "id": 12, "nombre": "Claro Recarga" },
    "identifier": "8095551234",
    "amount": 100.00,
    "currency": "DOP",
    "provider_message": "Recarga procesada exitosamente",
    "processed_at": "2026-08-12T20:44:31-04:00"
  },
  "message": "Recarga procesada exitosamente",
  "request_id": "req_..."
}
```

**202 — resultado desconocido:**
```json
{
  "success": false,
  "error": {
    "code": "TRANSACTION_PENDING",
    "message": "La operación quedó en proceso. Consulte su estado antes de reintentar; el importe permanece retenido.",
    "details": {
      "transaction_id": 48831,
      "xid": "RD-...",
      "status": "PENDING",
      "consultar_en": "/v1/transactions/48831"
    }
  }
}
```

Ante un 202: **no reintente a ciegas.** Consulte la transacción. El importe está
retenido, no cobrado; se liquidará al conocerse el resultado real.

### `GET /v1/transactions`
Filtros: `page` (def. 1), `per_page` (def. 50, máx. 200), `status`, `date_from`,
`date_to`, `identifier`.

```json
{
  "items": [ ... ],
  "pagination": { "page": 1, "per_page": 50, "total": 1284, "total_pages": 26 }
}
```

### `GET /v1/transactions/{id}`
Detalle. Solo transacciones de su empresa; cualquier otra devuelve 404.

### `GET /v1/transactions/{id}/receipt`
Recibo en JSON. Solo para transacciones `SUCCESS`.

---

## SANDBOX

Los comercios con ambiente `development` no alcanzan al proveedor real. El escenario se
elige por el último dígito de `identifier`:

| Termina en | Resultado |
|---|---|
| `0` | `FAILED` / `INVALID_PHONE` |
| `1` | `FAILED` / `TRANSACTION_REJECTED` |
| `2` | `202 TRANSACTION_PENDING` |
| otro | `SUCCESS` |

Consulte `GET /v1/account` para saber en qué ambiente opera su token.

---

## EJEMPLO COMPLETO (cURL)

```bash
KEY="su_api_key"; SECRET="su_api_secret"
AUTH="Authorization: Bearer $KEY.$SECRET"

# Saldo
curl -s https://api.recarga.do/v1/balance -H "$AUTH"

# Catálogo
curl -s "https://api.recarga.do/v1/services?categoria=Telefon%C3%ADa" -H "$AUTH"

# Recarga (clave de idempotencia única por operación)
curl -s -X POST https://api.recarga.do/v1/recharges \
  -H "$AUTH" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"service_id":12,"identifier":"8095551234","amount":100}'

# Consultar
curl -s https://api.recarga.do/v1/transactions/48830 -H "$AUTH"
```

---

## ENDPOINTS PREVISTOS (aún no disponibles)

`POST /v1/transactions/{id}/reverse` · `POST /v1/service-payments` (pago de facturas) ·
`GET /v1/invoices` · webhooks salientes. Ver `CHANGELOG.md`.