Documentación de Rekomi
Para desarrolladores
Desarrolladores

Referencia de la API

Todos los endpoints v1 con el esquema de la petición, un ejemplo de respuesta JSON, el permiso necesario y notas, verificados contra el código en producción.

Esta página cubre los endpoints principales expuestos bajo /api/v1/* para quienes se autentican con clave de API. Cada entrada muestra la forma de la petición, un JSON de respuesta realista, el permiso (scope) necesario y cualquier restricción de plan o de rol. No es exhaustiva: los endpoints de cupones están documentados aparte en Seguimiento por código de cupón, y unos cuantos endpoints auxiliares (comprobación de slugs, estado de seguimiento por campaña, resúmenes de comisión, libro mayor y recibos de pagos) no aparecen aquí. Las respuestas también pueden traer campos de conveniencia además de los mostrados (nombres visibles, datos del cliente, URLs de avatar, campos de presupuesto y umbral); toma los esquemas de abajo como la forma básica, no como un techo estricto.

¿No vas a construir un cliente a medida? Rekomi expone la misma API a través de dos consumidores sin código o con poco código:

  • Zapier, 9 triggers, 9 acciones, 4 búsquedas. Conexión en un clic desde el marketplace de Zapier. Úsalo cuando tu objetivo es conectar Rekomi con Slack, Gmail, HubSpot, Notion, Google Sheets, Typeform o cualquier otra app compatible con Zapier.
  • Servidor MCP, 61 herramientas expuestas a Claude, Cursor, ChatGPT y otros clientes de IA a través del Model Context Protocol. Úsalo cuando quieres que un asistente de IA maneje Rekomi por ti.

Los dos consumidores se rigen por las mismas restricciones de plan y el mismo registro de auditoría que la API REST documentada abajo; son transportes alternativos sobre el mismo modelo de dominio, no APIs separadas.

Cabecera de autenticación en cada endpoint autenticado:

Authorization: Bearer rk_live_xxxxxxxxxxxxxxxxxxxxx

La columna Permiso te dice qué permiso de la clave de API satisface el endpoint:

  • read: se aceptan las claves creadas con el permiso read (y también las read_write)
  • read_write: solo se aceptan claves read_write

Inferencia por defecto: GET/HEAD/OPTIONS → read; POST/PUT/PATCH/DELETE → read_write. Los endpoints de tokens de embed siempre requieren read_write.

Plan necesario por familia de recursos (consulta Visión general → Requisitos de plan para la tabla completa):

  • Starter+: seguimiento S2S, programas, afiliados, conversiones, pagos, métricas del panel, webhooks de cliente, Zapier
  • Growth+: iframe de embed, AI Co-Pilot
  • Pro+: exportación del registro de auditoría por API

Las restricciones de plan responden 402 plan_tier_required con required, current y trialing en el cuerpo de la respuesta. El panel de la app en app.rekomi.com no pasa por las restricciones de plan (ruta de autenticación con JWT).

Envoltorios de respuesta comunes (definidos en Visión general):

// Cursor-paginated list (the core resource lists: programs, affiliates, conversions, payouts)
{
  "items": [ /* ... */ ],
  "nextCursor": "eyJpZCI6IjAxNzg5..." ,
  "hasMore": true
}

// Business-rule error
{ "error": "plan_tier_required", "message": "Feature requires a higher plan tier" }

Los fallos de validación de la petición devuelven un objeto problem details estándar ({ type, title, status, errors }) en lugar del envoltorio de regla de negocio, y los 401 y muchos 404 no llevan cuerpo; consulta Visión general → Errores.

Programas

Plan necesario: Starter+ para llamadas con clave de API. El panel con JWT no tiene restricción.

Recursos AffiliateProgram. Las marcas suelen tener de 1 a 3 programas (por ejemplo, uno por defecto y otro con una tarifa promocional especial).

GET /api/v1/programs

Permiso: read. Lista los programas. Paginado por cursor.

Parámetros de consulta: take (por defecto 50, máximo 200), cursor (valor opaco del nextCursor anterior).

