# Guía de integración — API Recarga.do v1

**Para quién es esto:** para el comercio que va a vender recargas desde su propio sistema, y
para el técnico que va a conectarlo. Punto de venta, app móvil, portal web, ERP o bot de
WhatsApp.

**Qué logrará al terminar:** su aplicación consultará saldo, mostrará el catálogo de servicios,
ejecutará recargas y consultará transacciones, todo desde su propio código y con su propia
interfaz, sin depender de ninguna pantalla de Recarga.do.

**Si usted no programa:** entregue esta guía a su técnico y quédese con cuatro decisiones que son
suyas, no de él:

1. **Cuánto saldo mantiene depositado, y quién vigila que no se acabe.** El modelo es prepago
   ([§4](#s4)).
2. **Qué hace la caja cuando una recarga queda «en verificación».** Es una política de negocio,
   no un detalle técnico ([§6](#s6)).
3. **Qué hace la caja cuando una recarga «en verificación» se cobra un rato después.** Le puede
   costar dinero si no lo decide antes ([§6](#s6)).
4. **Quién revisa al cierre las operaciones que quedaron pendientes** ([§6](#s6) y [§13](#s13)).

Si además quiere el camino corto —un punto de venta ya hecho o una librería de un solo
archivo—, empiece por [EMPIECE-AQUI.md](EMPIECE-AQUI.md).

### Datos fijos

| Dato | Valor |
|---|---|
| API | `https://api.recarga.do` |
| Moneda | DOP |
| Formato de los importes | **Pesos con hasta 2 decimales. No son centavos.** `100` es RD$100.00. Más de 2 decimales se rechaza con `422` |
| Zona horaria | `America/Santo_Domingo` (UTC−4) |
| Modelo | Prepago: usted deposita saldo y cada venta lo consume |

**¿No usa terminal ni escribe código?** Pruebe la API desde la consola interactiva de
[integracion.html](https://doc.recarga.do/integracion.html).

### Índice

| Sección | De qué trata |
|---|---|
| [1. Su primera recarga en 5 minutos](#s1) | El código que hay que ejecutar, y lo que devuelve |
| [2. No es una pantalla incrustada](#s2) | Qué NO hay que construir |
| [3. Cómo se conecta su aplicación](#s3) | Arquitectura, credenciales y qué guardar |
| [4. Cómo funciona el dinero](#s4) | Depósitos, saldo, comisión y aviso de saldo bajo |
| [5. La regla que evita cobrar dos veces](#s5) | Idempotencia, reintentos y sus límites |
| [6. Los desenlaces y qué hacer con cada uno](#s6) | Los cinco finales posibles de una venta |
| [6-ter. Seguro de ley (Seguro Dominicana)](#s6c) | Datos, código SMS, plan, cotización, venta y PDF de la póliza |
| [7. Probar sin gastar dinero](#s7) | El simulador y los escenarios de prueba |
| [8. Errores: qué significan y qué hacer](#s8) | Tabla completa de códigos |
| [9. Límites y buenas prácticas de consumo](#s9) | Rate limit, timeouts, caché y fechas |
| [10. Lista de comprobación para producción](#s10) | Antes de mover dinero real |
| [11. Cómo pasar a producción](#s11) | Qué pedir y qué verificar |
| [12. Qué no existe todavía](#s12) | Para que no lo diseñe contando con ello |
| [13. Soporte](#s13) | A quién escribir y con qué datos |

### Palabras que va a leer

| Término | Qué significa |
|---|---|
| *endpoint* | Una ruta de la API. Por ejemplo `GET /v1/saldo` |
| *token* / *credenciales* | El par `api_key` + `api_secret` que identifica a su empresa. En esta guía «el token» y «sus credenciales» son la misma cosa. Un token puede llevar permisos declarados y una lista de IPs autorizadas |
| *cabecera* (*header*) | Un dato que viaja junto a la petición o la respuesta, aparte del cuerpo. Por ejemplo `Authorization`. En esta guía se dice siempre «cabecera» |
| *cuerpo* o *payload* | El JSON que usted envía en un `POST` |
| *clave de idempotencia* (`Idempotency-Key`) | Un código único por venta que le dice a la API: «esta es la misma venta de antes, no la ejecutes otra vez». En esta guía, «clave» a secas siempre se refiere a esta, nunca al `api_key` |
| *UUID v4* | Identificador único universal: una cadena aleatoria que en la práctica nunca se repite. En Linux y macOS se genera con `uuidgen` |
| *sondear* | Consultar el estado de una operación cada cierto tiempo, hasta que cambie. Es lo que se hace con una recarga que queda pendiente |
| *sandbox* / *ambiente `development`* | El simulador. Son la misma cosa. En producción verá `ambiente: production` y `sandbox: false` |
| *el proveedor* | Quien entrega la recarga: la operadora (Claro, Altice, Viva, Digicel, Natcom) a través del mayorista con el que Recarga.do se conecta |
| *reconciliación* | El proceso automático de Recarga.do que corre **cada 5 minutos**, le pregunta al proveedor por cada operación sin desenlace y la cierra en cuanto hay una respuesta firme |
| `request_id` | El identificador de una llamada HTTP concreta. Viene en el cuerpo de toda respuesta y en la cabecera `X-Request-Id` |

- **Referencia de endpoints:** [API.md](API.md) · [openapi.yaml](openapi.yaml)
- **Manual con consola interactiva:** [integracion.html](https://doc.recarga.do/integracion.html)

---

<a id="s1"></a>

## 1. SU PRIMERA RECARGA EN 5 MINUTOS

Las credenciales de abajo son públicas a propósito y apuntan al simulador.

```bash
# Credenciales públicas del ambiente de pruebas
KEY="rk_sbx_8c4cacb52c6b8f65bf389480ce3f8891"
SECRET="sk_sbx_a8e4de1dbd5e135a4be191cfd8901f386e541279a6550b1d30af9fbeaa65bbd0"
AUTH="Authorization: Bearer $KEY.$SECRET"

# 1 · ¿En qué ambiente estoy?  →  "ambiente":"development" y "sandbox":true = pruebas
curl -s https://api.recarga.do/v1/account -H "$AUTH"

# 2 · ¿Cuánto puedo gastar?
curl -s https://api.recarga.do/v1/saldo -H "$AUTH"

# 3 · ¿Qué puedo vender?  De aquí salen service_id, monto_minimo y monto_maximo.
curl -sG https://api.recarga.do/v1/services --data-urlencode "categoria=Telefonía" -H "$AUTH"

# 4 · Recargar. La clave de idempotencia debe ser única por operación.
#     Ojo: en el simulador el ÚLTIMO CARÁCTER del identifier decide el resultado.
#     Este termina en 5, así que da éxito. Los demás escenarios, en la §7.
IDEM=$(uuidgen)          # alternativa: IDEM=$(cat /proc/sys/kernel/random/uuid)
RESP=$(curl -s -X POST https://api.recarga.do/v1/recharges \
  -H "$AUTH" \
  -H "Idempotency-Key: $IDEM" \
  -H "Content-Type: application/json" \
  -d '{"service_id":1,"identifier":"8095551235","amount":100}')
echo "$RESP"

# 5 · Consultar la transacción por su id (el suyo, no el del ejemplo)
TX=$(printf '%s' "$RESP" | python3 -c "import json,sys; print(json.load(sys.stdin)['data']['transaction_id'])")
curl -s "https://api.recarga.do/v1/transactions/$TX" -H "$AUTH"
```

> **Antes de copiar y pegar.** Los ejemplos usan `bash` + `curl` (Linux, macOS o WSL —el Linux
> que corre dentro de Windows—). `uuidgen` no está en todas las distribuciones: la alternativa es
> `cat /proc/sys/kernel/random/uuid`. La línea con `python3` solo extrae un campo del JSON; si no
> tiene `python3`, copie el `transaction_id` a mano de la respuesta anterior. **En Windows sin
> WSL, use la [colección de Postman](recarga-do.postman_collection.json)**, que ya trae estas
> credenciales cargadas.

> **El sandbox no ejecuta recargas reales ni genera cargos reales, pero sí mueve el saldo de la
> cuenta de pruebas:** reserva, confirma y libera con la mecánica real. Esa cuenta es pública y
> compartida, así que otro lector pudo dejarla sin fondos. Si el paso 4 responde
> `422 INSUFFICIENT_BALANCE`, no es su código: pida a soporte una cuenta de pruebas propia
> ([§13](#s13)).

> **Sobre el paso 3:** `categoria` es el nombre exacto de la categoría, con su mayúscula inicial.
> Si su cliente HTTP no codifica la URL por usted, escríbala codificada
> (`?categoria=Telefon%C3%ADa`) o use `curl -G --data-urlencode`, como arriba. Lo que devuelve una
> lista vacía es un nombre que no coincida exactamente, no la tilde.

### Lo que devuelve el paso 3, recortado

```json
{
  "success": true,
  "data": [
    { "id": 1, "nombre": "CLARO",   "tipo": "mobile_recharge", "categoria": "Telefonía",
      "monto_minimo": 30, "monto_maximo": 2000, "acepta_anulacion": true },
    { "id": 2, "nombre": "ALTICE",  "tipo": "mobile_recharge", "categoria": "Telefonía",
      "monto_minimo": 30, "monto_maximo": 2000, "acepta_anulacion": true },
    { "id": 4, "nombre": "DIGICEL", "tipo": "mobile_recharge", "categoria": "Telefonía",
      "monto_minimo": 50, "monto_maximo": 2000, "acepta_anulacion": false }
  ],
  "message": "Servicios consultados",
  "request_id": "req_…"
}
```

`monto_minimo` y `monto_maximo` son los que hay que respetar en el paso 4. Un monto fuera de ese
rango se rechaza con `422 VALIDATION_ERROR` ([§8](#s8)). El campo `acepta_anulacion` indica si
ese servicio admite anulación: si es `false`, anular se rechaza con
`422 REVERSAL_NOT_SUPPORTED`.

### Lo que devuelve el paso 4

```json
{
  "success": true,
  "data": {
    "transaction_id": 48898,
    "status": "SUCCESS",
    "xid": "RD-b0816c81eb324d7967804f67",
    "auth_code": "SBX804f67",
    "service": { "id": 1, "nombre": "CLARO" },
    "identifier": "8095551235",
    "amount": 100,
    "currency": "DOP",
    "message": "Operación procesada exitosamente.",
    "processed_at": "2026-08-12T21:57:20-04:00"
  },
  "message": "Recarga procesada exitosamente",
  "request_id": "req_80b97e9294cf38701472f6d4"
}
```

### Lo que devuelven los pasos 1 y 2

```json
{
  "success": true,
  "data": {
    "empresa_id": 370,
    "razon_social": "SANDBOX API v1 - Pruebas automatizadas",
    "codigo_empresa": "EMP-SBX01",
    "ambiente": "development",
    "sandbox": true,
    "token": { "nombre": "sandbox-pruebas-v1", "permisos": [] }
  },
  "message": "Cuenta consultada",
  "request_id": "req_dfd463719188d09c1ff89ec4"
}
```

`token.permisos` es una **lista**. Vacía significa que el token no tiene ninguna restricción, es
decir, acceso total ([§3](#s3)).

```json
{
  "success": true,
  "data": {
    "saldo_actual": 98285,
    "saldo_disponible": 98285,
    "saldo_retenido": 0,
    "tipo_credito": "prepago",
    "alerta_saldo_bajo": 1000,
    "saldo_bajo": false,
    "limites": { "diario": 0, "semanal": 0, "mensual": 0 },
    "consumo_periodo": { "diario": 2040, "semanal": 2040, "mensual": 2040 },
    "actualizado_en": "2026-08-12 22:35:02",
    "moneda": "DOP"
  },
  "message": "Saldo consultado",
  "request_id": "req_dda459b27ee5fb7abffdb1ff"
}
```

### Identificadores de una operación

Guarde los cuatro primeros junto a la venta. Cada uno sirve para algo distinto:

| Campo | Qué es | Para qué sirve |
|---|---|---|
| `transaction_id` | El número de la operación dentro de Recarga.do | Consultar el estado: `GET /v1/transactions/{id}` |
| `xid` | El identificador con el que el proveedor ve la operación | Rastreo con el proveedor. Se deriva de su `Idempotency-Key`, por eso un reintento llega con el mismo `xid` y el proveedor puede detectar el duplicado |
| `auth_code` | El código de autorización que devuelve la operadora | Es el que se imprime en el recibo y el que reclama el cliente final. Solo existe si la operación quedó en `SUCCESS` |
| `request_id` | El identificador de esa llamada HTTP | **Es lo primero que le pedirá soporte.** Viene en el cuerpo y en la cabecera `X-Request-Id` |
| `reference` | El identificador que devolvió el proveedor, que hoy coincide con el `xid`. **No viene en la respuesta de la venta:** aparece al consultar la transacción | Cotejo con el proveedor |

### Autenticación, en una línea

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

El `api_key` y el `api_secret` separados por un punto. Alternativa equivalente, si su cliente
HTTP se lleva mal con `Authorization`:

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

**Su empresa la determina el token.** 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`.

### Los campos de una recarga

| Campo | Obligatorio | Notas |
|---|---|---|
| `service_id` | Sí | Entero, tomado de `GET /v1/services` |
| `identifier` | Sí | Cadena de 3 a 100 caracteres. **La API no valida el formato ni normaliza nada.** Envíe solo dígitos —10 posiciones en los teléfonos dominicanos—: un guion, un espacio o el prefijo `+1` se transmiten al proveedor tal cual y provocan un rechazo `422`. Menos de 3 o más de 100 caracteres sí se rechaza antes, con `422 VALIDATION_ERROR` |
| `amount` | Depende | **Solo si el servicio es de monto libre.** Mayor que cero, máximo 2 decimales, dentro del rango (`monto_minimo` / `monto_maximo`) |
| `opcion_id` | Depende | **Solo en paquetes y facturas.** El identificador que devolvió la consulta previa |
| `terminal_id` | No | Referencia de su caja o terminal, hasta 50 caracteres. Se guarda y se devuelve, pero **no se puede filtrar por él** ([§9](#s9)) |

En servicios que no son recarga móvil, el `identifier` es el número de contrato o el **NIC**
(*número de identificación del contrato* que usan las distribuidoras eléctricas).

### No todos los productos se venden igual

Esta es la parte que rompe más integraciones, así que vale la pena leerla despacio.

Una recarga de celular se vende indicando un monto: usted elige cuánto. Pero **un paquete
de datos y una factura no funcionan así**:

- Los **paquetes** disponibles dependen de la línea. Dos números de Claro pueden tener
  ofertas distintas, así que no hay un catálogo fijo que usted pueda cachear: hay que
  preguntárselo al operador para ese número concreto.
- Las **facturas** de luz, agua o teléfono pospago traen su monto ya fijado por la
  distribuidora. Usted no elige cuánto pagar: paga lo que se debe.

Por eso esos productos se venden en **dos pasos**.

Cada servicio declara cuál le corresponde en `GET /v1/servicios`:

```json
{
  "id": 50,
  "nombre": "Claro Paquetes",
  "flujo": "paquetes",
  "requiere_consulta": true,
  "como_comprar": "Consulte primero POST /v1/consultas para obtener los paquetes de ese número, y envíe el `opcion_id` elegido."
}
```

| `flujo` | Cuántos servicios | Paso 1 | Paso 2 |
|---|---|---|---|
| `monto_libre` | 44 | *(opcional)* consultar el titular | `POST /v1/recargas` con `amount` |
| `paquetes` | 5 | `POST /v1/consultas` → paquetes de ese número | `POST /v1/recargas` con `opcion_id` |
| `facturas` | 9 | `POST /v1/consultas` → facturas de ese contrato | `POST /v1/recargas` con `opcion_id` |
| `seguros` | 1 | `POST /v1/seguros` → código SMS, versión, plan y cotización ([§6-ter](#s6c)) | `POST /v1/recargas` con la placa y `opcion_id` `seguro:{id}` |

#### El paso 1: consultar

```bash
curl -X POST https://api.recarga.do/v1/consultas \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"service_id":50,"identifier":"8094964444"}'
```

```json
{
  "flujo": "paquetes",
  "titular": null,
  "requiere_seleccion": true,
  "opciones": [
    { "opcion_id": "CL-D30",  "nombre": "Paquetito Diario 1GB", "precio": 30.00,  "vigencia": "1 día",   "datos": "1 GB" },
    { "opcion_id": "CL-M700", "nombre": "Mensual Ilimitado",    "precio": 700.00, "vigencia": "30 días", "datos": "25 GB" }
  ]
}
```

La respuesta tiene la **misma forma** para los tres flujos, así que su caja puede escribir
un solo manejador: mire `flujo`, y si `requiere_seleccion` es `true`, muestre `opciones`.

En facturas, `opciones` trae las facturas pendientes y `titular` el nombre del cliente —
útil para que el cajero confirme antes de cobrar. Si el contrato está al día, recibirá
`200` con `sin_deuda: true` y `opciones` vacío: **eso no es un error**, es un cliente que
no debe nada.

#### El paso 2: comprar

```bash
curl -X POST https://api.recarga.do/v1/recargas \
  -H "$AUTH" -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  -d '{"service_id":50,"identifier":"8094964444","opcion_id":"CL-M700"}'
```

Fíjese en que **no se envía `amount`**. El precio lo pone el operador, y la API lo vuelve
a consultar antes de cobrar. Si usted envía un `amount` que no coincide, la operación se
rechaza:

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "El precio de ese paquete es RD$700.00, no RD$1.00. Omita `amount`: lo fija el operador.",
    "details": { "amount": "no_coincide", "precio_real": 700 }
  }
}
```

#### Si se equivoca de flujo

No se queda adivinando: el error le dice exactamente qué hacer.

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "\"Claro Paquetes\" se vende por paquetes, no por monto libre. Consulte primero POST /v1/consultas...",
    "details": {
      "opcion_id": "requerido",
      "flujo": "paquetes",
      "consultar_en": "/v1/consultas",
      "como_comprar": "Consulte primero POST /v1/consultas para obtener los paquetes de ese número, y envíe el `opcion_id` elegido."
    }
  }
}
```

> **El sandbox reproduce esto igual que producción.** Un identificador terminado en `0`
> no existe, en `1` no tiene opciones —línea sin paquetes o contrato al día—, y en `2` el
> proveedor no responde. Pruebe los tres antes de salir a producción.

#### Ver los paquetes y las facturas reales mientras prueba

Por defecto el sandbox devuelve un catálogo de ejemplo. Sirve para programar contra la
forma de los datos, pero los nombres y precios no son los que verá su cajero.

Si necesita los reales, pida que activen la capacidad **`consultas_reales`** sobre su
token. A partir de ahí, `POST /v1/consultas` le devolverá los paquetes que ese número
tiene de verdad y las facturas que ese contrato debe de verdad.

El campo `origen_datos` de cada respuesta le dice qué está viendo:

```json
{ "origen_datos": "proveedor_real", "opciones": [ { "opcion_id": "11685", "nombre": "LIBRE 1 DIA", "precio": 50.00 } ] }
```

| `origen_datos` | Significado |
|---|---|
| `proveedor_real` | Consultado al operador |
| `simulado` | Catálogo de ejemplo del ambiente de pruebas |

Tres cosas que conviene tener claras:

1. **Solo cambia la consulta.** La compra sigue simulada y su saldo sigue siendo
   ficticio. Nunca se ejecuta una recarga real desde una cuenta de pruebas: lo reconocerá
   porque el `auth_code` empieza por `SBX`.
2. **No viene activada en las credenciales públicas** de esta documentación, y no se
   concede por defecto. La consulta de facturas devuelve nombre, dirección y deuda de un
   cliente real; abrirla a cualquiera sería publicar datos de terceros.
3. **Tiene su propio límite** —30 por minuto, 2,000 por día— porque cada consulta consume
   cuota del operador. Al superarlo la consulta no falla: cae al simulador y lo declara en
   `origen_datos`.

---

<a id="s2"></a>

## 2. NO ES UNA PANTALLA INCRUSTADA

Esto es lo que más confusión genera al empezar.

**Recarga.do se integra por consulta directa a su API.** Su aplicación hace peticiones HTTPS a
`https://api.recarga.do`, recibe JSON, y hace con ese JSON lo que quiera. Nada más.

| No se necesita | Por qué |
|---|---|
| Incrustar un `<iframe>` —una ventana de otra web metida dentro de la suya— con una pantalla de Recarga.do | La API **no sirve HTML**: solo devuelve JSON. Y responde con la cabecera `X-Frame-Options: DENY`, de modo que ningún navegador la mostrará dentro de un marco |
| Redirigir al usuario al portal de Recarga.do y traerlo de vuelta | No hay flujo de redirección ni *callback*. Su usuario nunca sale de su aplicación |
| Instalar un paquete con Composer, npm o pip | No hace falta. Cualquier cliente HTTP sirve: `curl`, `fetch`, `axios`, `requests`, `Guzzle`, `HttpClient`, `OkHttp`. Si prefiere no resolver a mano la idempotencia y los estados pendientes, hay librerías oficiales de un solo archivo —copiar y usar, sin dependencias— en [`sdk/`](sdk/) |
| Abrir una sesión, manejar cookies o renovar tokens cada pocos minutos | La autenticación es un par de credenciales fijas enviadas en una cabecera. No hay sesión, no hay cookies, no hay expiración cada pocos minutos |
| Pedir permiso de dominio o registrar orígenes | Los navegadores pueden llamarla desde cualquier origen sin configuración previa: la API declara `Access-Control-Allow-Origin: *` |

Si alguien de su equipo vio una integración de Recarga.do basada en una pantalla incrustada, eso
pertenece al portal interno del sistema antiguo, no a la API v1 y no a usted. La API v1 es un
sistema aparte, con su propio dominio, y es el único camino de integración soportado para
aplicaciones de terceros.

**La parte buena:** usted controla el 100 % de la experiencia. Sus pantallas, sus colores, su
idioma, sus validaciones, su flujo de caja. Recarga.do es un proveedor invisible detrás de su
aplicación.

---

<a id="s3"></a>

## 3. CÓMO SE CONECTA SU APLICACIÓN

### La arquitectura recomendada

```
   Su app móvil / web / POS          Su backend                  Recarga.do
   ────────────────────────          ──────────                  ──────────
        Su interfaz          ──►   Su servidor        ──►   https://api.recarga.do
        (sin credenciales)         (guarda api_key            JSON sobre HTTPS
                                    y api_secret)
                             ◄──                       ◄──   Respuesta JSON:
                                                             éxito, pendiente,
                                                             rechazo o error
```

**Regla de oro: el `api_secret` vive en su servidor, nunca en el dispositivo del usuario.**

Un `api_secret` incrustado en un APK —el archivo que se instala en un teléfono Android—, en el
paquete de JavaScript que descarga el navegador, o en el código de una app de escritorio, es un
secreto público: cualquiera puede extraerlo y gastar su saldo. Su backend es quien habla con
Recarga.do; su app habla con su backend.

**Hay una razón concreta para pedir la lista blanca de IPs desde el primer día.** Hoy su
`api_secret` se conserva en texto plano en la base de datos de Recarga.do; el cambio a
credenciales cifradas está pendiente. Trate su secreto como una credencial rotable: pida la lista
blanca de IPs al solicitar el token, y pida su rotación cuando Recarga.do complete ese cambio.

### Si su aplicación no tiene backend

Es posible llamar a la API directamente desde el navegador, porque la API acepta llamadas desde
cualquier origen. Si va por ese camino, **exija estas dos protecciones al pedir sus
credenciales**:

1. **Token con permisos declarados.** Atención a este punto: un token **sin permisos declarados
   conserva acceso total, incluida la recarga**. Ese es el estado por defecto. Pida
   explícitamente un token que declare **solo** `balance.read`, `catalog.read`,
   `transactions.read` y `account.read`. En cuanto un token declara al menos un permiso se aplica
   el modelo estricto, y todo lo no declarado responde `403`. Verifique los suyos en
   `GET /v1/account`, campo `token.permisos`; **una lista vacía significa que no hay ninguna
   restricción**. El permiso `account.read` va en esa lista precisamente porque sin él esa
   verificación responde `403`.
2. **Lista blanca de IPs.** Si el token solo funciona desde las IPs de salida de su
   infraestructura, un secreto filtrado no sirve fuera de ella. Si no conoce sus IPs de salida,
   ejecute `curl ifconfig.me` en su servidor o pregúntele a su proveedor de hosting.

> **Con esos permisos su aplicación puede consultar, pero NO puede vender.**
> `POST /v1/recharges` responderá `403 FORBIDDEN`, porque vender exige `recharges.create`. Para
> vender necesita un servidor propio, sin excepción.

Ambas protecciones se solicitan a soporte ([§13](#s13)). Detalle en [API.md](API.md), secciones
*Permisos del token* y *Lista blanca de IPs*.

### Qué debe guardar su backend

| Dato | Dónde | Nota |
|---|---|---|
| `api_key` / `api_secret` | Variables de entorno o gestor de secretos | Nunca en el repositorio ni en el cliente |
| `transaction_id` de cada operación | Su base de datos | Es la referencia para consultar el estado |
| `request_id` de cada respuesta | Su log | Es lo que le pedirá soporte |
| La `Idempotency-Key` que usó | Su base de datos, junto a la venta | Sin esto no puede reintentar con seguridad. Reserve un campo de 128 caracteres (`VARCHAR(128)`) |

---

<a id="s4"></a>

## 4. CÓMO FUNCIONA EL DINERO

El modelo es **prepago**: usted deposita saldo y cada operación lo consume.

### Cómo se deposita el saldo

| Pregunta | Respuesta |
|---|---|
| ¿Por qué vía? | Transferencia bancaria |
| ¿Cómo se confirma? | Enviando el comprobante por WhatsApp o desde la plataforma. Se acredita tras la verificación del comprobante |
| ¿Cuánto tarda en acreditarse? | **Dato comercial: confírmelo con su ejecutivo antes de planificar un lanzamiento.** No hay un plazo publicado que esta guía pueda garantizar |
| ¿Monto mínimo inicial? | **Dato comercial: confírmelo con su ejecutivo.** La cifra que se maneja es RD$3,000, pero no consta en ninguna fuente verificable del sistema |
| ¿Monto mínimo de los depósitos posteriores? | **Dato comercial: confírmelo con su ejecutivo.** No hay una cifra publicada |
| ¿Cómo sé que entró? | Con `GET /v1/saldo`: el depósito aparece en `saldo_actual` y en `saldo_disponible` |

Los datos de la cuenta bancaria se los entrega Recarga.do por los canales de [§13](#s13).

### Cuánto cuesta y dónde está su ganancia

**El saldo se descuenta por el importe íntegro de la recarga.** Una recarga de RD$100 consume
RD$100 de su saldo. La API **no calcula, no descuenta y no expone comisiones**: no existe ningún
endpoint de comisiones y el campo interno de comisión queda en cero.

Su comisión se liquida **fuera de la API**. Los porcentajes vigentes, el corte de liquidación y
la forma de pago se los confirma su ejecutivo ([§13](#s13)); esta guía no los publica porque la
API nunca los expone. Concilie contra su propio registro de ventas.

### Las tres partes del saldo

| Campo de `GET /v1/saldo` | Qué es |
|---|---|
| `saldo_actual` | Todo su dinero en la plataforma |
| `saldo_retenido` | Dinero comprometido en operaciones cuyo resultado aún no se conoce. Ni gastable ni cobrado |
| `saldo_disponible` | **Lo que puede gastar ahora.** Es `saldo_actual` − `saldo_retenido` |

Los tres van en pesos con hasta 2 decimales: `98285` es RD$98,285.00.

**Valide contra `saldo_disponible`, nunca contra `saldo_actual`.** Es un error clásico y produce
rechazos por `INSUFFICIENT_BALANCE` que su aplicación no supo anticipar.

### Cómo se entera de que se está quedando sin saldo

**No hay aviso automático.** No existen notificaciones ni correos de saldo bajo: si nadie
consulta, nadie se entera hasta que un cliente se queda sin recarga.

`GET /v1/saldo` trae dos campos para eso:

- `alerta_saldo_bajo`: el umbral configurado para su cuenta, en pesos.
- `saldo_bajo`: `true` cuando `saldo_disponible` ya está en ese umbral o por debajo.

Consulte el balance con la periodicidad que usted decida —por ejemplo, cada 5 minutos desde su
backend— y avise al dueño en cuanto `saldo_bajo` sea `true`. Si prefiere su propio umbral,
compárelo usted contra `saldo_disponible`. Para cambiar `alerta_saldo_bajo`, escriba a soporte.

### El ciclo de una recarga

```
  1. Reservar      El importe sale de saldo_disponible y pasa a saldo_retenido.
        │          Ocurre ANTES de contactar al proveedor.
        ▼
  2. Ejecutar      Se envía la operación al proveedor real.
        │
        ├── Éxito           → se confirma el cobro.        saldo_retenido → cobrado
        ├── Rechazo         → se libera.                   saldo_retenido → disponible
        └── Sin respuesta   → SE QUEDA RETENIDO. Ni cobrado ni devuelto,
                              hasta que se conozca el resultado real.
```

La consecuencia importante: **una recarga rechazada le devuelve su dinero automáticamente**, y
una recarga en duda **no se cobra a ciegas**. La reconciliación corre cada 5 minutos y cierra lo
que quedó abierto en cuanto el proveedor da una respuesta firme.

---

<a id="s5"></a>

## 5. LA REGLA QUE EVITA COBRAR DOS VECES

`POST /v1/recharges` **exige** la cabecera `Idempotency-Key`. Sin ella la petición se rechaza:

```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "El header Idempotency-Key es obligatorio en operaciones financieras.",
    "details": { "Idempotency-Key": "requerido" }
  },
  "request_id": "req_e107d4dc77bf08e3f7beeb65"
}
```

### Qué garantiza

Una clave de idempotencia es una cadena única por operación —se recomienda un UUID v4, hasta 128
caracteres— que identifica *el cobro*, no *la petición HTTP*. Su ámbito es su empresa: dos
comercios distintos pueden usar la misma cadena sin interferirse.

| Situación | Qué ocurre |
|---|---|
| Misma clave, mismo cuerpo, operación ya terminada con un desenlace de negocio (`201`, `202` o `422`) | Devuelve **la respuesta original guardada**, con la cabecera `Idempotent-Replay: true`. **No se ejecuta nada nuevo** |
| Misma clave, operación aún en curso | `409 IDEMPOTENT_REQUEST_IN_PROGRESS` |
| Misma clave, cuerpo distinto | `422 VALIDATION_ERROR`, con `details` igual a `{"Idempotency-Key": "reutilizada_con_otro_payload"}`. La clave ya pertenece a otra operación |
| Misma clave, pero la primera petición terminó en `500 INTERNAL_ERROR` | **La clave se liberó.** La petición entra como operación nueva. Lea el aviso de más abajo antes de hacerlo |
| Misma clave más de 24 horas después | El registro ya se purgó y la API **la acepta como operación nueva**: no hay error, se recarga otra vez. Nunca reutilice una clave de más de 24 h para el mismo cobro |
| Colisión que la API no puede resolver (choque con la purga) | `409 IDEMPOTENCY_CONFLICT`. Consulte por `identifier` y, si procede, use una clave nueva |
| Clave nueva | **Operación nueva.** Se recarga otra vez |

Las claves se conservan **24 horas**.

### El punto que casi todos entienden al revés

**Reintentar con la misma clave devuelve la respuesta guardada mientras la clave siga registrada
—24 horas— y la primera petición haya terminado con un desenlace de negocio: `201`, `202` o
`422`.** Incluidos los errores de negocio.

Verificado contra el sandbox: primera llamada → `422 INVALID_PHONE`; segunda llamada con la misma
clave → el mismo `422`, con `idempotent-replay: true` y **sin ningún intento nuevo contra el
proveedor**. Con un `201` ocurre lo mismo: la repetición no crea una segunda transacción.

> **La excepción que hay que conocer: el `500 INTERNAL_ERROR`.** Si la primera petición terminó
> así, la API **libera la clave** para no dejarla bloqueada. Un reintento con esa misma clave ya
> no devuelve nada guardado: vuelve a intentar la operación desde cero y reserva saldo otra vez.
> Y si aquella primera petición sí llegó a crear la transacción, el reintento choca contra el
> identificador único de esa transacción y responde **otro `500`**, no la respuesta original. Por
> eso, ante un `500`, lo primero es consultar, no reintentar ([§6](#s6)).

De ahí las dos reglas que parecen contradictorias y no lo son:

- **Timeout o corte de red —usted no sabe qué pasó—: la misma clave es segura.** La clave sigue
  registrada. Si la primera petición nunca llegó, la segunda la ejecuta por primera vez; si
  llegó, le devuelve el resultado real de aquella. En ningún caso cobra dos veces.
- **Rechazo del proveedor (`422`) —usted sí sabe qué pasó—: para volver a intentar necesita una
  clave NUEVA.** Con la misma clave solo recibirá el mismo rechazo guardado, una y otra vez.

> **`Idempotent-Replay` llega en minúsculas.** Sobre HTTP/2 los nombres de cabecera se entregan
> en minúsculas (`idempotent-replay: true`). Compare siempre sin distinguir mayúsculas.

### Cuando el `409 IDEMPOTENT_REQUEST_IN_PROGRESS` no se va

Esperar sirve solo si hay de verdad otra petición en vuelo. Si el proceso original murió a mitad
de la operación, la clave queda marcada como «en curso» y **devolverá `409` de forma
permanente**: esas claves no caducan ni se borran automáticamente, precisamente para no arriesgar
un doble cobro. Esa clave queda inutilizable para siempre.

Qué hacer si el `409` persiste más de unos minutos:

1. Consulte `GET /v1/transactions?identifier=<número>&date_from=<hoy>`. La reconciliación liquida
   esa transacción de todos modos, en la pasada de cada 5 minutos.
2. Si la venta se completó, no repita nada: ya está cobrada y entregada.
3. Si confirmó que la venta **no** se ejecutó y aun así necesita venderla, use una **clave de
   idempotencia nueva**.

### El patrón correcto

```
1. El cajero confirma la venta.
2. Su sistema genera un UUID v4 y LO GUARDA junto a la venta, antes de llamar.
3. Llama a POST /v1/recharges con esa clave.
4. ¿Timeout o corte de red?
      → Consulte GET /v1/transactions?identifier=<número>&date_from=<hoy>
      → Si no aparece nada, reintente CON LA MISMA CLAVE guardada. Nunca con una nueva.
5. ¿Error 500?
      → Consulte igual, pero NO reintente con la misma clave. Vea la §6.
6. Guarde transaction_id, xid, auth_code y request_id de la respuesta.
```

Sobre el paso 2: la clave tiene que estar **realmente escrita** antes de la llamada HTTP. Si usa
una transacción de base de datos, haga `COMMIT` antes de llamar a la API; si su framework trabaja
con confirmación automática, basta con que el `INSERT` haya terminado.

> **La única forma de recargar dos veces al mismo cliente es generar una clave nueva para el
> mismo cobro.** Si su código genera el UUID dentro de la función que reintenta, tiene un
> defecto: genérelo antes, una sola vez, y persístalo.

---

<a id="s6"></a>

## 6. LOS DESENLACES Y QUÉ HACER CON CADA UNO

Su código debe manejar cinco caminos. Los dos últimos son los que se olvidan.

### `201` — Éxito

`status: "SUCCESS"`. El proveedor confirmó la entrega y el saldo se cobró. En ese momento la
recarga ya está aplicada del lado de la operadora. Imprima el recibo con el `auth_code` y guarde
el `transaction_id`.

### `202` — Resultado desconocido

`code: "TRANSACTION_PENDING"`. La operación quedó en proceso y **el importe está retenido, no
cobrado**. Aquí caen los casos en que el proveedor no respondió a tiempo o no se pudo hablar con
él.

```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": 48941,
      "xid": "RD-b960d673c95571a5ee6f4a43",
      "status": "PENDING",
      "consultar_en": "/v1/transactions/48941"
    }
  },
  "request_id": "req_…"
}
```

> **Ojo con este JSON: el `202` viene con `success: false` y dentro de `error`, pero no es un
> fallo.** Un código del tipo `if (!success) mostrarError()` —el patrón por defecto— le pintará un
> error rojo al cajero justo en el único caso donde no debe. Trate `TRANSACTION_PENDING` **antes**
> de su rama genérica de error.

**Qué debe hacer su aplicación:** no reintentar a ciegas. Guardar el `transaction_id` y sondear
`GET /v1/transactions/{id}` hasta que el estado deje de ser `PENDING`.

**Cadencia de consulta sugerida:** a los 1, 5, 15 y 30 minutos, y después cada hora hasta las 24
horas. La reconciliación corre cada 5 minutos, así que la mayoría se resuelve en la primera o la
segunda consulta.

**No hay un plazo máximo.** Mientras el proveedor no confirme ni niegue, la operación sigue
`PENDING` y el importe sigue retenido —ni cobrado ni devuelto—. A los 60 minutos el sistema
levanta una alerta interna para que alguien la atienda a mano; esa alerta no libera el dinero. Si
una operación pasa de 60 minutos en `PENDING`, escriba a soporte con el `transaction_id`
([§13](#s13)).

> **Pasadas las 24 horas la clave de idempotencia ya no existe.** A partir de ahí no reintente
> nunca con ella: resuelva solo por `transaction_id` y con soporte.

**Política de caja sugerida, y sus dos partes:**

1. No cobre al cliente ni entregue comprobante mientras el estado sea `PENDING`. Si a los 30
   minutos sigue igual, devuelva el dinero al cliente y deje la operación en la lista de
   pendientes del cierre.
2. **Si más tarde esa transacción cierra en `SUCCESS`, la recarga sí se entregó y su saldo sí se
   cobró.** Tendrá que cobrarle al cliente o asumir la pérdida. Por eso, antes de devolver,
   retenga el comprobante y el contacto del cliente. Y por eso conviene que alguien revise todos
   los días la lista de pendientes del cierre.

### `422` — El proveedor rechazó

Número inválido, servicio no admitido o rechazo de la operadora. **El saldo se devuelve
automáticamente.** Muestre el mensaje al cajero y permita corregir y reintentar; esta vez sí, con
una **clave de idempotencia nueva**, porque es una operación nueva.

```json
{ "success": false, "error": { "code": "INVALID_PHONE", "message": "Número inválido (sandbox)." }, "request_id": "req_…" }
```

Un monto fuera del rango del servicio **no** llega aquí: se rechaza antes de tocar el dinero, con
`422 VALIDATION_ERROR` ([§8](#s8)).

### `422 INSUFFICIENT_BALANCE` — Su cuenta se quedó sin saldo

No es un fallo del cliente, ni del número, ni de su código. **No se cobró nada y no se retuvo
nada.** Avise al dueño de que hay que depositar ([§4](#s4)), y valide contra `saldo_disponible`
antes de llamar, para que la caja lo sepa antes de teclear el número del cliente.

### Sin respuesta o `500` — El desenlace ambiguo

Su cliente HTTP cortó por timeout, se cayó la red, o la API respondió `500 INTERNAL_ERROR`. En
los tres casos **usted no sabe si la venta se ejecutó**, y el importe puede haber quedado
retenido. Pero **no se tratan igual**:

| Qué pasó | Qué hacer, en este orden |
|---|---|
| **Timeout o corte de red** | 1) Consulte `GET /v1/transactions?identifier=<número>&date_from=<hoy>`. 2) Si la operación aparece, respete su estado y no genere otra. 3) Solo si no aparece nada, reintente **con la misma clave**: es seguro, porque la clave sigue registrada |
| **`500 INTERNAL_ERROR`** | **No reintente con la misma clave**: esa clave ya se liberó y un reintento puede terminar en otro `500` ([§5](#s5)). 1) Consulte `GET /v1/transactions?identifier=<número>&date_from=<hoy>`. 2) Si la transacción existe, respete su estado y espere a la reconciliación. 3) Si no existe, use una clave **nueva**. 4) Guarde el `request_id` del `500` y repórtelo a soporte |

En ningún caso repita la venta a ciegas. Si la transacción llegó a crearse, la reconciliación la
liquida en la siguiente pasada de 5 minutos: se cobra si el proveedor la entregó, se devuelve el
saldo si no.

### Qué hace la caja con cada desenlace

| Desenlace | Qué hace el cajero |
|---|---|
| `201` | Cobra y entrega el recibo con el `auth_code` |
| `422` | No cobra. Avisa del rechazo y ofrece corregir el número |
| `202` | **No cobra todavía.** Dice «la recarga está en verificación» y se consulta el estado. Retiene el comprobante y el contacto del cliente |
| `422 INSUFFICIENT_BALANCE` | No cobra. Avisa al dueño de que hay que depositar ([§4](#s4)). No es un fallo del cliente ni del número |
| Sin respuesta o `500` | No cobra y **no repite la venta**. Se consulta por número antes de volver a intentar |

---

<a id="s6b"></a>

## 6-bis. ANULAR UNA VENTA

Una recarga ya entregada **sí se puede anular** por API, y el importe vuelve al saldo del
comercio. No todos los servicios lo permiten: **32 de los 59 no aceptan anulación**, entre
ellos toda la electricidad prepago y buena parte del agua.

```bash
curl -X POST https://api.recarga.do/v1/transacciones/48967/anular \
  -H "$AUTH" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"reason":"El cliente dio un número equivocado"}'
```

`reason` es opcional y se recorta a 200 caracteres. **El header `Idempotency-Key` es
obligatorio**: anular también mueve dinero.

### Antes de mostrar el botón «Anular»

Compruebe `acepta_anulacion` en `GET /v1/servicios`. Si es `false`, no ofrezca la opción:
la API la rechazará con `422 REVERSAL_NOT_SUPPORTED` y el cajero se quedará sin entender
por qué.

### Respuesta correcta

```json
{
  "success": true,
  "data": { "transaction_id": 48967, "status": "REVERSED", "refunded": 50.00,
            "reversed_at": "2026-08-13T11:22:04-04:00" }
}
```

### Cuándo falla, y qué significa

| HTTP | Código | Qué pasó |
|---|---|---|
| `409` | `ALREADY_REVERSED` | Ya estaba anulada. No vuelva a intentarlo |
| `409` | `NOT_REVERSIBLE` | No está completada: pendiente, fallida o en curso. El detalle trae su `status` |
| `422` | `REVERSAL_NOT_SUPPORTED` | Ese servicio no admite anulación |
| `422` | `REVERSAL_REJECTED` | El proveedor la rechazó |
| `404` | `NOT_FOUND` | No existe, o es de otra empresa |
| `202` | `TRANSACTION_PENDING` | **El importe todavía NO ha vuelto** |

> **Sobre el `202` al anular.** La recarga sigue entregada y cobrada mientras no haya
> confirmación. Consulte la transacción antes de decidir; **no vuelva a anular a ciegas**.

### Una limitación del ambiente de pruebas

Los escenarios de rechazo de la anulación —identificador terminado en `1` o `2`— no se
pueden ensayar: esas recargas nunca llegan a completarse, así que no hay nada que anular.
En pruebas solo podrá recorrer el camino correcto y los conflictos (`ALREADY_REVERSED`,
`NOT_REVERSIBLE`).

---

<a id="s6c"></a>

## 6-ter. SEGURO DE LEY (SEGURO DOMINICANA)

El seguro de ley de vehículos se vende por la API igual que en la app de Recarga.do: su
caja recoge los datos, el dueño del vehículo confirma con un código que le llega por SMS, se
elige versión y plan, se cotiza y **solo entonces** se cobra con `POST /v1/recargas`.

Tres cosas antes de empezar:

- **Se habilita por comercio.** Pídalo a Recarga.do. Mientras no esté habilitado,
  `GET /v1/seguros` responde `disponible: false` con `motivo: "no_habilitado"`.
- **Su token necesita el permiso `recharges.create`**, también para los pasos previos.
- **Ningún paso previo mueve dinero.** El único que cobra es el último, y cobra el
  `monto_total` de la cotización: usted **no envía `amount`**.

Todas las rutas tienen alias en inglés (`/v1/insurance`, `/otp/verify`, `/plans`, `/plan`,
`/quote`, `/document`).

### El flujo, paso a paso

| Paso | Llamada | Qué obtiene |
|---|---|---|
| 0 | `GET /v1/seguros` | Si puede venderlo y el `service_id` |
| 1 | `POST /v1/seguros` | `seguro_id`, titular y vehículo enmascarados; **SMS al dueño** |
| 1-bis | `POST /v1/seguros/{id}/otp` | Reenvía el código (solo si no llegó) |
| 2 | `POST /v1/seguros/{id}/otp/verificar` | Versiones del vehículo |
| 3 | `GET /v1/seguros/{id}/planes?version=…` | Planes compatibles con esa versión |
| 4 | `POST /v1/seguros/{id}/plan` | Plan confirmado y servicios opcionales con su precio |
| 5 | `POST /v1/seguros/{id}/cotizar` | `monto_total` y `opcion_id` |
| 6 | `POST /v1/recargas` | **La venta.** `201` = póliza emitida |
| 7 | `GET /v1/seguros/{id}` y `/documento` | Número de póliza, vigencia y PDF |

#### Paso 0: ¿puedo venderlo?

```bash
curl https://api.recarga.do/v1/seguros -H "$AUTH"
```

```json
{ "disponible": true, "servicios": [ { "service_id": 12, "nombre": "Seguro Dominicana" } ], "motivo": null }
```

`motivo` vale `null`, `no_habilitado` o `proveedor_no_configurado`. Si `disponible` es
`false`, oculte el producto en su caja.

#### Paso 1: datos del dueño y del vehículo

```bash
curl -X POST https://api.recarga.do/v1/seguros \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"service_id":12,"cedula":"00112345678","telefono":"8095551234","placa":"A123456","terminal_id":"CAJA-01"}'
```

| Campo | Regla |
|---|---|
| `cedula` | Cédula del dueño, 11 dígitos (los guiones se ignoran) |
| `telefono` | Celular del dueño, 10 dígitos que empiezan por 809, 829 u 849. Ahí llega el código |
| `placa` | Una o dos letras y de 5 a 7 dígitos. Ejemplo: `A123456` |
| `terminal_id` | Opcional. Su referencia de caja |

Responde `201`:

```json
{
  "seguro_id": 381,
  "titular": "JUAN C*** R***",
  "vehiculo": "TOYOTA C*** 2015",
  "tipo_vehiculo": "AUTOMOVIL",
  "tiene_renovacion": false,
  "placa": "A123456",
  "telefono": "809-***-1234",
  "otp_enviado": true,
  "otp_expira_en": 600,
  "mensaje": null
}
```

El dueño recibe un **código de 6 dígitos que vence en 10 minutos**. Muéstrele al cajero el
titular y el vehículo enmascarados para que confirme con el cliente que es su carro. Si
`otp_enviado` es `false`, o el código no llega, pida otro con
`POST /v1/seguros/381/otp`.

#### Paso 2: verificar el código

```bash
curl -X POST https://api.recarga.do/v1/seguros/381/otp/verificar \
  -H "$AUTH" -H "Content-Type: application/json" -d '{"codigo":"482913"}'
```

```json
{
  "seguro_id": 381,
  "marca": "TOYOTA",
  "modelo": "COROLLA",
  "version_unica": false,
  "sugerida": "10|1050|20",
  "versiones": [
    { "id": "10|1050|20", "nombre": "COROLLA LE 1.8", "sugerida": true },
    { "id": "10|1050|21", "nombre": "COROLLA S 1.8", "sugerida": false }
  ]
}
```

Hay **5 intentos**. Un código equivocado responde `422 OTP_INCORRECTO`; al sexto,
`409 OTP_BLOQUEADO` y hay que empezar de nuevo desde el paso 1. Si `version_unica` es
`true`, no pregunte: use esa.

#### Paso 3: planes de esa versión

La versión lleva barras verticales: codifíquelas en la URL (`|` → `%7C`).

```bash
curl "https://api.recarga.do/v1/seguros/381/planes?version=10%7C1050%7C20" -H "$AUTH"
```

```json
{
  "version": "10|1050|20",
  "detalle": { "cilindraje": "1800", "tipo": "AUTOMOVIL", "clase": "PRIVADO" },
  "planes": [
    { "cd_tipo_plan": 3, "nombre": "Plan Básico 12 meses RD$2,850.00", "vigencia_meses": 12,
      "cobertura": "Ley", "precio_referencia": 2850.00, "sugerido": true }
  ]
}
```

`precio_referencia` es **orientativo**. El precio que se cobra es el de la cotización.

#### Paso 4: confirmar versión y plan

```bash
curl -X POST https://api.recarga.do/v1/seguros/381/plan \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"version":"10|1050|20","cd_tipo_plan":3}'
```

```json
{
  "plan": { "cd_tipo_plan": 3, "nombre": "Plan Básico 12 meses RD$2,850.00", "vigencia_meses": 12,
            "cobertura": "Ley", "precio_referencia": 2850.00, "sugerido": true },
  "servicios_opcionales": [
    { "campo": "incluye_grua", "nombre": "Servicio de grúa", "descripcion": null, "precio": 450.00 },
    { "campo": "incluye_casa_conductor", "nombre": "Casa del conductor", "descripcion": null, "precio": 300.00 }
  ]
}
```

Ofrezca solo los opcionales que vengan en la lista. **La grúa no aplica a motocicletas**: en
ese caso no aparece.

#### Paso 5: cotizar

```bash
curl -X POST https://api.recarga.do/v1/seguros/381/cotizar \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"incluye_grua":true,"incluye_casa_conductor":false}'
```

```json
{
  "seguro_id": 381,
  "service_id": 12,
  "opcion_id": "seguro:381",
  "monto_total": 3300.00,
  "moneda": "DOP",
  "valida_minutos": 30,
  "titular": "JUAN CARLOS RODRIGUEZ",
  "placa": "A123456",
  "vehiculo": "TOYOTA COROLLA 2015",
  "color": "GRIS",
  "chasis": "2T1BURHE0FC123456",
  "plan": "Plan Básico 12 meses",
  "grua": true,
  "casa_conductor": false,
  "cotizacion": "COT-2026-000123"
}
```

Muestre `monto_total` al cliente: **es exactamente lo que se cobrará**. La cotización vale
**30 minutos**. Si el vehículo ya tiene una póliza vigente, responde `422 POLIZA_ACTIVA` y el
mensaje trae la fecha a partir de la cual se puede renovar.

#### Paso 6: vender

```bash
curl -X POST https://api.recarga.do/v1/recargas \
  -H "$AUTH" -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  -d '{"service_id":12,"identifier":"A123456","opcion_id":"seguro:381"}'
```

El `identifier` es **la placa** y el `opcion_id` el de la cotización. **No envíe `amount`.**
Las reglas de dinero son las de siempre ([§5](#s5) y [§6](#s6)):

| Respuesta | Qué pasó | Qué hacer |
|---|---|---|
| `201` | **Póliza emitida y cobrada.** `auth_code` es el número de póliza | Entregue el comprobante y los PDF (paso 7) |
| `202 TRANSACTION_PENDING` | La aseguradora aún no confirma. **El importe queda retenido**, no cobrado | Muestre «verificando» y consulte `GET /v1/transacciones/{id}`. Se resuelve solo |
| `422 SEGURO_NO_EMITIDO` | No se emitió. **El importe ya volvió a su saldo** | Informe al cliente. Esa venta queda cerrada: para intentarlo otra vez, empiece desde el paso 1 |
| `409 COTIZACION_VENCIDA` | Pasaron más de 30 minutos desde la cotización | Vuelva al paso 5 y confirme el precio nuevo con el cliente |
| `409 SEGURO_YA_VENDIDO` | Ese `seguro_id` ya se vendió o se está vendiendo | Consulte `GET /v1/seguros/{id}`. **No lo venda otra vez** |
| `409 SEGURO_SIN_COTIZAR` | Falta el paso 5 | Cotice primero |
| Sin respuesta | Desconocido | Reintente **con la misma `Idempotency-Key`** |

> **Un reintento con la misma clave nunca cobra dos veces.** Si la primera venta llegó, el
> reintento le devuelve su estado real (`201`, `202` o `422`), sin volver a cobrar ni a
> emitir. Como en cualquier venta, una clave nueva es una venta nueva: aquí la API la
> rechaza con `409 SEGURO_YA_VENDIDO`, porque cada cotización se vende una sola vez.

#### Paso 7: la póliza

```bash
curl https://api.recarga.do/v1/seguros/381 -H "$AUTH"
```

```json
{
  "seguro_id": 381,
  "service_id": 12,
  "estado": "emitida",
  "placa": "A123456",
  "cedula": "001-****567-8",
  "telefono": "809-***-1234",
  "monto_total": 3300.00,
  "transaction_id": 49120,
  "numero_poliza": "POL-0012345",
  "titular": "JUAN CARLOS RODRIGUEZ",
  "vehiculo": "TOYOTA COROLLA 2015",
  "plan": "Plan Básico 12 meses",
  "grua": true,
  "casa_conductor": false,
  "vigencia_desde": "2026-09-25",
  "vigencia_hasta": "2027-09-25",
  "documentos": {
    "poliza": "/v1/seguros/381/documento?tipo=poliza",
    "marbete": "/v1/seguros/381/documento?tipo=marbete"
  },
  "mensaje": null
}
```

Estados posibles: `iniciada`, `otp_enviado`, `otp_validado`, `plan_confirmado`, `cotizado`,
`cobrando`, `emitiendo`, `emitida` y `fallida`. `documentos` es `null` hasta que el estado
es `emitida`. Si la venta quedó pendiente, esta consulta le pregunta a la aseguradora antes
de responder.

Los PDF se descargan con su token (responden `application/pdf`):

```bash
curl -o poliza.pdf  "https://api.recarga.do/v1/seguros/381/documento?tipo=poliza"  -H "$AUTH"
curl -o marbete.pdf "https://api.recarga.do/v1/seguros/381/documento?tipo=marbete" -H "$AUTH"
```

Antes de la emisión responden `409 POLIZA_NO_EMITIDA`. **El cliente también recibe el enlace
por SMS de la aseguradora**, así que no depende de que usted lo imprima.

### Lo que no se puede hacer

- **Anular.** Un seguro emitido no se anula por la API: `422 REVERSAL_NOT_SUPPORTED`. La
  póliza ya existe en la aseguradora.
- **Consultarlo por `POST /v1/consultas`.** Responde `501` indicando que se use
  `/v1/seguros`.

### Errores de los pasos previos

| HTTP | Código | Qué pasó |
|---|---|---|
| `422` | `VALIDATION_ERROR` | Cédula, teléfono o placa con formato inválido. `details` dice cuál |
| `422` | `VEHICULO_NO_SOPORTADO` | «Tipo de vehículo no soportado» por la aseguradora |
| `422` | `SEGURO_RECHAZADO` | La aseguradora rechazó los datos. Muestre el mensaje |
| `422` | `OTP_INCORRECTO` | Código equivocado o vencido. Pida otro o reintente |
| `409` | `OTP_BLOQUEADO` | 5 intentos fallidos. Empiece de nuevo |
| `409` | `SEGURO_PASO_INVALIDO` | Llamó un paso fuera de orden |
| `409` | `SEGURO_CERRADO` | Esa venta terminó en fallo. Empiece una nueva |
| `422` | `POLIZA_ACTIVA` | El vehículo ya tiene póliza vigente (al cotizar) |
| `403` | `FORBIDDEN` | El seguro no está habilitado para su comercio |
| `502` | `SEGURO_SIN_RESPUESTA` | La aseguradora no respondió. Intente de nuevo |
| `503` | `SEGUROS_NO_DISPONIBLE` | Venta de seguros no disponible por el momento |

> **En el ambiente de pruebas** el seguro va contra el ambiente de pruebas de la
> aseguradora, no contra el simulador: los escenarios por último dígito de la [§7](#s7) no
> aplican aquí.

---

<a id="s7"></a>

## 7. PROBAR SIN GASTAR DINERO

Toda cuenta con `ambiente: "development"` (lo mismo que `sandbox: true`) opera contra un
simulador: **ninguna recarga real, ningún cargo real**. Pero el saldo, las transacciones, los
estados y los errores se comportan igual que en producción, y **el saldo de la cuenta de pruebas
sí se mueve**: se reserva, se confirma y se libera con la mecánica real.

Verifique dónde está con `GET /v1/account`.

> `GET /v1/info` devuelve `"environment": "production"` incluso con un token de pruebas: ese
> campo describe **la plataforma**, no su cuenta. Para saber si USTED está en producción, use
> `GET /v1/account` y mire `ambiente` y `sandbox`.

**El escenario lo elige el último carácter de `identifier`:**

| Termina en | Resultado | Sirve para probar |
|---|---|---|
| `0` | `422` · `INVALID_PHONE` — el saldo vuelve | Su manejo de rechazos |
| `1` | `422` · `TRANSACTION_REJECTED` — el saldo vuelve | Su mensaje de error genérico |
| `2` | `202` · `TRANSACTION_PENDING` — el saldo queda retenido | **Su sondeo de estado. Pruébelo** |
| cualquier otro | `201` · `SUCCESS` — el saldo se cobra | El camino feliz |

**Esta regla solo existe en el simulador.** En producción el último carácter no significa nada.

**No pase a producción sin haber probado el dígito `2`.** Es el caso que, mal manejado, cobra dos
veces a un cliente real.

Dos advertencias sobre esa prueba:

- **En sandbox, una `PENDING` siempre termina en `FAILED`**, y el saldo se libera en la siguiente
  pasada de reconciliación, en menos de 5 minutos.
- **La rama «`PENDING` → `SUCCESS`, el dinero se cobra» no es reproducible en sandbox.** Solo
  ocurre en producción, y es la que le cuesta dinero si su caja ya devolvió el efectivo.

Para probar esa rama, haga que su código lea este JSON en lugar de llamar a la API. Es la
respuesta real de `GET /v1/transactions/{id}` para una transacción que cerró en `SUCCESS`:

```json
{
  "success": true,
  "data": {
    "transaction_id": 48898,
    "xid": "RD-b0816c81eb324d7967804f67",
    "status": "SUCCESS",
    "service": { "id": 1, "nombre": "CLARO" },
    "identifier": "8095551235",
    "amount": 100,
    "currency": "DOP",
    "auth_code": "SBX804f67",
    "reference": "RD-b0816c81eb324d7967804f67",
    "terminal_id": null,
    "message": "Operación procesada exitosamente.",
    "created_at": "2026-08-12 21:57:20",
    "processed_at": "2026-08-12 21:57:20"
  },
  "message": "Transacción consultada",
  "request_id": "req_b93981ba1538c88850e10520"
}
```

Su prueba debe cubrir esta secuencia completa: la venta responde `202`; la primera consulta
devuelve `status: "PENDING"` con `auth_code: null`; una consulta posterior devuelve el JSON de
arriba. Lo que hay que verificar es que su sistema, en ese punto, marca la venta como cobrada y
la manda a la lista que revisa el cierre, en lugar de dejarla como devuelta ([§6](#s6)).

La cuenta de pruebas de [§1](#s1) es pública y compartida: no dé por hecho ningún saldo. Si
necesita una cuenta de pruebas propia, pídala a soporte ([§13](#s13)).

---

<a id="s8"></a>

## 8. ERRORES: QUÉ SIGNIFICAN Y QUÉ HACER

Toda respuesta de error trae `error.code` —estable, para su código— y `error.message` —en
español, para mostrar—. Programe contra el `code`, nunca contra el texto. Toda respuesta, con
error o sin él, trae también `request_id`: en el cuerpo y en la cabecera `X-Request-Id`.

La columna «Dinero» dice qué le pasó a su saldo, y remite al desenlace de [§6](#s6).

| Código | HTTP | Dinero | Qué hacer |
|---|---|---|---|
| `UNAUTHENTICATED` | 401 | No se movió | Credenciales inválidas, formato distinto de `key.secret`, **o token expirado**. **Detenga los reintentos** y revise la configuración; si el token expiró, escriba a soporte |
| `AUTH_THROTTLED` | 429 | No se movió | Bloqueo por intentos de autenticación fallidos: 15 minutos. **No reintente.** Espere `error.details.retry_after` segundos y corrija las credenciales |
| `FORBIDDEN` | 403 | No se movió | Token sin ese permiso, IP no autorizada, empresa suspendida, o `empresa_id` ajeno en el cuerpo |
| `HTTPS_REQUIRED` | 403 | No se movió | Llamó por `http://`. Use siempre `https://`. Antes de llegar aquí verá un `301` de redirección |
| `NOT_FOUND` | 404 | No se movió | Transacción o servicio inexistente. Una transacción de otra empresa también responde 404 |
| `IDEMPOTENT_REQUEST_IN_PROGRESS` | 409 | Puede estar retenido | Hay una operación en curso con esa clave. Espere y consulte el estado. **No genere una clave nueva para reintentar el mismo cobro.** Use una clave nueva solo si ya confirmó por `GET /v1/transactions` que la venta no se ejecutó ([§5](#s5)) |
| `IDEMPOTENCY_CONFLICT` | 409 | Puede estar retenido | La API no pudo resolver la clave (choque con la purga). Consulte por `identifier` y, si procede, use una clave nueva |
| `RECEIPT_UNAVAILABLE` | 409 | No se movió | Solo se emite recibo de transacciones `SUCCESS` |
| `PAYLOAD_TOO_LARGE` | 413 | No se movió | Cuerpo mayor de 64 KB |
| `UNSUPPORTED_MEDIA_TYPE` | 415 | No se movió | Envió un `Content-Type` distinto de `application/json`. Si lo **omite** por completo, la petición se acepta y el cuerpo se interpreta como JSON; envíelo de todos modos |
| `VALIDATION_ERROR` | 422 | No se movió | Corrija los datos; `details` dice qué campo. Cubre la falta de `Idempotency-Key`, la reutilización de una clave con otro cuerpo, más de 2 decimales, el `identifier` fuera de 3-100 caracteres y **el monto fuera del rango del servicio** |
| `INSUFFICIENT_BALANCE` | 422 | No se movió | Deposite saldo ([§4](#s4)). Valide contra `saldo_disponible` antes de llamar |
| `LIMIT_EXCEEDED` | 422 | No se movió | Límite diario, semanal o mensual superado. Consúltelos en `GET /v1/saldo`, campo `limites` |
| `RATE_LIMIT_EXCEEDED` | 429 | No se movió | Demasiadas peticiones. Espere `error.details.retry_after` segundos; si vuelve a fallar, duplique la espera en cada intento —1 s, 2 s, 4 s, 8 s—, con tope de 60 s y máximo 5 intentos |
| `TRANSACTION_PENDING` | 202 | **Retenido** | No es un fallo. Sondee el estado ([§6](#s6)) |
| `INVALID_PHONE` · `INVALID_PRODUCT` · `INVALID_AMOUNT` · `TRANSACTION_REJECTED` · `DUPLICATE_TRANSACTION` · `SERVICE_TEMPORARILY_UNAVAILABLE` | 422 | **Devuelto** | La operación fue rechazada. Corrija y reintente con una clave nueva ([§6](#s6)) |
| `INTERNAL_ERROR` | 500 | Desconocido | **No reintente con la misma clave.** Consulte por `identifier` y reporte el `request_id` ([§6](#s6)) |

Ejemplo de monto fuera de rango:

```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "El monto mínimo para este servicio es RD$30.00.",
    "details": { "amount": "menor_al_minimo", "minimo": 30 }
  },
  "request_id": "req_…"
}
```

Dos precisiones que evitan código equivocado:

- **`SERVICE_TIMEOUT` y `SERVICE_UNAVAILABLE` nunca llegan como error `422`.** Un timeout o una
  caída del proveedor se le presentan como `202 TRANSACTION_PENDING`, con el importe retenido. Se
  manejan sondeando el estado, no reintentando ([§6](#s6)).
- **No trate todo `429` igual.** `RATE_LIMIT_EXCEEDED` se resuelve esperando unos segundos;
  `AUTH_THROTTLED` es un bloqueo de 15 minutos por credenciales incorrectas, y reintentar solo lo
  prolonga.

> **Cuidado con reintentar una autenticación fallida.** Existe un freno de fuerza bruta: unos 10
> intentos fallidos por `api_key` y 20 por IP provocan un **bloqueo de 15 minutos**, que se
> devuelve como `429 AUTH_THROTTLED`. Si su despliegue arranca con credenciales mal configuradas
> y reintenta en bucle, se bloqueará solo. Ante un `401`, **detenga los reintentos y revise la
> configuración**.

---

<a id="s9"></a>

## 9. LÍMITES Y BUENAS PRÁCTICAS DE CONSUMO

**Rate limit:** 120 peticiones por minuto por token **por defecto**. Si su token tiene un límite
diario configurado, el límite efectivo es ese cupo repartido entre los minutos del día: un token
con 10,000 peticiones al día obtiene 7 por minuto, no 120 (10.000 ÷ 1.440 minutos ≈ 6,9, que se
redondea hacia arriba). **Lea siempre `X-RateLimit-Limit`** en lugar de dar por hecho el valor.

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

Estas cabeceras solo vienen en las respuestas correctas (`2xx`). **Las respuestas de error no las
llevan** —ni siquiera el propio `429`—, y `GET /v1/health` y `GET /v1/info` tampoco. Cuando
reciba un `429`, el dato que necesita está en el cuerpo: `error.details.retry_after`, en
segundos.

**Cachee el catálogo.** `GET /v1/categories` y `GET /v1/services` cambian rara vez: consúltelos
al arrancar y **refrésquelos una vez al día**. Consultarlos en cada pantalla es el error de
consumo más común y el que agota el rate limit sin necesidad.

**Pagine el historial.** `GET /v1/transactions` admite `page`, `per_page` (máx. 200), `status`,
`date_from`, `date_to` e `identifier`. **No existe filtro por `terminal_id`:** si necesita cuadrar
por caja, guarde el `terminal_id` en su propio sistema y cuadre allí.

**Formatos de fecha.**

- `date_from` y `date_to` se envían como `YYYY-MM-DD` —por ejemplo, `date_from=2026-08-12`—, en
  hora de Santo Domingo. `date_from` cuenta desde las 00:00:00 de ese día y `date_to` hasta las
  23:59:59. Una fecha que no se pueda interpretar responde `422 VALIDATION_ERROR`.
- La respuesta de `POST /v1/recharges` trae `processed_at` con desfase horario
  (`2026-08-12T21:57:20-04:00`).
- Las consultas `GET /v1/transactions` devuelven `created_at` y `processed_at` como
  `2026-08-12 22:24:07`, **sin desfase**: están en hora de Santo Domingo (UTC−4).

**Tiempos de espera de su cliente HTTP.** Use **65 segundos o más** en `POST /v1/recharges`. Una
recarga puede hacer dos llamadas al proveedor —autenticación y recarga—, con hasta 30 segundos
cada una: el peor caso ronda los 60 segundos de red, más el tiempo de base de datos. Un timeout
de 10 o de 40 segundos en su lado cortará antes que la API y le generará justo los `PENDING` que
esta guía le pide evitar.

- Si usa las librerías de [`sdk/`](sdk/), su timeout de recarga por defecto es de **40 segundos**
  (`timeoutRecarga` en PHP y Node, `timeout_recarga` en Python). Súbalo a 65.
- **Si su hosting no le deja llegar a 65 segundos** —en el hosting compartido con PHP, el
  `max_execution_time` de 30 segundos es lo normal y muchas veces no se puede cambiar—, dé por
  hecho que verá `PENDING` con frecuencia. No es un fallo de su código: persista la clave de
  idempotencia, respóndale al cajero «en verificación» y sondee el estado desde un proceso aparte
  ([§6](#s6)).

---

<a id="s10"></a>

## 10. LISTA DE COMPROBACIÓN PARA PRODUCCIÓN

Antes de mover dinero real, confirme cada punto:

- [ ] El `api_secret` **no** está en el código del cliente, ni en el APK, ni en el paquete de JavaScript, ni en el repositorio.
- [ ] La clave de idempotencia se genera **una vez por venta** y se persiste (con `COMMIT`) antes de llamar.
- [ ] El reintento tras un timeout o un corte de red consulta primero y, si no aparece nada, usa **la clave guardada**.
- [ ] Ante un `500` el código **no reintenta con la misma clave**: consulta por `identifier`.
- [ ] El reintento tras un `422` usa una **clave nueva**; con la misma solo recibiría el rechazo guardado.
- [ ] Está implementado el manejo de `202 PENDING` con sondeo de estado, y probado con el dígito `2`.
- [ ] `TRANSACTION_PENDING` se maneja **antes** de la rama genérica de error, porque llega con `success: false`.
- [ ] Está definida la política de caja ante un `202`: no cobrar hasta que el estado cambie, **y qué se hace si después cierra en `SUCCESS`**.
- [ ] Se valida contra `saldo_disponible`, no contra `saldo_actual`, y alguien vigila `saldo_bajo`.
- [ ] Se guardan `transaction_id`, `xid`, `auth_code` y `request_id` de cada operación.
- [ ] El timeout del cliente HTTP es de **65 s o más** en las recargas, o se asume el `PENDING` frecuente.
- [ ] El catálogo se cachea y se refresca una vez al día.
- [ ] Se maneja `429` leyendo `error.details.retry_after`, distinguiendo `RATE_LIMIT_EXCEEDED` de `AUTH_THROTTLED`.
- [ ] El código decide según `error.code`, no según el texto del mensaje.
- [ ] El token de producción **declara permisos**: una lista vacía significa acceso total.
- [ ] Se solicitó **lista blanca de IPs** para el token de producción.
- [ ] `GET /v1/account` confirma `"ambiente": "production"` y `"sandbox": false` antes de la primera venta real. Esa consulta exige el permiso `account.read`.

---

<a id="s11"></a>

## 11. CÓMO PASAR A PRODUCCIÓN

Las credenciales de producción se las entrega Recarga.do. Se solicitan por los canales de
[§13](#s13).

**Qué debe indicar al solicitarlas:**

1. Razón social y RNC (o cédula) del comercio, y el nombre de la cuenta que ya opera con
   Recarga.do, si la tiene.
2. Las **IPs de salida** de su servidor, para la lista blanca del token. Si no las conoce,
   ejecute `curl ifconfig.me` en su servidor o pregúntele a su proveedor de hosting.
3. Los **permisos** que necesita el token. Si su integración vende: `recharges.create`,
   `account.read` y los de consulta que use (`balance.read`, `catalog.read`,
   `transactions.read`). Sin `account.read` no podrá hacer la verificación de más abajo.
   Recuerde: si no declara ninguno, el token queda con acceso total.
4. Si quiere un **límite diario** de peticiones para ese token, teniendo en cuenta su efecto
   sobre el rate limit ([§9](#s9)).
5. El plazo de entrega, que se acuerda al solicitarlas. No hay un plazo publicado.

**Qué recibirá:** un par `api_key` / `api_secret` de producción, por el canal que acuerden. No
pida ni reciba esas credenciales por un canal público, y no las publique en ningún repositorio.

**Requisitos de la cuenta para operar:** la empresa debe tener la API habilitada, estar en estado
activo y tener saldo depositado ([§4](#s4)).

**Primera verificación, antes de la primera venta real:**

```bash
curl -s https://api.recarga.do/v1/account -H "Authorization: Bearer $KEY.$SECRET"
```

Debe responder `"ambiente": "production"`, `"sandbox": false` y, en `token.permisos`, la lista de
permisos que solicitó.

---

<a id="s12"></a>

## 12. QUÉ NO EXISTE TODAVÍA

Para que no lo diseñe contando con ello:

| Función | Estado | Mientras tanto |
|---|---|---|
| **Webhooks salientes** | Pendiente | **Sondee `GET /v1/transactions/{id}`.** No espere notificaciones push |
| Aviso automático de saldo bajo | No existe | Consulte `GET /v1/saldo` y vigile `saldo_bajo` ([§4](#s4)) |
| Cálculo de comisiones por API | Requiere validación financiera | Concilie contra su propio registro ([§4](#s4)) |

Tres aclaraciones sobre campos que aparecen en las respuestas y **hoy no habilitan nada**:

- **Servicios que no son recarga móvil.** El catálogo incluye electricidad, agua y
  otros (el seguro de ley tiene su propio flujo, en la [§6-ter](#s6c)). `POST /v1/recharges` acepta cualquier `service_id` activo, pero el catálogo no declara
  qué `identifier` espera cada servicio, ni existe endpoint para consultar una factura.
  **Confirme con soporte antes de vender por API un servicio que no sea recarga móvil.**
- **Sin webhooks.** El estado de una operación `PENDING` se conoce consultando, no esperando a
  que le avisen. Diseñe su integración con esa premisa.

---

<a id="s13"></a>

## 13. SOPORTE

| Canal | Dato |
|---|---|
| WhatsApp (ventas y soporte) | **+1 (829) 335-1000** |
| Correo | **info@recarga.do** |
| Horario del equipo humano | Lunes a viernes, 8:00 a. m. a 5:00 p. m.; sábados, 8:00 a. m. a 12:00 del mediodía (hora de Santo Domingo) |
| Canal de WhatsApp con IA | 24/7 |

> **Los cuatro datos de esta tabla son datos comerciales que esta guía no puede verificar contra
> ninguna fuente del sistema.** Confírmelos con su ejecutivo de Recarga.do antes de darlos por
> definitivos. Lo mismo aplica a las cifras marcadas como dato comercial en [§4](#s4).

Use estos mismos canales para: credenciales de producción ([§11](#s11)), una cuenta de pruebas
propia, lista blanca de IPs, permisos del token, umbral de `alerta_saldo_bajo`, datos bancarios
para depósitos y operaciones que llevan más de 60 minutos en `PENDING`.

Al reportar cualquier incidencia, incluya siempre:

1. El `request_id` de la respuesta.
2. El `transaction_id`, si lo hubo.
3. La `Idempotency-Key` que usó.
4. Fecha y hora aproximadas.

Con esos cuatro datos la operación se localiza en segundos. Sin ellos, no.

### Qué pasa con el dinero de una recarga que no se resuelve

Que quede dicho sin ambigüedad, porque es lo que más se pregunta:

- La reconciliación le pregunta al proveedor cada 5 minutos por cada operación sin desenlace, y
  la cierra en cuanto hay una respuesta firme: cobra si se entregó, devuelve el saldo si no.
- Si el proveedor no da esa respuesta firme, **el importe sigue retenido: ni cobrado ni
  devuelto**. A los 60 minutos se levanta una alerta interna para atención manual. Esa alerta
  avisa, no corrige.
- **Hoy no existe un plazo máximo tras el cual el dinero se libere solo.** Fijarlo es una regla
  de negocio que todavía no está definida. Si en algún acuerdo comercial le ofrecieron una
  devolución automática a los 5 minutos, esa promesa no está implementada en el sistema:
  confírmela con su ejecutivo antes de prometérsela a un cliente.
- Las reclamaciones se atienden por WhatsApp, con los cuatro datos de la lista de arriba.

---

## Documentos relacionados

| Documento | Para qué |
|---|---|
| [EMPIECE-AQUI.md](EMPIECE-AQUI.md) | El camino corto: librerías de un archivo y punto de venta listo para usar |
| [sdk/](sdk/) | Librerías oficiales para PHP, Node y Python |
| [examples/](examples/) | Ejemplos ejecutables, y un punto de venta completo en PHP |
| [recarga-do.postman_collection.json](recarga-do.postman_collection.json) | Colección de Postman con credenciales de prueba cargadas. La vía más rápida si no usa terminal |
| [integracion.html](https://doc.recarga.do/integracion.html) | Manual técnico con consola interactiva y ejemplos en cURL, PHP, Node y Python |
| [API.md](API.md) | Referencia completa de endpoints, campos y errores |
| [openapi.yaml](openapi.yaml) | Especificación OpenAPI 3.0 para generar clientes |

---

*Todos los ejemplos, códigos de error y respuestas JSON de esta guía se ejecutaron contra
`https://api.recarga.do` el 2026-08-12.*