Ir al contenido

Reseller: operar tu cartera de clientes por API

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.

  • Una cuenta de reseller y una sesión del CLI. Sólo la persona con el rol RESELLER_FULL_ACCESS de la empresa crea, renombra y revoca credenciales. Si no hay sesión, inicia con redcumbre login --sin-navegador y pásale a la persona la dirección y el código que entrega; cuando apruebe, corre redcumbre login --completar.
  • Una credencial de máquina del reseller. No es la llave del proyecto: la que instala redcumbre init es FULL-API, y estas operaciones declaran los roles RESELLER_API_LECTURA o RESELLER_API_ESCRITURA (redcumbre api describir <operación> los muestra). La credencial tiene dos ejes:
    • Tipo: lectura (sólo consultas) o escritura (consultas y cambios). Toda operación que no sea un GET exige la de escritura; con la de lectura responde 403.
    • Entorno: prueba o produccion.
  • 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_EXISTE y 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_EXCEDIDO al 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.

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:

Ventana de terminal
REDCUMBRE_LLAVE_PRUEBA=keys/reseller-<empresa>-escritura-prueba.json redcumbre api obtenerResumenDelReseller

El 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 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 (permisos 0600) 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.

  2. 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).

  3. 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ó.

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.

  1. Resumen del reseller:

    Ventana de terminal
    redcumbre api obtenerResumenDelReseller

    Resultado esperado: 200 con el resumen del reseller de ejemplo.

  2. Clientes:

    Ventana de terminal
    redcumbre api listarClientesDelReseller --todas

    Resultado esperado: los tres clientes de ejemplo, con su estado. --todas recorre todas las páginas del listado.

  3. Configuración y plan mayorista: redcumbre api obtenerConfiguracionDelReseller y redcumbre api obtenerPlanMayorista. Resultado esperado: 200 con 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ónQué haceCredencial
obtenerResumenDelResellerObtener el resumen del resellerlectura o escritura

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:

Ventana de terminal
redcumbre api verificarDisponibilidadDeSlug --param slug=panaderia-luna

Resultado esperado: 200 que dice si el identificador está disponible.

  1. Lee el contrato de la alta y revisa los datos que pide:

    Ventana de terminal
    redcumbre api describir crearClienteDelReseller
    redcumbre api obtenerPlanMayorista
    redcumbre api listarPlanesRetail --param limit=50
    redcumbre api listarRolesDeCreacionDeCliente

    Resultado 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, tipoDocumento y lagoPlanCode, que es el código de uno de tus planes retail; trae además datos opcionales de facturación (razonSocial, direccion, comuna, ciudad), usuarios iniciales, el emisorDte y isDraft para dejarlo en borrador. Usa en rut un RUT de prueba (por ejemplo 12345678-5) mientras estés en modo de prueba, nunca el de una persona. No mandes tempPassword: por API cada persona nueva recibe su invitación por correo y una contraseña temporal responde 400 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 acepta tipoDocumento no está publicado en el contrato: pregúntaselo a la persona o léelo del panel, no lo adivines.

  2. 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 --ensayo
    redcumbre api crearClienteDelReseller --cuerpo @cliente.json

    Resultado esperado en prueba: 201 con 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 mismo slug y los mismos datos devuelve ese mismo cliente (200); con otros datos responde 409 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.

  3. Consulta, cambia y borra:

    Ventana de terminal
    redcumbre api obtenerClienteDelReseller --param tenantId=-1
    redcumbre api consultarUsoDelCliente --param tenantId=-1
    redcumbre api listarServiciosDelCliente --param tenantId=-1

    Resultado 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, actualizarServiciosDelCliente con {"services":[{"serviceCode":"…","enabled":true}]}; ambas escriben en producción (su precio: redcumbre tarifas actualizarClienteDelReseller --produccion). Si el cliente tiene aguaSSR, obtenerOperadorDeAguaDelCliente lee la forma jurídica de su operador de agua (null si aún no tiene) y fijarOperadorDeAguaDelCliente la fija. eliminarClienteBorrador sólo borra clientes en borrador. Cuando el cliente reemplaza su certificado digital, notificarCertificadoReemplazado lo avisa (pide emisorId, rut, razonSocial y los nombres del certificado anterior y del nuevo).