{
  "items": [
    {
      "id": "0789abcd-...",
      "name": "Default program",
      "slug": "default",
      "description": "Earn 20% recurring on every annual plan.",
      "termsUrl": "https://yourbrand.com/affiliate-terms",
      "isActive": true,
      "defaultCommissionType": "Percentage",
      "defaultCommissionValue": 20.0,
      "defaultCommissionModel": "Cps",
      "cookieWindowDays": 60,
      "recurringMonths": 12,
      "recurringDelayInvoices": 0,
      "attributionModel": "LastTouch",
      "autoApprove": false,
      "customDomain": null,
      "customDomainVerified": false,
      "networkVisibility": "Private",
      "isPubliclyDiscoverable": true,
      "createdAt": "2026-05-01T12:00:00Z",
      "updatedAt": "2026-05-12T08:30:00Z",
      "archivedAt": null
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

isPubliclyDiscoverable controla la visibilidad SEO de la página pública {handle}.rekomi.com/{campaign}. Cuando es false, la página emite <meta name="robots" content="noindex"> y se excluye del sitemap; ponlo en false para programas solo por invitación o con tarifas que prefieres no publicar.

GET /api/v1/programs/{id}

Permiso: read. Devuelve un único ProgramResponse (la misma forma que un elemento de la lista de arriba).

GET /api/v1/programs/stats

Permiso: read. El resumen de la lista de campañas: un array con una entrada por campaña (programId en cada una), con affiliatesCount, clicks30d, conversions30d (ventas, leads y clics pagados juntos), sales30d, leads30d, paidClicks30d, pendingCommissionCents, availableCommissionCents, settlingCommissionCents, owedEligibleInHomeCents y settlingInHomeCents. Las cifras de dinero están en unidades menores de la moneda principal (home currency) de la organización, con cada conversión valorada al tipo de cambio de referencia guardado para su propia fecha. Las filas cuya moneda de venta no tiene un tipo utilizable se dejan fuera de la cifra en lugar de contarse a valor nominal, y se informan por moneda, en unidades menores nativas, en los mapas aditivos pendingUnconvertibleByCurrency, availableUnconvertibleByCurrency y settlingUnconvertibleByCurrency (cada uno null cuando todo se pudo convertir); esos mapas son el registro oficial de lo que se dejó fuera. Una campaña que todavía no tiene actividad recibe igualmente una entrada con ceros.

POST /api/v1/programs

Permiso: read_write. Rol necesario: Manager o superior (con JWT; las claves de API equivalen a Propietario y pasan).

Petición:

{
  "name": "Holiday promo program",
  "slug": "holiday-2026",
  "description": "Limited-time 30% commission for Q4.",
  "termsUrl": "https://yourbrand.com/affiliate-terms",
  "defaultCommissionType": "Percentage",
  "defaultCommissionValue": 30.0,
  "defaultCommissionModel": "Cps",
  "cookieWindowDays": 30,
  "recurringMonths": null,
  "recurringDelayInvoices": 0,
  "attributionModel": "LastTouch",
  "autoApprove": false,
  "budgetCents": 500000,
  "referralDestinationUrl": "https://yourbrand.com/landing",
  "minPayoutCents": 2500
}

Respuesta: 201 Created con el nuevo ProgramResponse. No dispara ningún webhook (hoy los programas no emiten webhooks).

Enumeraciones:

  • defaultCommissionType: Percentage | Fixed
  • defaultCommissionModel: Cps (por venta, importe fijo o % recurrente) | Cpc (por clic) | Cpl (por lead). Nombra el tramo principal de pago de la campaña; defaultCommissionType / defaultCommissionValue llevan su tarifa y las tarifas por partner la sobrescriben. Añade los demás tramos con leadBountyCents, clickRewardCents y saleCommissionType / saleCommissionValue (cualquier combinación; ver más abajo). Valores heredados que se siguen aceptando en campañas existentes pero no se ofrecen para las nuevas: Cpa, RevShare, Hybrid (todos se comportan como Cps).
  • attributionModel: FirstTouch | LastTouch
  • networkVisibility: Private | Networked | InviteOnly. Networked publica la campaña en la red de creadores de Rekomi tras una revisión y necesita un plan de pago activo y una fuente de financiación en la organización; cuando falta cualquiera de las dos, una petición que activa la publicación se guarda como Private y se devuelve así sin error, así que lee networkVisibility de la respuesta. Una campaña que ya es Networked conserva ese valor; los creadores dejan de verla mientras falte el plan o la fuente de financiación, y vuelve a mostrarse sola cuando vuelven a estar los dos.
  • recurringMonths: duración recurrente por venta. null u omitido = de por vida (cada renovación); 0 = una sola vez (sin renovaciones); N = cada pago dentro de los primeros N meses naturales de cada cliente, contados desde su primer pago (un plan mensual paga N veces, un plan anual paga una vez cuando N es 12); la ventana es por cliente, indexada por el id de cliente de la plataforma de cobro, así que volver a suscribirse con un nuevo id de suscripción sigue dentro de ella. En PATCH, envía -1 para quitar un tope existente y volver a "de por vida".
  • budgetCents: campañas que pagan por clic o por lead (cualquier tramo principal). Tope del gasto en recompensas por clic y por lead en unidades menores de la moneda principal de la organización; cuando las recompensas por clic y por lead no reembolsadas lo alcanzan, los nuevos clics y leads dejan de generar ganancias. Las comisiones por venta nunca cuentan contra él. Omítelo para no poner tope, algo que no recomendamos cuando pagas por clic o por lead. El tope puede ser como máximo el equivalente a USD 100,000,000, valorado contra tu moneda principal al tipo de cambio de referencia guardado hoy; un valor mayor se rechaza con 400 budget_out_of_range (el cuerpo indica homeCurrency), nunca se recorta. Consulta el gasto con GET /api/v1/programs/{id}/budget-status.
  • referralDestinationUrl: el sitio web que promocionan los afiliados (en toda campaña); un clic validado en rekomi.link redirige ahí con el código del afiliado. minPayoutCents: umbral mínimo de pago por campaña (unidades menores).
  • hostedCheckoutDoorEnabled (booleano, por defecto false), hostedCheckoutDoorMode (redirect | email, por defecto redirect), hostedCheckoutThankYouUrl (URL http(s) o "" para borrarla): la puerta de checkout para plataformas donde no se puede ejecutar ningún script (suscripciones de pago de beehiiv). Cuando está activada, los enlaces para compartir son https://rekomi.link/{code}?p={campaignId} (un &to=/path opcional enlaza a una ruta concreta dentro del sitio de la campaña) y la redirección posterior a la compra de la plataforma debería ser https://rekomi.link/thanks?p={campaignId}&session_id={CHECKOUT_SESSION_ID}. Las ventas acreditadas así llevan attributionMethod: "checkout_door". Modo inválido: 400 invalid_hosted_checkout_door_mode; URL inválida: 400 invalid_hosted_checkout_thank_you_url.
  • leadBountyCents: cualquier tramo principal salvo Cpl (en una campaña Cpl, la tarifa por lead es defaultCommissionValue). El tramo por lead: un importe fijo en unidades menores, pagado por cada lead cualificado capturado a través del formulario de leads de la campaña alojado por Rekomi, además de lo que ya pague la campaña. Necesita un plan Starter o superior. El valor va en unidades menores de la moneda principal de la organización (centavos si la moneda principal es USD, yenes enteros si es JPY) y tiene que quedar entre el equivalente a USD 0.10 y USD 1,000, valorado al tipo de cambio de referencia guardado hoy para esa moneda; cualquier valor fuera de esa franja se rechaza con 400 lead_bounty_out_of_range (el cuerpo indica homeCurrency), nunca se recorta. Un valor positivo lo fija, 0 lo quita, omitirlo = sin cambios en PATCH. Se ignora (se pone a null) en un tramo principal Cpl.
  • clickRewardCents: cualquier tramo principal salvo Cpc (en una campaña Cpc, la tarifa por clic es defaultCommissionValue). El tramo por clic: un importe fijo en unidades menores de la moneda principal de la organización, pagado por cada clic validado (puntuado contra fraude, deduplicado, con tope, dentro de budgetCents), entre el equivalente a USD 0.01 y USD 1,000 al tipo guardado hoy; si no, 400 click_reward_out_of_range, nunca se recorta. Un valor positivo lo fija, 0 lo quita, omitirlo = sin cambios en PATCH; se ignora (se pone a null) en un tramo principal Cpc. Activarlo convierte la campaña en solo por invitación (la aprobación automática, la publicación en la red y la visibilidad pública se desactivan a la fuerza) y necesita un plan Starter o superior.
  • saleCommissionType / saleCommissionValue: solo con tramo principal Cpc o Cpl. El tramo por venta en una campaña de clics o leads: Percentage (de 0 a 100) o Fixed (unidades mayores de la moneda en la que llega cada venta, hasta 1,000,000), enviados juntos. Las renovaciones siguen recurringMonths / recurringDelayInvoices exactamente como en una campaña de ventas. En PATCH, saleCommissionValue: 0 borra el par. Se pone a null en los tramos principales de venta (su tarifa de venta es la tarifa por defecto). Las tarifas por partner nunca se le aplican (sobrescriben la tarifa por unidad del tramo principal).
  • Límites de defaultCommissionValue: Percentage va de 0 a 100. Un valor Fixed en Cpc/Cpl es la tarifa por clic o por lead en unidades mayores de la moneda principal de la organización y puede ser como máximo el equivalente a USD 1,000 (400 unit_fee_out_of_range); un valor Fixed en un modelo de ventas paga esa cantidad de unidades de la moneda propia de cada venta y puede ser como máximo el equivalente a USD 1,000,000 (400 fixed_commission_out_of_range). Los dos techos se valoran al tipo de cambio de referencia guardado hoy y se rechazan en lugar de recortarse.

PATCH /api/v1/programs/{id}

Permiso: read_write. Rol: Manager.

Todos los campos son opcionales; solo se actualizan las claves que envías.

{
  "name": "Holiday promo (extended)",
  "isActive": true,
  "defaultCommissionValue": 35.0,
  "autoApprove": true,
  "customDomain": "go.yourbrand.com",
  "networkVisibility": "Networked"
}

Respuesta: 200 con el ProgramResponse actualizado. customDomainVerified vuelve a false si cambia customDomain; verifícalo desde el panel.

DELETE /api/v1/programs/{id}

Permiso: read_write. Rol: Owner. Borrado lógico (fija archivedAt). Devuelve 204 No Content.

GET /api/v1/programs/{id}/tracking-status

Permiso: read. Verificación de la instalación: si la campaña ha registrado alguna vez un clic o una conversión. Devuelve { verified, lastClickAt, lastConversionAt, totalClicks30d, totalConversions30d }.

GET /api/v1/programs/{id}/recent-events

Permiso: read. Los clics y conversiones más recientes de la campaña, intercalados. Consulta: limit (por defecto 20, máximo 100).

GET /api/v1/programs/check-slug

Permiso: read. Comprueba de antemano si un slug está libre antes de crear una campaña. Consulta: slug. Devuelve { "available": true, "slug": "spring-launch" }, o { "available": false, "slug": "spring-launch", "suggestion": "spring-launch-2" } con la primera variante libre de -2 a -10. 400 slug_required o 400 invalid_slug_format (de 4 a 64 letras minúsculas, dígitos y guiones, empezando y terminando en alfanumérico).

PATCH /api/v1/programs/{id}/slug

Permiso: read_write. Rol: Manager. Cambia el slug de una campaña, el segmento de ruta de su página de registro. El slug anterior se conserva como alias de redirección, así que los enlaces antiguos redirigen con 308 al nuevo. Cuerpo: { "slug": "new-slug" }. Devuelve { "slug": "new-slug", "previousSlug": "old-slug" }. Errores: 400 invalid_slug_format, 400 slug_reserved, 409 cuando el slug lo usa otra campaña activa o es un alias retirado de una campaña distinta.

GET /api/v1/programs/{id}/tracking-status/lookup

Permiso: read. Lo que Rekomi vio de un comprador concreto, para atender incidencias en un checkout alojado. Consulta: email. Las variantes con "+" de una misma bandeja cuentan como la misma persona. Devuelve el lead (si lo hay), la venta atribuida (si la hay), las últimas compras que la pasarela conectada entregó para ese correo y un verdict de una palabra: attributed, attributed_by_platform, lead_and_purchase_but_no_sale, lead_only, purchase_without_lead o nothing_seen.

POST /api/v1/programs/{id}/custom-domain/verify

Permiso: read_write. Rol: Admin. Plan necesario: cualquier plan de pago, pruebas incluidas. Vuelve a ejecutar la verificación DNS del dominio de seguimiento personalizado de la campaña y aprovisiona el certificado si todo va bien. Devuelve { "verified": true, "domain": "go.yourbrand.com", "resolvedTarget": "cname.rekomi.com", "errorReason": null }. Con límite de peticiones.

POST /api/v1/programs/{id}/test-event

Permiso: read_write. Rol: Manager. Dispara un clic sintético más una conversión de $10.00 para el afiliado de prueba de la campaña a través del pipeline real, incluido el webhook conversion.created, para que puedas probar una integración de principio a fin. Las filas de prueba aparecen en la lista de conversiones y en la actividad de la campaña, pero nunca cuentan para los pagos ni para los totales del panel. Devuelve { "clickId": "...", "conversionId": "...", "commissionCents": 100 }.

Afiliados

Plan necesario: Starter+ para llamadas con clave de API. El panel con JWT no tiene restricción.

GET /api/v1/affiliates

Permiso: read. Lista los afiliados. Paginado por cursor.

Consulta: take (por defecto 50, máximo 200), skip, cursor, programId. Esta lista no tiene filtro por estado ni búsqueda por texto; las solicitudes pendientes están en GET /api/v1/affiliates/applications.

{
  "items": [
    {
      "id": "01234567-...",
      "programId": "0789abcd-...",
      "email": "jane@creator.com",
      "fullName": "Jane Doe",
      "status": "Approved",
      "customCommissionType": null,
      "customCommissionValue": null,
      "tags": ["youtube", "tier-1"],
      "notes": "Top performer Q1 2026",
      "source": "Public",
      "appliedAt": "2026-04-15T10:00:00Z",
      "approvedAt": "2026-04-16T11:30:00Z",
      "createdAt": "2026-04-15T10:00:00Z",
      "links": [
        {
          "id": "abcdef12-...",
          "affiliateId": "01234567-...",
          "slug": "jane-recommends",
          "customAlias": null,
          "isDefault": true,
          "format": "Short",
          "createdAt": "2026-04-16T11:30:00Z"
        }
      ]
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

Notas:

  • email es el correo del afiliado, visible para ti como dueño de la marca (son tus propios datos).
  • notes son comentarios internos del lado de la marca. No los compartas con el afiliado.
  • La respuesta omite a propósito ClerkUserId, StripeConnectAccountId, PaypalEmail, TaxFormStatus y KycStatus. Para llamadas con clave de API, la respuesta también omite applicationData (el JSON del formulario de solicitud). La ruta con JWT del panel conserva applicationData para que la pantalla de revisión del producto pueda mostrarlo.
  • Enumeración de status: Pending | Approved | Rejected | Paused | Banned.
  • Enumeración de source: Direct | Public | Invite | Network.
  • Enumeración de format (en cada entrada de links[]): Short | Query | Path | Hash.
  • El enlace por defecto (isDefault: true) es el slug principal de la cuenta del afiliado. En campañas con modelo de ventas, los afiliados pueden tener hasta 20 enlaces por campaña (incluido el principal), gestionados desde su panel.

GET /api/v1/affiliates/stats

Permiso: read. Una fila por afiliado con los números que muestran los informes de afiliados del panel: clics (visitors), leads, ventas (conversions), los bloques de comisión y los ingresos, todo el dinero en unidades menores normalizado a tu moneda principal. Cifras de por vida por defecto. Consulta: programId (opcional: una campaña), since y until (marcas de tiempo ISO opcionales; since inclusivo, until exclusivo).

{
  "currency": "USD",
  "items": [
    {
      "affiliateId": "01234567-...",
      "visitors": 43,
      "leads": 2,
      "conversions": 5,
      "unpaidCommissionCents": 12000,
      "dueNowCommissionCents": 8000,
      "paidCommissionCents": 45000,
      "processingCommissionCents": 0,
      "failedPayoutCommissionCents": 0,
      "grossRevenueCents": 310000,
      "netRevenueCents": 298000
    }
  ]
}

Para la evolución día a día de un afiliado usa GET /api/v1/dashboard/timeseries con affiliateId.

GET /api/v1/affiliates/{id}

Permiso: read. Un único AffiliateResponse. Devuelve 404 si el afiliado no está en tu organización.

GET /api/v1/affiliates/applications

Permiso: read. Lista las solicitudes pendientes de aprobación. La misma forma por afiliado que la lista principal, filtrada a status=Pending. Devuelve un array plano paginado con take/skip (sin envoltorio de cursor).

GET /api/v1/affiliates/{id}/tax-form

Permiso: read. Rol: Admin. Devuelve una URL firmada de 5 minutos para descargar el PDF del W-9 / W-8BEN del afiliado. Cada lectura queda en el registro de auditoría.

{
  "id": "tx-form-uuid",
  "affiliateId": "01234567-...",
  "type": "W9",
  "submittedAt": "2026-04-20T14:00:00Z",
  "signedUrl": "https://nyc3.digitaloceanspaces.com/rekomi-tax/...sig=...&exp=...",
  "expiresInSeconds": 300
}

signedUrl es una URL prefirmada con tiempo limitado (5 minutos); no es de un solo uso, así que no la registres en logs, no la compartas y no la guardes en caché. Cuando el formulario lo custodia el proveedor de pagos en lugar de guardarlo Rekomi, el endpoint devuelve { "heldByStripe": true } en lugar de la forma de arriba.

POST /api/v1/affiliates

Permiso: read_write. Creación de afiliados por la vía de administración (se salta el formulario de solicitud). El enlace de seguimiento por defecto del nuevo afiliado se genera automáticamente.

Petición:

{
  "programId": "0789abcd-...",
  "email": "newaffiliate@example.com",
  "fullName": "New Affiliate",
  "status": "Approved",
  "customCommissionType": null,
  "customCommissionValue": null,
  "customAlias": null
}

Respuesta: 201 con el nuevo AffiliateResponse. Dispara affiliate.created. Si status=Approved, también dispara affiliate.approved.

PATCH /api/v1/affiliates/{id}

Permiso: read_write. Actualiza campos del afiliado. Todos opcionales.

{
  "fullName": "Jane Doe (updated)",
  "status": "Approved",
  "customCommissionType": "Percentage",
  "customCommissionValue": 25.0,
  "notes": "Promoted to tier-1 on 2026-05-12.",
  "tags": ["youtube", "tier-1", "vip"]
}

Respuesta: 200 con el AffiliateResponse actualizado.

POST /api/v1/affiliates/{id}/approve

Permiso: read_write. Aprueba una solicitud pendiente. Dispara affiliate.approved.

Cuerpo de la petición: {} (vacío). Respuesta: 200 con el AffiliateResponse actualizado.

POST /api/v1/affiliates/{id}/reject

Permiso: read_write. Rechaza una solicitud pendiente.

{ "reason": "Off-topic audience" }

Respuesta: 200 con el AffiliateResponse actualizado (el estado pasa a Rejected).

POST /api/v1/affiliates/bulk-action

Permiso: read_write. Rol: Admin (JWT) con correo verificado; las llamadas con clave de API pasan la comprobación de rol por diseño. Aplica approve, pause o delete en bloque a hasta 200 afiliados en una sola llamada. Idempotente (volver a aprobar a un afiliado ya aprobado no hace nada), con registro de auditoría por acción.

{ "affiliateIds": ["uuid-1", "uuid-2"], "action": "approve" }

POST /api/affiliates/bulk/approve y POST /api/affiliates/bulk/pause

Aprueba o pausa afiliados en bloque. Son endpoints de sesión del panel (solo JWT de Clerk; no hay alias para clave de API Bearer). Rol: Manager con correo verificado. Hasta 500 ids por llamada.

{ "ids": ["uuid-1", "uuid-2", "..."] }

La respuesta indica cuántas filas se vieron afectadas; los ids que no están en tu organización o que no cumplen la condición previa de la acción se omiten.

GET /api/v1/affiliates/export.csv

Permiso: read. La lista de afiliados completa en CSV, una fila por afiliado (toda la organización, o una campaña con programId), con las columnas de identidad que muestra el panel más las columnas de estadísticas de GET /api/v1/affiliates/stats (clicks, leads, sales, los bloques de comisión, ingresos brutos y netos, currency). since y until opcionales acotan las columnas de estadísticas. Transmite hasta 50,000 filas. Con el mismo límite de peticiones que /stats.

GET /api/v1/affiliates/{id}/commission-summary

Permiso: read. El dinero de un afiliado, agrupado por moneda, con las mismas reglas que usa una ejecución de pagos, así que dueNowCents es exactamente lo que pagaría la próxima ejecución.

{
  "primaryCurrency": "USD",
  "graceDays": 30,
  "hasStripeConnect": true,
  "payoutReady": true,
  "rail": "StripeConnect",
  "blockedReason": null,
  "byCurrency": [
    { "currency": "USD", "dueNowCents": 8000, "pendingInGraceCents": 4000, "paidCents": 45000, "processingCents": 0, "refundedCents": 1200, "totalCommissionCents": 58200, "grossRevenueCents": 310000, "netRevenueCents": 298000, "dueConversionCount": 3 }
  ],
  "referrals": { "visitors": 43, "leads": 2, "conversions": 5 }
}

GET /api/v1/affiliates/{id}/commissions

Permiso: read. Filas de comisión paginadas de un afiliado y un bloque. Consulta: bucket (due | pending | paid | refunded), currency (opcional), page (por defecto 1), pageSize (por defecto 25). Solo se listan las filas que pagan algo; un marcador de lead o clic de $0 nunca aparece. Se incluye la identidad del cliente porque este es el lado de la marca.

{
  "items": [
    { "conversionId": "c0nv0001-...", "programId": "0789abcd-...", "programName": "Spring launch", "amountCents": 9900, "commissionCents": 1980, "netCommissionCents": 1980, "refundedAmountCents": 0, "currency": "USD", "type": "Sale", "payoutStatus": "Paid", "payoutId": "payout-uuid", "customerName": "Sam Lee", "customerEmail": "sam@example.com", "customerAvatarUrl": null, "createdAt": "2026-04-16T11:30:00Z" }
  ],
  "page": 1, "pageSize": 25, "totalCount": 12, "currency": "USD",
  "counts": { "due": 3, "pending": 2, "paid": 6, "refunded": 1 }
}

GET /api/v1/affiliates/{id}/crm-sync

Permiso: read. Una fila por integración CRM conectada con el último trabajo de sincronización de este afiliado.

[
  { "integrationId": "...", "slug": "klaviyo", "displayName": "Klaviyo", "integrationEnabled": true, "defaultListName": "Voltra Affiliates", "jobId": "...", "status": "Succeeded", "attempts": 1, "lastAttemptAt": "2026-09-12T12:19:00Z", "succeededAt": "2026-09-12T12:19:02Z", "error": null }
]

status es NeverSynced cuando todavía no existe ningún trabajo; si no, el estado del trabajo (Pending, Succeeded, Failed, Skipped); error lleva el motivo del fallo o de la omisión.

POST /api/v1/affiliates/{id}/crm-resync

Permiso: read_write. Plan necesario: solo planes de pago (las pruebas reciben 402). Descarta los trabajos de sincronización anteriores del afiliado y vuelve a encolar una sincronización nueva con cada CRM conectado. Devuelve { "deletedPriorJobs": 2 }. Con límite de peticiones.

POST /api/v1/affiliates/{id}/remind-payout-setup

Permiso: read_write. Rol: Admin. Envía un correo a un afiliado que ya ha generado comisión pero todavía no tiene cuenta de cobro, pidiéndole que conecte una. Una vez por afiliado cada 24 horas. Devuelve { "sent": true, "email": "jane@creator.com" }; 409 already_connected cuando ya tiene una; 422 no_email; 429 dentro del periodo de espera.

GET /api/v1/affiliates/{id}/claim-reminder/context

Permiso: read. Para afiliados importados que todavía no han reclamado su cuenta de Rekomi. Devuelve lo que un correo recordatorio puede incorporar: las campañas de la persona, las ganancias acumuladas por moneda, el número de referidos, los valores de ejemplo resueltos de {{claim.campaigns}} y {{claim.earnings}} y el estado del periodo de espera.

{
  "email": "jane@creator.com", "firstName": "Jane",
  "campaigns": [ { "programId": "0789abcd-...", "name": "Spring launch" } ],
  "earnings": [ { "currency": "USD", "totalCommissionCents": 12000 } ],
  "referralCount": 7,
  "resolvedTokens": { "campaigns": "Spring launch", "earnings": "$120.00" },
  "cooldown": { "canSend": true, "retryAfterHours": 0, "sendsRemaining": 3 }
}

409 already_joined cuando la persona ya tiene cuenta, 409 not_eligible para filas pendientes, rechazadas o bloqueadas.

POST /api/v1/affiliates/{id}/claim-reminder

Permiso: read_write. Envía el recordatorio para reclamar la cuenta a una persona. Cuerpo: { "subject": "...", "bodyHtml": "..." }. El cuerpo se sanea en el servidor, las etiquetas de combinación se resuelven al enviar y Rekomi añade el enlace para reclamar la cuenta. Devuelve { "sent": true, "email": "..." }. Errores: 409 already_joined o not_eligible, 422 unsafe_subject, empty_body o no_email, 429 cooldown (24 horas por persona, con Retry-After) o resend_limit_reached. Con límite de peticiones.

POST /api/v1/affiliates/claim-reminder/bulk

Permiso: read_write. Plan necesario: solo planes de pago. Cuerpo: { "ids": ["..."], "subject": "...", "bodyHtml": "..." }, hasta 200 ids. Deduplica por correo, omite a quienes ya se unieron o están en periodo de espera y encola un envío por persona a un ritmo de aproximadamente uno por segundo. Devuelve solo recuentos agregados: { "queued": 18, "skippedJoined": 1, "skippedCooldown": 0, "skippedIneligible": 1 }.

Conversiones

Plan necesario: Starter+ para llamadas con clave de API (acceso programático de lectura y escritura). La creación de conversiones por S2S tiene su propia restricción en Starter+. El panel con JWT no tiene restricción.

Estos endpoints son el seguimiento de comisiones que hay detrás del libro de cuentas de cada afiliado: así es como una conversión se convierte en una comisión que se paga.

GET /api/v1/conversions

Permiso: read. Lista las conversiones. Paginado por cursor.

Consulta: take (máximo 200; ojo, esta lista devuelve 100 filas cuando se omite take, a diferencia de las 50 por defecto de las otras listas), cursor, affiliateId, programId, status (Pending | Approved | Paid | Denied | Refunded | Invalidated), kind (sale | lead | click; la misma división que las pestañas Ventas, Leads y Clics de la página de Conversiones), since (ISO), until (ISO, límite superior exclusivo sobre createdAt), stripeCustomerId (el id de cliente capturado en la conversión; en un postback S2S es el customerId que enviaste) y customerEmail (sin distinguir mayúsculas). Usa status=Invalidated para obtener la cola de revisión de la cuarentena antifraude de clics y leads (CPC/CPL) (tráfico retenido fuera del pago por inválido).

{
  "items": [
    {
      "id": "c0nv0001-...",
      "affiliateId": "01234567-...",
      "programId": "0789abcd-...",
      "amountCents": 9900,
      "currency": "USD",
      "commissionCents": 1980,
      "status": "Approved",
      "type": "Recurring",
      "stripeSubscriptionId": "sub_1ABC...",
      "stripeCustomerId": "cus_1ABC...",
      "externalEventId": "in_1XYZ...",
      "createdAt": "2026-05-10T16:00:00Z",
      "refundedAt": null,
      "attributionMethod": "coupon",
      "couponCode": "SARAH20",
      "subId": null
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

Notas:

  • Enumeración de type: OneTime | Recurring | Bonus | ClickReward | LeadReward.
  • Enumeración de status: Pending | Approved | Paid | Refunded | Denied | Invalidated. Invalidated = tráfico de clics o leads en cuarentena antifraude, retenido fuera del pago; valídalo (libéralo) o invalida una fila Pending desde la página de Conversiones o por la API (ver más abajo).
  • attributionMethod es cómo se atribuyó la venta (por ejemplo coupon, metadata_or_customer, cpc_aggregation, sub_affiliate_override, o null para S2S). El conjunto completo de valores y cómo los agrupa el panel está en la referencia de webhooks. couponCode es el código canjeado cuando (y solo cuando) la venta se atribuyó por cupón; si no, null.
  • Las filas de lead usan type = LeadReward con amountCents a 0. Un alta gratuita identificada (atribución lead_signup) también tiene commissionCents a 0 y vincula el correo de un cliente con el referido antes de cualquier pago; un lead en una campaña que paga por lead (CPL) (atribución lead_form) lleva en commissionCents la tarifa fija por lead de la campaña. Ninguna de las dos es una venta; una venta pagada posterior se registra como una fila OneTime / Recurring aparte. El discriminador fiable de comisión cero es la atribución lead_signup, no el tipo LeadReward. Consulta Seguimiento de leads y altas.
  • payability dice si una fila lleva dinero: payable (una venta, o un lead o clic que la campaña paga; sigue el ciclo de vida de la comisión de arriba), not_paid_on_campaign (un lead o clic registrado en una campaña que no paga por ese tipo; se conserva para atribución y revisión antifraude, nunca es una comisión) o attribution_only (un marcador de lead o clic de $0 en una campaña que sí paga ese tramo; el lead o clic pagado es una fila aparte). Lo llevan tanto la respuesta de lista como la de detalle.
  • stripeSubscriptionId y stripeCustomerId son los identificadores de Stripe de la propia marca (es decir, tus cus_* / sub_*). No son identificadores de Stripe del afiliado (los afiliados no tienen). Úsalos para cruzar las conversiones de Rekomi con tus datos de Stripe.
  • subId es la etiqueta de canal que llevaba la visita del cliente (?sub=yt en el enlace del afiliado), o null si no llevaba ninguna. Filtra la lista con subId=yt, o subId=untagged para las filas sin etiqueta. Consulta Sub-IDs.
  • Para ver una conversión en detalle, incluido el historial de eventos de la suscripción, llama a GET /api/v1/conversions/{id}.

GET /api/v1/conversions/{id}

Permiso: read. Incluye la línea de tiempo de eventos de la suscripción.

{
  "id": "c0nv0001-...",
  "affiliateId": "01234567-...",
  "programId": "0789abcd-...",
  "amountCents": 9900,
  "currency": "USD",
  "commissionCents": 1980,
  "status": "Approved",
  "type": "Recurring",
  "stripeSubscriptionId": "sub_1ABC...",
  "stripeCustomerId": "cus_1ABC...",
  "externalEventId": "in_1XYZ...",
  "createdAt": "2026-05-10T16:00:00Z",
  "paidAt": null,
  "refundedAt": null,
  "refundedAmountCents": 2000,
  "attributionMethod": "coupon",
  "couponCode": "SARAH20",
  "events": [
    { "id": "evt-uuid-1", "eventType": "Charged", "amountCents": 9900, "commissionCents": 1980, "occurredAt": "2026-05-10T16:00:00Z" },
    { "id": "evt-uuid-2", "eventType": "Refunded", "amountCents": -2000, "commissionCents": -400, "occurredAt": "2026-06-02T09:12:03Z" }
  ]
}

refundedAmountCents es el total reembolsado acumulado en unidades menores de la moneda de la conversión; refundedAt solo se fija cuando ese total cubre el importe completo. Cada reembolso aparece también en events como una entrada con eventType Refunded, con un amountCents negativo para ese reembolso y su occurredAt, así que un reembolso cuya respuesta HTTP se perdió se puede confirmar aquí antes de reintentarlo. Los valores de eventType son Created, Charged, Upgraded, Downgraded, Paused, Cancelled, Reactivated y Refunded.

GET /api/v1/conversions/export.csv

Permiso: read. Exportación CSV. Los mismos filtros que el endpoint de lista más until. Tope de 50,000 filas por llamada. Queda en el registro de auditoría.

Fila de cabecera (verificada contra el código):

id,affiliate_id,program_id,amount_cents,currency,commission_cents,status,type,external_event_id,created_at,refunded_at,attribution_method,coupon_code,sub_id

attribution_method, coupon_code y sub_id son las tres últimas columnas (añadidas al final, así que las posiciones de las columnas existentes no cambian). coupon_code solo se rellena en las filas atribuidas por cupón; sub_id es la etiqueta de canal, vacía cuando no hay. Los ids de Stripe se omiten a propósito en el CSV; usa el endpoint JSON si los necesitas.

POST /api/v1/conversions

Permiso: read_write. Rol necesario: Manager o superior con correo verificado (con JWT; las claves de API equivalen a Propietario y pasan). Con el límite de peticiones de la política estricta de escritura.

Registra a mano una venta que ocurrió fuera de tu plataforma de cobro conectada, o crea una comisión extra independiente para un afiliado. La fila pasa por el mismo pipeline que cualquier otra conversión (método de atribución manual), así que se aplican el motor de comisiones de la campaña, los overrides de subafiliados, el webhook conversion.created y la notificación de comisión ganada. La comisión pasa a ser pagadera a través del flujo normal de gracia y umbral. Esto crea dinero pagadero; queda en el registro de auditoría como conversion.manual_created.

Petición:

{
  "programId": "0789abcd-...",
  "affiliateId": "01234567-...",
  "kind": "sale",
  "amountCents": 9900,
  "currency": "USD",
  "commissionCents": null,
  "customerEmail": "buyer@example.com",
  "occurredAt": "2026-05-01T12:00:00Z",
  "note": "Invoice #1042, paid by bank transfer"
}
  • kind: sale (por defecto) | bonus.
  • amountCents: solo para ventas, obligatorio y > 0, en unidades menores de currency. Límite superior de 1,000,000,000,000 unidades menores, el mismo tope de seguridad independiente de la moneda que usa toda ruta de ingesta (por encima de cualquier venta individual plausible). Un bonus tiene que omitirlo (bonus_has_no_amount).
  • currency: opcional; por defecto la moneda principal de tu organización. Tiene que estar en la lista de monedas admitidas (unsupported_currency).
  • commissionCents: en una sale, un override opcional de la comisión que calcula el motor, con tope de 5 veces amountCents (commission_exceeds_cap). En un bonus, obligatorio y > 0, en unidades menores de currency, con el mismo límite superior de 1,000,000,000,000 unidades menores.
  • customerEmail: opcional; vincula la venta con un cliente.
  • occurredAt: fecha retroactiva opcional (ISO 8601). Nunca en el futuro, como máximo 5 años atrás. Una venta retroactiva que ya pasó la ventana de retención por reembolsos se vuelve pagadera de inmediato.
  • note: opcional, recortada a 1,000 caracteres; se devuelve en el envoltorio de la respuesta.

El afiliado tiene que pertenecer al programa elegido y estar Approved (affiliate_not_in_program, 409 affiliate_not_approved). El Afiliado de prueba se rechaza (test_affiliate_not_allowed); usa el evento de prueba de un clic. Una campaña suspendida devuelve 409 program_suspended. Este endpoint no deduplica (cada llamada genera un id de evento interno nuevo), así que un reintento a ciegas crea una segunda conversión; envía una cabecera Idempotency-Key en cualquier petición que puedas llegar a reintentar.

Respuesta: 201 Created.

{
  "conversion": {
    "id": "c0nv0002-...",
    "affiliateId": "01234567-...",
    "programId": "0789abcd-...",
    "amountCents": 9900,
    "currency": "USD",
    "commissionCents": 1980,
    "status": "Pending",
    "type": "OneTime",
    "attributionMethod": "manual",
    "createdAt": "2026-05-01T12:00:00Z"
  },
  "note": "Invoice #1042, paid by bank transfer"
}

Un bonus vuelve con amountCents: 0 y type: "Bonus".

GET /api/v1/conversions/kind-counts

Permiso: read. Recuento histórico de filas por tipo para la organización, sin las filas invalidadas: { "sales": 120, "leads": 34, "clicks": 0 }. El panel lo usa para decidir si mostrar las pestañas Leads y Clics.

Revisión antifraude y presupuesto de clics y leads (CPC/CPL)

Las campañas que pagan por clic o por lead (CPC/CPL), incluidos el endpoint de leads pagados, la cola de revisión antifraude y el estado del presupuesto, están en vista previa limitada. El endpoint de leads pagados devuelve 404 hasta que la vista previa se activa en tu cuenta. Estos endpoints manejan el flujo antifraude de clics y leads y los topes de gasto. Las acciones de escritura requieren el rol Manager.

POST /api/v1/conversions/{id}/validate

Rol: Manager. Devuelve una conversión en cuarentena antifraude (Invalidated) a Pending para que vuelva a entrar en el flujo normal de aprobación, es decir, descarta un falso positivo. Dispara conversion.validated.

POST /api/v1/conversions/{id}/invalidate

Rol: Manager. Pone en cuarentena una conversión Pending o Approved que consideras fraudulenta, marcándola Invalidated para que no se pague. Dispara conversion.invalidated.

GET /api/v1/programs/{id}/budget-status

Permiso: read. El estado del tope de gasto en clics y leads de la campaña: presupuesto total, gastado (comisión no reembolsada) y restante, en unidades menores de la moneda principal de la organización. Ilimitado cuando la campaña no tiene presupuesto definido. El gasto que no se pudo valorar en la moneda principal (una moneda de venta sin tipo de cambio utilizable para la fecha de la fila) se deja fuera de spentCents en lugar de contarse a valor nominal, y se informa en fxUnconvertibleByCurrency, un mapa de código de moneda a unidades menores nativas; ese mapa es la cifra oficial. El escalar antiguo fxUnconvertibleCents se mantiene por compatibilidad, pero es una suma de unidades menores nativas de varias monedas, una señal de presencia más que un importe: cuando no es cero, lee el mapa.

GET /api/v1/fraud-events

Permiso: read. Lista las señales de fraude que Rekomi marcó en clics y leads pagados (IPs de alto riesgo, bots, leads propios, correos desechables, topes por IP alcanzados, afiliados abusivos). Ya se descartaron, sin pago. Consulta: programId, status (open por defecto; también resolved, dismissed o all).

  • PATCH /api/v1/fraud-events/{id} (Manager) con { "action": "resolve" | "dismiss" } revisa una señal.
  • POST /api/v1/fraud-events/ban-affiliate/{affiliateId} (Manager) bloquea a un partner: todos sus clics, leads y conversiones futuros dejan de generar ganancias.

GET /api/v1/fraud-events/summary

Permiso: read. Rol: Manager. Estadísticas agregadas de fraude de una campaña que paga por clic o por lead. Consulta: programId (obligatorio; 400 program_id_required sin él), days (por defecto 30, acotado entre 1 y 365). Devuelve { windowDays, blockedClicks, blockedClicksByReason, heldClicks, quarantinedLeads, estimatedNotBilledCents, currency, fraudStrictness }.

GET /api/v1/uncredited-conversions

Permiso: read. Ventas que llegaron atribuidas a un afiliado que en ese momento no podía generar ganancias (no estaba Approved al vender: pendiente, pausado, rechazado o bloqueado). Consulta: status (open por defecto | dismissed | all), affiliateId. Devuelve hasta 500 filas de { id, affiliateId, affiliateEmail, affiliateName, programId, amountCents, currency, reason, affiliateStatusAtDrop, status, occurredAt }. Endpoints complementarios:

  • GET /api/v1/uncredited-conversions/summary devuelve { openCount, byCurrency: [{ currency, amountCents, count }] }.
  • PATCH /api/v1/uncredited-conversions/{id}/dismiss (Manager) marca una fila como revisada.

Si una fila fue un error (un afiliado pausado por accidente, por ejemplo), corrige el estado del afiliado y acredítale el importe con una conversión manual.

POST /api/v1/lead (lead pagado en una campaña que paga por lead, CPL)

Vista previa limitada (devuelve 404 hasta que se activa en tu cuenta). Registra un lead facturable en una campaña que paga por lead. Cuerpo: { slug, programId?, email, name?, token }, donde token es un token de Cloudflare Turnstile obligatorio. El lead pasa las comprobaciones de formato de correo, dominio desechable, lead propio, deduplicación por campaña, tope diario, presupuesto y fraude de IPQS. Un lead de alto riesgo se pone en cuarentena (Invalidated, 200 opaco); una campaña con el presupuesto agotado devuelve 409 campaign_budget_reached; si la puntuación antifraude no está disponible, la llamada devuelve 503 (reintenta) y no registra nada. Es distinto del lead de alta sin comisión (/api/v1/lead/signup); consulta Seguimiento de leads y altas.

Importación (migración en bloque)

Plan necesario: Starter+ para llamadas con clave de API. El panel con JWT no tiene restricción. Permiso: read_write.

Importación en bloque genérica, independiente de la plataforma de origen. A diferencia del flujo de migración del panel (que interpreta el CSV de un proveedor concreto), aquí envías filas JSON canónicas, así que cualquier origen sirve una vez que lo conviertes a la forma de Rekomi. Las dos vías convergen en los mismos servicios auditados: hay exactamente una ruta que crea afiliados y una que registra conversiones.

Protecciones compartidas por todos los endpoints de abajo:

  • Tope de filas: como máximo 1,000 filas por petición (row_cap_exceeded, 400). Divide en páginas las importaciones más grandes.
  • Tamaño del cuerpo: unos 4 MB de JSON (413 por encima del límite).
  • Límite de peticiones: la política dedicada import, 6 peticiones/min por cliente (429 por encima del límite).
  • Concurrencia: una importación por organización a la vez. Una segunda importación simultánea devuelve 409 migration_already_in_progress (compartido con el importador del panel).
  • Aislamiento por cliente: un programId que no está en tu organización devuelve 404 program_not_found.
  • Reversible: cada importación guarda un MigrationJob; el jobId devuelto aparece en el historial de importaciones y se puede deshacer desde el panel.

POST /api/v1/affiliates/import

Permiso: read_write. Importa en bloque una lista de afiliados. Deduplica por correo dentro de la campaña Y dentro del lote (volver a ejecutarla es idempotente: los correos existentes vuelven como skipped, nunca duplicados). Cada fila recibe un slug de seguimiento conservado o recién generado.

Petición:

{
  "programId": "0789abcd-...",
  "affiliates": [
    { "email": "alex@example.com", "fullName": "Alex Smith", "status": "approved", "paypalEmail": "alex@example.com", "slug": "alex" },
    { "email": "jordan@example.com", "fullName": "Jordan Lee" }
  ],
  "includeStatuses": ["approved", "pending"],
  "notifyAffiliates": false,
  "notificationMessageHtml": null
}
  • email es obligatorio en cada fila. status es opcional y por defecto es approved cuando se omite (el afiliado ya estaba activo en la plataforma anterior); un valor no reconocido cae en pending. Se aceptan: approved | pending | rejected | paused | banned.
  • slug (opcional) conserva el slug de referido que ya tenía el afiliado para que sus enlaces antiguos sigan funcionando; si está ocupado o no es válido, se genera uno nuevo.
  • includeStatuses (opcional) es una lista de permitidos; las filas cuyo estado resultante no está en el conjunto se omiten (status_excluded). Omítelo para importar todas las filas.
  • notifyAffiliates requiere Growth+ con suscripción activa; en un plan inferior la importación se completa igual pero no se envía ningún correo.

Respuesta: 200.

{
  "jobId": "1234abcd-...",
  "status": "Completed",
  "kind": "Affiliates",
  "total": 2,
  "imported": 2,
  "skipped": 0,
  "errored": 0,
  "reasons": {}
}

reasons resume por qué no se importaron algunas filas (por ejemplo already_exists, status_excluded, missing_email).

POST /api/v1/conversions/import/preview

Permiso: read_write. Simulación de una importación de conversiones: clasifica y resuelve afiliados y suma el dinero, pero no escribe nada. Llámalo siempre antes de la importación real para poder mostrar el saldo sin pagar antes de autorizar el pago. La misma forma de fila y la misma validación que el endpoint de importación.

Petición: { "programId": "...", "conversions": [ ... ], "excludePaid": false } (la misma forma de fila que la importación). Pasa el mismo excludePaid que vayas a usar en la importación: cuando es true, las filas pagadas se reportan como omitidas (excluded_paid) y quedan fuera de wouldImport / paidBalance, así que la vista previa coincide exactamente con lo que escribirá la importación.

Respuesta: 200.

{
  "rowsTotal": 2,
  "wouldImport": 2,
  "wouldSkip": 0,
  "wouldError": 0,
  "skipReasons": {},
  "paidBalance": [{ "currency": "USD", "commissionCents": 2500, "count": 1 }],
  "unpaidBalance": [{ "currency": "USD", "commissionCents": 5000, "count": 1 }]
}

unpaidBalance es exactamente cuánta comisión por moneda pasaría a ser pagadera si después importas con confirmUnpaidPayout=true.

POST /api/v1/conversions/import

Permiso: read_write. Importa conversiones y comisiones históricas para que los afiliados migrados conserven sus ganancias y estadísticas (y, con ids de Stripe, las renovaciones futuras se les vuelvan a acreditar). Idempotente (volver a ejecutarla omite las filas ya importadas; nunca paga dos veces).

Petición:

{
  "programId": "0789abcd-...",
  "conversions": [
    {
      "affiliateEmail": "alex@example.com",
      "affiliateSlug": null,
      "customerEmail": "buyer@example.com",
      "customerName": "Buyer One",
      "amountCents": 10000,
      "commissionCents": 2500,
      "currency": "USD",
      "occurredAt": "2025-01-15T00:00:00Z",
      "paid": true,
      "type": "OneTime",
      "stripeCustomerId": "cus_ABC",
      "stripeSubscriptionId": "sub_XYZ",
      "externalId": "src-row-1"
    }
  ],
  "confirmUnpaidPayout": false,
  "excludePaid": false
}

Validación por fila (cualquier fallo devuelve 400 invalid_rows con { index, error } por cada fila problemática, antes de escribir nada):

  • Hace falta al menos uno de affiliateEmail / affiliateSlug (affiliate_email_or_slug_required).
  • amountCents y commissionCents tienen que ser enteros en [0, 1000000000000] (unidades menores de currency; un tope de seguridad independiente de la moneda por encima de cualquier venta individual plausible). Un valor negativo o por encima del tope se rechaza (amount_out_of_range / commission_out_of_range).
  • currency tiene que ser un código ISO 4217 admitido (unsupported_currency).
  • occurredAt es obligatorio (ISO 8601; fija el mes de cohorte histórico).
  • type es OneTime (por defecto) o Recurring (invalid_type).

Seguridad del dinero (lee esto):

  • Las filas con paid: true se registran como historial liquidado (Paid, bloqueado) y nunca se pueden volver a pagar.
  • Las filas con paid: false se registran como historial bloqueado por defecto. Se convierten en un saldo pagadero (Approved, un importe que Rekomi pagará) solo cuando pones confirmUnpaidPayout: true. confirmUnpaidPayout es false por defecto.
  • Importar nunca mueve dinero por sí solo; los pagos los sigue ejecutando un operador y siguen protegidos por Stripe Connect.
  • excludePaid: true omite por completo las filas ya pagadas (importa solo los saldos abiertos).

Respuesta: 200.

{
  "jobId": "1234abcd-...",
  "status": "Completed",
  "kind": "Conversions",
  "total": 1,
  "imported": 1,
  "skipped": 0,
  "errored": 0,
  "unpaidConfirmed": [],
  "unpaidConfirmedCurrency": null,
  "unpaidConfirmedCents": 0,
  "confirmUnpaidPayout": false,
  "excludePaid": false,
  "reasons": {}
}

unpaidConfirmed es la comisión exacta que esta importación convirtió en pagadera (las conversiones Approved que creó), listada por moneda como registros { currency, commissionCents, count } con la misma forma que el unpaidBalance de la vista previa. Un lote que confirmó JPY 1,000 y USD 10.00 devuelve [{ "currency": "JPY", "commissionCents": 1000, "count": 1 }, { "currency": "USD", "commissionCents": 1000, "count": 1 }]. Está vacío siempre que confirmUnpaidPayout es false.

unpaidConfirmedCurrency es el código de esa moneda cuando exactamente una moneda pasó a ser pagadera; si no, null.

unpaidConfirmedCents se conserva para integraciones antiguas. Es una suma bruta de unidades menores nativas de todas las monedas del lote, así que léelo como un importe solo cuando unpaidConfirmedCurrency tiene valor. Cuando unpaidConfirmedCurrency es null, solo indica que algo pasó a ser pagadero; los importes están en unpaidConfirmed.

Pagos

Plan necesario: Starter+ para llamadas con clave de API. El panel con JWT no tiene restricción.

GET /api/v1/payouts

Permiso: read. Lista los pagos (payouts), una fila por afiliado y ejecución. Paginado por cursor.

{
  "items": [
    {
      "id": "payout-uuid",
      "affiliateId": "01234567-...",
      "amountCents": 9800,
      "currency": "USD",
      "method": "StripeConnect",
      "status": "Paid",
      "stripeTransferId": "tr_1ABC...",
      "externalTransactionId": null,
      "notes": null,
      "failureReason": null,
      "periodStart": "2026-04-01",
      "periodEnd": "2026-04-30",
      "createdAt": "2026-05-01T09:00:00Z",
      "paidAt": "2026-05-01T09:00:05Z",
      "failedAt": null,
      "lineItems": [
        { "id": "li-uuid-1", "conversionId": "c0nv0001-...", "amountCents": 1980, "currency": "USD", "nativeAmountCents": 1980, "nativeCurrency": "USD", "fxRate": 1, "fxRateDate": "2026-05-01", "reversedAmountCents": 0, "reversedAt": null },
        { "id": "li-uuid-2", "conversionId": "c0nv0002-...", "amountCents": 7820, "currency": "USD", "nativeAmountCents": 7200, "nativeCurrency": "EUR", "fxRate": 0.9207, "fxRateDate": "2026-04-30", "reversedAmountCents": 0, "reversedAt": null }
      ]
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

Enumeraciones:

  • method en los pagos guardados es StripeConnect, PayPal o GlobalPayouts (Manual solo aparece en filas históricas). Las peticiones pueden enviar StripeConnect o Auto (pagar a cada afiliado por su vía de pago resuelta); Wise no se admite.
  • status: Pending | Processing | Paid | Failed.

Cada fila de pago es el pago de un afiliado en una ejecución, y lineItems lista las comisiones que contiene:

  • amountCents + currency: lo que pagó la línea (USD en las ejecuciones consolidadas; una ejecución antigua de una sola moneda lleva la moneda de esa ejecución).
  • nativeAmountCents + nativeCurrency: la comisión tal como se ganó.
  • fxRate: el tipo de cambio de referencia guardado con base USD al que se convirtió la línea, expresado como unidades mayores nativas por 1 USD (el valor del tipo de cambio de nativeCurrency en fxRateDate; las líneas en USD llevan 1). usd = native / fxRate reproduce la línea, y el tipo se lee como "0.9207 EUR por USD", nunca como USD por unidad nativa.
  • fxRateDate: la fecha en que se publicó el tipo (la fecha de la ejecución en las líneas en USD).
  • reversedAmountCents + reversedAt: una recuperación (clawback) aplicada después del pago (0 / null mientras la línea está intacta).

Los cuatro campos FX son null en los pagos creados antes de que se registrara el tipo de cambio por línea.

GET /api/v1/payouts/{id}

Permiso: read. Un único PayoutResponse (la misma forma que un elemento de la lista).

La financiación es solo desde el panel

La financiación de los pagos (vincular un banco de financiación en cualquier vía, activar la financiación por transferencia bancaria, ejecutar, reintentar o revertir pagos) no se expone a propósito a las claves de API ni a los tokens OAuth: mover dinero requiere una sesión interactiva de Propietario o Administrador en el panel. La API es solo de lectura y vista previa. Consulta Pagos: financiar tus pagos.

GET /api/v1/payouts/funding/status sí se puede leer con una clave de API. Devuelve el modo de financiación (debit o balance), el saldo por transferencia bancaria en centavos cuando el modo es balance, el estado de verificación, payoutsAllowed con payoutsBlockedReason y payoutsBlockedMessage (la frase que muestra el panel) y unverifiedRules (días de retención, el tope móvil, lo usado del tope y lo que queda en la ventana actual). bankTransferInstructions es siempre null para las llamadas con clave de API y OAuth, y canManageFunding es false: los números de la cuenta de depósito dedicada solo se muestran a una sesión interactiva de Propietario o Administrador en el panel.

POST /api/v1/payouts/preview

Rol: Manager o superior. Calcula los saldos elegibles sin confirmar nada. Se puede llamar tantas veces como quieras.

Cuerpo de la petición (todos los campos opcionales):

{
  "programId": null,
  "since": null,
  "affiliateId": null
}
  • programId: limita la vista previa a una campaña.
  • since: solo considera las conversiones desde esta marca de tiempo ISO 8601 en adelante.
  • affiliateId: vista previa de un solo afiliado.

La respuesta informa de los totales elegibles y de los candidatos por afiliado:

  • totalEligibleCents, candidateCount, candidatesWithStripeConnectCount
  • graceDays y homeCurrency
  • eligibleByCurrency: totales elegibles por moneda sobre todos los candidatos, en unidades menores nativas de cada moneda
  • unconvertibleByCurrency: unidades menores nativas por moneda que no se pudieron valorar en la moneda principal (sin tipo guardado utilizable); totalEligibleInHomeCurrencyCents las deja fuera
  • nativeTotalsForRun: sumas elegibles nativas por moneda sobre los candidatos listos para cobrar. Es exactamente el mapa que el panel confirma al ejecutar el pago, y su conjunto de claves es el conjunto de monedas que cubre la ejecución
  • fxUnavailableCurrencies: monedas retenidas fuera de la ejecución porque no existe un tipo de cambio de referencia reciente guardado; sus saldos siguen acumulándose y pasan a ser pagaderos cuando vuelven los tipos
  • usdEstimateAtRunRateCents: una estimación en USD, solo para mostrar, de todo lo pagadero a los tipos guardados hoy (los pagos se liquidan en USD; la cifra final se fija cuando se ejecuta la ronda)
  • fxRunRates: mapa de código de moneda a { rate, asOf }, el tipo de cambio de referencia guardado con base USD al que se convertiría cada moneda de la vista previa, como unidades mayores nativas por 1 USD (USD es 1), ausente para las monedas de fxUnavailableCurrencies. El valor en USD de un bloque es round(nativeCents / minorUnitsPerMajor(native) / rate * 100)
  • campos de comisión de plataforma que describen lo que Rekomi retiene en la ejecución previsualizada
  • candidates[]: una entrada por afiliado con affiliateId, affiliateEmail, currency, eligibleCents, eligibleConversionIds, payoutReady y blockedReason (por qué un afiliado todavía no puede cobrar, por ejemplo porque le falta la cuenta de cobro)

Una ejecución genera un pago en USD por afiliado a partir de las monedas confirmadas, convirtiendo cada comisión al tipo guardado de la fecha de la ejecución y dejando en cada línea el importe nativo, el tipo y la fecha del tipo (los campos de lineItems de arriba).

POST /api/v1/payouts/run

Solo con sesión del panel. Ejecutar un pago no se puede disparar con una clave de API ni con un token OAuth; cualquier llamada con clave de API recibe 403 interactive_session_required. Solo una sesión de Propietario iniciada en el panel puede lanzar una ejecución de pagos.

Como referencia, la llamada del panel acepta confirmTotalCents (comprobación de seguridad obligatoria), más affiliateIds, programId, since, currency (por defecto "USD"), method, externalTransactionId, notes y conversionIds, todos opcionales. confirmTotalCents tiene que coincidir con el total calculado por el servidor; si no coinciden (por ejemplo, porque una conversión se cerró entre la vista previa y la ejecución), la petición devuelve 409 { "error": "confirm_total_mismatch" }; vuelve a previsualizar y reintenta. Cada ejecución dispara payout.created por destinatario, y después payout.paid o payout.failed.

Confianza y seguridad (2026-09-05). Una ejecución puede devolver cuatro códigos 409 más: payouts_require_active_subscription (la organización está en prueba o no tiene un plan de pago activo), unverified_prefund_only (una organización sin verificar intentó ejecutar contra un mandato de débito bancario; financia por transferencia bancaria o solicita la verificación), unverified_cap_exceeded (la ejecución dejaría a una organización sin verificar por encima de su tope móvil; el mensaje lleva las cifras) y funding_frozen (la financiación de pagos está en pausa tras una disputa bancaria sobre un cargo de financiación; el mensaje indica escribir a support@rekomi.com). Un quinto, high_risk_unverified, vuelve de una ejecución y de los endpoints de configuración de financiación cuando la puntuación de fraude de una organización sin verificar alcanza o supera el umbral que fijan los superadministradores de Rekomi (60 por defecto): la financiación y los pagos esperan hasta que una persona de Rekomi aprueba la cuenta para financiar o la verifica, y el estado de financiación lleva verificationRequired: true junto al código. Un sexto, identity_required, vuelve de una ejecución y de los endpoints de financiación cuando Rekomi exige una verificación de identidad (una puntuación de fraude que alcanza o supera el umbral que fijan para ello los superadministradores de Rekomi, o un requisito impuesto por un revisor a la marca) hasta que la marca supera la comprobación de documento oficial y selfie de Stripe o un superadministrador retira la exigencia; se comprueba antes que high_risk_unverified, y el estado de financiación lleva identityRequired: true junto al código. Una ejecución también puede completarse con todas las filas marcadas needsManualReview: true: la ejecución queda retenida para revisión de Rekomi antes de cualquier cargo de financiación, no se cobra ni se paga nada hasta que se aprueba, y las filas pasan al flujo normal de financiación (o a Failed) cuando se decide la revisión. El recibo de la ejecución muestra reviewStatus y, para organizaciones sin verificar, holdUntil: la financiación liquidada espera el periodo de retención antes de pagar a los afiliados. Consulta Verificación y revisiones de pagos.

POST /api/v1/payouts/{id}/retry

Solo con sesión del panel. Reintenta un pago Failed. Igual que /run, este endpoint rechaza cualquier llamada con clave de API u OAuth con 403 interactive_session_required; solo una sesión de Propietario iniciada en el panel puede reintentar. Si va bien, dispara los mismos eventos que /run.

GET /api/v1/payouts/automatic/preview

Permiso: read. Simulación de la programación de pagos automáticos: qué pagaría la próxima ejecución, quién pasa a la siguiente ronda por no llegar al mínimo y quién tiene dinero esperando pero ninguna cuenta conectada.

{
  "enabled": true, "cadence": "Weekly", "minPayoutCents": 2000,
  "lastAutomaticPayoutAt": "2026-09-22T14:00:00Z", "nextRunAtUtc": "2026-09-29T14:00:00Z",
  "wouldPay": { "affiliateCount": 6, "totalCents": 41800, "byCurrency": { "USD": 41800 } },
  "belowMinimum": { "affiliateCount": 2, "totalCents": 1500, "byCurrency": { "USD": 1500 } },
  "notConnected": { "affiliateCount": 1, "totalCents": 9000, "byCurrency": { "USD": 9000 } }
}

GET /api/v1/payouts/ledger

Permiso: read. El libro mayor de la plataforma para tu organización: cargos a la marca, pagos a afiliados y reversiones, de más reciente a más antiguo. Consulta: take, skip.

[
  { "id": "...", "payoutId": "...", "affiliateId": "...", "direction": "Debit", "type": "BrandFunding", "amountCents": 10094, "currency": "USD", "rail": "StripeAch", "railReferenceId": "py_...", "occurredAt": "2026-09-01T09:00:00Z", "reconciliationStatus": "Settled" }
]

GET /api/v1/payouts/receipts

Permiso: read. Un recibo por cada ejecución de pagos financiada. Consulta: take, skip.

[
  { "id": "...", "receiptNumber": "R-2026-0031", "currency": "USD", "grossCents": 98000, "platformFeeCents": 2940, "affiliateFeeCents": 1125, "passthroughCents": 0, "netToAffiliatesCents": 96875, "brandTotalCents": 100940, "payoutCount": 5, "billingCase": "BrandFunded", "brandFundingChargeId": "py_...", "brandFundingStatus": "Succeeded", "periodStart": "2026-08-01", "periodEnd": "2026-08-31", "createdAt": "2026-09-01T09:00:00Z", "settledAt": "2026-09-03T00:00:00Z", "reversedAt": null }
]

GET /api/v1/payouts/receipts/{id} devuelve el mismo elemento bajo receipt más organizationName y affiliates, una fila por pago (payoutId, affiliateId, affiliateName, affiliateEmail, grossCents, platformFeeCents, affiliateFeeCents, netCents, currency, status, reversed y fxLines para los pagos consolidados en varias monedas). GET /api/v1/payouts/receipts/{id}/receipt.html muestra el recibo en HTML y GET /api/v1/payouts/receipts/{id}/receipt.csv descarga las filas. En cualquier otro caso, 404 receipt_not_found.

Acciones de pago solo desde el panel

POST /api/v1/payouts/funding/setup, POST /api/v1/payouts/funding/bank-transfer/enable, POST /api/v1/payouts/funding/bank-transfer/disable, POST /api/v1/payouts/verification-request, POST /api/v1/payouts/{id}/reverse y POST /api/v1/payouts/{id}/reverse-lines mueven dinero o cambian cómo se financia, así que requieren una sesión iniciada en el panel. Una clave de API recibe 403 en ellos.

Registro de auditoría

Plan necesario: Pro+ para llamadas con clave de API (exportación para SIEM o cumplimiento). El panel de Propietario con JWT no tiene restricción y recibe el esquema completo. Las llamadas con clave de API reciben además una respuesta redactada (los campos de IP, UserAgent y UserId interno del operador van a null en el JSON; la cabecera del CSV se reduce a 8 columnas).

GET /api/v1/audit-log

Permiso: read. Rol: Owner (solo con JWT; las claves de API se saltan la comprobación de rol, pero la respuesta va redactada; ver más abajo).

Consulta: action, entityType, since (ISO), until (ISO), page (por defecto 1), pageSize (por defecto 50, máximo 100).

Las llamadas con clave de API reciben un payload redactado, sin los datos personales del operador (IPs, UserIds internos, UserAgents). Las llamadas con JWT del panel reciben el payload completo para el análisis forense dentro del producto. Los filtros de consulta actorUserId e ip también están desactivados para las llamadas con clave de API (en línea con la redacción, para que no puedan inferir valores).

// API-key response (redacted)
{
  "page": 1,
  "pageSize": 50,
  "total": 1234,
  "items": [
    {
      "id": "audit-uuid",
      "action": "program.created",
      "entityType": "program",
      "entityId": "0789abcd-...",
      "actorType": "user",
      "actorUserId": null,
      "ip": null,
      "userAgent": null,
      "before": null,
      "after": "{\"id\":\"0789abcd-...\",\"name\":\"Default program\",\"...\":...}",
      "createdAt": "2026-05-01T12:00:00Z"
    }
  ]
}

actorType clasifica quién o qué inició la acción; los valores son user (operador de la marca autenticado con Clerk), api_key (llamada programática con rk_live_*), mcp (llamada a través de MCP con rk_mcp_*), system (trabajo en segundo plano / Hangfire) y admin (acción desde el portal de superadministración). Se expone a las llamadas con clave de API porque es una categoría, no un dato personal.

GET /api/v1/audit-log/export.csv

Permiso: read. Rol: Owner (la misma redacción que el endpoint JSON).

Cabecera del CSV con clave de API (redactada, 8 columnas):

id,created_at,action,entity_type,entity_id,actor_type,before,after

Cabecera del CSV con JWT del panel (completa, 11 columnas):

id,created_at,action,entity_type,entity_id,actor_type,actor_user_id,ip,user_agent,before,after

Tope de 10,000 filas. En el registro de auditoría solo se añaden entradas, nunca se borran; no se puede editar ni eliminar nada por la API.

Métricas del panel

Plan necesario: Starter+ para llamadas con clave de API. El panel con JWT no tiene restricción.

Métricas agregadas del lado de la marca. Rol: Manager con JWT; las claves de API se saltan la comprobación y leen.

GET /api/v1/dashboard/summary

Permiso: read. Devuelve los indicadores principales de la ventana activa (el parámetro de consulta since es por defecto hace 30 días).

{
  "totalClicks": 1842,
  "totalConversions": 87,
  "totalLeads": 134,
  "totalEarningsCents": 1734500,
  "conversionRate": 4.7232,
  "activeAffiliates": 23,
  "pendingPayoutsCents": 412000,
  "homeCurrency": "USD",
  "earningsUnconvertibleByCurrency": [],
  "pendingPayoutsUnconvertibleByCurrency": []
}

conversionRate es el valor en porcentaje (por ejemplo, 4.72 = 4.72%) redondeado a 4 decimales. Las conversiones Refunded y Denied quedan fuera de totalConversions y totalEarningsCents. Los campos de dinero están normalizados a tu homeCurrency; los importes que no pudimos convertir (sin tipo de cambio para esa moneda) se informan por moneda en earningsUnconvertibleByCurrency y pendingPayoutsUnconvertibleByCurrency, en lugar de sumarse a los totales sin avisar. totalLeads cuenta todas las filas de lead de la ventana (altas gratuitas identificadas más leads de campañas que pagan por lead); consulta Seguimiento de leads y altas.

GET /api/v1/dashboard/timeseries

Permiso: read. Series temporales para gráficos.

Consulta: metric (obligatorio: clicks | conversions | commissions | leads | payouts | refunds | revenue), since, until, granularity (hoy solo day; las ventanas de más de 400 días se agrupan por mes), affiliateId (opcional: limita la serie a un afiliado, que es lo que lee la vista Actividad en la página de detalle de un afiliado; funciona con todas las métricas salvo payouts), programId (opcional: limita a una campaña). Suma los valores de count para obtener el total de la ventana, por ejemplo el número de clics de un afiliado.

metric=leads devuelve el recuento diario de todas las filas de lead (altas gratuitas identificadas más leads de campañas que pagan por lead); consulta Seguimiento de leads y altas.

{
  "metric": "conversions",
  "granularity": "day",
  "since": "2026-04-14T00:00:00Z",
  "until": "2026-05-14T00:00:00Z",
  "points": [
    { "bucket": "2026-04-14", "count": 3 },
    { "bucket": "2026-04-15", "count": 5 },
    { "bucket": "2026-04-16", "count": 0 }
  ]
}

En las métricas de dinero (payouts, commissions, refunds, revenue), el campo count es la suma diaria normalizada por tipo de cambio en unidades menores (a pesar del nombre); revenue son los importes brutos de venta, commissions son las ganancias de los afiliados. En clicks, conversions y leads, count es un recuento literal.

GET /api/v1/dashboard/leaderboard

Permiso: read. Los mejores afiliados según una métrica.

Consulta: metric (clicks | conversions | earnings | epc), limit (por defecto 10, máximo 50), since, programId (opcional: clasifica solo a los afiliados de una campaña).

[
  { "affiliateId": "01234567-...", "fullName": "Jane Doe", "email": "jane@creator.com", "value": 12 },
  { "affiliateId": "abcdef00-...", "fullName": "Joe Smith", "email": "joe@example.com", "value": 9 }
]

value es el número de conversiones del afiliado (metric=conversions), el número de clics (clicks), la suma de commissionCents en la moneda principal (earnings) o las ganancias por clic en centavos (epc, comisión normalizada por tipo de cambio dividida entre los clics; solo cuentan los afiliados con al menos un clic). email es el correo del afiliado (son tus propios datos).

GET /api/v1/dashboard/traffic-sources

Permiso: read. Desglose de clics por fuente, clasificados por canal. Las 20 fuentes principales; cada fila lleva un channel: paid (gclid/msclkid/ttclid o referidores de anuncios; ojo, fbclid por sí solo se clasifica como social, porque Facebook lo añade también cuando se comparte de forma orgánica), search, social, email, ai (referidores de ChatGPT/Perplexity/Claude), signin (proveedores de autenticación), onsite (el propio sitio de la marca), portal (páginas de registro alojadas por Rekomi), bot, referral o direct.

Consulta: since, until, programId (opcional: una campaña), affiliateId (opcional: un afiliado).

[
  { "source": "youtube.com", "channel": "social", "count": 540, "percentage": 32.5 },
  { "source": "Google Ads", "channel": "paid", "count": 312, "percentage": 18.8 },
  { "source": "(direct)", "channel": "direct", "count": 280, "percentage": 16.9 }
]

Los referidores vacíos o que no se pueden interpretar se agrupan como (direct).

GET /api/v1/dashboard/export.csv

Permiso: read. Exportación CSV de las series temporales (solo metric=clicks|conversions|payouts, más since / until).

date,conversions
2026-04-14,3
2026-04-15,5

Insights (analítica)

Plan necesario: Starter+ para llamadas con clave de API. El panel con JWT no tiene restricción. Rol: Manager con JWT; las claves de API se saltan la comprobación y leen. Permiso: read.

Desgloses más profundos del lado de la marca bajo GET /api/v1/dashboard/insights/{module} (alias de /api/metrics/insights/{module}). Cada módulo acepta since, until, programId (una campaña), affiliateId (un afiliado) y format=csv para descargar las mismas filas en CSV (protegido contra la inyección de fórmulas en hojas de cálculo). Todo el dinero está normalizado por tipo de cambio a tu moneda principal; las filas cuya moneda no tiene un tipo guardado utilizable para su fecha se dejan fuera y se informan por moneda (ver overview más abajo). Se construyen solo con datos que Rekomi ya registra, así que las vistas que atribuyen una venta a una dimensión de clic tienen en cuenta la cobertura: solo las conversiones con un clic de origen llevan esa dimensión. sale-origin informa de una fracción numérica coverage (conversiones atribuidas frente al total); geography y devices agrupan las ventas sin dimensión de clic bajo (unknown) en lugar de dar a entender una atribución completa.

Módulos:

  • overview: clicks, conversions, conversionRate, epcCents, aovCents, grossRevenueCents, commissionCents, refundedConversions, refundRate, recurringConversions, recurringSharePct, homeCurrency. También devuelve leads (número de altas), clickToLeadRate y leadToSaleRate (las dos como fracciones 0..1); consulta Seguimiento de leads y altas. El dinero que no se pudo valorar en la moneda principal (una moneda de venta sin tipo guardado utilizable para la fecha de la fila) se deja fuera de grossRevenueCents, aovCents, commissionCents y epcCents en lugar de contarse a valor nominal, y se informa por moneda en unidades menores nativas: fxUnconvertibleByCurrency para las filas de ingresos y fxUnconvertibleCommissionByCurrency para las filas de comisión (cada uno null cuando todo se pudo convertir). Esos mapas son las cifras oficiales. El escalar antiguo fxUnconvertibleCents se mantiene por compatibilidad, pero es una suma de unidades menores nativas de varias monedas, una señal de presencia más que un importe: cuando no es cero, lee los mapas. La descarga CSV lleva los mismos tres como fx_unconvertible_cents, fx_unconvertible_by_currency y fx_unconvertible_commission_by_currency (cada mapa escrito como pares CODE:minorUnits separados por espacios).
  • sale-origin: principales hosts de origen por conversions + revenueCents, más attributedConversions / totalConversions / coverage.
  • geography: clicks, conversions y revenueCents por país.
  • devices: reparto Mobile / Tablet / Desktop / Bot de clicks + conversions.
  • utm: consulta dimension (source | medium | campaign); clicks, conversions y revenueCents por valor.
  • time-patterns: celdas de día de la semana (0=domingo) x hora del día (UTC) con clicks + conversions.
  • time-to-convert: bloques <1h / 1-24h / 1-7d / >7d.
  • funnel: clicks -> conversions -> approved -> paid. Cada paso es { step, count }; el panel muestra la proporción de cada paso respecto al anterior (calculada en el cliente, no devuelta como campo de la API). Cuando hay datos de leads en la ventana, se inserta de forma adaptativa una etapa leads entre clicks y conversions (clicks -> leads -> conversions -> approved -> paid); las marcas sin leads en la ventana nunca ven una fila de leads vacía.
  • attribution: reparto Coupon / Link / Other de conversions, revenueCents y commissionCents.
  • recurring: mezcla de pago único y recurrente, mrrByMonth (a partir de los cargos de suscripción), churnedSubscriptions.
  • customers: recuentos de clientes nuevos y recurrentes (cliente de Stripe repetido) + revenueCents (no se devuelve la identidad del cliente).
  • top-products: los productos más vendidos por ingresos referidos. La cobertura incluye Shopify, Stripe, Paddle y Chargebee (líneas de pedido), Gumroad, Lemon Squeezy, Polar, Creem y Dodo (pedidos de un solo producto), Mollie (cuando el pago lleva líneas de pedido) y las suscripciones de Braintree; Recurly todavía no está cubierto. revenueCents es el subtotal de la línea antes de descuentos, no el importe con descuento que realmente se pagó.
// GET /api/v1/dashboard/insights/sale-origin
{
  "sources": [{ "source": "youtube.com", "conversions": 12, "revenueCents": 184000 }],
  "attributedConversions": 41,
  "totalConversions": 58,
  "coverage": 0.7069,
  "homeCurrency": "USD"
}

Los afiliados tienen un equivalente limitado a su propio ámbito y sin datos personales de clientes bajo GET /api/me/insights/{module} (overview, sale-origin, geography, devices, links, time-patterns, utm, channels), cada uno también con affiliateId (para centrarse en una membresía) y format=csv. Devuelven solo los recuentos y la comisión de quien llama más hosts, países, clases de dispositivo, slugs de enlace, sub-ids y bloques de tiempo, nunca la identidad del cliente.

Embed (iframe de marca blanca)

Plan necesario: Growth+ (se aplica tanto con JWT como con clave de API, porque el embed es una función de marca blanca, no solo acceso a la API). Devuelve 402 { "error": "plan_tier_required", required: "Growth", current: "Starter" } en planes inferiores.

POST /api/v1/embed/tokens

Permiso: read_write. Genera un token de iframe por afiliado.

{
  "affiliateId": "01234567-...",
  "allowedOrigins": "https://yourapp.com,https://app.yourapp.com",
  "rotate": false,
  "expiresInHours": 24
}
  • allowedOrigins: orígenes con URL completa separados por comas (esquema + host + puerto). Igualdad estricta en el endpoint público del iframe; sin comodines, sin coincidencia por StartsWith.
  • rotate: cuando es false y ya existe un token para este par (program, affiliate), la respuesta devuelve solo metadatos (alreadyExists: true) y ningún token en texto plano. Cuando es true, el token existente se sustituye y se devuelve un texto plano nuevo.
  • expiresInHours: por defecto 24. Acotado a [1, 720] (30 días como máximo).

Respuesta (token nuevo o rotado):

{
  "token": "ZGVtbzAxYWJjZGVm...",
  "allowedOrigins": "https://yourapp.com,https://app.yourapp.com",
  "expiresAt": "2026-05-15T12:00:00Z"
}

Respuesta (el token ya existe, rotate=false):

{
  "id": "embed-token-uuid",
  "allowedOrigins": "https://yourapp.com,https://app.yourapp.com",
  "expiresAt": "2026-05-15T12:00:00Z",
  "alreadyExists": true
}

El token en texto plano se devuelve exactamente una vez. Guárdalo en el servidor de tu aplicación de inmediato; Rekomi solo guarda su hash SHA-256 y no puede recuperar el texto plano.

POST /api/v1/embed/tokens/{id}/revoke

Permiso: read_write. Revoca un token vigente.

Cuerpo: {}. Respuesta: { "ok": true }.

GET /api/embed/public/dashboard?token=...

Sin autenticación, pero protegido por token y por Origin. Lo usa directamente el iframe en el navegador. Devuelve las ganancias del afiliado y la personalización de la marca.

{
  "affiliateName": "Jane Doe",
  "programName": "Default program",
  "earnedCents": 12450,
  "paidCents": 9800,
  "pendingCents": 2650,
  "brandColor": "#0E7C7B",
  "brandName": "Your Brand",
  "recentConversions": [
    {
      "id": "c0nv0001-...",
      "amountCents": 9900,
      "commissionCents": 1980,
      "status": "Approved",
      "createdAt": "2026-05-10T16:00:00Z"
    }
  ]
}

Fallos:

  • 400: falta el parámetro de consulta token
  • 401: cuerpo vacío {} O { "error": "token_expired" } si el expiresAt del token ya pasó
  • 403: { "error": "no_allowed_origins_configured" } | { "error": "origin_required" } | { "error": "origin_invalid" } | { "error": "origin_not_allowed" }

La comprobación de Origin exige que la petición envíe una cabecera Origin Y que ese origen coincida (esquema + host + puerto) con una entrada de allowedOrigins. Las llamadas servidor a servidor sin cabecera Origin se rechazan.

earnedCents, paidCents y pendingCents se calculan sobre las 50 conversiones más recientes del afiliado, no sobre todo el historial.

GET /api/v1/embed/dashboard

Sin autenticación. Los datos que muestra el iframe de marca blanca, leídos con el token por afiliado de POST /api/v1/embed/tokens: consulta token. Se comprueba contra los orígenes permitidos del token. Devuelve affiliateName, programName, earnedCents, paidCents, pendingCents, brandColor, brandName y recentConversions (hasta 20 filas con id, amountCents, commissionCents, status y createdAt).

Seguimiento S2S

Plan necesario: Starter+. Las organizaciones en periodo de prueba siempre se aceptan (14 días gratis en cualquier plan). Las organizaciones por debajo de Starter que no están en prueba reciben 402.

POST /api/tracking/s2s

Separado del espacio /api/v1/*, que solo usa Bearer, porque S2S añade una comprobación de integridad HMAC encima del Bearer.

Cabeceras:

X-Rekomi-Api-Key: rk_live_xxxx
X-Rekomi-Signature: t=1715366423,sig=8f4e2c5b...
Content-Type: application/json

(Authorization: Bearer rk_live_xxxx también funciona en lugar de X-Rekomi-Api-Key.)

Cuerpo de la petición:

{
  "externalEventId": "purchase_abc123",
  "affiliateSlug": "jane-recommends",
  "amountCents": 9900,
  "currency": "USD",
  "customerId": "cus_external_xyz"
}

Campos opcionales del cuerpo: customerName, customerEmail, customerAvatarUrl, subId y commissionCents (tu propia comisión para esta venta en unidades menores, de 0 a 5 veces amountCents, que sustituye la cifra del motor; la misma validación que POST /api/v1/conversions, con 400 invalid_commission / 400 commission_exceeds_cap). Una tarifa por cliente fijada en la página de Clientes se aplica aquí por customerId o customerEmail.

Respuesta (nueva):

{ "ok": true, "conversionId": "c0nv0001-..." }

Respuesta (duplicada, segura ante reenvíos; el mismo externalEventId ya se había registrado para esta organización):

{ "ok": true, "deduped": true }

Exclusividad mutua: mientras una conexión nativa con un procesador esté activa (Stripe Connect, Paddle, Braintree, Lemon Squeezy, las apps de Shopify, Wix y BigCommerce, el plugin de WooCommerce, Chargebee, Polar, Recurly, Gumroad, Creem, Dodo o Mollie), el endpoint devuelve 409 con el código de error correspondiente (stripe_connect_active, paddle_connect_active, braintree_connect_active, lemonsqueezy_connect_active, shopify_connect_active, wix_connect_active, bigcommerce_connect_active, wordpress_connect_active, chargebee_connect_active, polar_connect_active, recurly_connect_active, gumroad_connect_active, creem_connect_active, dodo_connect_active, mollie_connect_active) para que la misma venta nunca se cuente dos veces.

Consulta Seguimiento S2S para el cálculo completo de la firma, la protección contra reenvíos y los ejemplos por lenguaje.

POST /api/tracking/lead

Registra un lead (un alta gratuita identificada, un correo vinculado al referido) en lugar de una venta. La misma autenticación que /api/tracking/s2s (clave de API Bearer o X-Rekomi-Api-Key, más el HMAC X-Rekomi-Signature), y los mismos conflictos de exclusividad 409 *_connect_active mientras una conexión nativa con un procesador esté activa. Un lead por sí solo no genera comisión; una venta posterior con el mismo correo se acredita al afiliado que lo refirió a través del respaldo por coincidencia de correo, aunque la cookie de clic ya no exista.

Cuerpo de la petición:

{
  "affiliateSlug": "jane-recommends",
  "email": "user@example.com",
  "name": "Jane Doe",
  "externalEventId": "signup_abc123"
}
  • affiliateSlug (obligatorio): el afiliado al que acreditar. La comparación no distingue mayúsculas, así que SERKAN y serkan acreditan al mismo afiliado.
  • email (obligatorio): el correo del cliente con el que se cotejará una venta posterior.
  • name (opcional) y externalEventId (opcional, se usa para deduplicar y que los reintentos sean seguros).
  • subId (opcional): la etiqueta de canal que llevaba el alta; una venta posterior con el mismo correo la hereda.

Consulta Seguimiento de leads y altas para el equivalente Rekomi.convert() en el navegador, la ruta automática con Stripe / Paddle y cómo funciona la atribución por coincidencia de correo.

Página pública (sin autenticación)

Estos endpoints no requieren clave de API; tienen límite de peticiones por IP.

GET /api/p/by-handle/{handle}/{campaign?}

Información pública del programa para la página de destino que ven los afiliados, limitada a una organización. Anónimo; con límite de peticiones por IP. El {handle} es el subdominio con marca de la organización (el {handle} de {handle}.rekomi.com); primero se localiza la organización por el handle y después la campaña dentro de ella por el slug. Omite {campaign} para obtener la campaña principal de la organización (la que se sirve en la raíz {handle}.rekomi.com).

Esto sustituye a la antigua búsqueda por slug global GET /api/p/{slug}, que se retiró porque los slugs de campaña son únicos solo dentro de cada organización, no globalmente.

{
  "id": "0789abcd-...",
  "organizationName": "Your Brand",
  "name": "Default program",
  "slug": "default",
  "description": "Earn 20% recurring on every annual plan.",
  "termsUrl": "https://yourbrand.com/affiliate-terms",
  "customAliasSupported": true
}

La respuesta completa trae más de lo que se muestra arriba: también incluye organizationDescription, la configuración de comisión (defaultCommissionType, defaultCommissionValue, defaultCommissionModel), cookieWindowDays, recurringMonths, attributionModel, autoApprove, isPubliclyDiscoverable, landingPageConfig y las URLs del logo y el favicon de la marca, todo lo que la página pública necesita para mostrarse.

Un slug de campaña retirado (renombrado) devuelve 200 { "redirect": true, "campaign": "<current-slug>" } para que quien llama pueda seguir hasta el slug actual. Devuelve 404 Not Found cuando el handle no corresponde a ninguna organización, o para campañas inactivas o archivadas. No se expone ningún GUID de organización más allá del id del programa.

GET /api/p/by-domain?host={host}

Resuelve un dominio personalizado (un dominio propio de la marca, por ejemplo affiliates.yourbrand.com; disponible en todos los planes) a su handle de organización y al slug de su campaña principal. Anónimo; con límite de peticiones por IP.

{ "handle": "yourbrand", "slug": "default" }

Devuelve 404 Not Found cuando el host no es un dominio personalizado verificado de ninguna organización.

POST /api/p/id/{programId}/apply

Envía una solicitud de afiliado. La ruta se indexa por el GUID del programa ({programId}), no por su slug, porque los slugs de campaña son únicos solo dentro de cada organización, no globalmente. Obtén primero el GUID con GET /api/p/by-handle/{handle}/{campaign?} (el campo id). Anónimo; limitado a 5 peticiones/min por IP. Dispara affiliate.created; si el programa tiene autoApprove=true, también dispara affiliate.approved.

Petición:

{
  "email": "newaffiliate@example.com",
  "fullName": "New Affiliate",
  "website": "https://creator.example.com",
  "audience": "200k YouTube subscribers in the fitness niche",
  "whyInterested": "Already an evangelist for the product",
  "customAlias": "newaff-fit"
}

Todos los campos salvo email son opcionales. customAlias tiene que cumplir [a-z0-9-]{3,64}.

Respuesta: el endpoint devuelve una única forma uniforme y anonimizada para impedir la enumeración de solicitantes. Nunca devuelve el id real del afiliado ni el slug de su enlace; affiliateId es siempre el GUID todo ceros y affiliateLinkSlug es siempre null. Una solicitud duplicada (el mismo correo ya solicitó entrar en este programa) devuelve exactamente la misma forma que una solicitud nueva.

{
  "affiliateId": "00000000-0000-0000-0000-000000000000",
  "status": "Pending",
  "affiliateLinkSlug": null,
  "accountExists": false,
  "email": "newaffiliate@example.com",
  "message": "Application received."
}
  • accountExists: si el solicitante ya tiene una cuenta de afiliado de Rekomi con este correo (el formulario público lo usa para enviarle a iniciar sesión).
  • email: el propio correo del solicitante, devuelto tal cual.

Fallos:

  • 400: fallo de validación de la petición; devuelve un objeto problem details estándar ({ type, title, status, errors }), no el envoltorio de regla de negocio
  • 404: programa no encontrado o inactivo
  • 409: { "error": "alias_already_taken" } o { "error": "program_at_capacity", "message": "..." }

Referencia de cabeceras

CabeceraDirecciónPropósito
Authorization: Bearer rk_live_*PeticiónClave de API Bearer (todos los endpoints autenticados).
X-Rekomi-Api-Key: rk_live_*Petición (solo S2S)Alternativa a Authorization en /api/tracking/s2s.
X-Rekomi-Signature: t=<unix>,sig=<hex>Petición (solo S2S)HMAC sobre <unix>.<body> con tu secreto de firma rks_*.
Idempotency-Key: <uuid>PeticiónAdmitida en todo POST y PATCH que puedas reintentar (importaciones, invitaciones, creación de afiliados). Ventana de reenvío de 60 minutos. Misma clave + mismo cuerpo → respuesta original; misma clave + cuerpo distinto → 409.
Idempotency-Replayed: trueRespuestaPresente cuando una respuesta se reproduce desde una llamada idempotente anterior.
X-Rekomi-Signature: t=<unix>,v1=<hex>Saliente (entrega de webhooks)Firma HMAC de los payloads de webhook salientes. Usa v1= para verificar webhooks (frente a sig= en el S2S entrante; son rutas de código distintas).
X-Rekomi-Timestamp: <unix>Saliente (entrega de webhooks)Marca de tiempo en segundos Unix sobre la que se calcula la firma.
X-Rekomi-Event: <type>Saliente (entrega de webhooks)Tipo de evento para enrutar sin interpretar el cuerpo.
X-Rekomi-Delivery-Id: <uuid>Saliente (entrega de webhooks)Clave de deduplicación para los reintentos.

Configuración

GET /api/v1/settings/home-currency

Devuelve la HomeCurrency actual de la organización, la marca de tiempo del último cambio, la lista de códigos ISO 4217 admitidos y si el plan de quien llama permite cambiarla (plan Pro o superior).

{
  "homeCurrency": "USD",
  "changedAt": null,
  "supportedCurrencies": [
    "AED", "AFN", "ALL", "AMD", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM",
    "BBD", "BDT", "BHD", "BIF", "BMD", "BND", "BOB", "BRL", "BSD", "BWP",
    "BYN", "BZD", "CAD", "CDF", "CHF", "CLP", "CNY", "COP", "CRC", "CVE",
    "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ETB", "EUR", "FJD", "FKP",
    "GBP", "GEL", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HTG",
    "HUF", "IDR", "ILS", "INR", "ISK", "JMD", "JOD", "JPY", "KES", "KGS",
    "KHR", "KMF", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD",
    "LSL", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MUR", "MVR",
    "MWK", "MXN", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD",
    "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON",
    "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SEK", "SGD", "SHP", "SLE",
    "SOS", "SRD", "SZL", "THB", "TJS", "TND", "TOP", "TRY", "TTD", "TWD",
    "TZS", "UAH", "UGX", "USD", "UYU", "UZS", "VND", "VUV", "WST", "XAF",
    "XCD", "XCG", "XOF", "XPF", "YER", "ZAR", "ZMW"
  ],
  "canChange": true
}

PUT /api/v1/settings/home-currency

Cambia la HomeCurrency. Requiere plan Pro o superior. La operación es idempotente cuando el valor anterior y el nuevo coinciden; queda en el registro de auditoría como org.home_currency_changed. Las conversiones históricas conservan su moneda nativa; solo la normalización del panel al leer se recalcula contra la nueva moneda principal.

Cuerpo:

{ "homeCurrency": "EUR" }

Respuesta:

{ "homeCurrency": "EUR", "changed": true, "changedAt": "2026-05-18T05:42:00Z" }

Fallos:

  • 400 unsupported_currency: no está en la lista de admitidas.
  • 402 plan_tier_required: quien llama está en Starter o Growth.
  • 403: quien llama no es Propietario o no tiene el correo verificado.

Guía conceptual completa: Multimoneda para marcas. Detalles de la ingesta: Moneda de las conversiones.

Integraciones CRM

Plan necesario: Starter+ para llamadas con clave de API. Permiso: read.

GET /api/v1/integrations/crm

Solo las integraciones de CRM y plataformas de email conectadas; un proveedor sin conexión simplemente no aparece. Una fila por integración, ordenadas por slug: provider, slug, enabled, syncCustomers, salesAttributionEnabled, salesAttributionStatus, salesAttributionCheckedAt, salesAttributionCredited y webhookRegisteredAt. El estado de sincronización por afiliado está en GET /api/v1/affiliates/{id}/crm-sync.

Reclutamiento de subafiliados

Plan necesario: incluido en todos los planes para activarlo en una campaña. Los endpoints del lado del afiliado (/me/sub-affiliate/*) no tienen restricción una vez que la campaña lo activa.

Override acotado de 2 niveles: el afiliado A recluta a B; A gana B.commission × Program.SubAffiliateCommissionPercent / 100 en cada venta que cierra B. Un solo nivel de reclutamiento, con tope fijo; sin propagación en cadena, nunca multinivel. Las filas de override tienen amountCents = 0, commissionCents > 0, attributionMethod = "sub_affiliate_override" y parentAffiliateConversionId apuntando a la fila de la venta padre. Página de concepto completa: Reclutamiento de subafiliados. Guía completa para desarrolladores con los payloads de webhook: API de subafiliados.

GET /api/v1/programs/{id}/sub-affiliate-config

Permiso: read. Devuelve la configuración actual de la campaña.

{
  "enabled": true,
  "percent": 10.0
}

PUT /api/v1/programs/{id}/sub-affiliate-config

Permiso: read_write. Rol: Owner. Plan: incluido en todos los planes. Verificación de correo: obligatoria. Queda en el registro de auditoría como program.sub_affiliate_config_changed.

{ "enabled": true, "percent": 10 }

Fallos:

HTTPerrorCausa
400unsupported_valuePorcentaje fuera de [0, 100]
403email_not_verifiedEl Propietario no ha verificado su correo
403(vacío)Quien llama no es Propietario
404(vacío)El programa no está en tu organización

GET /api/v1/me/sub-affiliate/link?programId={id}

Permiso: solo JWT de Clerk (lado del afiliado). Devuelve la URL de reclutamiento personal del afiliado que llama.

{
  "affiliateId": "01234567-...",
  "programId": "0789abcd-...",
  "programSlug": "default",
  "url": "https://{handle}.rekomi.com/default?recruited_by=v6media"
}

El token recruited_by prioriza el slug: el slug ?via= de la cuenta del afiliado cuando tiene uno, si no el slug de su enlace en la campaña, y si no el GUID del id de afiliado. Devuelve 400 program_id_required sin el parámetro de consulta, 400 sub_affiliate_recruiting_disabled cuando la campaña tiene la opción desactivada, 403 cuando el afiliado que llama no está Approved, 404 cuando la campaña no es visible para el afiliado que llama y 409 portal_not_configured cuando la marca no tiene un host de portal público.

GET /api/v1/me/sub-affiliate/recruits

Permiso: solo JWT de Clerk (lado del afiliado). Los reclutados del afiliado que llama. Paginado por cursor.

{
  "items": [
    {
      "affiliateId": "fed00b00-...",
      "email": "recruit@example.com",
      "fullName": "Recruited Person",
      "status": "Approved",
      "totalCommissionGeneratedCents": 12400,
      "overrideEarnedCents": 1240,
      "currency": "USD",
      "joinedAt": "2026-05-12T10:00:00Z"
    }
  ],
  "nextCursor": null
}

GET /api/v1/affiliates/{id}/sub-affiliates

Permiso: read. Vista detallada del lado de la marca de los reclutados de cualquier afiliado. Devuelve un array plano (sin envoltorio de paginación).

[
  {
    "id": "fed00b00-...",
    "email": "recruit@example.com",
    "fullName": "Recruited Person",
    "status": "Approved",
    "totalCommissionCents": 12400,
    "overrideEarnedCents": 1240,
    "currency": "USD"
  }
]

Añadido al formulario de solicitud

POST /api/p/id/{programId}/apply acepta una referencia opcional al reclutador en el cuerpo: recruitedBy (cadena: GUID del id de afiliado, slug del enlace en la campaña o slug ?via= de la cuenta) o el heredado recruitedByAffiliateId (GUID). Cuando la referencia corresponde a un afiliado Approved de la misma campaña, se rellena el RecruitedByAffiliateId del nuevo afiliado. Los valores que no se pueden resolver se ignoran sin avisar; el autorreclutamiento (mismo usuario de Clerk o mismo correo) se descarta sin avisar mientras la solicitud sigue adelante; no se vincula ningún reclutador mientras la opción de reclutamiento de la campaña está desactivada.

Perfil de la organización

Estos endpoints están en su ruta canónica /api/organizations/me (sin alias /v1).

GET /api/organizations/me

Permiso: read. Devuelve el perfil completo de la organización que llama: nombre, slug, subdominio con marca y su contador y tope de cambios, correo de facturación, zona horaria, color de marca, URLs del logo y el favicon, descripción, indicador de marca blanca, plan, estado de la suscripción, fin de la prueba, días de gracia de los pagos (y el máximo permitido en el plan actual) y la configuración de pagos automáticos.

{
  "id": "01234567-...",
  "name": "Acme",
  "slug": "acme",
  "subdomain": "acme",
  "subdomainChangeCount": 0,
  "subdomainChangesMax": 2,
  "billingEmail": "billing@acme.com",
  "timezone": "America/Los_Angeles",
  "primaryBrandColor": "#3B0764",
  "logoUrl": "https://cdn.rekomi.com/...",
  "faviconUrl": null,
  "description": "Acme makes the world's best widgets.",
  "whiteLabelEnabled": false,
  "planTier": "Growth",
  "subscriptionStatus": "Active",
  "trialEndsAt": null,
  "payoutGraceDays": 30,
  "payoutGraceDaysMax": 90,
  "automaticPayoutEnabled": false,
  "automaticPayoutCadence": "Manual",
  "minPayoutCents": 0,
  "lastAutomaticPayoutAt": null
}

La respuesta también lleva la categoría de sector de la marca y los campos del catálogo de parámetros de atribución que usa la interfaz del panel.

Las escrituras (PATCH /api/organizations/me, POST /api/organizations/me/logo, etc.) siguen siendo solo con JWT y rol de Propietario. Las claves de API y los tokens MCP no pueden modificar el perfil.

Estado de facturación

GET /api/billing/state

Permiso: read. Devuelve el plan de la organización, el estado de la suscripción, el fin de la prueba, el estado de la vinculación con Stripe y una instantánea de los límites del plan. Es el endpoint canónico que hay que llamar antes de recomendar una vía de instalación: stripeConnectLinked = true significa que los webhooks del checkout de la organización llegan a Rekomi automáticamente (el nombre del campo se conserva por estabilidad del contrato; la vinculación es la app de Rekomi para Stripe); false significa que la organización no ha vinculado Stripe para atribuir conversiones y necesita códigos de cupón, el píxel del navegador o S2S para atribuirlas.

{
  "planTier": "Growth",
  "subscriptionStatus": "Active",
  "billingProvider": "Stripe",
  "trialEndsAt": null,
  "interval": "Monthly",
  "stripeSubscriptionId": "sub_...",
  "stripeCustomerLinked": true,
  "stripeConnectLinked": true,
  "couponsEnabled": true,
  "limits": {
    "affiliates": { "current": 12, "max": null },
    "campaigns": { "current": 2, "max": null },
    "partnerPayoutsThisMonthCents": { "current": 285000, "max": 1500000 },
    "teamSeats": { "current": 1, "max": 5 }
  },
  "stripeConnectedVia": "StripeApp"
}

billingProvider es cómo se factura a la organización (por ejemplo Stripe o Shopify). couponsEnabled indica si la función de cupones se puede usar. stripeConnectedVia es StripeApp cuando la cuenta de Stripe de la organización está vinculada a través de la app de Rekomi, o null cuando Stripe no está vinculado; siempre coincide con stripeConnectLinked.

Los endpoints de Stripe Checkout, el portal y los métodos de pago siguen siendo solo con JWT. Las claves de API y los tokens MCP no pueden abrir nuevas sesiones de Checkout ni modificar la facturación.

Invitaciones a afiliados

Flujo de invitación de la marca al afiliado. Vive en /api/affiliate-invites (sin alias /v1). El endpoint en bloque requiere un plan de pago Starter+; la invitación individual está disponible en todos los planes, prueba incluida.

POST /api/affiliate-invites

Permiso: read_write. Rol: Manager+. Verificación de correo: obligatoria para las llamadas desde el panel (JWT); las claves de API y los tokens MCP están exentos.

Crea una invitación. Devuelve la fila de la invitación más una URL de aceptación de un solo uso.

Cuerpo:

{
  "programId": "01234567-...",
  "email": "alex@example.com",
  "fullName": "Alex Example",
  "slug": "alex",
  "personalNoteHtml": "<p>Hi Alex, would love to have you on our affiliate program.</p>",
  "customCommissionType": "Percentage",
  "customCommissionValue": 30,
  "autoApprove": true
}

El campo opcional slug conserva el slug que el afiliado ya tenía en una plataforma anterior (caso de uso de migración directa). Cuando se envía, el flujo de aceptación lo asigna como nuevo AffiliateLink.Slug si sigue pasando la validación de forma (de 3 a 64 caracteres, [a-z0-9-], sin guion al principio ni al final) Y sigue siendo único globalmente. Si no, el flujo de aceptación recurre a un slug aleatorio y muestra un aviso. En el primer inicio de sesión del afiliado se convierte en el slug de referido de su cuenta (el que se comparte entre todas las campañas y se usa como ?via={slug}); si ya tiene una cuenta de afiliado en Rekomi, se conserva el slug que ya tenía. El servidor devuelve 409 slug_already_taken si el slug ya está en uso al crear la invitación; 400 slug_reserved si coincide con la lista de palabras reservadas (api, admin, etc.); 400 con field: "slug" si falla la validación de caracteres o longitud.

personalNoteHtml se sanea con RichTextSanitizer (basado en el analizador Ganss.Xss) a una lista estricta de permitidos: p, br, strong, b, em, i, u, ul, ol, li, a. El único atributo permitido es href en <a>, restringido a URLs https://. Todo lo demás se elimina. Etiquetas de combinación admitidas: {{affiliate.firstName}}, {{program.commission}}, {{brand.name}}. Las etiquetas se resuelven después del saneado, así que sus valores no pueden colar marcado.

Respuesta:

{
  "invite": {
    "id": "...",
    "programId": "...",
    "programName": "...",
    "email": "alex@example.com",
    "state": "Pending",
    "expiresAt": "2026-05-26T...",
    "...": "..."
  },
  "acceptUrl": "https://app.rekomi.com/invites/affiliate/<one-time-token>"
}

Fallos:

  • 400 validation_failed con field: correo ausente o inválido, programId ausente.
  • 409 affiliate_already_exists: ya existe un afiliado con este correo en el programa.
  • 409 pending_invites_limit_reached: la organización tiene 500 invitaciones pendientes.

POST /api/affiliate-invites/bulk

Permiso: read_write. Rol: Manager+. Verificación de correo: obligatoria para las llamadas con JWT. Plan: Starter+ con SubscriptionStatus = Active (los usuarios en prueba reciben 402 paid_plan_required por diseño; la vía de posible abuso del correo masivo no tiene pase libre por MCP).

Hasta 50 correos por llamada. Los duplicados dentro del lote y los correos ya asociados a afiliados existentes se omiten sin avisar. Las invitaciones aceptadas se envían por correo a un ritmo constante y controlado.

Se aceptan dos formas de cuerpo. La forma más nueva, recipients, es la recomendada para migraciones porque permite conservar el slug de cada afiliado; la forma heredada emails sigue disponible por compatibilidad.

Forma recomendada:

{
  "programId": "01234567-...",
  "recipients": [
    { "email": "alex@example.com", "slug": "alex", "fullName": "Alex Example" },
    { "email": "ben@example.com", "slug": "ben-r" },
    { "email": "carol@example.com" }
  ],
  "personalNoteHtml": "<p>We're migrating from Tapfiliate. Same commission, same campaign.</p>",
  "autoApprove": true
}

Forma heredada (sin slug por fila):

{
  "programId": "01234567-...",
  "emails": ["alex@example.com", "ben@example.com", "carol@example.com"],
  "personalNoteHtml": "<p>...</p>",
  "autoApprove": true
}

Cuando se envían tanto recipients como emails, gana recipients.

Respuesta:

{
  "created": 3,
  "skipped": 0,
  "invites": [ /* InviteResponse[] */ ],
  "slugConflicts": [
    { "email": "ben@example.com", "requestedSlug": "alex", "reason": "duplicate_within_batch" }
  ]
}

slugConflicts informa fila a fila de los slugs solicitados que se rechazaron (ocupado globalmente, reservado, caracteres inválidos o duplicado dentro del mismo lote). Esas filas reciben igualmente su invitación; al aceptarla recurren a un slug aleatorio nuevo. Usa el array para mostrar en tu interfaz un aviso del tipo "estos 3 afiliados no recibieron el slug que pidieron".

Fallos:

  • 400 validation_failed: lote vacío o demasiado grande, programId inválido.
  • 402 paid_plan_required: organización en prueba o por debajo de Starter.
  • 409 pending_invites_limit_reached: la organización tiene 500 invitaciones pendientes.

Ciclo de vida

  • GET /api/affiliate-invites (solo JWT): lista las invitaciones filtradas por programId y state (Pending / Accepted / Expired / Revoked).
  • POST /api/affiliate-invites/{id}/resend (solo JWT): rota el token y reenvía.
  • DELETE /api/affiliate-invites/{id} (solo JWT): revoca una invitación pendiente.
  • GET /api/affiliate-invites/by-token/{token} (anónimo, con límite de peticiones): vista previa de la marca y el programa de una invitación sin aceptar.
  • POST /api/affiliate-invites/by-token/{token}/accept (anónimo, con límite de peticiones): acepta la invitación. Crea la fila Affiliate (Approved o Pending según AutoApprove). Idempotente: volver a aceptar devuelve el id de afiliado original.

Generador del fragmento de instalación

GET /api/v1/r/install-snippet

Permiso: read. Genera en el servidor el fragmento <script> de instalación canónico con el id de programa real de la organización que llama, los parámetros de atribución personalizados (cuando están configurados en Configuración > Atribución), la captura de correo y, opcionalmente, la clave pública del píxel ya incrustados. Lo usa la herramienta MCP get_install_snippet para que un agente de IA pueda entregar a una marca el texto exacto que debe pegar sin componer atributos HTML por su cuenta; la tarjeta de instalación del panel genera la misma etiqueta desde sus propias plantillas.

Parámetros de consulta opcionales:

  • programId (Guid): qué programa o campaña incrustar. Por defecto, el programa activo más reciente de la organización.
  • withPixel (booleano): incluir data-rekomi-org para la vía de disparo de conversiones por el píxel del navegador. Requiere que antes se haya aprovisionado una clave pública del píxel en /dashboard/setup/install. Devuelve 409 pixel_not_provisioned cuando es true y no existe ninguna clave.
  • emailCapture (booleano): si la etiqueta lleva data-rkmi-email-capture="auto". Omitido o true = activado, el valor por defecto de toda etiqueta que entrega Rekomi; false genera la etiqueta sin el atributo. Con la captura activada, Rekomi registra el correo que un visitante referido escribe en cualquier campo de correo o de texto de las páginas donde corre la etiqueta (registro, inicio de sesión, checkout y otros formularios) para que la venta se pueda acreditar aunque el checkout no pase ningún referido. Sin referido no se registra nada. La marca también puede quitar el atributo de una etiqueta ya pegada para desactivarlo; las llamadas explícitas a Rekomi.convert() siguen funcionando.

Respuesta:

{
  "snippet": "<!-- Rekomi tracking -->\n<script async src=\"https://api.rekomi.com/api/v1/r/loader.js\" data-program-id=\"01234567-...\" data-rkmi-email-capture=\"auto\" data-rkmi-params=\"my_aff,brand_ref\"></script>\n<noscript>\n  <img src=\"https://api.rekomi.com/api/v1/r/c.gif\" width=\"1\" height=\"1\" alt=\"\" />\n</noscript>",
  "programId": "01234567-...",
  "programSlug": "default",
  "withPixel": false,
  "hasCustomAttributionParams": true,
  "customAttributionParams": "my_aff,brand_ref",
  "scriptHost": "https://api.rekomi.com",
  "usingTrackingDomain": false,
  "emailCapture": true
}

emailCapture en la respuesta indica si la etiqueta generada lleva el atributo, así que quien llama puede mostrar la línea de arriba junto a la etiqueta sin interpretar el HTML. scriptHost es el host desde el que carga la etiqueta (el dominio de seguimiento propio verificado de la marca cuando hay uno activo; si no, el host de la API) y usingTrackingDomain indica cuál de los dos.

Fallos:

HTTPerrorCausa
404no_program_foundNingún programa coincide en la organización que llama (o todavía no hay programas activos)
409pixel_not_provisionedwithPixel=true pero la organización no tiene clave pública del píxel
403forbiddenLa clave de API no tiene el permiso necesario; el cuerpo lleva un mensaje que nombra el permiso

Seguro contra XSS por construcción: cada campo incrustado en el fragmento viene del servidor (el id de programa es un Guid, los parámetros personalizados se vuelven a validar con AttributionParamsService.ParseCustom contra [a-z0-9_-]{2,32}, la clave pública del píxel viene de la base de datos). Ningún dato controlado por quien llama acaba en la salida HTML.

Captura de leads (navegador)

POST /api/v1/r/lead/signup

El endpoint público del navegador que hay detrás de Rekomi.convert() / Rekomi.identify(). Registra un lead (un alta gratuita identificada) contra el referido actual, enviado por el loader de seguimiento mediante sendBeacon / fetch con keepalive. CORS de seguimiento público, con límite de peticiones por IP. Para evitar la enumeración de altas, siempre devuelve un 200 opaco, se haya registrado un lead o no.

Cuerpo:

{ "slug": "jane-recommends", "email": "user@example.com", "name": "Jane Doe", "programId": "0789abcd-..." }

slug (el slug de referido resuelto) es obligatorio; programId limita el lead a una campaña; name es opcional. El loader de Rekomi (Rekomi.convert) resuelve el referido a partir de la cookie de Rekomi del visitante y envía por ti el slug resuelto (y el programId) en el cuerpo. No llamas a este endpoint en bruto directamente; usa Rekomi.convert({ email }) del loader. Con Stripe y Paddle, los leads se capturan automáticamente sin ninguna llamada. Consulta Seguimiento de leads y altas.

El servidor MCP alojado expone la herramienta equivalente record_lead (affiliateSlug, email, name opcional, campaignId); consulta MCP.

Parámetros de atribución (migración directa)

Estos endpoints controlan qué parámetros de consulta reconoce el loader de Rekomi para la atribución de afiliados. Los 21 valores canónicos por defecto (los que usan Rewardful, Affonso, Tapfiliate, FirstPromoter, UpPromote, GoAffPro, BixGrow y otras plataformas de afiliados importantes) se reconocen siempre; las marcas pueden añadir hasta 10 parámetros personalizados para plataformas de nicho.

GET /api/v1/settings/attribution-params/defaults

Público, sin autenticación. Devuelve la lista canónica de valores por defecto más el envoltorio de validación (máximo de entradas personalizadas, máximo de caracteres totales, límites de longitud por parámetro). Lo usan la interfaz del panel y el sitio de marketing para mostrar la cuadrícula de chips sin tener el catálogo escrito a mano.

{
  "defaults": ["via", "ref", "fpr", "aff", "afmc", "rfsn", "sca_ref", "bg_ref", "a_aid", "atp", "affonso", "awc", "sscid", "cjevent", "irclickid", "partner_key", "affid", "affiliate_id", "affcode", "idev", "mbsy"],
  "maxCustomEntries": 10,
  "maxTotalChars": 256,
  "minParamLength": 2,
  "maxParamLength": 32
}

Con límite de peticiones según la política anonymous-tracking.

GET /api/v1/settings/attribution-params

Permiso: read. Devuelve la configuración actual de la organización que llama más el orden de prioridad efectivo combinado.

{
  "custom": "myparam,brand_ref",
  "defaults": ["via", "ref", "fpr", "aff", "..."],
  "effectiveOrder": ["myparam", "brand_ref", "via", "ref", "..."],
  "maxCustomEntries": 10,
  "maxTotalChars": 256
}

custom es null cuando la marca no ha configurado ningún parámetro personalizado; en ese caso effectiveOrder es igual a defaults. Las entradas personalizadas se deduplican contra los valores por defecto al leer, así que el mismo parámetro nunca aparece dos veces en effectiveOrder.

PATCH /api/v1/settings/attribution-params

Permiso: read_write. Rol: Owner (se omite con el esquema de autenticación api_key, según el comportamiento estándar del atributo de rol). Verificación de correo: obligatoria para las llamadas con JWT (se omite con api_key). Queda en el registro de auditoría como org.attribution_params_changed con el valor anterior y el nuevo.

Cuerpo:

{ "custom": "myparam,brand_ref" }

Envía null o "" para borrar la personalización y volver a solo los valores por defecto.

Fallos:

HTTPerrorCausa
400attribution_params_too_longEl cuerpo supera los 256 caracteres
400too_many_attribution_paramsMás de 10 entradas
400invalid_attribution_paramUna entrada no cumple [a-z0-9_-]{2,32} (la respuesta incluye las entradas rechazadas en un array invalid)
403(vacío)Sin rol de Propietario y sin clave de API
404(vacío)Organización no encontrada

Cada cambio correcto genera una única fila en el registro de auditoría con el valor anterior y el nuevo. El loader recoge la nueva configuración en la siguiente carga de página del sitio de la marca (sin más retraso de caché que el Cache-Control de 1 hora de la respuesta del loader).

Siguientes pasos

  • Autenticación: genera y gestiona claves.
  • Webhooks: recibe eventos, verifica firmas, gestiona reintentos.
  • Seguimiento S2S: ingesta de conversiones fuera de Stripe.
  • Seguimiento de leads y altas: captura altas gratuitas y coteja por correo una venta posterior.
  • Embed: aloja el panel de afiliados en tu dominio.
  • Servidor MCP: integración con asistentes de IA con 61 herramientas, incluido un asistente de instalación.
  • Zapier: automatizaciones sin código con más de 8,000 apps. 9 triggers, 9 acciones, 4 búsquedas.
  • Moneda de las conversiones: lista de códigos ISO 4217, forma de los errores, comportamiento del tipo de cambio.

En esta página

ProgramasGET /api/v1/programsGET /api/v1/programs/{id}GET /api/v1/programs/statsPOST /api/v1/programsPATCH /api/v1/programs/{id}DELETE /api/v1/programs/{id}GET /api/v1/programs/{id}/tracking-statusGET /api/v1/programs/{id}/recent-eventsGET /api/v1/programs/check-slugPATCH /api/v1/programs/{id}/slugGET /api/v1/programs/{id}/tracking-status/lookupPOST /api/v1/programs/{id}/custom-domain/verifyPOST /api/v1/programs/{id}/test-eventAfiliadosGET /api/v1/affiliatesGET /api/v1/affiliates/statsGET /api/v1/affiliates/{id}GET /api/v1/affiliates/applicationsGET /api/v1/affiliates/{id}/tax-formPOST /api/v1/affiliatesPATCH /api/v1/affiliates/{id}POST /api/v1/affiliates/{id}/approvePOST /api/v1/affiliates/{id}/rejectPOST /api/v1/affiliates/bulk-actionPOST /api/affiliates/bulk/approve y POST /api/affiliates/bulk/pauseGET /api/v1/affiliates/export.csvGET /api/v1/affiliates/{id}/commission-summaryGET /api/v1/affiliates/{id}/commissionsGET /api/v1/affiliates/{id}/crm-syncPOST /api/v1/affiliates/{id}/crm-resyncPOST /api/v1/affiliates/{id}/remind-payout-setupGET /api/v1/affiliates/{id}/claim-reminder/contextPOST /api/v1/affiliates/{id}/claim-reminderPOST /api/v1/affiliates/claim-reminder/bulkConversionesGET /api/v1/conversionsGET /api/v1/conversions/{id}GET /api/v1/conversions/export.csvPOST /api/v1/conversionsGET /api/v1/conversions/kind-countsRevisión antifraude y presupuesto de clics y leads (CPC/CPL)POST /api/v1/conversions/{id}/validatePOST /api/v1/conversions/{id}/invalidateGET /api/v1/programs/{id}/budget-statusGET /api/v1/fraud-eventsGET /api/v1/fraud-events/summaryGET /api/v1/uncredited-conversionsPOST /api/v1/lead (lead pagado en una campaña que paga por lead, CPL)Importación (migración en bloque)POST /api/v1/affiliates/importPOST /api/v1/conversions/import/previewPOST /api/v1/conversions/importPagosGET /api/v1/payoutsGET /api/v1/payouts/{id}POST /api/v1/payouts/previewPOST /api/v1/payouts/runPOST /api/v1/payouts/{id}/retryGET /api/v1/payouts/automatic/previewGET /api/v1/payouts/ledgerGET /api/v1/payouts/receiptsAcciones de pago solo desde el panelRegistro de auditoríaGET /api/v1/audit-logGET /api/v1/audit-log/export.csvMétricas del panelGET /api/v1/dashboard/summaryGET /api/v1/dashboard/timeseriesGET /api/v1/dashboard/leaderboardGET /api/v1/dashboard/traffic-sourcesGET /api/v1/dashboard/export.csvInsights (analítica)Embed (iframe de marca blanca)POST /api/v1/embed/tokensPOST /api/v1/embed/tokens/{id}/revokeGET /api/embed/public/dashboard?token=...GET /api/v1/embed/dashboardSeguimiento S2SPOST /api/tracking/s2sPOST /api/tracking/leadPágina pública (sin autenticación)GET /api/p/by-handle/{handle}/{campaign?}GET /api/p/by-domain?host={host}POST /api/p/id/{programId}/applyReferencia de cabecerasConfiguraciónGET /api/v1/settings/home-currencyPUT /api/v1/settings/home-currencyIntegraciones CRMGET /api/v1/integrations/crmReclutamiento de subafiliadosGET /api/v1/programs/{id}/sub-affiliate-configPUT /api/v1/programs/{id}/sub-affiliate-configGET /api/v1/me/sub-affiliate/link?programId={id}GET /api/v1/me/sub-affiliate/recruitsGET /api/v1/affiliates/{id}/sub-affiliatesAñadido al formulario de solicitudPerfil de la organizaciónGET /api/organizations/meEstado de facturaciónGET /api/billing/stateInvitaciones a afiliadosPOST /api/affiliate-invitesPOST /api/affiliate-invites/bulkCiclo de vidaGenerador del fragmento de instalaciónGET /api/v1/r/install-snippetCaptura de leads (navegador)POST /api/v1/r/lead/signupParámetros de atribución (migración directa)GET /api/v1/settings/attribution-params/defaultsGET /api/v1/settings/attribution-paramsPATCH /api/v1/settings/attribution-paramsSiguientes pasos