Saltar al contenido

    REFERENCIA DE INTEGRACIÓN

    Subafiliaciones (API)

    Integra cuentas independientes, invitaciones, créditos y facturación con los contratos publicados de Pabilo. La autenticación y el envoltorio de respuesta se indican por operación.

    Base: https://api.pabilo.app. Las rutas de esta referencia son JSON; /register, /afiliado/… y /pay/… son páginas de la web.

    Ver guía web de Subafiliaciones

    Autenticación y alcance por operación

    Cada ejemplo privado usa Authorization: Bearer con el JWT de la identidad autorizada indicada en ese ejemplo. «Titular» significa el dueño de esa cuenta de empresa; Owner de plataforma es un rol administrativo distinto. Un JWT de empleado o cliente conserva su identidad subordinada.

    Credenciales y alcance por operación

    • T · titular JWT: preferencias, código general, códigos únicos, invitación manual, cambios y checkout propio rechazan empleados, clientes y appKey.
    • C · comercial delegado: algunas rutas legadas de resumen, reenvío/cancelación, integración y pagos se evalúan con sus permisos. Pueden admitir empleado o appKey autorizados; eso no habilita rutas T, X o F. Los clientes siguen excluidos del acceso comercial genérico.
    • X · acceso entre cuentas: JWT de titular real, cuenta habilitada y contraseña completada. Propiedad y consentimiento se comprueban de nuevo; ser administrador no autoriza copiar la llave principal ajena.
    • F · finanzas de bolsa: JWT del titular o empleado activo con la facultad específica. Rechaza toda appKey y sesión de cliente.
    • Público: código, token de invitación/restablecimiento o ID opaco de pago, según la ruta. Conocer un ID no da acceso a los datos privados del titular.

    Los cuatro permisos financieros son independientes: commercial_credit_monitor de lectura, commercial_credit_purchase y commercial_credit_allocate de escritura, y commercial_credit_configure de lectura/escritura. Tener uno no concede los demás. Consulta capabilities y valida el resultado de cada operación.

    No hay un bloqueo global de plan activo para estas rutas: se debe poder consultar y pagar una deuda vencida. Aun así, comprar o asignar créditos exige los estados y la elegibilidad que valida el servicio.

    Las respuestas de error tienen forma {"error":"CODE","message":"…"}, sin data. Usa el código y el HTTP status; el mensaje puede cambiar. Los ejemplos de este documento son datos demo y nunca ejecutan solicitudes al leerlos o copiarlos.

    Cuentas, códigos e invitaciones

    Un subafiliado tiene su propia cuenta. Los clientes normales que operan bajo el titular son otra entidad: consulta Clientes y límites B2B2B para ese alcance.

    En móvil puedes desplazar la tabla. «Directo» indica JSON sin envoltorio data.

    Método y rutaAutorización y alcanceRespuesta
    GET/v1/subaffiliations/overview
    Entrada y notas

    query.month?

    Filtra datos por capacidades. No hay endpoint GET /relationships o GET /invoices separado; overview devuelve arrays. No paginado.

    JWT o appKey según permisos; clientes rechazados; empleado sólo con permiso y alcance

    Lectura de subaffiliations, subaffiliation_billing, subaffiliation_commissions o subaffiliation_integrations; también acceso financiero mínimo

    HTTP 200Directo
    GET/v1/subaffiliations/referral-settings
    Entrada y notas

    Sin cuerpo JSON.

    Puede materializar por primera vez el código general. Incluye global_code, revision, allowed_modes y opciones de precio.

    JWT del titular; rechaza empleado, cliente y appKey

    subaffiliations: lectura

    HTTP 200{account}
    PUT/v1/subaffiliations/referral-settings
    Entrada y notas

    default_payer, default_benefit, referral_default_plan_id?, plan_pricing?

    Este DTO NO admite expected_revision. Afecta ofertas futuras, no acuerdos aceptados.

    JWT del titular; rechaza empleado, cliente y appKey

    subaffiliations: escritura

    HTTP 200{account}
    GET/v1/subaffiliations/referral-code/availability
    Entrada y notas

    query.code

    Normaliza minúsculas/trim. Disponibilidad no reserva; PUT realiza CAS atómico.

    JWT del titular; rechaza empleado, cliente y appKey

    subaffiliations: lectura

    HTTP 200Directo
    PUT/v1/subaffiliations/referral-code
    Entrada y notas

    code, expected_revision

    Código 4..64 ASCII a-z,0-9,guion y guion bajo. Conserva aliases anteriores; misma clave actual puede devolverse sin nuevo cambio.

    JWT del titular; rechaza empleado, cliente y appKey

    subaffiliations: escritura

    HTTP 200{account}
    POST/v1/subaffiliations/referral-codes
    Entrada y notas

    request_id, payer?, benefit?, plan_id?

    Código de un uso, expira en 7d. Omisiones usan defaults de cuenta. Misma request_id recupera el mismo código; no cambia configuración general.

    JWT del titular; rechaza empleado, cliente y appKey

    subaffiliations: escritura

    HTTP 201Directo
    GET/v1/subaffiliations/referrals/:code
    Entrada y notas

    path.code, query.plan_id?

    Devuelve oferta y quote_token; el registro lo envía como expected_review_token. Preview no consume código de un uso.

    Público por código o token de capacidad específico

    Sin credencial; conoce código general, alias o de un uso

    HTTP 200Directo
    POST/users
    Entrada y notas

    affiliate_code, plan_id, expected_review_token, accept_referral_terms, consent_primary_key?, full_name, company_name?, email, password, phone_country_code, phone_number, dni?, consent_policy_version

    Sin payer/benefit de cliente: se resuelven desde el código. Username derivado del teléfono. Contraseña 8..1024. Devuelve default_user_api_key sensible; cuenta self-pay no queda pagada por registrarse. Identificación opcional única dni:{code,number}. La política primary_key_consent_policy del preview indica el requisito: sponsor exige autorización explícita y consent_policy_version payer_rules_v1; member mantiene la elección opcional.

    Público; crea la propia cuenta con código aceptado

    Sin credencial; no combinar onboarding_id

    HTTP 201Directo
    POST/v1/subaffiliations/invitations
    Entrada y notas

    request_id, full_name, company_name, email, phone_country_code, phone_number, plan_id, payer, benefit, integration_permissions?, dni?

    Sin contraseña del invitado; username de entrada se sustituye por teléfono. Nueva respuesta invitation_url; replay puede devolver reused sin token. request_id estable 8..200.

    JWT del titular; rechaza empleado, cliente y appKey

    subaffiliations: escritura

    HTTP 201Directo
    GET/v1/subaffiliations/invitations/:token
    Entrada y notas

    path.token

    Contiene datos del invitado y quote_token. No es un buscador por email ni por ID de usuario. Expira en 7d.

    Público por código o token de capacidad específico

    Token opaco del correo de invitación

    HTTP 200Directo
    POST/v1/subaffiliations/invitations/:token/accept
    Entrada y notas

    path.token, quote_token, password, phone?, consent_integration, consent_primary_key, accept_terms, consent_policy_version

    El destinatario revisa el quote_token vigente y confirma accept_terms:true y consent_policy_version:payer_rules_v1. consent_primary_key es opcional si paga el miembro y obligatorio si financia la empresa. Crear la invitación no concede acceso; aceptar no verifica un pago.

    Público por código o token de capacidad específico

    Token opaco del correo; contraseña propia del invitado

    HTTP 200Directo
    POST/v1/subaffiliations/invitations/:id/resend
    Entrada y notas

    path.id

    Rota token y vence el enlace anterior; devuelve invitation, invitation_url, email_sent.

    JWT o appKey según permisos; clientes rechazados; empleado sólo con permiso y alcance

    subaffiliations: escritura; padre propietario de invitación o PlatformOwner

    HTTP 200Directo
    DELETE/v1/subaffiliations/invitations/:id
    Entrada y notas

    path.id

    Cancela pendiente; repetir cancelada es idempotente. Aceptada no puede cancelarse.

    JWT o appKey según permisos; clientes rechazados; empleado sólo con permiso y alcance

    subaffiliations: escritura; padre propietario o PlatformOwner

    HTTP 200{message}
    POST/v1/subaffiliations/relationships/:id/password-reset
    Entrada y notas

    path.id, request_id

    Sólo correo guardado del hijo; no acepta destinatario. 202 queued no confirma entrega; cooldown 60s, reset 1h.

    JWT titular real; cuenta completada; rechaza empleado, cliente y appKey

    subaffiliations: escritura; padre activo, hijo con contraseña ya completada

    HTTP 202Directo
    POST/v1/subaffiliations/invitations/:id/password-setup-email
    Entrada y notas

    path.id, request_id

    Reenvía acceso a primera contraseña (7d). request_id 1..128 tras trim; respuesta status/kind/email_masked.

    JWT titular real; cuenta completada; rechaza empleado, cliente y appKey

    subaffiliations: escritura; padre de invitación pendiente

    HTTP 202Directo
    GET/v1/subaffiliations/password-resets/:token
    Entrada y notas

    path.token

    Sólo company_name,email_masked,expires_at. Token sensible, no adivinar rutas por user_id.

    Público por código o token de capacidad específico

    Token específico del correo de restablecimiento

    HTTP 200Directo
    POST/v1/subaffiliations/password-resets/:token
    Entrada y notas

    path.token, password, confirm_password

    Actualizar contraseña no inicia sesión; entrar de nuevo. No exponer contraseña en logs.

    Público por código o token de capacidad específico

    Mismo token válido

    HTTP 200{message}

    Código general y preferencias

    Obtén account.global_code con GET /v1/subaffiliations/referral-settings. No existe un GET de /referral-code. La primera consulta puede materializar el primer código general duradero. Puedes construir el enlace web https://pabilo.app/register?affiliateCode=CODIGO.

    La disponibilidad de un código es orientativa. El PUT reserva de forma atómica el código normalizado con expected_revision: de 4 a 64 caracteres ASCII a–z, 0–9, guion o guion bajo, en minúsculas. Los códigos generales anteriores quedan como alias. Un código de un solo uso dura siete días y sólo se consume al confirmar el registro, no al consultar su preview; no cambia las preferencias globales.

    PUT referral-settings no acepta expected_revision en su DTO actual. En cambio, cambiar el código y guardar plan-pricing sí requieren la revisión de la cuenta. Cada operación indica su campo de revisión correspondiente.

    Registro y aceptación

    1. Consulta GET /v1/subaffiliations/referrals/:code con el plan elegido y revisa precio, pagador y prestaciones.
    2. Para registrar con código, envía el quote_token de ese preview como expected_review_token a POST /users, junto con affiliate_code, el plan y la aceptación expresa. No envíes payer/benefit ni lo combines con onboarding_id.
    3. Para invitación manual, el titular envía nombre, empresa, correo y teléfono con país. El usuario se genera a partir del teléfono; el cliente elige su propia contraseña.
    4. El invitado abre el token recibido, revisa el nuevo quote_token y acepta con su propia contraseña y sus decisiones de consentimiento. Una cuenta existente confirma su contraseña; el afiliador no la reemplaza.

    El registro admite contraseña de 8 a 1024 caracteres, nombre de 1 a 200, empresa de hasta 200 y correo válido de hasta 254; el teléfono se normaliza en el servidor. La invitación manual vence a los siete días y reenviarla invalida el enlace anterior. Un replay de creación puede devolver reused:true sin URL ni token. Para obtener otro enlace, usa el reenvío autorizado, que rota e invalida el anterior.

    La respuesta de registro contiene default_user_api_key, que es un secreto del usuario creado: no publiques ni registres su valor real. Completar registro o contraseña no paga un plan self-pay de importe positivo ni concede servicio de pago antes del pago requerido.

    Los datos de registro e invitación admiten una identificación opcional dni: {code:"V",number:"12345678"}: cédula (V/E), RIF (J/G) o pasaporte (P). Se conserva en la cuenta nueva. Afiliar una cuenta existente no cambia su identificación. El titular puede actualizarla o borrarla desde su perfil; las sesiones delegadas no pueden editar ese dato.

    Los previews incluyen primary_key_consent_policy con version, required, default_checked y scope. El flujo actualizado confirma consent_policy_version: payer_rules_v1 y la aceptación explícita de las condiciones. Si paga la empresa, consent_primary_key debe ser true; si paga el cliente es opcional. Usa el token vigente y vuelve a revisar si cambia la cotización.

    Encontrar factura, saldo y revisión antes del checkout

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    GET /v1/subaffiliations/overview
    curl --request GET 'https://api.pabilo.app/v1/subaffiliations/overview?month=2026-11' \
      --header 'Authorization: Bearer JWT_DEL_TITULAR'
    Respuesta HTTP 200 · extracto
    {
      "invoices": [
        {
          "id": "000000000000000000000301",
          "month": "2026-11",
          "status": "open",
          "total_cents": 7600,
          "paid_cents": 0,
          "credit_cents": 0,
          "balance_cents": 7600,
          "revision": 1
        }
      ],
      "capabilities": {
        "view_billing": true,
        "pay_invoices": true
      }
    }

    El extracto conserva el envoltorio y los campos relevantes; no enumera todos los campos de la respuesta.

    Código general y condiciones vigentes

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    GET /v1/subaffiliations/referral-settings
    curl --request GET 'https://api.pabilo.app/v1/subaffiliations/referral-settings' \
      --header 'Authorization: Bearer JWT_DEL_TITULAR'
    Respuesta HTTP 200 · extracto
    {
      "account": {
        "id": "000000000000000000000110",
        "user_id": "000000000000000000000100",
        "global_code": "empresa-demo",
        "revision": 2,
        "enabled": true,
        "sponsor_enabled": false,
        "default_payer": "member",
        "default_benefit": "commission",
        "allowed_modes": [
          {
            "payer": "member",
            "benefit": "discount"
          },
          {
            "payer": "member",
            "benefit": "commission"
          }
        ]
      }
    }

    El extracto conserva el envoltorio y los campos relevantes; no enumera todos los campos de la respuesta.

    Cambiar código conservando aliases

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    PUT /v1/subaffiliations/referral-code
    curl --request PUT 'https://api.pabilo.app/v1/subaffiliations/referral-code' \
      --header 'Authorization: Bearer JWT_DEL_TITULAR' \
      --header 'Content-Type: application/json' \
      --data-raw '{"code":"empresa-demo-nuevo","expected_revision":2}'
    Cuerpo JSON de la solicitud
    {
      "code": "empresa-demo-nuevo",
      "expected_revision": 2
    }
    Respuesta HTTP 200 · extracto
    {
      "account": {
        "global_code": "empresa-demo-nuevo",
        "revision": 3
      }
    }

    El extracto conserva el envoltorio y los campos relevantes; no enumera todos los campos de la respuesta.

    Una invitación con modo distinto al global

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    POST /v1/subaffiliations/referral-codes
    curl --request POST 'https://api.pabilo.app/v1/subaffiliations/referral-codes' \
      --header 'Authorization: Bearer JWT_DEL_TITULAR' \
      --header 'Content-Type: application/json' \
      --data-raw '{"request_id":"demo-one-use-001","payer":"member","benefit":"discount","plan_id":"000000000000000000000030"}'
    Cuerpo JSON de la solicitud
    {
      "request_id": "demo-one-use-001",
      "payer": "member",
      "benefit": "discount",
      "plan_id": "000000000000000000000030"
    }
    Respuesta HTTP 201
    {
      "code": "pa-once-demo-no-utilizar",
      "url": "https://pabilo.app/register?affiliateCode=pa-once-demo-no-utilizar",
      "registration_url": "https://pabilo.app/register?affiliateCode=pa-once-demo-no-utilizar",
      "expires_at": "2026-11-22T16:00:00Z",
      "payer": "member",
      "benefit": "discount",
      "plan_id": "000000000000000000000030",
      "single_use": true,
      "consumed": false
    }
    Revisar oferta antes del registro

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    GET /v1/subaffiliations/referrals/:code
    curl --request GET 'https://api.pabilo.app/v1/subaffiliations/referrals/empresa-demo-nuevo?plan_id=000000000000000000000030'
    Respuesta HTTP 200 · extracto
    {
      "company": {
        "name": "Empresa Demo"
      },
      "account": {
        "default_payer": "member",
        "default_benefit": "commission",
        "referral_default_plan_id": "000000000000000000000030"
      },
      "quote": {
        "payer": "member",
        "benefit": "commission",
        "list_cents": 3000,
        "margin_cents": 1500,
        "discount_cents": 500,
        "amount_cents": 2500,
        "commission_cents": 1000,
        "platform_cents": 1500
      },
      "quote_token": "cq1.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "single_use": false,
      "primary_key_consent_policy": {
        "version": "payer_rules_v1",
        "required": false,
        "default_checked": false,
        "scope": "primary_api_key_and_masked_banks"
      }
    }

    El extracto conserva el envoltorio y los campos relevantes; no enumera todos los campos de la respuesta.

    Registrar la propia cuenta con condiciones revisadas

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    POST /users
    curl --request POST 'https://api.pabilo.app/users' \
      --header 'Content-Type: application/json' \
      --data-raw '{"affiliate_code":"empresa-demo-nuevo","plan_id":"000000000000000000000030","expected_review_token":"cq1.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","accept_referral_terms":true,"consent_primary_key":false,"full_name":"Persona Demo","company_name":"Comercio Demo","email":"[email protected]","password":"CLAVE_DEMO_NO_UTILIZAR","phone_country_code":"58","phone_number":"4120000001","dni":{"code":"V","number":"12345678"},"consent_policy_version":"payer_rules_v1"}'
    Cuerpo JSON de la solicitud
    {
      "affiliate_code": "empresa-demo-nuevo",
      "plan_id": "000000000000000000000030",
      "expected_review_token": "cq1.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "accept_referral_terms": true,
      "consent_primary_key": false,
      "full_name": "Persona Demo",
      "company_name": "Comercio Demo",
      "email": "[email protected]",
      "password": "CLAVE_DEMO_NO_UTILIZAR",
      "phone_country_code": "58",
      "phone_number": "4120000001",
      "dni": {
        "code": "V",
        "number": "12345678"
      },
      "consent_policy_version": "payer_rules_v1"
    }
    Respuesta HTTP 201 · extracto
    {
      "message": "Cuenta creada y afiliada correctamente",
      "user": {
        "id": "000000000000000000000101",
        "plan_is_active": false
      },
      "relationship_id": "000000000000000000000201"
    }

    El extracto conserva el envoltorio y los campos relevantes; no enumera todos los campos de la respuesta.

    Invitar por correo sin elegir contraseña del cliente

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    POST /v1/subaffiliations/invitations
    curl --request POST 'https://api.pabilo.app/v1/subaffiliations/invitations' \
      --header 'Authorization: Bearer JWT_DEL_TITULAR' \
      --header 'Content-Type: application/json' \
      --data-raw '{"request_id":"demo-invite-001","full_name":"Persona Demo","company_name":"Comercio Demo","email":"[email protected]","phone_country_code":"58","phone_number":"4120000001","plan_id":"000000000000000000000030","payer":"member","benefit":"commission","dni":{"code":"V","number":"12345678"}}'
    Cuerpo JSON de la solicitud
    {
      "request_id": "demo-invite-001",
      "full_name": "Persona Demo",
      "company_name": "Comercio Demo",
      "email": "[email protected]",
      "phone_country_code": "58",
      "phone_number": "4120000001",
      "plan_id": "000000000000000000000030",
      "payer": "member",
      "benefit": "commission",
      "dni": {
        "code": "V",
        "number": "12345678"
      }
    }
    Respuesta HTTP 201 · extracto
    {
      "invitation": {
        "id": "000000000000000000000202",
        "status": "pending",
        "email": "[email protected]",
        "username": "584120000001",
        "expires_at": "2026-11-22T16:00:00Z"
      },
      "invitation_url": "https://pabilo.app/afiliado/BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
      "email_sent": true
    }

    El extracto conserva el envoltorio y los campos relevantes; no enumera todos los campos de la respuesta.

    El invitado revisa condiciones antes de su primera contraseña

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    GET /v1/subaffiliations/invitations/:token
    curl --request GET 'https://api.pabilo.app/v1/subaffiliations/invitations/BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB'
    Respuesta HTTP 200 · extracto
    {
      "full_name": "Persona Demo",
      "email": "[email protected]",
      "username": "584120000001",
      "phone_country_code": "58",
      "phone_number": "4120000001",
      "password_unset": true,
      "company_name": "Comercio Demo",
      "parent_name": "Empresa Demo",
      "plan_name": "Pro",
      "payer": "member",
      "benefit": "commission",
      "existing_account": false,
      "integration_scope": "general",
      "quote_token": "cq1.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "amount_cents": 2500,
      "quote": {
        "amount_cents": 2500,
        "discount_cents": 500,
        "commission_cents": 1000
      },
      "primary_key_consent_policy": {
        "version": "payer_rules_v1",
        "required": false,
        "default_checked": false,
        "scope": "primary_api_key_and_masked_banks"
      }
    }

    El extracto conserva el envoltorio y los campos relevantes; no enumera todos los campos de la respuesta.

    El propio invitado completa el registro

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    POST /v1/subaffiliations/invitations/:token/accept
    curl --request POST 'https://api.pabilo.app/v1/subaffiliations/invitations/BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB/accept' \
      --header 'Content-Type: application/json' \
      --data-raw '{"quote_token":"cq1.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","password":"CLAVE_DEMO_NO_UTILIZAR","phone":"04120000001","consent_integration":false,"consent_primary_key":false,"accept_terms":true,"consent_policy_version":"payer_rules_v1"}'
    Cuerpo JSON de la solicitud
    {
      "quote_token": "cq1.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "password": "CLAVE_DEMO_NO_UTILIZAR",
      "phone": "04120000001",
      "consent_integration": false,
      "consent_primary_key": false,
      "accept_terms": true,
      "consent_policy_version": "payer_rules_v1"
    }
    Respuesta HTTP 200
    {
      "relationship_id": "000000000000000000000201",
      "user_id": "000000000000000000000101",
      "message": "Cuenta vinculada; inicia sesión con tus credenciales."
    }
    Solicitar correo al destino guardado del cliente

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    POST /v1/subaffiliations/relationships/:id/password-reset
    curl --request POST 'https://api.pabilo.app/v1/subaffiliations/relationships/000000000000000000000201/password-reset' \
      --header 'Authorization: Bearer JWT_DEL_TITULAR' \
      --header 'Content-Type: application/json' \
      --data-raw '{"request_id":"demo-reset-001"}'
    Cuerpo JSON de la solicitud
    {
      "request_id": "demo-reset-001"
    }
    Respuesta HTTP 202
    {
      "status": "queued",
      "kind": "password_reset",
      "email_masked": "c***@example.invalid"
    }

    Precios por modalidad y condiciones aceptadas

    Las combinaciones válidas son {"payer":"member","benefit":"commission"}, {"payer":"member","benefit":"discount"} y {"payer":"sponsor","benefit":"discount"}. Sponsor con commission es inválido. Los dos modos self-pay están disponibles por defecto para titulares elegibles; financiar al cliente requiere aprobación expresa.

    Consulta plan_pricing_options_by_mode para la modalidad seleccionada. Una lista vacía significa que esa cuenta no tiene planes autorizados y elegibles para esa modalidad. Los planes omitidos o deshabilitados en su selección particular no hacen fallback a la política general ni al margen de otro modo. El array plan_pricing_options corresponde al modo predeterminado. Las condiciones de administradores y la atribución interna de Owner pueden ser distintas de las de una empresa.

    El beneficio depende de la cuenta, el plan o servicio, la modalidad y la vigencia; 15 USD no es un beneficio universal. El comercio declara sólo discount_cents por plan dentro del margen autorizado. En un ejemplo aprobado de empresa con lista 3000, margen 1500 y descuento 500 centavos: el cliente paga 2500, la comisión es 1000 y el neto de Pabilo 1500. El descuento completo deja comisión cero. El precio final y las prestaciones los determina la oferta revisada. Utiliza esa oferta vigente; los contratos aceptados conservan sus condiciones. Cuando una cotización de cambio de plan devuelve quote_token, reenvíalo al confirmar aunque el importe final del cliente no haya cambiado: puede haber cambiado el reparto o la autorización revisada.

    En móvil puedes desplazar la tabla. «Directo» indica JSON sin envoltorio data.

    Método y rutaAutorización y alcanceRespuesta
    PUT/v1/subaffiliations/plan-pricing
    Entrada y notas

    expected_revision, plan_pricing[].plan_id, plan_pricing[].discount_cents

    Sólo reparte margen autorizado por plan, no define precio base o margen. Revisión stale: CREDIT_OPERATION_CONFLICT.

    JWT del titular; rechaza empleado, cliente y appKey

    subaffiliations: escritura

    HTTP 200{account}
    Reparto company aprobado: Pro30, margen15, descuento5

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    PUT /v1/subaffiliations/plan-pricing
    curl --request PUT 'https://api.pabilo.app/v1/subaffiliations/plan-pricing' \
      --header 'Authorization: Bearer JWT_DEL_TITULAR' \
      --header 'Content-Type: application/json' \
      --data-raw '{"expected_revision":3,"plan_pricing":[{"plan_id":"000000000000000000000030","discount_cents":500}]}'
    Cuerpo JSON de la solicitud
    {
      "expected_revision": 3,
      "plan_pricing": [
        {
          "plan_id": "000000000000000000000030",
          "discount_cents": 500
        }
      ]
    }
    Respuesta HTTP 200 · extracto
    {
      "account": {
        "revision": 4,
        "plan_pricing": [
          {
            "plan_id": "000000000000000000000030",
            "discount_cents": 500
          }
        ],
        "plan_pricing_options": [
          {
            "plan_id": "000000000000000000000030",
            "plan_name": "Pro",
            "list_cents": 3000,
            "margin_cents": 1500,
            "discount_cents": 500,
            "commission_cents": 1000,
            "billing_months": 1
          }
        ]
      }
    }

    El extracto conserva el envoltorio y los campos relevantes; no enumera todos los campos de la respuesta.

    Relaciones, monitoreo y opciones del cliente

    overview incluye arrays de relaciones, invitaciones, facturas, pagos, comisiones y liquidaciones filtrados por permisos. Las colecciones de relaciones y facturas se consultan en ese resumen. Con sólo facultades financieras, el resumen no entrega identidades de hijos ni información comercial ajena.

    Para cambiar una relación, solicita un preview, muestra fecha e importes y confirma el mismo input con su quote_token. El cambio se programa y conserva condiciones históricas. El miembro puede finalizar su propia relación; no puede elegir condiciones económicas de su afiliador.

    En móvil puedes desplazar la tabla. «Directo» indica JSON sin envoltorio data.

    Método y rutaAutorización y alcanceRespuesta
    POST/v1/subaffiliations/relationships/:id/preview
    Entrada y notas

    path.id, request_id, payer, benefit, plan_id, end

    Devuelve current_quote/proposed_quote/prorrateo/fecha y quote_token del mismo cambio.

    JWT del titular; rechaza empleado, cliente y appKey

    subaffiliations: escritura; padre o PlatformOwner, miembro sólo end=true

    HTTP 200Directo
    PUT/v1/subaffiliations/relationships/:id
    Entrada y notas

    path.id, request_id, quote_token, payer, benefit, plan_id, end

    Mismo snapshot/request; programa pending_change sin reescribir retroactivo. Nueva cotización si COMMERCIAL_QUOTE_CHANGED.

    JWT del titular; rechaza empleado, cliente y appKey

    subaffiliations: escritura; mismo alcance que preview

    HTTP 200{relationship}
    POST/v1/subaffiliations/relationships/:id/integration-key
    Entrada y notas

    path.id

    Devuelve objeto ApiKey en api_key. Es llave delegada con permisos, diferente de principal. Relación activa y consentimiento.

    JWT o appKey según permisos; clientes rechazados; empleado sólo con permiso y alcance

    subaffiliation_integrations: escritura; padre/miembro/PlatformOwner y consentimiento vigente

    HTTP 200{api_key}
    DELETE/v1/subaffiliations/relationships/:id/integration-key
    Entrada y notas

    path.id

    Revoca integración delegada; no implica rotar la llave principal independiente.

    JWT o appKey según permisos; clientes rechazados; empleado sólo con permiso y alcance

    subaffiliation_integrations: escritura; padre/miembro/PlatformOwner

    HTTP 200{message}
    GET/v1/subaffiliations/relationships/:id/primary-api-key
    Entrada y notas

    path.id

    Secreto real. No logs/URL públicas; ser Admin no permite saltar propiedad. GET registra auditoría y CAS de relación.

    JWT titular real; cuenta completada; rechaza empleado, cliente y appKey

    Padre de relación activa; consentimiento específico principal_v1 del miembro

    HTTP 200Directo
    GET/v1/subaffiliations/relationships/:id/user-banks
    Entrada y notas

    path.id

    IDs de conexión y números enmascarados; sin credenciales ni metadata bancaria completa. GET registra auditoría.

    JWT titular real; cuenta completada; rechaza empleado, cliente y appKey

    Mismo padre y consentimiento principal_v1; ambas cuentas completadas

    HTTP 200Directo

    Llave delegada, llave principal y bancos

    integration-key emite una credencial delegada y devuelve un objeto en api_key; no presupongas que es un string. Consultar la llave principal requiere otro consentimiento específico principal_v1 y una relación activa del padre autorizado. El PUT de consentimiento lo hace el titular miembro con su JWT, no el padre.

    La consulta de bancos entrega identificadores User Bank ID y cuentas enmascaradas; no credenciales ni metadatos bancarios completos. Revocar el consentimiento impide consultas futuras, pero no invalida copias de la llave principal: el titular debe rotarla en Integraciones. No pongas llaves en URLs, logs ni en el frontend público.

    Las solicitudes de contraseña sólo van al correo persistido del titular; no aceptan un destino arbitrario. El HTTP 202 con status:"queued" confirma cola, no entrega. Esta familia usa request_id de 1 a 128 caracteres tras trim, cooldown de 60 segundos, reset de una hora y setup de siete días.

    El monitoreo pagina por cursor y devuelve campos numéricos que pueden ser null. Para operaciones de bolsa, limit va de 1 a 100 (por defecto 50), kind es purchase o allocation y month usa YYYY-MM. Usage admite hasta 100 por página (por defecto 100); all=true requiere Owner de plataforma sin empleado. Ambos usan cursor ObjectID de 24 hexadecimales. Conserva status, reason, credit_model y unlimited: desconocido o ilimitado no significa saldo cero. Los campos de disponibilidad son autoritativos para su propósito; in-flight no se añade a total_available.

    El propio miembro puede revisar GET /v1/subaffiliations/relationships/:id/primary-key-consent y aceptar el requisito de acceso antes de que la empresa empiece a financiarlo. El PUT usa enabled:true, accept_sponsor_requirement:true, policy_version y el quote_token recibido. El permiso opcional anterior no implica aceptar esas condiciones de financiación. Los acuerdos existentes conservan sus autorizaciones; el afiliador no puede conceder consentimiento en nombre del cliente.

    Copiar la llave principal después del consentimiento específico

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    GET /v1/subaffiliations/relationships/:id/primary-api-key
    curl --request GET 'https://api.pabilo.app/v1/subaffiliations/relationships/000000000000000000000201/primary-api-key' \
      --header 'Authorization: Bearer JWT_DEL_TITULAR'
    Respuesta HTTP 200
    {
      "relationship_id": "000000000000000000000201",
      "member_user_id": "000000000000000000000101",
      "key_id": "000000000000000000000901",
      "api_key": "API_KEY_PRINCIPAL_DEMO_NO_UTILIZAR",
      "kind": "primary"
    }
    El miembro autoriza una llave delegada independiente de la principal

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    POST /v1/subaffiliations/relationships/:id/integration-key
    curl --request POST 'https://api.pabilo.app/v1/subaffiliations/relationships/000000000000000000000201/integration-key' \
      --header 'Authorization: Bearer JWT_DEL_SUBAFILIADO' \
      --header 'Content-Type: application/json' \
      --data-raw '{}'
    Cuerpo JSON de la solicitud
    {}
    Respuesta HTTP 200 · extracto
    {
      "api_key": {
        "id": "000000000000000000000902",
        "name": "Integración de empresa afiliadora",
        "api_key": "API_KEY_DELEGADA_DEMO_NO_UTILIZAR",
        "user_id": "000000000000000000000101",
        "default": false,
        "is_active": true,
        "commercial_relationship_id": "000000000000000000000201"
      }
    }

    El extracto conserva el envoltorio y los campos relevantes; no enumera todos los campos de la respuesta.

    Consentimiento específico del subafiliado

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    PUT /v1/subaffiliations/relationships/:id/primary-key-consent
    curl --request PUT 'https://api.pabilo.app/v1/subaffiliations/relationships/000000000000000000000201/primary-key-consent' \
      --header 'Authorization: Bearer JWT_DEL_SUBAFILIADO' \
      --header 'Content-Type: application/json' \
      --data-raw '{"enabled":true}'
    Cuerpo JSON de la solicitud
    {
      "enabled": true
    }
    Respuesta HTTP 200
    {
      "relationship_id": "000000000000000000000201",
      "primary_key_consent": true,
      "primary_key_consent_at": "2026-11-15T16:00:00Z",
      "primary_key_consent_required": false,
      "primary_key_consent_version": "principal_v1"
    }
    Consultar IDs de conexión sin credenciales

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    GET /v1/subaffiliations/relationships/:id/user-banks
    curl --request GET 'https://api.pabilo.app/v1/subaffiliations/relationships/000000000000000000000201/user-banks' \
      --header 'Authorization: Bearer JWT_DEL_TITULAR'
    Respuesta HTTP 200 · extracto
    {
      "relationship_id": "000000000000000000000201",
      "member_user_id": "000000000000000000000101",
      "user_banks": [
        {
          "id": "000000000000000000000801",
          "user_bank_id": "000000000000000000000801",
          "description": "Banco de demostración",
          "accounts": [
            {
              "last_four": "0000",
              "masked_account_number": "••••0000",
              "account_type": "CORRIENTE"
            }
          ]
        }
      ]
    }

    El extracto conserva el envoltorio y los campos relevantes; no enumera todos los campos de la respuesta.

    Revisar la autorización requerida antes de financiar

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    GET /v1/subaffiliations/relationships/:id/primary-key-consent
    curl --request GET 'https://api.pabilo.app/v1/subaffiliations/relationships/000000000000000000000201/primary-key-consent' \
      --header 'Authorization: Bearer JWT_DEL_SUBAFILIADO'
    Respuesta HTTP 200
    {
      "relationship_id": "000000000000000000000201",
      "parent_user_id": "000000000000000000000001",
      "parent_name": "Empresa Demo",
      "primary_key_consent_policy": {
        "version": "payer_rules_v1",
        "required": true,
        "default_checked": true,
        "scope": "primary_api_key_and_masked_banks"
      },
      "quote_token": "cq1.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
    Aceptar el requisito de acceso para financiación

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    PUT /v1/subaffiliations/relationships/:id/primary-key-consent
    curl --request PUT 'https://api.pabilo.app/v1/subaffiliations/relationships/000000000000000000000201/primary-key-consent' \
      --header 'Authorization: Bearer JWT_DEL_SUBAFILIADO' \
      --header 'Content-Type: application/json' \
      --data-raw '{"enabled":true,"accept_sponsor_requirement":true,"policy_version":"payer_rules_v1","quote_token":"cq1.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}'
    Cuerpo JSON de la solicitud
    {
      "enabled": true,
      "accept_sponsor_requirement": true,
      "policy_version": "payer_rules_v1",
      "quote_token": "cq1.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
    Respuesta HTTP 200
    {
      "relationship_id": "000000000000000000000201",
      "primary_key_consent": true,
      "primary_key_consent_at": "2026-11-15T16:00:00Z",
      "primary_key_consent_required": false,
      "primary_key_consent_version": "principal_v1",
      "primary_key_sponsor_policy_version": "payer_rules_v1",
      "primary_key_sponsor_policy_accepted_at": "2026-11-15T16:00:00Z"
    }

    Bolsa: cotizar, comprar y recuperar

    La bolsa es inventario de créditos. Comprometer una compra entrega stock y registra un cargo único en la factura global; no representa dinero ya cobrado. La compra requiere suscripción activa del comprador, permiso financiero y habilitación de compras de Pabilo.

    CampoUnidad y ejemplo
    quantity_creditsCréditos enteros: 1000 créditos.
    *_units100 unidades = 1 crédito; 100000 unidades = 1000 créditos.
    amount_centsCentavos USD: 6000 = 60 USD.
    wallet_afterEntero de unidades de crédito, no centavos ni objeto wallet.

    GET credit-pool separa purchase_authorized (permiso) de purchase (compra efectiva). Revisa purchase_status y purchase_blocked_reason: forbidden, policy_unavailable, policy_disabled, account_disabled o account_inactive. Una habilitación no activa automáticamente compras periódicas.

    En móvil puedes desplazar la tabla. «Directo» indica JSON sin envoltorio data.

    Método y rutaAutorización y alcanceRespuesta
    GET/v1/subaffiliations/credit-pool
    Entrada y notas

    Sin cuerpo JSON.

    Overview con wallet/policy/settings/budget/account_settings/capabilities/self_usage. purchase_authorized no equivale a purchase efectiva. Las cuentas Unlimited usan la bolsa para sus subafiliados Counter elegibles.

    JWT titular o empleado autorizado; rechaza cliente y toda appKey

    Cualquiera de los cuatro permisos financieros; cada capability independiente

    HTTP 200Directo
    GET/v1/subaffiliations/credit-pool/operations
    Entrada y notas

    query.limit?, query.cursor?, query.month?, query.kind?

    limit1..100 default50; cursor24hex; month YYYY-MM; kind purchase|allocation; {items,next_cursor}. Nunca sumar páginas para calcular saldo financiero autoritativo.

    JWT titular o empleado autorizado; rechaza cliente y toda appKey

    commercial_credit_monitor: lectura

    HTTP 200Directo
    GET/v1/subaffiliations/relationships/usage
    Entrada y notas

    query.limit?, query.cursor?, query.all?

    limit1..100 default100, cursor24hex. {items,next_cursor,as_of,credit_scale:100}; null no es cero, Unlimited no es agotado.

    JWT titular o empleado autorizado; rechaza cliente y toda appKey

    commercial_credit_monitor: lectura; all=true sólo PlatformOwner sin empleado

    HTTP 200Directo
    POST/v1/subaffiliations/credit-pool/purchase-quotes
    Entrada y notas

    quantity_credits, allocations[].target_user_id, allocations[].relationship_id?, allocations[].quantity_credits

    Cotización de 15 minutos; el servidor calcula unidades, precio, política, mes y wallet_after en unidades. Cotizar no compromete la compra. El modelo y los tramos de la versión vigente determinan el importe; el cliente sólo indica cantidad de créditos.

    JWT titular o empleado autorizado; rechaza cliente y toda appKey

    commercial_credit_purchase: escritura; además allocate si incluye asignaciones

    HTTP 200Directo
    POST/v1/subaffiliations/credit-pool/purchases
    Entrada y notas

    quote_token, operation_key

    Mismo key+token recupera commit antes de policy/expiry; conservar tras respuesta perdida. Compra y cargo único global son atómicos. Precio en operation.amount_cents; additional siempre0.

    JWT titular o empleado autorizado; rechaza cliente y toda appKey

    commercial_credit_purchase: escritura; allocate si quote lo necesita

    HTTP 200Directo
    1. Pide purchase-quotes con créditos enteros y, opcionalmente, destinatarios. Si incluyes asignaciones necesitas también permiso allocate.
    2. Revisa cantidad, costo, política, mes Caracas, vencimiento de 15 minutos y asignaciones; una cotización no compra ni reserva precio perpetuamente.
    3. Confirma con el quote_token recibido y un operation_key estable de 8 a 160 caracteres, sin espacios externos ni CR/LF/NUL.
    4. Comprueba operation.status:"committed" y conserva el recibo. Si pierdes la respuesta, repite el mismo key y token. No cambies de identidad para «reintentar».

    El replay de una compra comprometida se resuelve antes de exigir de nuevo política o vencimiento: puede recuperar su recibo aunque nuevas compras estén apagadas, si el actor sigue autorizado. Key con token distinto produce conflicto. Una intención nueva requiere cotización nueva.

    El costo comprometido está en operation.amount_cents. amount_cents_additional es actualmente siempre cero, también en una compra: no lo tomes como precio total ni sumes ambos campos. El wallet del recibo es una lectura del saldo actual, no el balance histórico congelado del commit.

    Con pricing_model:"volume_tiers_v1", pricing_tiers contiene tramos con amount_cents y quantity_credits. La política de referencia usa 200/500, 1200/1000, 3000/2000 y 5000/3000 (créditos/centavos USD), con compra mínima de 200 créditos y 500 centavos. El precio interpola linealmente entre tramos y, sobre 5.000 créditos, mantiene la proporción 3000/5000; redondea el importe al centavo más cercano, con empate hacia arriba. Por eso 10.000 créditos cotizan 6000 centavos. El body del cliente sigue indicando créditos enteros, no un presupuesto en dólares. Los tramos y límites pertenecen a una versión de política administrada por un Owner de Pabilo; la cotización del servidor es la autoridad. Las políticas históricas sin pricing_model conservan su cálculo anterior, y los recibos comprometidos conservan su precio original. El número de verificaciones por crédito varía según los costos de cada operación, las reservas, las cuotas y el modelo del plan.

    Bolsa del titular Unlimited que compra para hijos Counter

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    GET /v1/subaffiliations/credit-pool
    curl --request GET 'https://api.pabilo.app/v1/subaffiliations/credit-pool' \
      --header 'Authorization: Bearer JWT_DEL_TITULAR'
    Respuesta HTTP 200 · extracto
    {
      "purchase_status": "available",
      "purchase_blocked_reason": "",
      "uninvoiced_purchase_cents": 0,
      "wallet": {
        "user_id": "000000000000000000000100",
        "pool_available_units": 0,
        "pool_reserved_units": 0,
        "extra_available_units": 0,
        "extra_reserved_units": 0,
        "revision": 1
      },
      "capabilities": {
        "monitor": true,
        "purchase_authorized": true,
        "purchase": true,
        "allocate": true,
        "configure": true
      },
      "self_usage": {
        "user_id": "000000000000000000000100",
        "plan_id": "000000000000000000000030",
        "status": "unlimited",
        "eligible": false,
        "unlimited": true
      }
    }

    El extracto conserva el envoltorio y los campos relevantes; no enumera todos los campos de la respuesta.

    Cotizar 10 000 créditos: 1 000 000 unidades por 6000 centavos

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    POST /v1/subaffiliations/credit-pool/purchase-quotes
    curl --request POST 'https://api.pabilo.app/v1/subaffiliations/credit-pool/purchase-quotes' \
      --header 'Authorization: Bearer JWT_DEL_TITULAR' \
      --header 'Content-Type: application/json' \
      --data-raw '{"quantity_credits":10000,"allocations":[]}'
    Cuerpo JSON de la solicitud
    {
      "quantity_credits": 10000,
      "allocations": []
    }
    Respuesta HTTP 200
    {
      "quote_token": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "quote_id": "000000000000000000000701",
      "quantity_credits": 10000,
      "quantity_units": 1000000,
      "amount_cents": 6000,
      "currency": "USD",
      "policy_id": "000000000000000000000601",
      "policy_version": 2,
      "billing_month": "2026-11",
      "invoice_issue_at": "2026-12-01T04:00:00Z",
      "expires_at": "2026-11-15T16:15:00Z",
      "wallet_after": 1000000,
      "allocation_summary": []
    }
    Confirmar la compra una sola vez

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    POST /v1/subaffiliations/credit-pool/purchases
    curl --request POST 'https://api.pabilo.app/v1/subaffiliations/credit-pool/purchases' \
      --header 'Authorization: Bearer JWT_DEL_TITULAR' \
      --header 'Content-Type: application/json' \
      --data-raw '{"quote_token":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA","operation_key":"demo-purchase-001"}'
    Cuerpo JSON de la solicitud
    {
      "quote_token": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "operation_key": "demo-purchase-001"
    }
    Respuesta HTTP 200 · extracto
    {
      "operation": {
        "id": "000000000000000000000702",
        "kind": "purchase",
        "status": "committed",
        "operation_key": "demo-purchase-001",
        "quantity_credits": 10000,
        "quantity_units": 1000000,
        "amount_cents": 6000,
        "currency": "USD",
        "billing_month": "2026-11"
      },
      "wallet": {
        "user_id": "000000000000000000000100",
        "pool_available_units": 1000000
      },
      "allocations": [],
      "amount_cents_additional": 0
    }

    El extracto conserva el envoltorio y los campos relevantes; no enumera todos los campos de la respuesta.

    Respetar unidad, cuotas y números desconocidos

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    GET /v1/subaffiliations/relationships/usage
    curl --request GET 'https://api.pabilo.app/v1/subaffiliations/relationships/usage?limit=100' \
      --header 'Authorization: Bearer JWT_DEL_TITULAR'
    Respuesta HTTP 200 · extracto
    {
      "items": [
        {
          "relationship_id": "000000000000000000000201",
          "member_user_id": "000000000000000000000101",
          "status": "available",
          "as_of": "2026-11-15T16:00:00Z",
          "credit_scale": 100,
          "included_base_units": 20000,
          "included_remaining_units": 15000,
          "included_reserved_units": 0,
          "included_in_flight_units": 0,
          "extra_available_units": 50000,
          "extra_reserved_units": 0,
          "total_available_credit_units": 65000,
          "unlimited": false,
          "bank_connections_used": 1,
          "effective_bank_limit": 2
        }
      ],
      "next_cursor": "",
      "as_of": "2026-11-15T16:00:00Z",
      "credit_scale": 100
    }

    El extracto conserva el envoltorio y los campos relevantes; no enumera todos los campos de la respuesta.

    Asignar inventario sin otro cargo

    Una asignación mueve créditos ya comprados, con costo cero. Admite hasta 100 destinatarios sin duplicar usuarios; para la propia cuenta omite relationship_id, y para hijos usa su relación activa propia. La asignación manual no exige que la empresa pague la suscripción del hijo.

    Los destinatarios deben tener Counter activo, visible, finito y elegible por política. Los planes Unlimited, Admin y el saldo proporcional anterior no reciben estos extras. Un comprador Unlimited puede comprar para sus hijos elegibles, pero no asignarse extras propios. Deshabilitar compras nuevas no bloquea el reparto de stock existente si siguen cumpliéndose los demás requisitos.

    En móvil puedes desplazar la tabla. «Directo» indica JSON sin envoltorio data.

    Método y rutaAutorización y alcanceRespuesta
    POST/v1/subaffiliations/credit-pool/allocations
    Entrada y notas

    operation_key, allocations[].target_user_id, allocations[].relationship_id?, allocations[].quantity_credits

    Mueve stock ya comprado, coste0. Máx100 destinos únicos Counter elegibles activos; self sin relationship_id, otros relación propia. Extras no pagan/renuevan suscripción.

    JWT titular o empleado autorizado; rechaza cliente y toda appKey

    commercial_credit_allocate: escritura

    HTTP 200Directo

    Conserva operation_key y el mismo payload ante una respuesta perdida. El servidor calcula las unidades desde quantity_credits, que es la cantidad operativa de la asignación. Los extras sobreviven a renovaciones, pero no activan ni renuevan una suscripción.

    Asignar 500 créditos del stock sin recobrar

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    POST /v1/subaffiliations/credit-pool/allocations
    curl --request POST 'https://api.pabilo.app/v1/subaffiliations/credit-pool/allocations' \
      --header 'Authorization: Bearer JWT_DEL_TITULAR' \
      --header 'Content-Type: application/json' \
      --data-raw '{"operation_key":"demo-allocation-001","allocations":[{"target_user_id":"000000000000000000000101","relationship_id":"000000000000000000000201","quantity_credits":500}]}'
    Cuerpo JSON de la solicitud
    {
      "operation_key": "demo-allocation-001",
      "allocations": [
        {
          "target_user_id": "000000000000000000000101",
          "relationship_id": "000000000000000000000201",
          "quantity_credits": 500
        }
      ]
    }
    Respuesta HTTP 200 · extracto
    {
      "operation": {
        "id": "000000000000000000000703",
        "kind": "allocation",
        "status": "committed",
        "quantity_credits": 500,
        "quantity_units": 50000,
        "amount_cents": 0
      },
      "wallet": {
        "user_id": "000000000000000000000100",
        "pool_available_units": 950000
      },
      "allocations": [
        {
          "target_user_id": "000000000000000000000101",
          "relationship_id": "000000000000000000000201",
          "quantity_credits": 500,
          "quantity_units": 50000
        }
      ],
      "amount_cents_additional": 0
    }

    El extracto conserva el envoltorio y los campos relevantes; no enumera todos los campos de la respuesta.

    Autorrecarga, excepciones y presupuesto

    El PUT global es una configuración completa, no un patch parcial. Usa expected_revision, habilitación de autorrecarga, consentimiento separado de compra automática, cantidad fija, versión aceptada, precio máximo y tope mensual positivo. Las reglas individuales usan inherit, enabled o disabled con su propia revisión.

    En móvil puedes desplazar la tabla. «Directo» indica JSON sin envoltorio data.

    Método y rutaAutorización y alcanceRespuesta
    GET/v1/subaffiliations/credit-pool/automation
    Entrada y notas

    Sin cuerpo JSON.

    {settings,budget,capabilities}. Budget mes Caracas y gastos automáticos comprometidos, no pagos de factura.

    JWT titular o empleado autorizado; rechaza cliente y toda appKey

    commercial_credit_configure: lectura o escritura

    HTTP 200Directo
    PUT/v1/subaffiliations/credit-pool/automation
    Entrada y notas

    expected_revision, enabled, auto_purchase_enabled, purchase_quantity_credits, accepted_policy_version, max_purchase_cents, monthly_automatic_limit_cents

    Configuración completa. Auto compra requiere autorizaciones adicionales, aceptar política vigente, máximo por compra y presupuesto mensual.

    JWT titular o empleado autorizado; rechaza cliente y toda appKey

    commercial_credit_configure: escritura

    HTTP 200Directo
    POST/v1/subaffiliations/credit-pool/automation/preview
    Entrada y notas

    relationship_id

    Sólo calcula resultado, no dispara recarga/compra. Base incluida capturada, umbral<10%, grant20% a crédito entero, incluye reservas.

    JWT titular o empleado autorizado; rechaza cliente y toda appKey

    commercial_credit_configure: lectura o escritura; relación propia efectiva

    HTTP 200Directo
    GET/v1/subaffiliations/relationships/:id/credit-automation
    Entrada y notas

    path.id

    Resultado mode/effective_enabled/status/reason/unidades/revision, no settings global.

    JWT titular o empleado autorizado; rechaza cliente y toda appKey

    commercial_credit_configure: lectura o escritura; relación propia efectiva

    HTTP 200Directo
    PUT/v1/subaffiliations/relationships/:id/credit-automation
    Entrada y notas

    path.id, expected_revision, mode

    mode inherit|enabled|disabled. Autorrecarga ejecutable sólo en sponsor vigente Counter activo, no todas las relaciones.

    JWT titular o empleado autorizado; rechaza cliente y toda appKey

    commercial_credit_configure: escritura; relación propia efectiva

    HTTP 200Directo

    La regla atiende relaciones sponsor vigentes con Counter activo y elegible. Con base incluida del ciclo de 1000 créditos, quedan menos de 100 para disparar otra entrega de 200. El umbral es estrictamente menor de 10% y el 20% se redondea hacia arriba a créditos enteros: base 3 entrega 1. La base del primer ciclo puede ser prorrateada.

    El servidor contempla extras, reservas y base in-flight para no comprar por retenciones temporales. Si no conoce una base conciliada, pausa con un motivo. Usa el preview: no reconstruyas la decisión disparando compras desde un saldo parcial de la pantalla. El preview no ejecuta recargas y no hay un endpoint público para disparar el worker.

    La compra automática requiere habilitaciones de política/cuenta, consentimiento de la versión vigente y cantidad suficiente para el déficit. Se respeta el menor tope plataforma/cuenta/usuario y el máximo por compra. automatic_spent_cents consume presupuesto al comprometer la compra, aunque esté impaga; pagar su factura no restaura el tope del mes. Una nueva política requiere aceptación de nuevo para comprar, pero conserva el stock ya adquirido.

    Autorizar autoasignación y compra con límites distintos

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    PUT /v1/subaffiliations/credit-pool/automation
    curl --request PUT 'https://api.pabilo.app/v1/subaffiliations/credit-pool/automation' \
      --header 'Authorization: Bearer JWT_DEL_TITULAR' \
      --header 'Content-Type: application/json' \
      --data-raw '{"expected_revision":1,"enabled":true,"auto_purchase_enabled":true,"purchase_quantity_credits":2000,"accepted_policy_version":1,"max_purchase_cents":500,"monthly_automatic_limit_cents":2000}'
    Cuerpo JSON de la solicitud
    {
      "expected_revision": 1,
      "enabled": true,
      "auto_purchase_enabled": true,
      "purchase_quantity_credits": 2000,
      "accepted_policy_version": 1,
      "max_purchase_cents": 500,
      "monthly_automatic_limit_cents": 2000
    }
    Respuesta HTTP 200 · extracto
    {
      "settings": {
        "revision": 2,
        "enabled": true,
        "auto_purchase_enabled": true,
        "purchase_quantity_credits": 2000,
        "accepted_policy_version": 1,
        "max_purchase_cents": 500,
        "monthly_automatic_limit_cents": 2000
      },
      "budget": {
        "month": "2026-11",
        "automatic_spent_cents": 0,
        "effective_limit_cents": 2000,
        "remaining_cents": 2000
      },
      "capabilities": {
        "configure": true
      }
    }

    El extracto conserva el envoltorio y los campos relevantes; no enumera todos los campos de la respuesta.

    Anular herencia en una relación patrocinada

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    PUT /v1/subaffiliations/relationships/:id/credit-automation
    curl --request PUT 'https://api.pabilo.app/v1/subaffiliations/relationships/000000000000000000000201/credit-automation' \
      --header 'Authorization: Bearer JWT_DEL_TITULAR' \
      --header 'Content-Type: application/json' \
      --data-raw '{"expected_revision":1,"mode":"disabled"}'
    Cuerpo JSON de la solicitud
    {
      "expected_revision": 1,
      "mode": "disabled"
    }
    Respuesta HTTP 200 · extracto
    {
      "relationship_id": "000000000000000000000201",
      "mode": "disabled",
      "effective_enabled": false,
      "status": "disabled",
      "reason": "La autorrecarga está deshabilitada",
      "revision": 2
    }

    El extracto conserva el envoltorio y los campos relevantes; no enumera todos los campos de la respuesta.

    Simular una autorrecarga sin ejecutarla

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    POST /v1/subaffiliations/credit-pool/automation/preview
    curl --request POST 'https://api.pabilo.app/v1/subaffiliations/credit-pool/automation/preview' \
      --header 'Authorization: Bearer JWT_DEL_TITULAR' \
      --header 'Content-Type: application/json' \
      --data-raw '{"relationship_id":"000000000000000000000201"}'
    Cuerpo JSON de la solicitud
    {
      "relationship_id": "000000000000000000000201"
    }
    Respuesta HTTP 200
    {
      "relationship_id": "000000000000000000000201",
      "mode": "inherit",
      "effective_enabled": true,
      "status": "needs_topup",
      "reason": "El saldo está por debajo del 10% de la base incluida",
      "base_units": 20000,
      "threshold_units": 2000,
      "grant_units": 4000,
      "remaining_units": 1000,
      "purchase_quantity_credits": 0,
      "purchase_amount_cents": 0,
      "revision": 1
    }

    Factura global, checkout y aplicación del dinero

    Hay una factura global por empresa y mes, con corte día 1 en America/Caracas. Reúne servicio sponsor prorrateado por días reales y compras de bolsas completas, incluso sin hijos. El redondeo acumulado conserva la mensualidad exacta de un mes entero; los intervalos terminan en un until exclusivo. Devengo del mes abierto no equivale a factura emitida ni a efectivo cobrado.

    La renovación sponsor se registra a cargo de la empresa aunque su factura esté pendiente; el hijo financiado no paga personalmente esa renovación. Pagar una factura no renueva otra vez ni entrega créditos. El vencimiento usa due_days de la cuenta, no un plazo universal.

    En móvil puedes desplazar la tabla. «Directo» indica JSON sin envoltorio data.

    Método y rutaAutorización y alcanceRespuesta
    POST/v1/subaffiliations/invoices/:id/checkout
    Entrada y notas

    path.id, request_id, amount_cents, expected_revision

    Quote15min, USDcents, tasa/receptor congelados. request_id1..200; mismo cuerpo devuelve mismo enlace incluso vencido. No recibe dinero ni concede servicio.

    JWT del titular; rechaza empleado, cliente y appKey

    subaffiliation_billing: escritura; factura del propio deudor

    HTTP 200Directo
    GET/paymentlink/:id/info
    Entrada y notas

    path.id

    No lleva v1. Proyección mínima receptor/instrucciones/estado. Puede recuperar y aplicar recibo confirmado persistido sin consultar banco otra vez. can_pay debe ser true para iniciar.

    Público por ID opaco del checkout

    Sin JWT/appKey; no adivinar IDs

    HTTP 200{data}
    POST/v1/paymentlink/:paymentLinkId/pay
    Entrada y notas

    path.paymentLinkId, request_id, bank_reference?, dni_pagador?, phone_pagador?, bank_origin?, movement_type?, account_pagador?, fecha_pago?, otp?, invoice_number?

    Sólo 2xx si paid. Amount/banco/tasa/asignación servidor. Ante pending conservar enlace y comprobar estado; no repetir transferencia. Paid puede abonar parcialmente factura; excedente dinero disponible, no créditos.

    Público por mismo ID opaco

    Sin JWT/appKey; requisitos dinámicos del receptor

    HTTP 200{data}
    POST/v1/subaffiliations/payments
    Entrada y notas

    request_id, amount_cents, reference, payment_input, allocations[].invoice_id, allocations[].amount_cents

    Ruta autenticada legacy. Handler admite alias payment. Puede responder payment.verifying/uncertain en200: no asumir cobro. Para checkout con tasa congelada usar invoice-checkout.

    JWT o appKey según permisos; clientes rechazados; empleado sólo con permiso y alcance

    subaffiliation_billing: escritura; deudor actor propio

    HTTP 200{payment}
    POST/v1/subaffiliations/payments/:id/applications
    Entrada y notas

    path.id, request_id, allocations[].invoice_id, allocations[].amount_cents

    Aplica dinero disponible ya recibido a facturas del mismo deudor; no cobra ni genera stock. request_id estable por aplicación.

    JWT o appKey según permisos; clientes rechazados; empleado sólo con permiso y alcance

    subaffiliation_billing: escritura; deudor propio o PlatformOwner

    HTTP 200{payment}
    POST/v1/subaffiliations/payouts/:id/receive
    Entrada y notas

    path.id

    Sólo paid pasa a received; repetir received no repite efectivo.

    JWT o appKey según permisos; clientes rechazados; empleado sólo con permiso y alcance

    subaffiliation_commissions: lectura; beneficiario propio

    HTTP 200{message}
    1. Busca la factura propia en overview.invoices y toma saldo y revision actuales.
    2. El titular deudor prepara checkout con request_id, amount_cents positivo hasta el saldo y expected_revision. Rechaza empleado, cliente y appKey.
    3. Resuelve el checkout_url relativo contra https://pabilo.app. Conserva el ID opaco y no publiques ese enlace sensible.
    4. Consulta la información pública. Exige estado prepared y can_pay:true, vigencia, moneda y receptor. Prepared por sí solo no asegura que se pueda pagar.
    5. El pagador envía la verificación con otro request_id estable y los campos que indique user_bank.verifications_types_available. No todos los proveedores requieren los mismos campos.
    6. Interpreta el estado confirmado, lo aplicado y lo disponible; conserva el mismo intento ante incertidumbre.

    Los envoltorios son distintos: preparar checkout devuelve JSON directo; la información pública se consulta en GET /paymentlink/:id/info sin v1 y devuelve {data:…}. El pago público es POST /v1/paymentlink/:paymentLinkId/pay y también devuelve data. Este checkout comercial conserva su tasa: la ruta PATCH de enlaces no permite editarlo.

    La moneda, tasa, receptor y monto quedan congelados durante 15 minutos. 1500 amount_cents = 15 USD; con tasa 100, 150000 settlement_amount_cents = 1500 VEF. En cambio, payment_link.amount usa monto mayor: 15, no 1500. El servidor fija banco e importe; no agregues invoice_id, debtor_user_id, asignaciones privadas o montos para dirigir el pago público.

    El body público admite request_id y PaymentInput: bank_reference, movement_type, fecha_pago, dni_pagador, phone_pagador, bank_origin, account_pagador, otp o invoice_number según el método. fecha_pago usa YYYY-MM-DD de Caracas. No guardes OTP ni referencias reales en ejemplos o logs.

    Un estado paid significa que se recibió ese pago, no que toda la factura quedó saldada. Abonar 15 USD a una factura de 76 USD deja 61 USD pendientes. Si el saldo bajó después de validar el banco, se aplica el mínimo entre deuda actual e importe y el resto queda disponible en el pago. Ese excedente es dinero, no inventario de créditos.

    GET info puede recuperar y aplicar un recibo ya confirmado y persistido, idempotentemente y sin volver a consultar el banco; esa recuperación puede completar la aplicación interna del recibo. Paid se recupera aun después del vencimiento. Sin prueba confirmada, verifying/uncertain requieren conservar enlace/identidad y revisión; no repitas la transferencia.

    El request_id de preparación y el de verificación admiten de 1 a 200 caracteres tras trim, y pertenecen a intenciones distintas. Reusar una preparación con otra factura, importe o revisión genera conflicto. Ante enlace vencido o revisión cambiada, confirma el rechazo, actualiza la factura y revisa un nuevo enlace; una respuesta ambigua no autoriza a crear otro pago a ciegas.

    Para usar dinero ya recibido y disponible se llama a payments/:id/applications con claves estables y asignaciones de centavos, sin nueva caja. El endpoint legado POST /v1/subaffiliations/payments puede devolver 200 con verifying/uncertain: tampoco es prueba de pago confirmado.

    Preparar un abono de 15 USD sobre una factura global de 76 USD

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    POST /v1/subaffiliations/invoices/:id/checkout
    curl --request POST 'https://api.pabilo.app/v1/subaffiliations/invoices/000000000000000000000301/checkout' \
      --header 'Authorization: Bearer JWT_DEL_TITULAR' \
      --header 'Content-Type: application/json' \
      --data-raw '{"request_id":"demo-checkout-001","amount_cents":1500,"expected_revision":1}'
    Cuerpo JSON de la solicitud
    {
      "request_id": "demo-checkout-001",
      "amount_cents": 1500,
      "expected_revision": 1
    }
    Respuesta HTTP 200
    {
      "payment_link_id": "000000000000000000000501",
      "checkout_url": "/pay/000000000000000000000501",
      "status": "prepared",
      "invoice_id": "000000000000000000000301",
      "invoice_month": "2026-11",
      "invoice_revision": 1,
      "amount_cents": 1500,
      "currency": "USD",
      "settlement_currency": "VEF",
      "settlement_amount_cents": 150000,
      "exchange_rate": 100,
      "expires_at": "2026-12-02T12:15:00Z"
    }
    Recuperar recibo con excedente tras cambio concurrente posterior al banco

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    GET /paymentlink/:id/info
    curl --request GET 'https://api.pabilo.app/paymentlink/000000000000000000000501/info'
    Respuesta HTTP 200 · extracto
    {
      "data": {
        "commercial_checkout": {
          "status": "paid",
          "can_pay": false,
          "amount_cents": 1500,
          "currency": "USD",
          "settlement_currency": "VEF",
          "settlement_amount_cents": 150000,
          "exchange_rate": 100,
          "expires_at": "2026-12-02T12:15:00Z",
          "applied_cents": 1200,
          "unapplied_cents": 300
        }
      }
    }

    El extracto conserva el envoltorio y los campos relevantes; no enumera todos los campos de la respuesta.

    Verificar abono:paid no implica factura completa pagada

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    POST /v1/paymentlink/:paymentLinkId/pay
    curl --request POST 'https://api.pabilo.app/v1/paymentlink/000000000000000000000501/pay' \
      --header 'Content-Type: application/json' \
      --data-raw '{"request_id":"demo-verify-001","movement_type":"TRANSFER","bank_reference":"DEMO-REFERENCE-001","fecha_pago":"2026-12-02"}'
    Cuerpo JSON de la solicitud
    {
      "request_id": "demo-verify-001",
      "movement_type": "TRANSFER",
      "bank_reference": "DEMO-REFERENCE-001",
      "fecha_pago": "2026-12-02"
    }
    Respuesta HTTP 200 · extracto
    {
      "data": {
        "commercial_checkout": {
          "status": "paid",
          "can_pay": false,
          "amount_cents": 1500,
          "currency": "USD",
          "settlement_currency": "VEF",
          "settlement_amount_cents": 150000,
          "exchange_rate": 100,
          "expires_at": "2026-12-02T12:15:00Z",
          "applied_cents": 1500,
          "unapplied_cents": 0
        }
      }
    }

    El extracto conserva el envoltorio y los campos relevantes; no enumera todos los campos de la respuesta.

    Administración reservada de Pabilo

    Estas rutas requieren privilegios administrativos de Pabilo según la operación. Owner de plataforma no equivale a titular de empresa. El resumen global exige Owner efectivo; hasta GET companies/:id está protegido. Los endpoints administrativos de bolsa distinguen Admin/Owner para lectura y configuración de cuentas, y Owner para publicar política.

    El Owner configura la autorización por cuenta en GET/PUT /v1/admin/subaffiliations/companies/:id/plan-policies, con JWT propio; rechaza Admin referente, empleado, cliente y appKey. La respuesta es directa: user_id, revision, mode, plans, catalog. El PUT usa expected_revision de esa cuenta. mode:inherit exige plans:[] y conserva la configuración general; mode:explicit con array vacío deniega nuevas admisiones. Cada fila lleva Plan ID, enabled y margin_cents mensual: null hereda el margen general vigente, cero es un margen particular de cero. Un margen particular válido puede autorizar Company sin política general previa, con las restricciones de gratuidad y prestaciones vigentes.

    En el catálogo, list_cents y minimum_net_cents corresponden al período completo; margin_cents es mensual. Los valores desconocidos son null. mode_options entrega elegibilidad, importes, fuente y motivo de cada modalidad; las fuentes de Admin/Owner se conservan. Catálogo, motivos y contexto son sólo lectura. Las autorizaciones de cuenta se guardan con versiones propias; no alteran acuerdos ni facturas aceptadas. Una revisión obsoleta produce 409 y exige consultar y revisar antes de guardar de nuevo.

    En móvil puedes desplazar la tabla. «Directo» indica JSON sin envoltorio data.

    Método y rutaAutorización y alcanceRespuesta
    GET/v1/admin/subaffiliations/overview
    Entrada y notas

    query.month?

    Consulta global reservada a la administración de Pabilo.

    Owner de plataforma; no confundir con titular de empresa; empleados rechazados

    Owner efectivo para Overview all=true

    HTTP 200Directo
    GET/v1/admin/subaffiliations/companies/:id
    Entrada y notas

    path.id

    El handler y servicio restringen a Owner, no a todo Admin.

    Owner de plataforma; no confundir con titular de empresa; empleados rechazados

    Owner de plataforma

    HTTP 200{account}
    PUT/v1/admin/subaffiliations/companies/:id
    Entrada y notas

    path.id, enabled, sponsor_enabled?, allowed_modes?, closing_day, timezone, due_days?, default_payer?, default_benefit?, referral_default_plan_id?

    Configuración comercial. closing_day=1,timezone America/Caracas. Sponsor requiere aprobación explícita; no equivale a habilitar compras de bolsa.

    JWT Owner de plataforma; rechaza empleado, cliente y toda appKey

    Owner de plataforma

    HTTP 200{account}
    POST/v1/admin/subaffiliations/policies
    Entrada y notas

    plan_id, effective_from?, effective_until?, discount_cents, commission_cents, margin_cents?, bank_account_limit?, allow_free, allow_custom_price, enabled

    Referencia de política company versionada; servidor fija program=company/version/list_price_cents. effective_from omitido usa ahora; no días anteriores. No modificar tarifa desde tenant.

    Owner de plataforma; no confundir con titular de empresa; empleados rechazados

    Owner de plataforma

    HTTP 201{policy}
    POST/v1/admin/subaffiliations/payments/manual
    Entrada y notas

    request_id, debtor_user_id, amount_cents, reference, allocations, currency?, original_amount?, exchange_rate?

    Conciliación manual con prueba conservando moneda y tasa; no bypass de contabilidad de cliente.

    Owner de plataforma; no confundir con titular de empresa; empleados rechazados

    Owner de plataforma

    HTTP 200{payment}
    PUT/v1/admin/subaffiliations/payments/:id
    Entrada y notas

    path.id, reference, allocations

    Conciliar intención original por ID exacto/prueba; checkout conserva binding original y no puede redirigirse a otra factura.

    Owner de plataforma; no confundir con titular de empresa; empleados rechazados

    Owner de plataforma

    HTTP 200{payment}
    POST/v1/admin/subaffiliations/payouts
    Entrada y notas

    request_id, beneficiary_user_id, amount_cents, reference, status, channel, destination?, allocations

    Referencia administrativa; no emitir sin prueba de proceso financiero.

    Owner de plataforma; no confundir con titular de empresa; empleados rechazados

    Owner de plataforma

    HTTP 201{payout}
    PUT/v1/admin/subaffiliations/payouts/:id
    Entrada y notas

    path.id, status, reference

    Conciliación de la intención original con prueba del pago y privilegios de plataforma.

    Owner de plataforma; no confundir con titular de empresa; empleados rechazados

    Owner de plataforma

    HTTP 200{payout}
    POST/v1/admin/subaffiliations/adjustments
    Entrada y notas

    request_id, invoice_id, amount_cents, reason

    Ajuste explícito auditado, no reinterpretar como pago de caja.

    Owner de plataforma; no confundir con titular de empresa; empleados rechazados

    Owner de plataforma

    HTTP 200{invoice}
    GET/v1/admin/commercial/credit-policies
    Entrada y notas

    Sin cuerpo JSON.

    Devuelve un único objeto policy, NO items ni array.

    JWT Admin u Owner de plataforma; sin empleado/cliente/appKey

    Admin de plataforma

    HTTP 200Directo
    PUT/v1/admin/commercial/credit-policies
    Entrada y notas

    version, enabled, eligible_plan_ids, min_purchase_credits, max_purchase_credits, auto_purchase_allowed, max_automatic_monthly_cents, pricing_base_credits, pricing_base_price_cents, pricing_model, pricing_tiers[].amount_cents, pricing_tiers[].quantity_credits

    version debe ser actual, NO expected_revision. Servidor crea versión siguiente con effective_from actual. volume_tiers_v1 usa tramos de precio y créditos; pricing_base_* se conservan por compatibilidad, pero este modelo cotiza mediante pricing_tiers. Publicar una versión no modifica recibos comprometidos. El body debe declarar volume_tiers_v1 y sus cuatro tramos: esquema ausente o anterior devuelve CREDIT_POLICY_SCHEMA_CHANGED (409), para actualizar y revisar el formulario antes de reintentar.

    JWT Owner de plataforma; sin empleado/cliente/appKey

    Owner de plataforma

    HTTP 200Directo
    GET/v1/admin/users/:id/credit-pool-settings
    Entrada y notas

    path.id

    Habilitaciones independientes y limit_context readonly con topes guardados, límite efectivo, gasto y bloqueos. Una lectura no concede compras.

    JWT Admin u Owner de plataforma; sin empleado/cliente/appKey

    Admin de plataforma

    HTTP 200Directo
    PUT/v1/admin/users/:id/credit-pool-settings
    Entrada y notas

    path.id, revision, purchases_enabled, auto_topup_allowed, auto_purchase_allowed, max_automatic_monthly_cents

    Usa revision actual. El tope propio es independiente del global:500c puede guardarse con plataforma0 sin activar flags. Una nueva concesión de compra automática necesita autorización global; conservar una concesión existente no evita los gates de ejecución. CanManagePlatformAccount protege el destino.

    JWT Admin u Owner de plataforma; sin empleado/cliente/appKey

    Admin de plataforma; CanManagePlatformAccount sobre target

    HTTP 200Directo
    POST/v1/subaffiliations/hook/reconcile
    Entrada y notas

    Sin cuerpo JSON.

    Operación programada de Pabilo que requiere credencial cron interna.

    Credencial cron interna

    Reservado a operación interna

    HTTP 200Directo
    POST/v1/admin/subaffiliations/migrate
    Entrada y notas

    apply

    Operación de mantenimiento reservada al Owner de plataforma.

    Owner de plataforma; no confundir con titular de empresa; empleados rechazados

    Reservado a operación administrativa

    HTTP 200Directo
    GET/v1/admin/subaffiliations/companies/:id/plan-policies
    Entrada y notas

    path.id

    Vista por cuenta con catálogo y condiciones readonly por modalidad. Una consulta no crea autorizaciones. Lista y neto cubren el período; margen es mensual.

    JWT Owner de plataforma; rechaza empleado, cliente, Admin referente y toda appKey

    Owner de plataforma; titular destino gestionable

    HTTP 200Directo
    PUT/v1/admin/subaffiliations/companies/:id/plan-policies
    Entrada y notas

    path.id, expected_revision, mode, plans[].plan_id, plans[].enabled, plans[].margin_cents

    CAS de cuenta. inherit exige plans=[]; explicit[] bloquea nuevas admisiones. null hereda margen vigente,0 es margen explícito cero. Un margen propio puede autorizar sin baseline global; acuerdos aceptados conservan snapshots.

    JWT Owner de plataforma; rechaza empleado, cliente, Admin referente y toda appKey

    Owner de plataforma; titular destino gestionable

    HTTP 200Directo

    La política de bolsa es un único objeto. Su PUT usa version actual y el servidor crea la siguiente versión. Las habilitaciones por cuenta usan revision; no expected_revision. La automatización sí usa expected_revision. El tope de cuenta puede guardarse aunque supere al global; por ejemplo, 500 centavos con global cero conserva el importe y no habilita compras. limit_context es readonly: muestra topes de plataforma/cuenta/titular, efectivo, gasto comprometido, restante y motivos de bloqueo; el límite efectivo sigue siendo el menor. Una nueva concesión de compra automática requiere autorización global. Conservar una concesión anterior mientras la plataforma la bloquea no permite ejecutar compras. Una modificación debe respetar las cuentas protegidas y los controles vigentes.

    Los cobros manuales ajenos y la conciliación necesitan pruebas del dinero recibido y privilegios de plataforma. No vuelven a conceder suscripciones o créditos. El hook de reconciliación usa credencial interna cron; no es una API pública para una appKey.

    Referencia admin: publicar una nueva política con la versión actual

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    PUT /v1/admin/commercial/credit-policies
    curl --request PUT 'https://api.pabilo.app/v1/admin/commercial/credit-policies' \
      --header 'Authorization: Bearer JWT_OWNER_PABILO' \
      --header 'Content-Type: application/json' \
      --data-raw '{"version":1,"enabled":true,"eligible_plan_ids":["000000000000000000000010","000000000000000000000020"],"min_purchase_credits":200,"max_purchase_credits":128000,"auto_purchase_allowed":true,"max_automatic_monthly_cents":5000,"pricing_model":"volume_tiers_v1","pricing_tiers":[{"amount_cents":500,"quantity_credits":200},{"amount_cents":1000,"quantity_credits":1200},{"amount_cents":2000,"quantity_credits":3000},{"amount_cents":3000,"quantity_credits":5000}],"pricing_base_credits":200,"pricing_base_price_cents":500}'
    Cuerpo JSON de la solicitud
    {
      "version": 1,
      "enabled": true,
      "eligible_plan_ids": [
        "000000000000000000000010",
        "000000000000000000000020"
      ],
      "min_purchase_credits": 200,
      "max_purchase_credits": 128000,
      "auto_purchase_allowed": true,
      "max_automatic_monthly_cents": 5000,
      "pricing_model": "volume_tiers_v1",
      "pricing_tiers": [
        {
          "amount_cents": 500,
          "quantity_credits": 200
        },
        {
          "amount_cents": 1000,
          "quantity_credits": 1200
        },
        {
          "amount_cents": 2000,
          "quantity_credits": 3000
        },
        {
          "amount_cents": 3000,
          "quantity_credits": 5000
        }
      ],
      "pricing_base_credits": 200,
      "pricing_base_price_cents": 500
    }
    Respuesta HTTP 200 · extracto
    {
      "version": 2,
      "enabled": true,
      "effective_from": "2026-11-15T16:00:00Z",
      "pricing_model": "volume_tiers_v1",
      "pricing_tiers": [
        {
          "amount_cents": 500,
          "quantity_credits": 200
        },
        {
          "amount_cents": 1000,
          "quantity_credits": 1200
        },
        {
          "amount_cents": 2000,
          "quantity_credits": 3000
        },
        {
          "amount_cents": 3000,
          "quantity_credits": 5000
        }
      ],
      "min_purchase_credits": 200,
      "pricing_base_credits": 200,
      "pricing_base_price_cents": 500
    }

    El extracto conserva el envoltorio y los campos relevantes; no enumera todos los campos de la respuesta.

    Guardar tope de cuenta5USD con global0, sin conceder compras automáticas

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    PUT /v1/admin/users/:id/credit-pool-settings
    curl --request PUT 'https://api.pabilo.app/v1/admin/users/000000000000000000000100/credit-pool-settings' \
      --header 'Authorization: Bearer JWT_ADMIN_PABILO' \
      --header 'Content-Type: application/json' \
      --data-raw '{"revision":1,"purchases_enabled":false,"auto_topup_allowed":false,"auto_purchase_allowed":false,"max_automatic_monthly_cents":500}'
    Cuerpo JSON de la solicitud
    {
      "revision": 1,
      "purchases_enabled": false,
      "auto_topup_allowed": false,
      "auto_purchase_allowed": false,
      "max_automatic_monthly_cents": 500
    }
    Respuesta HTTP 200 · extracto
    {
      "user_id": "000000000000000000000100",
      "revision": 2,
      "purchases_enabled": false,
      "auto_topup_allowed": false,
      "auto_purchase_allowed": false,
      "max_automatic_monthly_cents": 500,
      "limit_context": {
        "platform_policy_version": 1,
        "platform_enabled": true,
        "platform_auto_purchase_allowed": false,
        "platform_limit_cents": 0,
        "account_limit_cents": 500,
        "user_limit_cents": 0,
        "effective_limit_cents": 0,
        "automatic_spent_cents": 0,
        "remaining_cents": 0,
        "month": "2026-11",
        "user_auto_purchase_enabled": false,
        "user_accepted_policy_version": 0,
        "blocking_reasons": [
          "platform_auto_purchase_disabled",
          "platform_limit_zero",
          "account_purchases_disabled",
          "account_topup_disabled",
          "account_auto_purchase_disabled",
          "user_auto_topup_disabled",
          "user_auto_purchase_disabled",
          "user_limit_zero",
          "policy_review_required"
        ]
      }
    }

    El extracto conserva el envoltorio y los campos relevantes; no enumera todos los campos de la respuesta.

    Consultar planes y beneficio de una cuenta: lista30, beneficio12, neto18

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    GET /v1/admin/subaffiliations/companies/:id/plan-policies
    curl --request GET 'https://api.pabilo.app/v1/admin/subaffiliations/companies/000000000000000000000100/plan-policies' \
      --header 'Authorization: Bearer JWT_OWNER_PABILO'
    Respuesta HTTP 200
    {
      "user_id": "000000000000000000000100",
      "revision": 2,
      "mode": "explicit",
      "plans": [
        {
          "plan_id": "000000000000000000000030",
          "enabled": true,
          "margin_cents": 1200
        }
      ],
      "catalog": [
        {
          "plan_id": "000000000000000000000030",
          "plan_name": "Pro",
          "list_cents": 3000,
          "billing_months": 1,
          "period": "month",
          "enabled": true,
          "margin_cents": 1200,
          "minimum_net_cents": 1800,
          "source": "account",
          "policy_id": "000000000000000000000601",
          "policy_version": 2,
          "status": "available",
          "reason": "",
          "mode_options": {
            "member_commission": {
              "eligible": true,
              "margin_cents": 1200,
              "minimum_net_cents": 1800,
              "source": "account",
              "status": "available",
              "reason": ""
            },
            "member_discount": {
              "eligible": true,
              "margin_cents": 1200,
              "minimum_net_cents": 1800,
              "source": "account",
              "status": "available",
              "reason": ""
            },
            "sponsor_discount": {
              "eligible": false,
              "margin_cents": null,
              "minimum_net_cents": null,
              "source": "none",
              "status": "blocked",
              "reason": "La financiación requiere aprobación expresa"
            }
          }
        }
      ]
    }
    Autorizar sólo Pro para esta cuenta con beneficio mensual de12USD

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    PUT /v1/admin/subaffiliations/companies/:id/plan-policies
    curl --request PUT 'https://api.pabilo.app/v1/admin/subaffiliations/companies/000000000000000000000100/plan-policies' \
      --header 'Authorization: Bearer JWT_OWNER_PABILO' \
      --header 'Content-Type: application/json' \
      --data-raw '{"expected_revision":2,"mode":"explicit","plans":[{"plan_id":"000000000000000000000030","enabled":true,"margin_cents":1200}]}'
    Cuerpo JSON de la solicitud
    {
      "expected_revision": 2,
      "mode": "explicit",
      "plans": [
        {
          "plan_id": "000000000000000000000030",
          "enabled": true,
          "margin_cents": 1200
        }
      ]
    }
    Respuesta HTTP 200
    {
      "user_id": "000000000000000000000100",
      "revision": 3,
      "mode": "explicit",
      "plans": [
        {
          "plan_id": "000000000000000000000030",
          "enabled": true,
          "margin_cents": 1200
        }
      ],
      "catalog": [
        {
          "plan_id": "000000000000000000000030",
          "plan_name": "Pro",
          "list_cents": 3000,
          "billing_months": 1,
          "period": "month",
          "enabled": true,
          "margin_cents": 1200,
          "minimum_net_cents": 1800,
          "source": "account",
          "policy_id": "000000000000000000000602",
          "policy_version": 3,
          "status": "available",
          "reason": "",
          "mode_options": {
            "member_commission": {
              "eligible": true,
              "margin_cents": 1200,
              "minimum_net_cents": 1800,
              "source": "account",
              "status": "available",
              "reason": ""
            },
            "member_discount": {
              "eligible": true,
              "margin_cents": 1200,
              "minimum_net_cents": 1800,
              "source": "account",
              "status": "available",
              "reason": ""
            },
            "sponsor_discount": {
              "eligible": false,
              "margin_cents": null,
              "minimum_net_cents": null,
              "source": "none",
              "status": "blocked",
              "reason": "La financiación requiere aprobación expresa"
            }
          }
        }
      ]
    }
    Selección explícita vacía: no admitir nuevas subafiliaciones

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    PUT /v1/admin/subaffiliations/companies/:id/plan-policies
    curl --request PUT 'https://api.pabilo.app/v1/admin/subaffiliations/companies/000000000000000000000100/plan-policies' \
      --header 'Authorization: Bearer JWT_OWNER_PABILO' \
      --header 'Content-Type: application/json' \
      --data-raw '{"expected_revision":3,"mode":"explicit","plans":[]}'
    Cuerpo JSON de la solicitud
    {
      "expected_revision": 3,
      "mode": "explicit",
      "plans": []
    }
    Respuesta HTTP 200 · extracto
    {
      "user_id": "000000000000000000000100",
      "revision": 4,
      "mode": "explicit",
      "plans": []
    }

    El extracto conserva el envoltorio y los campos relevantes; no enumera todos los campos de la respuesta.

    Volver a heredar las condiciones generales para próximas ofertas

    Ejemplo sintético. Sustituye los identificadores y el JWT por los de la identidad autorizada. Copiar no ejecuta la solicitud.

    PUT /v1/admin/subaffiliations/companies/:id/plan-policies
    curl --request PUT 'https://api.pabilo.app/v1/admin/subaffiliations/companies/000000000000000000000100/plan-policies' \
      --header 'Authorization: Bearer JWT_OWNER_PABILO' \
      --header 'Content-Type: application/json' \
      --data-raw '{"expected_revision":4,"mode":"inherit","plans":[]}'
    Cuerpo JSON de la solicitud
    {
      "expected_revision": 4,
      "mode": "inherit",
      "plans": []
    }
    Respuesta HTTP 200 · extracto
    {
      "user_id": "000000000000000000000100",
      "revision": 5,
      "mode": "inherit",
      "plans": []
    }

    El extracto conserva el envoltorio y los campos relevantes; no enumera todos los campos de la respuesta.

    Errores, estados y recuperación segura

    CódigoHTTPSiguiente paso
    BAD_REQUEST400Corregir campos/formato; no asumir que todo rechazo implica ausencia de transferencia.
    UNAUTHORIZED401Iniciar sesión o renovar JWT de la cuenta correcta.
    FORBIDDEN403Revisar rol, propiedad, consentimiento, permiso granular y habilitación efectiva; no cambiar a una appKey para eludirlo.
    NOT_FOUND404Verificar ID o token correcto sin enumerar recursos ajenos.
    CREDIT_POLICY_SCHEMA_CHANGED409Actualizar el formulario de política y revisar el modelo volume_tiers_v1 con sus cuatro tramos antes de publicar; conservar el borrador hasta decidir reemplazarlo.
    COMMERCIAL_QUOTE_CHANGED409Consultar oferta/cotización otra vez y presentar términos actualizados. Ante compra ambigua conservar operation_key y quote_token para recuperar primero.
    COMMERCIAL_CODE_ALREADY_USED409Elegir otro código general y consultar disponibilidad; la comprobación final es atómica.
    COMMERCIAL_ACCOUNT_CHANGED409Recargar account.revision y revisar antes de guardar código.
    COMMERCIAL_PRIMARY_KEY_CONSENT_REQUIRED403El titular miembro debe otorgar el consentimiento principal_v1; padre no puede otorgárselo.
    COMMERCIAL_PRIMARY_KEY_UNAVAILABLE409El titular revisa su llave principal activa en Integraciones.
    COMMERCIAL_PRIMARY_KEY_AMBIGUOUS409El titular debe resolver múltiples llaves principales activas; no elegir una arbitrariamente.
    PASSWORD_EMAIL_COOLDOWN429Esperar al menos un minuto; conservar request_id para recuperar la solicitud.
    PASSWORD_RESET_INVALID400Solicitar nuevo correo; no adivinar token ni cambiar destinatario.
    CREDIT_POOL_INSUFFICIENT409Recargar stock autorizado o reducir asignación; no duplicar intento con key nueva si respuesta anterior es incierta.
    CREDIT_OPERATION_CONFLICT409Consultar estado/revisión; no reutilizar operation_key con otro payload ni revision incorrecta.
    CREDIT_STATE_REQUIRES_RECONCILIATION409Revisar/conciliar saldos; no simular saldo0 ni otorgar créditos por fuera.
    AUTO_CREDIT_BUDGET_EXHAUSTED409Revisar presupuesto mensual vigente; pagar factura no restaura el tope.
    AUTO_CREDIT_PRICE_REVIEW_REQUIRED409Revisar y aceptar versión actual de política para compra automática.
    COMMERCIAL_CHECKOUT_CHANGED409Consultar factura y preparar otro enlace sólo si está confirmado que no inició cobro; si ya verificó, conservar enlace y revisar recibo.
    COMMERCIAL_CHECKOUT_EXPIRED409Preparar nuevo enlace si no hay pago iniciado; recuperar primero estado de un intento anterior.
    COMMERCIAL_CHECKOUT_PENDING409Conservar enlace/comprobante y consultar mismo info; sin prueba persistida requiere conciliación administrativa, no repetir transferencia.
    PAYMENT_ALREADY_EXISTS400Revisar recibo/consumidor ganador y conciliación; nunca tratarlo como409 ni transferir de nuevo ciegamente.

    COMMERCIAL_CHECKOUT_CHANGED, COMMERCIAL_CHECKOUT_EXPIRED y COMMERCIAL_CHECKOUT_PENDING usan HTTP 409. PAYMENT_ALREADY_EXISTS usa HTTP 400: conserva el comprobante y revisa conciliación; no repitas dinero por tratarlo como conflicto genérico.

    Una respuesta perdida no justifica cambiar request_id u operation_key. En bolsa, recupera con la misma key y token; si tienes monitor, también puedes consultar movimientos. En pago, consulta el mismo enlace y conserva la referencia. Sólo inicia una intención distinta después de conocer el resultado anterior y revisar las nuevas condiciones.

    Estados prepared, verifying, uncertain y paid describen el checkout; expired es una proyección por tiempo. Los recibos de bolsa usan committed. No intercambies estos estados ni conviertas un 2xx sin estado confirmado en una nueva prestación o en factura totalmente saldada.

    Ejemplos sintéticos, cotejados con los contratos publicados. No son tokens, llaves ni operaciones bancarias reales. Usa las ofertas y respuestas vigentes del servidor como autoridad.

    Volver a la guía web de Subafiliaciones