Operaciones de esta tarea:

OperaciónQué haceCredencial
actualizarClienteDelResellerActualizar un clienteescritura
consultarUsoDelClienteConsultar el uso de un clientelectura o escritura
crearClienteDelResellerCrear un clienteescritura
eliminarClienteBorradorEliminar un cliente en borradorescritura
listarClientesDelResellerListar los clienteslectura o escritura
listarRolesDeCreacionDeClienteListar los roles disponibles al crear un clientelectura o escritura
notificarCertificadoReemplazadoAvisar que cambió el certificado de un clienteescritura
obtenerClienteDelResellerObtener un clientelectura o escritura
obtenerPlanMayoristaObtener el plan mayoristalectura o escritura
verificarDisponibilidadDeSlugVerificar si un identificador de empresa está disponiblelectura o escritura

Operaciones de esta tarea:

OperaciónQué haceCredencial
actualizarServiciosDelClienteActualizar los servicios de un clienteescritura
fijarOperadorDeAguaDelClienteFijar la forma jurídica del operador de agua de un clienteescritura
listarServiciosDelClienteListar los servicios de un clientelectura o escritura
obtenerOperadorDeAguaDelClienteLeer el operador de agua de un clientelectura 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: actualizarServiciosDelCliente con {"services":[{"serviceCode":"EMISORES_CON_CERTIFICADO_API","enabled":true}]}. El master no lo activa en una empresa que tiene reseller (responde 400): 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 403 en 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.

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.

  1. Mira con qué armar el plan:

    Ventana de terminal
    redcumbre api listarMetricasFacturables
    redcumbre api consultarCargosMayoristas
    redcumbre api listarSaasExternos

    Resultado esperado: las métricas (billableMetricId) que puedes cobrar, los cargos de tu plan mayorista y tus SaaS externos.

  2. 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 con name, code (letras, números y guion bajo), interval (monthly, yearly o weekly), amountCents y charges; cada cargo lleva billableMetricId, chargeModel (standard, graduated, package o volume) y properties. Un plan de un SaaS tuyo lleva además saasExternoCodigo, cicloDeCobro (ANIVERSARIO o CALENDARIO) y alLlegarAlCupo.
    • clonarPlanRetail: copia uno existente con newCode y newName.
    { "name": "Plan Básico", "code": "basico", "markupPercent": 30 }
    Ventana de terminal
    redcumbre api crearPlanRetailDesdeMayorista --cuerpo @plan.json --ensayo
    redcumbre api crearPlanRetailDesdeMayorista --cuerpo @plan.json

    Resultado esperado en prueba: 201 con el plan de la respuesta de ejemplo, sin crear nada. La respuesta de un plan trae además warnings: léelos.

  3. 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.json

    Resultado esperado en prueba: 201 con el resultado de la asignación, sin guardar nada. Para cambiar de plan, cambiarPlanDeCliente recibe en la ruta el plan actual y en el cuerpo tenantSlug y newLagoPlanCode. 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.

  4. Ordena el catálogo: actualizarPlanRetail cambia un plan, actualizarActivacionDePlanRetail lo activa o desactiva, archivarPlanRetail y desarchivarPlanRetail lo guardan o lo devuelven, y listarClientesDelPlan dice quiénes lo tienen.

Operaciones de esta tarea:

OperaciónQué haceCredencial
actualizarActivacionDePlanRetailActivar o desactivar un plan retailescritura
actualizarPlanRetailActualizar un plan retailescritura
archivarPlanRetailArchivar un plan retailescritura
asignarPlanAClienteAsignar un plan a un clienteescritura
cambiarPlanDeClienteCambiar el plan de un clienteescritura
clonarPlanRetailClonar un plan retailescritura
consultarCargosMayoristasConsultar los cargos mayoristaslectura o escritura
crearPlanRetailCrear un plan retailescritura
crearPlanRetailDesdeMayoristaCrear un plan retail desde el mayoristaescritura
desarchivarPlanRetailDesarchivar un plan retailescritura
listarClientesDelPlanListar los clientes de un planlectura o escritura
listarMetricasFacturablesListar las métricas facturableslectura o escritura
listarPlanesRetailListar los planes retaillectura o escritura
listarSaasExternosListar los SaaS externoslectura o escritura
obtenerPlanRetailObtener un plan retaillectura 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.

  1. Registra el SaaS. codigo de 3 a 40 caracteres (minúsculas, números y guion bajo; no cambia después) y nombre:

    { "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 --ensayo
    redcumbre api crearSaasDelReseller --cuerpo @saas.json

    Resultado esperado en prueba: 201 con el SaaS de la respuesta de ejemplo, sin crear nada. Repetir la misma alta devuelve el SaaS existente (200); con otros datos responde 409 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, responde 409 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.

  2. Crea sus métricas. La forma queda fija desde que la creas:

    FormaQué cuenta
    conteoCada evento aceptado suma 1
    sumaSuma la cantidad de cada evento (mayor que 0, hasta 4 decimales)
    unicoCuenta identificadores distintos dentro del período (identificador_contado)
    unico con recurrente: trueEl identificador queda dado de alta hasta que llega su baja y cuenta en todos los períodos intermedios (cada evento lleva operacion: alta o baja)
    { "codigo": "horas_soporte", "nombre": "Horas de soporte", "saas": "mesa_ayuda", "forma": "suma" }

    Resultado esperado en prueba: 201 con la métrica de ejemplo. Tienes hasta 50 métricas activas. recurrente sólo con unico (400 RECURRENTE_SOLO_CON_UNICO). Una métrica propia sólo se usa en un plan de suscripción adicional de su propio SaaS.

  3. Informa el consumo. enviarEventosDelReseller recibe 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 responde 403 SOLO_POR_CREDENCIAL. En el conjunto de prueba existe ejemplo-saas con una métrica por forma (ejemplo_conteo, ejemplo_horas de suma, ejemplo_unico y ejemplo_usuarios único recurrente), el cliente -1 con suscripción y cupo en ejemplo_horas, el -3 sin suscripción y el -4 con un plan sin ejemplo_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_en por 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 forma cantidad, identificador_contado u operacion. Cualquier otro campo se rechaza con CAMPO_NO_ADMITIDO.

    Ventana de terminal
    redcumbre api enviarEventosDelReseller --cuerpo @eventos.json

    Resultado esperado: un resultado por evento, en el mismo orden: aceptado, duplicado (ya se aceptó ese evento_id) o rechazado con su motivo. 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 evento aceptado siempre se te cobra a ti; si el cliente no paga ese consumo, el resultado trae sin_cobro_al_cliente con la causa sin-suscripcion o plan-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_SUSCRIPCION y LIMITE_EXCEDIDO. El cobro va al período en que REDCUMBRE recibió el evento, no al de ocurrido_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_VERIFICABLE y no guarda nada: reintenta tras el Retry-After.

  4. Revisa lo recibido:

    Ventana de terminal
    redcumbre api listarEventosDelReseller --param saas=mesa_ayuda --param resultado=rechazado
    redcumbre api obtenerResumenDeEventosDelReseller
    redcumbre api listarContadoresDeTopeDelReseller

    Resultado 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ónQué haceCredencial
archivarSaasDelResellerArchivar un SaaS externoescritura
cambiarSaasDelResellerCambiar el nombre o la descripción de un SaaS externoescritura
crearSaasDelResellerCrear un SaaS externoescritura
listarSaasDelResellerListar tus SaaS externoslectura o escritura
obtenerSaasDelResellerObtener un SaaS externolectura o escritura

Operaciones de esta tarea:

OperaciónQué haceCredencial
archivarMetricaPropiaArchivar una métrica propiaescritura
cambiarMetricaPropiaCambiar el nombre o la descripción de una métrica propiaescritura
crearMetricaPropiaCrear una métrica propiaescritura
listarMetricasPropiasListar tus métricas propiaslectura o escritura
obtenerMetricaPropiaObtener una métrica propialectura o escritura

Operaciones de esta tarea:

OperaciónQué haceCredencial
enviarEventosDelResellerEnviar eventos de tus SaaS externosescritura
listarContadoresDeTopeDelResellerRechazos por tope, por hora y por SaaSlectura o escritura
listarEventosDelResellerListar los eventos recibidos de tus SaaS externoslectura o escritura
obtenerResumenDeEventosDelResellerResumen de los eventos recibidos por métricalectura 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.

  1. Mira qué se puede contratar:

    Ventana de terminal
    redcumbre api listarSaasDisponibles --param tenantId=-1
    redcumbre api listarPlanesDisponiblesDeSuscripcionAdicional --param tenantId=-1 --param saas=ejemplo-saas

    Resultado esperado: los SaaS disponibles para ese cliente y los planes de ejemplo-saas.

  2. Contrata: contratarSuscripcionAdicional pide saas y lagoPlanCode, y admite correoAvisos, silenciarCorreosAlCliente y alLlegarAlCupo (seguir-cobrando o cortar).

    Ventana de terminal
    redcumbre api contratarSuscripcionAdicional --param tenantId=-1 --cuerpo @suscripcion.json --ensayo

    Resultado esperado: la petición POST hacia las suscripciones adicionales de ese cliente; sin --ensayo, en prueba, 201 con la suscripción de ejemplo.

  3. Cambia o da de baja: cambiarPlanDeSuscripcionAdicional (lagoPlanCode), eliminarSuscripcionAdicional (baja, con motivo opcional), cancelarOperacionProgramada (cancela una bajada o baja programada), actualizarCorreosAlClienteDeSuscripcionAdicional (silencia o reactiva los correos al cliente) y actualizarAlLlegarAlCupoDeSuscripcionAdicional. Con tu cuenta suspendida se permite bajar de plan, no subir.

  4. Consulta el cupo antes de prestar el servicio:

    Ventana de terminal
    redcumbre api consultarCupoDelCliente --param tenantId=-1 --param saas=ejemplo-saas

    Resultado esperado: por cada métrica activa del SaaS, un estado explícito: cupo (trae incluidas, consumidas, quedan y corta: true si tu configuración es cortar), sin-cupo (el plan lo cobra todo como adicional) o fuera-del-plan (el plan no tiene esa métrica). Sin suscripción activa responde suscripcion: "sin-suscripcion" y todo en fuera-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ónQué haceCredencial
actualizarAlLlegarAlCupoDeSuscripcionAdicionalElegir qué ocurre al llegar al cupoescritura
actualizarCorreosAlClienteDeSuscripcionAdicionalSilenciar o reactivar los correos al clienteescritura
cambiarPlanDeSuscripcionAdicionalCambiar el plan de una suscripción adicionalescritura
cancelarOperacionProgramadaCancelar la operación programada de una suscripción adicionalescritura
contratarSuscripcionAdicionalContratar una suscripción adicionalescritura
eliminarSuscripcionAdicionalDar de baja una suscripción adicionalescritura
listarPlanesDisponiblesDeSuscripcionAdicionalListar los planes disponibles para una suscripción adicionallectura o escritura
listarSaasDisponiblesListar los SaaS disponibleslectura o escritura
listarSuscripcionesAdicionalesListar las suscripciones adicionales de un clientelectura o escritura
obtenerSuscripcionAdicionalObtener una suscripción adicionallectura o escritura

Operaciones de esta tarea:

OperaciónQué haceCredencial
consultarCupoDelClienteConsultar el cupo de un cliente en un SaaS tuyolectura 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»
Ventana de terminal
redcumbre api obtenerConfiguracionDelReseller
redcumbre api consultarDominioPropio

Resultado esperado: 200 con la configuración y el estado del dominio propio. Para cambiarlos:

  • actualizarMarcaDelReseller: primaryColor y secondaryColor (#RRGGBB), primaryPalette, surfacePalette y platformName (hasta 100 caracteres).
  • actualizarAtencionAlCliente: contactEmail, contactPhone (hasta 50) y horarioAtencion (hasta 255).
  • registrarDominioPropio: domain; dispara la emisión de su certificado. Consúltalo después con consultarDominioPropio.
  • actualizarCobranzaDelReseller: diasVencimiento (1 a 180), diasCorte (2 a 365) y emisorLiquidacionesId, el emisor con que facturas las liquidaciones a tus clientes.

Operaciones de esta tarea:

OperaciónQué haceCredencial
actualizarAtencionAlClienteActualizar la atención al clienteescritura
actualizarCobranzaDelResellerActualizar la cobranza del resellerescritura
actualizarMarcaDelResellerActualizar la marca del resellerescritura
consultarDominioPropioConsultar el estado del dominio propiolectura o escritura
obtenerConfiguracionDelResellerObtener la configuración del resellerlectura o escritura
registrarDominioPropioRegistrar el dominio propio del resellerescritura

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).

Ventana de terminal
redcumbre api listarLiquidacionesEmitidas --param limit=20
redcumbre api listarLiquidacionesRecibidas --param limit=20
redcumbre api listarAuditoriaDeLiquidaciones --param limit=20

Resultado 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:

Ventana de terminal
redcumbre api suspenderPagoDeCliente --param childId=-1
redcumbre api reactivarPagoDeCliente --param childId=-1

Resultado 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ónQué haceCredencial
listarAuditoriaDeLiquidacionesListar la auditoría de liquidacioneslectura o escritura
listarLiquidacionesEmitidasListar las liquidaciones emitidaslectura o escritura
listarLiquidacionesRecibidasListar las liquidaciones recibidaslectura o escritura
reactivarPagoDeClienteReactivar a un cliente suspendidoescritura
suspenderPagoDeClienteSuspender a un cliente por impagoescritura

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:

FamiliaTiposCampos que se agregan
Estadocliente.activado, cliente.suspendido, cliente.reactivado, cliente.dado-de-bajaestadoAnterior, estadoNuevo; motivo sólo en cliente.suspendido (pago, decision-de-redcumbre, decision-del-reseller o suspension-del-reseller)
Suscripción adicionalsuscripcion-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-canceladosaas, planAnterior, planNuevo, rigeEn
Cupocupo.umbral-80, cupo.umbral-100saas, metrica, umbral, cupo, consumo, alLlegar

Todos llevan id (descarta repetidos por ese id), tipo, esEjemplo, ocurridoEn y cliente. Nunca traen datos de personas.

  1. 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.

  2. 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.json
    redcumbre api obtenerConfiguracionDeAvisos

    Resultado esperado en prueba: la configuración de ejemplo con tu url y activo, sin guardar nada. En producción, activar sin haber generado el secreto responde 409 AVISOS_SIN_SECRETO, y una dirección que no es https responde 400.

  3. Prueba tu receptor con un aviso de ejemplo (hasta 10 por hora; el exceso responde 429 con Retry-After):

    { "tipo": "cliente.suspendido" }
    Ventana de terminal
    redcumbre api enviarAvisoDeEjemplo --cuerpo @aviso.json

    Resultado esperado: 201 con un avisoId; el aviso llega a tu receptor con esEjemplo: true. En prueba el avisoId es simulado y no llega nada. Responde 409 AVISOS_INACTIVOS si los avisos están desactivados.

  4. 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 si t está a más de 5 minutos. Con el secreto regenerado no conviven dos firmas.

  5. Lee el historial:

    Ventana de terminal
    redcumbre api listarHistorialDeAvisos --param resultado=FALLIDO
    redcumbre api obtenerAvisoDelHistorial --param avisoId=<avisoId>

    Resultado esperado: los avisos con ese resultado (ENTREGADO, FALLIDO, NO_ENVIADO o EN_CURSO) y, por aviso, sus intentos de entrega. Admite tipo, clienteSlug, desde, hasta y page; el historial se conserva 30 días.

    Se entrega con hasta 12 intentos (espera creciente de 1 a 60 segundos); cuenta como entregado cualquier 2xx y una redirección 3xx cuenta como fallo. Un aviso es una notificación, no la fuente de verdad: si tu receptor estuvo caído, reconcilia leyendo listarClientesDelReseller y obtenerClienteDelReseller y quédate con el estado de la ficha.

Operaciones de esta tarea:

OperaciónQué haceCredencial
actualizarConfiguracionDeAvisosActualizar la configuración de avisosescritura
enviarAvisoDeEjemploEnviar un aviso de ejemploescritura
listarHistorialDeAvisosListar el historial de avisoslectura o escritura
obtenerAvisoDelHistorialVer un aviso del historiallectura o escritura
obtenerConfiguracionDeAvisosVer la configuración de avisoslectura o escritura
  • En prueba: cada lectura devuelve el conjunto de ejemplo (identificadores negativos, slugs ejemplo-…) y cada escritura responde con el resultado de ejemplo y el campo sandbox, 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 en listarPlanesRetail, un SaaS en listarSaasDelReseller, un evento aceptado en listarEventosDelReseller.
  • Avisos: el aviso de ejemplo llega a tu receptor con la firma válida, y listarHistorialDeAvisos lo muestra ENTREGADO.
  • Las operaciones con métrica traen en su respuesta un bloque cobro; su precio lo da redcumbre tarifas <operationId>.
Si vesSignificaQué haces
400 CLAVE_DE_REPETICION_REQUERIDAUna escritura que crea algo llegó sin idempotencyKeyUsa el CLI (la agrega) o manda tu propia clave
409 CLAVE_USADA_CON_OTROS_DATOSEsa clave ya se usó con otro cuerpoUsa una clave nueva para los datos nuevos
409 CLAVE_EN_CURSOLa primera llamada con esa clave sigue corriendoEspera unos segundos y repite
400 OPERACION_NO_DISPONIBLE_EN_PRUEBAEsa operación no tiene comportamiento de ejemploPruébala en producción con la persona presente, o no la ejercites
400 CONTRASENA_TEMPORAL_NO_PERMITIDAEl alta trae tempPasswordQuita el campo: cada usuario recibe su invitación por correo
401 API_KEY_REVOKED o API_KEY_EXPIREDLa credencial está revocada o vencióLa persona crea otra (redcumbre reseller credenciales crear)
403 en una escrituraEstás usando la credencial de lectura, o tocas el interior de un clienteUsa la de escritura; el interior de un cliente no es de esta superficie
403 API_KEY_TENANT_MISMATCHLa empresa de la ruta no es la de tu credencialUsa el slug de tu propio reseller
403 NO_ES_RESELLERLa empresa no tiene perfil de resellerUsa la empresa reseller correcta (--empresa)
403 RESELLER_SUSPENDIDOTu cuenta de reseller está suspendidaNo crees credenciales, clientes ni planes, ni subas de plan; regulariza el pago con REDCUMBRE. Las lecturas siguen funcionando
403 BAJA_SOLO_MASTERBaja de una suscripción de ValidaFirmaNo se hace por esta vía: sólo la hace REDCUMBRE
404 en un clienteNo es tuyo, o es de producción y estás en pruebaUsa los identificadores que devuelve listarClientesDelReseller
409 SLUG_YA_USADO, CODIGO_YA_USADO, LIMITE_ALCANZADO, CODIGO_RESERVADO_POR_ARCHIVADOUn identificador repetido, un tope de 50 o un código archivadoElige otro código; los archivados no se reutilizan
429 LIMITE_EXCEDIDOPasaste las 10.000 llamadas por horaEspera el Retry-After
503 TOPE_NO_VERIFICABLENo se pudo verificar el topeReintenta 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.

  • 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 https alcanzable desde internet.

  • Más detalle: Modo de prueba y producción.