Diccionario de productos

Cómo se usa esta tabla

El ID de cada servicio es el service_id que envía en POST /v1/recargas. El identificador es lo que va en el campo identifier. Si el monto dice «libre», el importe lo determina la factura del cliente y no hay tope fijado por nosotros.

Cómo se usa un producto

Tres pasos, siempre los mismos, sea cual sea el servicio.

1 · Busque el servicio y tome su ID

Puede tomarlo de esta tabla, o pedirlo por API para tenerlo siempre al día:

# Todos los servicios activos
curl -s https://api.recarga.do/v1/servicios -H "$AUTH"

# Solo una categoría
curl -s "https://api.recarga.do/v1/servicios?categoria=Telefon%C3%ADa" -H "$AUTH"

# Buscar por nombre
curl -s "https://api.recarga.do/v1/servicios?q=claro" -H "$AUTH"

2 · Arme la petición con el identificador correcto

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,                 // CLARO
        "identifier": "8095551234",       // el número de teléfono
        "amount": 100
      }'

Respete el rango de montos

Si el servicio indica un mínimo o un máximo, valídelo en su aplicación antes de enviar. Se ahorra un viaje de ida y vuelta y evita que el cajero vea un error en pantalla con el cliente delante.

3 · Guarde el resultado

Toda respuesta trae un transaction_id y un request_id. Guarde ambos junto a su venta: son la referencia para el recibo, para anular y para soporte.

Los seis tipos de producto

Cada tipo se comporta distinto. Saber cuál es le dice qué esperar de la respuesta.

Tipo	Qué es	Identificador	Particularidad
mobile_recharge	Recarga de saldo a un celular	Número de teléfono	El monto es libre dentro del rango. Es el caso más común.
data_package	Paquete de datos, minutos y SMS	Número de teléfono	El monto lo fija el paquete. Consulte primero `/v1/servicios/{id}/paquetes`.
electricity_prepaid	Electricidad prepago	Número de contrato o NIC	La respuesta incluye el token de recarga que el cliente teclea en su medidor. Imprímalo en el recibo.
generic	Pago de una factura o cuenta	El que asigna cada institución	El monto lo determina la factura del cliente.
insurance	Seguro de ley de vehículos (Seguro Dominicana)	Placa del vehículo	Antes de vender: cédula, placa y código SMS del dueño, plan y cotización con `/v1/seguros`. Se vende con `opcion_id` `seguro:{id}`, sin monto. Se habilita por comercio. No acepta anulación. Ver el flujo.
juancito_sport	Plataforma de apuestas	Número de cuenta del usuario	Acepta anulación.

Qué se puede anular

No todos los servicios admiten anulación, y conviene saberlo antes de poner el botón en la caja.

Sí admite

—

Estos servicios devuelven el importe si anula la operación. Verifíquelo siempre en el campo acepta_anulacion del catálogo, no lo dé por hecho.

No admite

—

Una vez procesada no hay vuelta atrás. Valide los datos con el cliente antes de enviar, especialmente el número.

Cómo anular

Un solo llamado

POST /v1/transacciones/{id}/anular con su Idempotency-Key. El importe vuelve a su saldo solo cuando la anulación se confirma.

Ver la referencia

Compruebe acepta_anulacion antes de mostrar el botón

Si ofrece anular un servicio que no lo admite, su cajero prometerá al cliente una devolución que no va a ocurrir. Es preferible no mostrar el botón que mostrarlo y fallar.