Reseller: operar tu cartera de clientes por API
Qué resuelve
Sección titulada «Qué resuelve»Un reseller construye un producto para sus propios clientes: les crea empresa, les asigna un plan, mide lo que consumen de sus servicios y les cobra. Esta ficha deja que un agente haga por API lo mismo que la persona hace en el panel del reseller: crear y administrar clientes, armar planes retail, registrar SaaS externos y sus métricas, informar consumo, contratar suscripciones adicionales, revisar liquidaciones y recibir avisos del estado de cada cliente.
Cada operación usa la misma ruta, el mismo método y la misma respuesta que el panel; no hay una copia de las rutas para máquinas. Lo que una credencial de reseller no alcanza: el interior de la empresa de un cliente (sus documentos, contactos y configuración), la API de documentos tributarios con el identificador de tu propio reseller, y cualquier cliente que no sea tuyo (responde como si no existiera).
Si lo que necesitas es emitir facturas u otros documentos tributarios para tu propia empresa, no es esta ficha: ve a Documentos tributarios. Para confirmar, anular o refacturar liquidaciones, ve a Liquidaciones.
Qué necesitas antes
Sección titulada «Qué necesitas antes»- Una cuenta de reseller y una sesión del CLI. Sólo la persona con el rol
RESELLER_FULL_ACCESSde la empresa crea, renombra y revoca credenciales. Si no hay sesión, inicia conredcumbre login --sin-navegadory pásale a la persona la dirección y el código que entrega; cuando apruebe, correredcumbre login --completar. - Una credencial de máquina del reseller. No es la llave del proyecto: la que instala
redcumbre initesFULL-API, y estas operaciones declaran los rolesRESELLER_API_LECTURAoRESELLER_API_ESCRITURA(redcumbre api describir <operación>los muestra). La credencial tiene dos ejes:- Tipo:
lectura(sólo consultas) oescritura(consultas y cambios). Toda operación que no sea unGETexige la de escritura; con la de lectura responde403. - Entorno:
pruebaoproduccion.
- Tipo:
- Límites de las credenciales. Puedes tener a lo más cuatro vigentes: una de lectura y una de escritura en cada entorno. Si ya hay
una vigente del mismo tipo y entorno, crear otra responde
409 CREDENCIAL_VIGENTE_EXISTEy no se crea nada. Rotar es revocar la vigente y crear otra: mientras no actualices tu sistema con la nueva, la vieja deja de funcionar. Cada credencial admite 10.000 llamadas por hora, lecturas y escrituras por igual (429 LIMITE_EXCEDIDOal pasarlas). - Cómo funciona el modo de prueba y qué cambia en producción: Modo de prueba y producción. Cómo se pagina, qué forma tienen los errores y qué límites hay: Reglas comunes. Los avisos del reseller se firman como cualquier otro webhook: Webhooks.
Cómo usa el CLI la credencial
Sección titulada «Cómo usa el CLI la credencial»redcumbre api trabaja con la llave del proyecto. Para que use la credencial del reseller, apunta la variable de la llave sólo en ese comando, sin tocar el .env:
REDCUMBRE_LLAVE_PRUEBA=keys/reseller-<empresa>-escritura-prueba.json redcumbre api obtenerResumenDelResellerEl archivo keys/reseller-<empresa>-<tipo>-<entorno>.json lo escribe el paso 1. No lo leas, no lo imprimas ni lo copies: deja que el CLI lo lea.
En producción la variable es REDCUMBRE_LLAVE_PRODUCCION y el comando lleva --produccion (ver Antes de pasar a producción).
En el resto de la ficha, redcumbre api … significa «con la credencial del reseller que corresponda al tipo y entorno de la operación».
Verificado: con esa variable el CLI arma la petición hacia la ruta del reseller con la empresa de la credencial (--ensayo, sin llamar al API).
Antes de ejecutar algo que escribe, corre el mismo comando con --ensayo y revisa la petición.
Todas las escrituras que crean algo o emiten un documento llevan una clave de repetición, el campo idempotencyKey del cuerpo. El CLI la agrega solo
y la imprime; para reintentar sin duplicar, repite el comando con --clave <esa clave>. Mismos datos y misma clave devuelven la respuesta de la primera vez; la misma clave con otros
datos responde 409 CLAVE_USADA_CON_OTROS_DATOS. enviarEventosDelReseller no usa esta clave: se reconoce por el evento_id de cada evento.
1. Crea una credencial de prueba
Sección titulada «1. Crea una credencial de prueba»-
Crea la credencial. Con tu sesión (nunca con una credencial) y dentro de la carpeta del proyecto:
Ventana de terminal redcumbre reseller credenciales crear --tipo escritura --entorno prueba --nombre "agente-prueba" --empresa <empresa-reseller>Resultado esperado: el secreto no se imprime. El CLI lo escribe en
keys/reseller-<empresa>-escritura-prueba.json(permisos0600) y la salida sólo dice esa ruta. Si pierdes el archivo no hay forma de recuperar el secreto: se revoca la credencial y se crea otra. -
Comprueba que quedó.
Ventana de terminal redcumbre reseller credenciales listar --empresa <empresa-reseller>Resultado esperado: una línea con la credencial, su tipo (
escritura), su entorno (prueba) y su estado, sin el secreto. El vencimiento es opcional (--vence 2027-12-31). -
Revoca una credencial que ya no uses:
redcumbre reseller credenciales revocar <id>. Revocar una ya revocada no falla y devuelve la credencial tal como quedó.
2. Reconoce la cartera
Sección titulada «2. Reconoce la cartera»Con una credencial de prueba, las lecturas devuelven siempre el mismo conjunto de ejemplo, igual para todo reseller: tres clientes
(ejemplo-panaderia-el-sol, activo con plan; ejemplo-taller-los-andes, suspendido; ejemplo-consultora-sur, en preactivación y sin plan), dos planes retail
(ejemplo-retail-basico y ejemplo-retail-plus), tres liquidaciones, su auditoría, métricas de uso, la configuración del reseller y un SaaS externo de ejemplo (ejemplo-saas) con su
plan y su suscripción. Todos los identificadores de ese conjunto son negativos y todos los slugs empiezan con ejemplo-. Las escrituras de prueba se validan igual que en
producción y rechazan lo mismo, pero no guardan nada y no avisan a nadie; la respuesta es la que recibirías si la operación hubiera ocurrido.
-
Resumen del reseller:
Ventana de terminal redcumbre api obtenerResumenDelResellerResultado esperado:
200con el resumen del reseller de ejemplo. -
Clientes:
Ventana de terminal redcumbre api listarClientesDelReseller --todasResultado esperado: los tres clientes de ejemplo, con su estado.
--todasrecorre todas las páginas del listado. -
Configuración y plan mayorista:
redcumbre api obtenerConfiguracionDelReselleryredcumbre api obtenerPlanMayorista. Resultado esperado:200con la marca, la atención al cliente, el dominio y la cobranza del reseller de ejemplo, y el plan mayorista.
Un identificador o un slug que pertenece a un cliente de producción responde como inexistente con una credencial de prueba: nunca ve ni toca tus datos de producción. Una operación sin comportamiento de ejemplo responde 400 OPERACION_NO_DISPONIBLE_EN_PRUEBA.
Operaciones de esta tarea:
| Operación | Qué hace | Credencial |
|---|---|---|
obtenerResumenDelReseller | Obtener el resumen del reseller | lectura o escritura |
3. Crea y administra clientes
Sección titulada «3. Crea y administra clientes»Los clientes se identifican por su tenantId, un número entero que entrega listarClientesDelReseller (en el conjunto de ejemplo son negativos). Para comprobar que un identificador de empresa está libre antes de crearla:
redcumbre api verificarDisponibilidadDeSlug --param slug=panaderia-lunaResultado esperado: 200 que dice si el identificador está disponible.
-
Lee el contrato de la alta y revisa los datos que pide:
Ventana de terminal redcumbre api describir crearClienteDelResellerredcumbre api obtenerPlanMayoristaredcumbre api listarPlanesRetail --param limit=50redcumbre api listarRolesDeCreacionDeClienteResultado esperado: el contrato con el efecto (
crea), la métrica y los campos del cuerpo; luego tus planes y los roles que se pueden asignar a los usuarios iniciales.El alta pide
nombre,slug(en minúsculas, números y guiones:panaderia-luna),rut,tipoDocumentoylagoPlanCode, que es el código de uno de tus planes retail; trae además datos opcionales de facturación (razonSocial,direccion,comuna,ciudad),usuariosiniciales, elemisorDteyisDraftpara dejarlo en borrador. Usa enrutun RUT de prueba (por ejemplo12345678-5) mientras estés en modo de prueba, nunca el de una persona. No mandestempPassword: por API cada persona nueva recibe su invitación por correo y una contraseña temporal responde400 CONTRASENA_TEMPORAL_NO_PERMITIDA. Si el correo de un usuario inicial ya tiene cuenta en la plataforma, esa persona se suma a la empresa nueva con los roles que pediste, sin otra cuenta ni contraseña nueva. Qué valores aceptatipoDocumentono está publicado en el contrato: pregúntaselo a la persona o léelo del panel, no lo adivines. -
Ensaya y crea. Escribe el cuerpo en un archivo (
cliente.json) con los campos de arriba y corre:Ventana de terminal redcumbre api crearClienteDelReseller --cuerpo @cliente.json --ensayoredcumbre api crearClienteDelReseller --cuerpo @cliente.jsonResultado esperado en prueba:
201con el cliente de la respuesta de ejemplo, sin crear nada. En producción crea la empresa, con sus usuarios iniciales, y la respuesta trae el cliente creado. Repetir el alta con el mismoslugy los mismos datos devuelve ese mismo cliente (200); con otros datos responde409 SLUG_YA_USADO. Un correo que ya tiene cuenta en la plataforma no se rechaza: esa persona se suma a la empresa con sus roles. -
Consulta, cambia y borra:
Ventana de terminal redcumbre api obtenerClienteDelReseller --param tenantId=-1redcumbre api consultarUsoDelCliente --param tenantId=-1redcumbre api listarServiciosDelCliente --param tenantId=-1Resultado esperado: la ficha del cliente de ejemplo (datos, estado, plan y servicios), su uso y sus servicios. Para cambiar el nombre o el estado,
actualizarClienteDelReseller; para activar o desactivar servicios,actualizarServiciosDelClientecon{"services":[{"serviceCode":"…","enabled":true}]}; ambas escriben en producción (su precio:redcumbre tarifas actualizarClienteDelReseller --produccion). Si el cliente tiene aguaSSR,obtenerOperadorDeAguaDelClientelee la forma jurídica de su operador de agua (nullsi aún no tiene) yfijarOperadorDeAguaDelClientela fija.eliminarClienteBorradorsólo borra clientes en borrador. Cuando el cliente reemplaza su certificado digital,notificarCertificadoReemplazadolo avisa (pideemisorId,rut,razonSocialy los nombres del certificado anterior y del nuevo).
Operaciones de esta tarea:
| Operación | Qué hace | Credencial |
|---|---|---|
actualizarClienteDelReseller | Actualizar un cliente | escritura |
consultarUsoDelCliente | Consultar el uso de un cliente | lectura o escritura |
crearClienteDelReseller | Crear un cliente | escritura |
eliminarClienteBorrador | Eliminar un cliente en borrador | escritura |
listarClientesDelReseller | Listar los clientes | lectura o escritura |
listarRolesDeCreacionDeCliente | Listar los roles disponibles al crear un cliente | lectura o escritura |
notificarCertificadoReemplazado | Avisar que cambió el certificado de un cliente | escritura |
obtenerClienteDelReseller | Obtener un cliente | lectura o escritura |
obtenerPlanMayorista | Obtener el plan mayorista | lectura o escritura |
verificarDisponibilidadDeSlug | Verificar si un identificador de empresa está disponible | lectura o escritura |
Operaciones de esta tarea:
| Operación | Qué hace | Credencial |
|---|---|---|
actualizarServiciosDelCliente | Actualizar los servicios de un cliente | escritura |
fijarOperadorDeAguaDelCliente | Fijar la forma jurídica del operador de agua de un cliente | escritura |
listarServiciosDelCliente | Listar los servicios de un cliente | lectura o escritura |
obtenerOperadorDeAguaDelCliente | Leer el operador de agua de un cliente | lectura o escritura |
El servicio del alta directa con certificado
Sección titulada «El servicio del alta directa con certificado»«Alta de emisores con certificado por API» (código EMISORES_CON_CERTIFICADO_API) es un servicio manual y sin cobro: no abre ningún módulo del panel, sólo permite que la llave de un cliente cree emisores y suba certificados por API (ver Emisores y tokenización). Cómo se reparte entre tú y REDCUMBRE:
- El servicio tiene que estar en tu catálogo para que puedas darlo. El catálogo lo define REDCUMBRE.
- Lo activas tú, en cada cliente:
actualizarServiciosDelClientecon{"services":[{"serviceCode":"EMISORES_CON_CERTIFICADO_API","enabled":true}]}. El master no lo activa en una empresa que tiene reseller (responde400): lo haces tú. Rige desde la llamada siguiente. Una empresa sin reseller lo recibe del equipo master de REDCUMBRE. - Sin el servicio, la llave del cliente recibe
403en las diez operaciones, también en el modo de prueba. - Apagarlo avisa: si lo apagas en un cliente, los administradores de ese cliente reciben un aviso, y tú, como reseller, también.
- Si REDCUMBRE lo quita de tu catálogo, se apaga en todos tus clientes que lo tenían activo, y los administradores de tu empresa reciben un único aviso con la cuenta de clientes apagados. Los demás servicios del catálogo no se apagan al quitarlos: ése es el único. La actualización del catálogo se puede repetir sin riesgo: si algún cliente falló (la respuesta trae la cuenta de apagados y de fallidos), repetir la misma actualización del catálogo reintenta sólo a los clientes donde el servicio sigue activo y sana lo que falló.
- Volver a poner el servicio en el catálogo no reactiva nada: cada cliente se activa de nuevo con
actualizarServiciosDelCliente.
4. Arma los planes y asígnalos
Sección titulada «4. Arma los planes y asígnalos»Un plan retail es lo que le cobras a tu cliente. Se arma sobre métricas facturables y los cargos mayoristas que te cobra REDCUMBRE.
-
Mira con qué armar el plan:
Ventana de terminal redcumbre api listarMetricasFacturablesredcumbre api consultarCargosMayoristasredcumbre api listarSaasExternosResultado esperado: las métricas (
billableMetricId) que puedes cobrar, los cargos de tu plan mayorista y tus SaaS externos. -
Crea el plan. Hay tres caminos:
crearPlanRetailDesdeMayorista: parte de los cargos mayoristas con un recargo (markupPercent, de 0 a 500).crearPlanRetail: lo armas desde cero conname,code(letras, números y guion bajo),interval(monthly,yearlyoweekly),amountCentsycharges; cada cargo llevabillableMetricId,chargeModel(standard,graduated,packageovolume) yproperties. Un plan de un SaaS tuyo lleva ademássaasExternoCodigo,cicloDeCobro(ANIVERSARIOoCALENDARIO) yalLlegarAlCupo.clonarPlanRetail: copia uno existente connewCodeynewName.
{ "name": "Plan Básico", "code": "basico", "markupPercent": 30 }Ventana de terminal redcumbre api crearPlanRetailDesdeMayorista --cuerpo @plan.json --ensayoredcumbre api crearPlanRetailDesdeMayorista --cuerpo @plan.jsonResultado esperado en prueba:
201con el plan de la respuesta de ejemplo, sin crear nada. La respuesta de un plan trae ademáswarnings: léelos. -
Asigna o cambia el plan de un cliente. El código del plan va en la ruta y el cliente en el cuerpo:
{ "tenantSlug": "ejemplo-consultora-sur" }Ventana de terminal redcumbre api asignarPlanACliente --param lagoPlanCode=ejemplo-retail-basico --cuerpo @asignar.jsonResultado esperado en prueba:
201con el resultado de la asignación, sin guardar nada. Para cambiar de plan,cambiarPlanDeClienterecibe en la ruta el plan actual y en el cuerpotenantSlugynewLagoPlanCode. Ambas escriben en producción (precio:redcumbre tarifas asignarPlanACliente --produccion). Con tu cuenta de reseller suspendida se rechazan, para subir y para bajar de plan. -
Ordena el catálogo:
actualizarPlanRetailcambia un plan,actualizarActivacionDePlanRetaillo activa o desactiva,archivarPlanRetailydesarchivarPlanRetaillo guardan o lo devuelven, ylistarClientesDelPlandice quiénes lo tienen.
Operaciones de esta tarea:
| Operación | Qué hace | Credencial |
|---|---|---|
actualizarActivacionDePlanRetail | Activar o desactivar un plan retail | escritura |
actualizarPlanRetail | Actualizar un plan retail | escritura |
archivarPlanRetail | Archivar un plan retail | escritura |
asignarPlanACliente | Asignar un plan a un cliente | escritura |
cambiarPlanDeCliente | Cambiar el plan de un cliente | escritura |
clonarPlanRetail | Clonar un plan retail | escritura |
consultarCargosMayoristas | Consultar los cargos mayoristas | lectura o escritura |
crearPlanRetail | Crear un plan retail | escritura |
crearPlanRetailDesdeMayorista | Crear un plan retail desde el mayorista | escritura |
desarchivarPlanRetail | Desarchivar un plan retail | escritura |
listarClientesDelPlan | Listar los clientes de un plan | lectura o escritura |
listarMetricasFacturables | Listar las métricas facturables | lectura o escritura |
listarPlanesRetail | Listar los planes retail | lectura o escritura |
listarSaasExternos | Listar los SaaS externos | lectura o escritura |
obtenerPlanRetail | Obtener un plan retail | lectura o escritura |
5. Conecta tus SaaS externos y mide su consumo
Sección titulada «5. Conecta tus SaaS externos y mide su consumo»Un SaaS externo es un servicio tuyo que quieres cobrarle a tus clientes por uso a través de REDCUMBRE. Registras el SaaS, defines sus métricas propias y tu sistema informa cada consumo como un evento.
-
Registra el SaaS.
codigode 3 a 40 caracteres (minúsculas, números y guion bajo; no cambia después) ynombre:{ "codigo": "mesa_ayuda", "nombre": "Mesa de ayuda", "descripcion": "Soporte por horas para los clientes del reseller" }Ventana de terminal redcumbre api crearSaasDelReseller --cuerpo @saas.json --ensayoredcumbre api crearSaasDelReseller --cuerpo @saas.jsonResultado esperado en prueba:
201con el SaaS de la respuesta de ejemplo, sin crear nada. Repetir la misma alta devuelve el SaaS existente (200); con otros datos responde409 CODIGO_YA_USADO. Tienes hasta 50 SaaS activos (409 LIMITE_ALCANZADO). Si es tu primer SaaS y tu plan mayorista no tiene cargo para ninguna de las tres métricas con que REDCUMBRE te cobra, responde409 MAYORISTA_SIN_CARGO: pídeselo a REDCUMBRE. Archivar es definitivo y se niega mientras haya una suscripción adicional activa (409 SAAS_CON_SUSCRIPCIONES_ACTIVAS); el código de un SaaS archivado no se reutiliza. -
Crea sus métricas. La
formaqueda fija desde que la creas:Forma Qué cuenta conteoCada evento aceptado suma 1 sumaSuma la cantidadde cada evento (mayor que 0, hasta 4 decimales)unicoCuenta identificadores distintos dentro del período ( identificador_contado)unicoconrecurrente: trueEl identificador queda dado de alta hasta que llega su bajay cuenta en todos los períodos intermedios (cada evento llevaoperacion:altaobaja){ "codigo": "horas_soporte", "nombre": "Horas de soporte", "saas": "mesa_ayuda", "forma": "suma" }Resultado esperado en prueba:
201con la métrica de ejemplo. Tienes hasta 50 métricas activas.recurrentesólo conunico(400 RECURRENTE_SOLO_CON_UNICO). Una métrica propia sólo se usa en un plan de suscripción adicional de su propio SaaS. -
Informa el consumo.
enviarEventosDelResellerrecibe un lote de 1 a 100 eventos, mezclando SaaS si quieres. Sólo acepta una credencial de máquina de escritura: una sesión de persona responde403 SOLO_POR_CREDENCIAL. En el conjunto de prueba existeejemplo-saascon una métrica por forma (ejemplo_conteo,ejemplo_horasde suma,ejemplo_unicoyejemplo_usuariosúnico recurrente), el cliente-1con suscripción y cupo enejemplo_horas, el-3sin suscripción y el-4con un plan sinejemplo_conteo.{"eventos": [{ "saas": "ejemplo-saas", "metrica": "ejemplo_horas", "cliente": "-1", "evento_id": "E-1", "ocurrido_en": "2026-11-05T14:03:00-03:00", "cantidad": 3 }]}Cambia
ocurrido_enpor la fecha y hora actuales (ISO 8601 con zona). Cada evento admite exactamente estos campos:saas,metrica,cliente(slug o identificador de un cliente tuyo),evento_id(hasta 100 caracteres, tu propio correlativo, nunca un RUT, correo, nombre ni teléfono),ocurrido_en, y según la formacantidad,identificador_contadouoperacion. Cualquier otro campo se rechaza conCAMPO_NO_ADMITIDO.Ventana de terminal redcumbre api enviarEventosDelReseller --cuerpo @eventos.jsonResultado esperado: un resultado por evento, en el mismo orden:
aceptado,duplicado(ya se aceptó eseevento_id) orechazadocon sumotivo. Un rechazo no cancela el resto. El lote entero se rechaza (400 LOTE_INVALIDO) sólo si está vacío, trae más de 100 eventos o está mal formado. Un eventoaceptadosiempre se te cobra a ti; si el cliente no paga ese consumo, el resultado traesin_cobro_al_clientecon la causasin-suscripcionoplan-sin-metrica.Motivos de rechazo:
SAAS_EXTERNO_NO_VALIDO,METRICA_INEXISTENTE,METRICA_ARCHIVADA,METRICA_DE_OTRO_SAAS,CLIENTE_NO_ES_DEL_RESELLER,CAMPO_INVALIDO,CAMPO_NO_ADMITIDO,FECHA_FUTURA(más de 5 minutos adelante),FECHA_FUERA_DE_PLAZO(hace más de 13 meses),RESELLER_SUSPENDIDO,RESELLER_SIN_SUSCRIPCIONyLIMITE_EXCEDIDO. El cobro va al período en que REDCUMBRE recibió el evento, no al deocurrido_en: informa lo más cerca posible de cuando ocurre.Topes: 20.000 eventos por hora por SaaS y 100.000 por hora en total, contando aceptados, duplicados y rechazados; en prueba, 1.000 por hora por SaaS de ejemplo. Si el contador no se puede verificar, el lote responde
503 TOPE_NO_VERIFICABLEy no guarda nada: reintenta tras elRetry-After. -
Revisa lo recibido:
Ventana de terminal redcumbre api listarEventosDelReseller --param saas=mesa_ayuda --param resultado=rechazadoredcumbre api obtenerResumenDeEventosDelResellerredcumbre api listarContadoresDeTopeDelResellerResultado esperado: los eventos con ese resultado, el resumen por métrica y los rechazos por tope, por hora y por SaaS. En prueba los eventos no aparecen en tu vista.
Operaciones de esta tarea:
| Operación | Qué hace | Credencial |
|---|---|---|
archivarSaasDelReseller | Archivar un SaaS externo | escritura |
cambiarSaasDelReseller | Cambiar el nombre o la descripción de un SaaS externo | escritura |
crearSaasDelReseller | Crear un SaaS externo | escritura |
listarSaasDelReseller | Listar tus SaaS externos | lectura o escritura |
obtenerSaasDelReseller | Obtener un SaaS externo | lectura o escritura |
Operaciones de esta tarea:
| Operación | Qué hace | Credencial |
|---|---|---|
archivarMetricaPropia | Archivar una métrica propia | escritura |
cambiarMetricaPropia | Cambiar el nombre o la descripción de una métrica propia | escritura |
crearMetricaPropia | Crear una métrica propia | escritura |
listarMetricasPropias | Listar tus métricas propias | lectura o escritura |
obtenerMetricaPropia | Obtener una métrica propia | lectura o escritura |
Operaciones de esta tarea:
| Operación | Qué hace | Credencial |
|---|---|---|
enviarEventosDelReseller | Enviar eventos de tus SaaS externos | escritura |
listarContadoresDeTopeDelReseller | Rechazos por tope, por hora y por SaaS | lectura o escritura |
listarEventosDelReseller | Listar los eventos recibidos de tus SaaS externos | lectura o escritura |
obtenerResumenDeEventosDelReseller | Resumen de los eventos recibidos por métrica | lectura o escritura |
6. Contrata suscripciones adicionales y vigila el cupo
Sección titulada «6. Contrata suscripciones adicionales y vigila el cupo»Una suscripción adicional le da a un cliente un plan de uno de tus SaaS.
-
Mira qué se puede contratar:
Ventana de terminal redcumbre api listarSaasDisponibles --param tenantId=-1redcumbre api listarPlanesDisponiblesDeSuscripcionAdicional --param tenantId=-1 --param saas=ejemplo-saasResultado esperado: los SaaS disponibles para ese cliente y los planes de
ejemplo-saas. -
Contrata:
contratarSuscripcionAdicionalpidesaasylagoPlanCode, y admitecorreoAvisos,silenciarCorreosAlClienteyalLlegarAlCupo(seguir-cobrandoocortar).Ventana de terminal redcumbre api contratarSuscripcionAdicional --param tenantId=-1 --cuerpo @suscripcion.json --ensayoResultado esperado: la petición
POSThacia las suscripciones adicionales de ese cliente; sin--ensayo, en prueba,201con la suscripción de ejemplo. -
Cambia o da de baja:
cambiarPlanDeSuscripcionAdicional(lagoPlanCode),eliminarSuscripcionAdicional(baja, conmotivoopcional),cancelarOperacionProgramada(cancela una bajada o baja programada),actualizarCorreosAlClienteDeSuscripcionAdicional(silencia o reactiva los correos al cliente) yactualizarAlLlegarAlCupoDeSuscripcionAdicional. Con tu cuenta suspendida se permite bajar de plan, no subir. -
Consulta el cupo antes de prestar el servicio:
Ventana de terminal redcumbre api consultarCupoDelCliente --param tenantId=-1 --param saas=ejemplo-saasResultado esperado: por cada métrica activa del SaaS, un estado explícito:
cupo(traeincluidas,consumidas,quedanycorta: truesi tu configuración escortar),sin-cupo(el plan lo cobra todo como adicional) ofuera-del-plan(el plan no tiene esa métrica). Sin suscripción activa respondesuscripcion: "sin-suscripcion"y todo enfuera-del-plan.REDCUMBRE nunca rechaza un evento por cupo: todo lo que informes se acepta y se registra como consumo, al precio de adicional si pasa el cupo incluido. Quien decide cortar el servicio eres tú, en tu SaaS, según «al llegar al cupo».
Operaciones de esta tarea:
| Operación | Qué hace | Credencial |
|---|---|---|
actualizarAlLlegarAlCupoDeSuscripcionAdicional | Elegir qué ocurre al llegar al cupo | escritura |
actualizarCorreosAlClienteDeSuscripcionAdicional | Silenciar o reactivar los correos al cliente | escritura |
cambiarPlanDeSuscripcionAdicional | Cambiar el plan de una suscripción adicional | escritura |
cancelarOperacionProgramada | Cancelar la operación programada de una suscripción adicional | escritura |
contratarSuscripcionAdicional | Contratar una suscripción adicional | escritura |
eliminarSuscripcionAdicional | Dar de baja una suscripción adicional | escritura |
listarPlanesDisponiblesDeSuscripcionAdicional | Listar los planes disponibles para una suscripción adicional | lectura o escritura |
listarSaasDisponibles | Listar los SaaS disponibles | lectura o escritura |
listarSuscripcionesAdicionales | Listar las suscripciones adicionales de un cliente | lectura o escritura |
obtenerSuscripcionAdicional | Obtener una suscripción adicional | lectura o escritura |
Operaciones de esta tarea:
| Operación | Qué hace | Credencial |
|---|---|---|
consultarCupoDelCliente | Consultar el cupo de un cliente en un SaaS tuyo | lectura o escritura |
7. Configura tu marca, tu atención, tu dominio y tu cobranza
Sección titulada «7. Configura tu marca, tu atención, tu dominio y tu cobranza»redcumbre api obtenerConfiguracionDelResellerredcumbre api consultarDominioPropioResultado esperado: 200 con la configuración y el estado del dominio propio. Para cambiarlos:
actualizarMarcaDelReseller:primaryColorysecondaryColor(#RRGGBB),primaryPalette,surfacePaletteyplatformName(hasta 100 caracteres).actualizarAtencionAlCliente:contactEmail,contactPhone(hasta 50) yhorarioAtencion(hasta 255).registrarDominioPropio:domain; dispara la emisión de su certificado. Consúltalo después conconsultarDominioPropio.actualizarCobranzaDelReseller:diasVencimiento(1 a 180),diasCorte(2 a 365) yemisorLiquidacionesId, el emisor con que facturas las liquidaciones a tus clientes.
Operaciones de esta tarea:
| Operación | Qué hace | Credencial |
|---|---|---|
actualizarAtencionAlCliente | Actualizar la atención al cliente | escritura |
actualizarCobranzaDelReseller | Actualizar la cobranza del reseller | escritura |
actualizarMarcaDelReseller | Actualizar la marca del reseller | escritura |
consultarDominioPropio | Consultar el estado del dominio propio | lectura o escritura |
obtenerConfiguracionDelReseller | Obtener la configuración del reseller | lectura o escritura |
registrarDominioPropio | Registrar el dominio propio del reseller | escritura |
8. Mira las liquidaciones y suspende por impago
Sección titulada «8. Mira las liquidaciones y suspende por impago»Las liquidaciones son lo que tú le facturas a tus clientes (emitidas) y lo que REDCUMBRE te factura a ti (recibidas).
redcumbre api listarLiquidacionesEmitidas --param limit=20redcumbre api listarLiquidacionesRecibidas --param limit=20redcumbre api listarAuditoriaDeLiquidaciones --param limit=20Resultado esperado en prueba: las tres liquidaciones del conjunto de ejemplo (dos emitidas a los dos primeros clientes y una recibida de REDCUMBRE) y su auditoría. Los listados admiten periodo y tipoDestinatario (tenant o reseller). listarLiquidacionesComoReseller y el resto de las operaciones de liquidaciones (confirmar, reintentar el documento, notas de crédito, refacturas, PDF) están en la ficha de Liquidaciones.
Para cortar a un cliente que no paga y volver a habilitarlo:
redcumbre api suspenderPagoDeCliente --param childId=-1redcumbre api reactivarPagoDeCliente --param childId=-1Resultado esperado: suspenderPagoDeCliente responde suspended: true (o alreadySuspended: true si ya lo estaba, sin cambiar nada); reactivarPagoDeCliente lo deja activo. Un cliente que no es tuyo responde 404.
Operaciones de esta tarea:
| Operación | Qué hace | Credencial |
|---|---|---|
listarAuditoriaDeLiquidaciones | Listar la auditoría de liquidaciones | lectura o escritura |
listarLiquidacionesEmitidas | Listar las liquidaciones emitidas | lectura o escritura |
listarLiquidacionesRecibidas | Listar las liquidaciones recibidas | lectura o escritura |
reactivarPagoDeCliente | Reactivar a un cliente suspendido | escritura |
suspenderPagoDeCliente | Suspender a un cliente por impago | escritura |
9. Recibe avisos del estado de tus clientes
Sección titulada «9. Recibe avisos del estado de tus clientes»REDCUMBRE le avisa a tu sistema con una llamada HTTP firmada cada vez que cambia el estado de un cliente, de su suscripción adicional o de su cupo. Son 17 tipos de aviso en tres familias:
| Familia | Tipos | Campos que se agregan |
|---|---|---|
| Estado | cliente.activado, cliente.suspendido, cliente.reactivado, cliente.dado-de-baja | estadoAnterior, estadoNuevo; motivo sólo en cliente.suspendido (pago, decision-de-redcumbre, decision-del-reseller o suspension-del-reseller) |
| Suscripción adicional | suscripcion-adicional. con creada, cambio-de-plan, bajada-programada, bajada-aplicada, bajada-cancelada, baja-programada, baja-aplicada, baja-cancelada, paso-de-ciclo-programado, paso-de-ciclo-aplicado o paso-de-ciclo-cancelado | saas, planAnterior, planNuevo, rigeEn |
| Cupo | cupo.umbral-80, cupo.umbral-100 | saas, metrica, umbral, cupo, consumo, alLlegar |
Todos llevan id (descarta repetidos por ese id), tipo, esEjemplo, ocurridoEn y cliente. Nunca traen datos de personas.
-
Genera el secreto de firma. Sólo se hace en el panel (Reseller, Avisos), por una persona con
RESELLER_FULL_ACCESS: no existe por API. Se muestra una sola vez; al regenerarlo el anterior deja de firmar al instante. Pídele a la persona que lo copie a tu receptor sin pegarlo en el chat. -
Configura la dirección (debe ser
https) y actívalos:{ "activo": true, "url": "https://ejemplo.cl/hooks/avisos-rcapi" }Ventana de terminal redcumbre api actualizarConfiguracionDeAvisos --cuerpo @avisos.jsonredcumbre api obtenerConfiguracionDeAvisosResultado esperado en prueba: la configuración de ejemplo con tu
urlyactivo, sin guardar nada. En producción, activar sin haber generado el secreto responde409 AVISOS_SIN_SECRETO, y una dirección que no eshttpsresponde400. -
Prueba tu receptor con un aviso de ejemplo (hasta 10 por hora; el exceso responde
429conRetry-After):{ "tipo": "cliente.suspendido" }Ventana de terminal redcumbre api enviarAvisoDeEjemplo --cuerpo @aviso.jsonResultado esperado:
201con unavisoId; el aviso llega a tu receptor conesEjemplo: true. En prueba elavisoIdes simulado y no llega nada. Responde409 AVISOS_INACTIVOSsi los avisos están desactivados. -
Verifica la firma. Cada llamada trae
X-Webhook-Signature: t=<unix>,v1=<hmac>: el HMAC-SHA256 de<t>.<cuerpo crudo>con el secreto, igual que los demás webhooks (ver Webhooks). Verifica sobre los bytes crudos y rechaza sitestá a más de 5 minutos. Con el secreto regenerado no conviven dos firmas. -
Lee el historial:
Ventana de terminal redcumbre api listarHistorialDeAvisos --param resultado=FALLIDOredcumbre api obtenerAvisoDelHistorial --param avisoId=<avisoId>Resultado esperado: los avisos con ese resultado (
ENTREGADO,FALLIDO,NO_ENVIADOoEN_CURSO) y, por aviso, sus intentos de entrega. Admitetipo,clienteSlug,desde,hastaypage; el historial se conserva 30 días.Se entrega con hasta 12 intentos (espera creciente de 1 a 60 segundos); cuenta como entregado cualquier
2xxy una redirección3xxcuenta como fallo. Un aviso es una notificación, no la fuente de verdad: si tu receptor estuvo caído, reconcilia leyendolistarClientesDelReselleryobtenerClienteDelResellery quédate con el estado de la ficha.
Operaciones de esta tarea:
| Operación | Qué hace | Credencial |
|---|---|---|
actualizarConfiguracionDeAvisos | Actualizar la configuración de avisos | escritura |
enviarAvisoDeEjemplo | Enviar un aviso de ejemplo | escritura |
listarHistorialDeAvisos | Listar el historial de avisos | lectura o escritura |
obtenerAvisoDelHistorial | Ver un aviso del historial | lectura o escritura |
obtenerConfiguracionDeAvisos | Ver la configuración de avisos | lectura o escritura |
Cómo saber que funcionó
Sección titulada «Cómo saber que funcionó»- En prueba: cada lectura devuelve el conjunto de ejemplo (identificadores negativos, slugs
ejemplo-…) y cada escritura responde con el resultado de ejemplo y el camposandbox, sin cambios. Eso confirma que la credencial, el tipo y la ruta son correctos; no confirma que algo se haya guardado. - Una escritura de verdad (producción): vuelve a leer el recurso. Un cliente creado aparece en
listarClientesDelReseller, un plan enlistarPlanesRetail, un SaaS enlistarSaasDelReseller, un evento aceptado enlistarEventosDelReseller. - Avisos: el aviso de ejemplo llega a tu receptor con la firma válida, y
listarHistorialDeAvisoslo muestraENTREGADO. - Las operaciones con métrica traen en su respuesta un bloque
cobro; su precio lo daredcumbre tarifas <operationId>.
Qué puede fallar
Sección titulada «Qué puede fallar»| Si ves | Significa | Qué haces |
|---|---|---|
400 CLAVE_DE_REPETICION_REQUERIDA | Una escritura que crea algo llegó sin idempotencyKey | Usa el CLI (la agrega) o manda tu propia clave |
409 CLAVE_USADA_CON_OTROS_DATOS | Esa clave ya se usó con otro cuerpo | Usa una clave nueva para los datos nuevos |
409 CLAVE_EN_CURSO | La primera llamada con esa clave sigue corriendo | Espera unos segundos y repite |
400 OPERACION_NO_DISPONIBLE_EN_PRUEBA | Esa operación no tiene comportamiento de ejemplo | Pruébala en producción con la persona presente, o no la ejercites |
400 CONTRASENA_TEMPORAL_NO_PERMITIDA | El alta trae tempPassword | Quita el campo: cada usuario recibe su invitación por correo |
401 API_KEY_REVOKED o API_KEY_EXPIRED | La credencial está revocada o venció | La persona crea otra (redcumbre reseller credenciales crear) |
403 en una escritura | Estás usando la credencial de lectura, o tocas el interior de un cliente | Usa la de escritura; el interior de un cliente no es de esta superficie |
403 API_KEY_TENANT_MISMATCH | La empresa de la ruta no es la de tu credencial | Usa el slug de tu propio reseller |
403 NO_ES_RESELLER | La empresa no tiene perfil de reseller | Usa la empresa reseller correcta (--empresa) |
403 RESELLER_SUSPENDIDO | Tu cuenta de reseller está suspendida | No crees credenciales, clientes ni planes, ni subas de plan; regulariza el pago con REDCUMBRE. Las lecturas siguen funcionando |
403 BAJA_SOLO_MASTER | Baja de una suscripción de ValidaFirma | No se hace por esta vía: sólo la hace REDCUMBRE |
404 en un cliente | No es tuyo, o es de producción y estás en prueba | Usa los identificadores que devuelve listarClientesDelReseller |
409 SLUG_YA_USADO, CODIGO_YA_USADO, LIMITE_ALCANZADO, CODIGO_RESERVADO_POR_ARCHIVADO | Un identificador repetido, un tope de 50 o un código archivado | Elige otro código; los archivados no se reutilizan |
429 LIMITE_EXCEDIDO | Pasaste las 10.000 llamadas por hora | Espera el Retry-After |
503 TOPE_NO_VERIFICABLE | No se pudo verificar el tope | Reintenta tras el Retry-After; la operación no se ejecutó |
La forma general de los errores y de la paginación está en Reglas comunes. Los mensajes de error no incluyen el correo, la razón social, el RUT ni la dirección de un cliente: nombran al cliente por su slug.
Antes de pasar a producción
Sección titulada «Antes de pasar a producción»-
Qué cambia: una credencial de producción opera sobre tus clientes, planes y liquidaciones de verdad, con los mismos efectos —correos, cobros, documentos al SII— que la misma acción hecha por una persona en el panel. Lo emitido en producción vale ante el SII. Lo que cuesta crear un cliente, cambiar su plan o sus servicios y enviar eventos de consumo depende de tu plan:
redcumbre tarifas --produccion. -
Quién lo decide: una persona. Díselo con esas palabras y espera su sí antes de usar la credencial de producción.
-
Cómo: la persona (o tú, con su sí) crea una credencial de producción:
redcumbre reseller credenciales crear --tipo escritura --entorno produccion --nombre "<nombre>" --empresa <empresa-reseller>. Cada escritura en producción lleva--produccion --confirmar <empresa>:Ventana de terminal REDCUMBRE_LLAVE_PRODUCCION=keys/reseller-<empresa>-escritura-produccion.json redcumbre api actualizarClienteDelReseller --param tenantId=<id> --cuerpo @cambio.json --produccion --confirmar <empresa>Verificado: el CLI arma esa petición con la credencial de producción (
--ensayo). No verificado: que las comprobaciones previas que hace el CLI en producción antes de una escritura (la identidad de la empresa y el consumo del plan) las acepte una credencial de reseller. Si el CLI se detiene ahí, la llamada la hace el sistema de la persona por HTTP, con la credencial leída desde su archivo o su variable de entorno, nunca pegada en el chat ni en el repositorio. -
Guarda la credencial fuera del repositorio (
keys/ya queda excluida del control de versiones) y planifica la rotación: entre revocar y crear la nueva hay un corte. -
Los avisos de producción necesitan el secreto de producción generado en el panel y una dirección
httpsalcanzable desde internet. -
Más detalle: Modo de prueba y producción.