> ## Documentation Index > Fetch the complete documentation index at: https://userepass.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Registra uma conversão via tracker client-side (público) > Rota pública autenticada pela publishable key (`pk_*`) no header `X-Repass-Key` — nunca pela chave secreta. Registra uma conversão disparada pelo tracker no browser (`source: script`). A organização é derivada da publishable key. Idempotente por `sourceEventId`. Se a organização não confia no client-side, a conversão fica `pending` sem comissão até ser confirmada pelo S2S (`POST /conversions`) com o mesmo `sourceEventId`. Responde 201 quando cria, 200 em replay/dedup/não atribuída. ## OpenAPI ````yaml /openapi.json post /track/conversion openapi: 3.1.0 info: title: Repass API description: >- API pública do Repass — plataforma de gestão de afiliados: programas, links, tracking, atribuição, conversões, comissões, payouts, fiscal (BR), reprocessamento, event store e webhooks. version: 0.1.0 servers: - url: https://api.userepass.com description: Produção security: - bearerAuth: [] - apiKeyAuth: [] tags: - name: Profile description: Perfil do usuário autenticado. - name: Guide description: >- Guia de onboarding do painel: estado de tours, telas visitadas e preferências por usuário e organização. - name: Portal description: >- Portal do afiliado: sessão por identidade de afiliado (sem org), convites e claim. - name: Programs description: 'Programas de afiliados: configuração, atribuição, hold e tiers.' - name: Commission Rules description: Regras de comissão versionadas (imutáveis) por programa. - name: Affiliates description: 'Ciclo de vida do afiliado: cadastro, aprovação, tier, saldo.' - name: Terms description: Termos do programa, versionados. - name: Materials description: >- Materiais (criativos) do programa: upload pelo gestor e download pelos afiliados. - name: Links description: Links rastreáveis e domínios de redirecionamento. - name: Coupons description: Cupons de afiliado e sync com gateway. - name: Pagamentos por PIX description: Habilitação de pagamentos por PIX (onboarding e documentos). - name: Tracking description: Endpoints públicos de redirect e registro de cliques. - name: Clicks description: Consulta de cliques e estatísticas de link. - name: Conversions description: 'Conversões: ingestão S2S, atribuição, matching, fraude e auditoria.' - name: Commissions description: Comissões calculadas, holds, aprovação, void e clawback. - name: Payouts description: Ciclos de pagamento, prévia, execução e comprovantes. - name: Invoices description: Notas fiscais (PJ), envio e validação (BR). - name: Fraud description: Fila de revisão e decisões de fraude. - name: Reprocess description: Reprocessamento com dry-run obrigatório e relatório de impacto. - name: Events description: Histórico de eventos para auditoria e consulta. - name: Notifications description: >- Notificações ao operador (falhas de sincronização, payouts e afins) — registro in-app espelhado por e-mail aos owners/admins. - name: Webhooks description: Endpoints de webhook, entregas, retries e dead-letter. - name: Ingest description: Ingestão de eventos de cobrança (S2S e gateways). - name: Settings description: Configurações por organização (políticas e integrações). - name: Billing description: 'Plano e cobrança: contadores de uso da organização para o painel.' - name: Dashboard description: >- Métricas agregadas da operação (receita, top afiliados, conversões, comissões, novos afiliados) para a home e os relatórios do gestor. - name: Health description: Liveness do serviço. paths: /track/conversion: post: tags: - Tracking summary: Registra uma conversão via tracker client-side (público) description: >- Rota pública autenticada pela publishable key (`pk_*`) no header `X-Repass-Key` — nunca pela chave secreta. Registra uma conversão disparada pelo tracker no browser (`source: script`). A organização é derivada da publishable key. Idempotente por `sourceEventId`. Se a organização não confia no client-side, a conversão fica `pending` sem comissão até ser confirmada pelo S2S (`POST /conversions`) com o mesmo `sourceEventId`. Responde 201 quando cria, 200 em replay/dedup/não atribuída. operationId: trackConversion requestBody: required: true content: application/json: schema: type: object properties: type: type: string enum: - subscription_created - one_time_purchase - trial_converted - upgrade - custom description: >- Tipo da conversão. `subscription_created`: nova assinatura. `one_time_purchase`: compra avulsa. `trial_converted`: trial convertido em assinatura paga. `upgrade`: upgrade de plano. `custom`: evento de conversão customizado. example: subscription_created amountCents: type: integer minimum: 0 maximum: 9007199254740991 description: >- Valor da conversão em centavos (inteiro). Ex.: 1990 = R$ 19,90. example: 1990 currency: default: BRL description: Moeda da conversão. Apenas `BRL` (Real brasileiro). type: string enum: - BRL customer: type: object properties: id: type: string minLength: 1 maxLength: 255 description: Identificador do cliente no sistema da loja. example: cust_8842 email: type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ description: >- E-mail do cliente. Quando presente, pode servir de identificador de atribuição. example: cliente@exemplo.com required: - id description: Dados do cliente que originou a conversão. sourceEventId: type: string minLength: 1 maxLength: 255 description: >- Identificador único do evento de origem na loja, usado para deduplicação/idempotência permanente. example: order_2026-0001 occurredAt: description: >- Data/hora em que a conversão ocorreu (ISO-8601). Default: momento do recebimento. example: '2026-06-13T12:00:00.000Z' productId: type: string minLength: 1 maxLength: 255 description: >- Identificador do produto vendido. Confrontado com `applicableProductIds` da regra vigente. example: plan_pro_monthly programId: type: string pattern: ^prog_[0-9A-HJKMNP-TV-Z]{26}$ description: >- Programa ao qual a conversão pertence. Obrigatório quando a organização tem mais de um programa. example: prog_01J9Z3K8N2QF4T7B9XP0WMD5RC clickId: type: string pattern: ^clk_[0-9A-HJKMNP-TV-Z]{26}$ description: >- Identificador do clique a ser atribuído (matching por click_id). example: clk_01J9Z3K8N2QF4T7B9XP0WMD5RC visitorId: type: string pattern: ^vis_[0-9A-HJKMNP-TV-Z]{26}$ description: >- Identificador do visitante rastreado (matching por visitor_id). example: vis_01J9Z3K8N2QF4T7B9XP0WMD5RC required: - type - amountCents - customer - sourceEventId responses: '200': description: Default Response content: application/json: schema: type: object properties: attributed: type: boolean description: >- Indica se a conversão foi atribuída a um afiliado e persistida. example: true deduplicated: type: boolean description: >- Indica se a conversão foi descartada por já existir uma ativa para o cliente no programa. example: false replayed: type: boolean description: >- Indica replay idempotente do mesmo `sourceEventId` (resposta armazenada reenviada). example: false reconciled: type: boolean description: >- Indica que este evento S2S confirmou/sobrescreveu uma conversão client-side provisória de mesmo `sourceEventId` (atualização in-place, não criação nova). example: false conversion: anyOf: - type: object properties: id: type: string description: Identificador único da conversão. example: conv_01J9Z3K8N2QF4T7B9XP0WMD5RC organizationId: type: string description: Organização dona da conversão. example: org_01J9Z3K8N2QF4T7B9XP0WMD5RC programId: type: string description: Programa ao qual a conversão pertence. example: prog_01J9Z3K8N2QF4T7B9XP0WMD5RC affiliateId: type: string description: Afiliado a quem a conversão foi atribuída. example: aff_01J9Z3K8N2QF4T7B9XP0WMD5RC clickId: anyOf: - type: string - type: 'null' description: >- Clique vencedor da atribuição (`null` quando não atribuída por clique). example: clk_01J9Z3K8N2QF4T7B9XP0WMD5RC couponId: anyOf: - type: string - type: 'null' description: >- Cupom usado na atribuição (`null` quando não houve cupom). example: coup_01J9Z3K8N2QF4T7B9XP0WMD5RC parentConversionId: anyOf: - type: string - type: 'null' description: >- Conversão original quando esta é uma recorrência derivada (`null` na conversão inicial). example: conv_01J9Z3K8N2QF4T7B9XP0WMD5RC type: type: string enum: - subscription_created - one_time_purchase - trial_converted - upgrade - custom description: >- Tipo da conversão. `subscription_created`: nova assinatura. `one_time_purchase`: compra avulsa. `trial_converted`: trial convertido em assinatura paga. `upgrade`: upgrade de plano. `custom`: evento de conversão customizado. example: subscription_created status: type: string enum: - pending - approved - voided - refunded description: >- Status da conversão. `pending`: aguardando revisão (ex.: travada por fraude). `approved`: aprovada e elegível a comissão. `voided`: anulada (manualmente ou por confirmação de fraude). `refunded`: estornada após reembolso do cliente. example: approved amountCents: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Valor da conversão em centavos. Ex.: 1990 = R$ 19,90. example: 1990 currency: type: string description: Moeda da conversão. example: BRL customerId: type: string description: Identificador do cliente na loja. example: cust_8842 customerEmailHash: anyOf: - type: string - type: 'null' description: >- Hash SHA-256 do e-mail do cliente (`null` quando não informado). productId: anyOf: - type: string - type: 'null' description: Produto vendido (`null` quando não informado). example: plan_pro_monthly sourceEventId: type: string description: >- Identificador do evento de origem usado na deduplicação. example: order_2026-0001 source: type: string enum: - api - manual - webhook - script description: >- Origem do registro. `api`: enviada pela sua integração servidor-a-servidor. `manual`: criada por um operador. `webhook`: recebida do seu gateway de pagamento. `script`: disparada pelo tracker client-side no browser. example: api matchMethod: type: string enum: - click_id - visitor_id - email_hash - fingerprint - coupon - manual description: >- Método usado para atribuir a conversão a um afiliado. `click_id`: clique identificado. `visitor_id`: visitante rastreado. `email_hash`: hash de e-mail do cliente. `fingerprint`: impressão digital do dispositivo. `coupon`: cupom de afiliado. `manual`: atribuição manual por operador. example: click_id commissionSkippedReason: anyOf: - type: string enum: - program_paused - affiliate_paused - self_referral - product_not_applicable - pending_confirmation description: >- Motivo pelo qual a comissão não foi gerada. `program_paused`: programa pausado. `affiliate_paused`: afiliado pausado. `self_referral`: autoindicação. `product_not_applicable`: produto fora dos `applicableProductIds` da regra vigente. `pending_confirmation`: conversão client-side aguardando confirmação via S2S (org não confia no client-side). example: affiliate_paused - type: 'null' description: >- Motivo de a comissão não ter sido gerada (`null` quando a comissão foi gerada normalmente). fraudDecision: type: string enum: - approve - monitor - review - cleared - confirmed description: >- Decisão antifraude. `approve`: score abaixo do limite, aprovada automaticamente. `monitor`: aprovada, porém monitorada. `review`: travada para revisão manual. `cleared`: revisão manual concluiu falso positivo. `confirmed`: fraude confirmada (conversão anulada). example: approve voidReason: anyOf: - type: string - type: 'null' description: >- Motivo da anulação (`null` quando a conversão não foi anulada). example: Reembolso solicitado pelo cliente attributionSnapshot: type: object properties: model: type: string enum: - first_click - last_click - linear - time_decay - position_based description: >- Modelo de atribuição aplicado. `first_click`: primeiro clique. `last_click`: último clique. `linear`: peso igual entre cliques. `time_decay`: peso maior para cliques recentes. `position_based`: peso maior nas pontas. example: last_click windowDays: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Janela de atribuição em dias considerada no matching. example: 30 matchMethod: type: string enum: - click_id - visitor_id - email_hash - fingerprint - coupon - manual description: >- Método usado para atribuir a conversão a um afiliado. `click_id`: clique identificado. `visitor_id`: visitante rastreado. `email_hash`: hash de e-mail do cliente. `fingerprint`: impressão digital do dispositivo. `coupon`: cupom de afiliado. `manual`: atribuição manual por operador. example: click_id gclid: type: string description: >- Google Click Identifier capturado na atribuição. example: Cj0KCQiA_gclid_example couponPolicy: type: string enum: - coupon_wins - click_wins - split_50_50 description: >- Política de desempate entre cupom e clique. `coupon_wins`: cupom prevalece. `click_wins`: clique prevalece. `split_50_50`: divide 50/50. example: click_wins candidates: type: array items: type: object properties: clickId: type: string description: Clique candidato avaliado na atribuição. example: clk_01J9Z3K8N2QF4T7B9XP0WMD5RC affiliateId: type: string description: Afiliado dono do clique candidato. example: aff_01J9Z3K8N2QF4T7B9XP0WMD5RC occurredAt: type: string description: >- Data/hora do clique candidato (ISO-8601). example: '2026-06-10T09:30:00.000Z' required: - clickId - affiliateId - occurredAt additionalProperties: false description: >- Cliques candidatos avaliados durante a atribuição. winners: type: array items: type: object properties: clickId: anyOf: - type: string - type: 'null' description: >- Clique vencedor (`null` quando a atribuição não veio de clique). example: clk_01J9Z3K8N2QF4T7B9XP0WMD5RC affiliateId: type: string description: Afiliado premiado pela atribuição. example: aff_01J9Z3K8N2QF4T7B9XP0WMD5RC weightBps: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Peso da atribuição em basis points (10000 = 100% para o vencedor único). example: 10000 required: - clickId - affiliateId - weightBps additionalProperties: false description: >- Afiliados vencedores e seus pesos de atribuição. required: - model - windowDays - matchMethod - candidates - winners additionalProperties: false description: >- Snapshot da decisão de atribuição registrada na conversão. ruleSnapshot: anyOf: - type: object properties: precedence: type: string enum: - custom - tier - default description: >- Origem da regra aplicada por precedência. `custom`: regra do afiliado. `tier`: regra do tier. `default`: regra padrão do programa. example: tier ruleId: type: string description: >- Identificador da regra de comissão aplicada. example: comm_01J9Z3K8N2QF4T7B9XP0WMD5RC version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Versão da regra vigente no momento da conversão. example: 3 type: type: string enum: - percentage - fixed - tiered description: >- Tipo da regra. `percentage`: percentual sobre o valor. `fixed`: valor fixo. `tiered`: por faixas de volume. example: percentage percentageBps: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: >- Percentual da comissão em basis points. Ex.: 1500 = 15%. example: 1500 fixedAmountCents: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: >- Valor fixo da comissão em centavos. Ex.: 1990 = R$ 19,90. example: 1990 recurrence: type: object properties: kind: type: string enum: - one_time - lifetime - months - decreasing description: >- Modo de recorrência da comissão. `one_time`: paga uma vez. `lifetime`: enquanto o cliente permanecer. `months`: por N ciclos. `decreasing`: percentual decrescente por ciclo. example: one_time months: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Número de ciclos pagos quando `kind` é `months`. example: 12 steps: type: array items: type: object properties: cycle: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Ciclo de cobrança (1 = primeiro ciclo). example: 1 percentageBps: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Percentual do ciclo em basis points. Ex.: 1500 = 15%. example: 1500 required: - cycle - percentageBps additionalProperties: false description: >- Percentuais por ciclo quando `kind` é `decreasing`. required: - kind additionalProperties: false description: >- Configuração de recorrência da regra de comissão. tiers: anyOf: - type: array items: type: object properties: minCount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Quantidade mínima de conversões para a faixa (a faixa base é 0). example: 0 percentageBps: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Percentual da faixa em basis points. Ex.: 2000 = 20%. example: 2000 fixedAmountCents: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Valor fixo da faixa em centavos. example: 5000 required: - minCount additionalProperties: false - type: 'null' description: >- Faixas da regra quando `type` é `tiered` (`null` caso contrário). applicableProductIds: anyOf: - type: array items: type: string - type: 'null' description: >- Produtos aos quais a regra se aplica. `null` significa todos os produtos. example: - plan_pro_monthly - plan_pro_yearly required: - precedence - ruleId - version - type - percentageBps - fixedAmountCents - recurrence - tiers - applicableProductIds additionalProperties: false description: >- Snapshot da regra de comissão aplicada na conversão. - type: 'null' description: >- Snapshot da regra de comissão aplicada (`null` quando nenhuma comissão foi gerada). fraudSnapshot: type: object properties: score: type: number description: >- Score de risco da conversão entre 0 (baixo) e 1 (alto). example: 0.12 decision: type: string enum: - approve - monitor - review - cleared - confirmed description: >- Decisão antifraude. `approve`: score abaixo do limite, aprovada automaticamente. `monitor`: aprovada, porém monitorada. `review`: travada para revisão manual. `cleared`: revisão manual concluiu falso positivo. `confirmed`: fraude confirmada (conversão anulada). example: approve signals: type: array items: type: object properties: key: type: string description: >- Identificador do sinal antifraude avaliado. example: ip_velocity weight: type: number description: Peso do sinal na composição do score. example: 0.3 triggered: type: boolean description: >- Indica se o sinal foi disparado para esta conversão. example: false detail: type: string description: Detalhe textual do sinal disparado. example: 3 conversões do mesmo IP em 1h required: - key - weight - triggered additionalProperties: false description: Sinais antifraude avaliados e seus pesos. policy: type: object properties: approveBelow: type: number description: >- Score abaixo do qual a conversão é aprovada automaticamente. example: 0.3 reviewAbove: type: number description: >- Score acima do qual a conversão é travada para revisão manual. example: 0.7 required: - approveBelow - reviewAbove additionalProperties: false description: >- Bandas de decisão antifraude vigentes no momento da avaliação. required: - score - decision - signals - policy additionalProperties: false description: >- Snapshot da avaliação antifraude registrada na conversão. occurredAt: description: Data/hora em que a conversão ocorreu (ISO-8601). example: '2026-06-13T12:00:00.000Z' type: string format: date-time createdAt: description: Data/hora de criação do registro (ISO-8601). example: '2026-06-13T12:00:05.000Z' type: string format: date-time updatedAt: description: Data/hora da última atualização (ISO-8601). example: '2026-06-13T12:00:05.000Z' type: string format: date-time required: - id - organizationId - programId - affiliateId - clickId - couponId - parentConversionId - type - status - amountCents - currency - customerId - customerEmailHash - productId - sourceEventId - source - matchMethod - commissionSkippedReason - fraudDecision - voidReason - attributionSnapshot - ruleSnapshot - fraudSnapshot - occurredAt - createdAt - updatedAt additionalProperties: false - type: 'null' description: >- Conversão criada (`null` quando nada foi atribuído/persistido). required: - attributed - deduplicated - replayed - reconciled - conversion additionalProperties: false '201': description: Default Response content: application/json: schema: type: object properties: attributed: type: boolean description: >- Indica se a conversão foi atribuída a um afiliado e persistida. example: true deduplicated: type: boolean description: >- Indica se a conversão foi descartada por já existir uma ativa para o cliente no programa. example: false replayed: type: boolean description: >- Indica replay idempotente do mesmo `sourceEventId` (resposta armazenada reenviada). example: false reconciled: type: boolean description: >- Indica que este evento S2S confirmou/sobrescreveu uma conversão client-side provisória de mesmo `sourceEventId` (atualização in-place, não criação nova). example: false conversion: anyOf: - type: object properties: id: type: string description: Identificador único da conversão. example: conv_01J9Z3K8N2QF4T7B9XP0WMD5RC organizationId: type: string description: Organização dona da conversão. example: org_01J9Z3K8N2QF4T7B9XP0WMD5RC programId: type: string description: Programa ao qual a conversão pertence. example: prog_01J9Z3K8N2QF4T7B9XP0WMD5RC affiliateId: type: string description: Afiliado a quem a conversão foi atribuída. example: aff_01J9Z3K8N2QF4T7B9XP0WMD5RC clickId: anyOf: - type: string - type: 'null' description: >- Clique vencedor da atribuição (`null` quando não atribuída por clique). example: clk_01J9Z3K8N2QF4T7B9XP0WMD5RC couponId: anyOf: - type: string - type: 'null' description: >- Cupom usado na atribuição (`null` quando não houve cupom). example: coup_01J9Z3K8N2QF4T7B9XP0WMD5RC parentConversionId: anyOf: - type: string - type: 'null' description: >- Conversão original quando esta é uma recorrência derivada (`null` na conversão inicial). example: conv_01J9Z3K8N2QF4T7B9XP0WMD5RC type: type: string enum: - subscription_created - one_time_purchase - trial_converted - upgrade - custom description: >- Tipo da conversão. `subscription_created`: nova assinatura. `one_time_purchase`: compra avulsa. `trial_converted`: trial convertido em assinatura paga. `upgrade`: upgrade de plano. `custom`: evento de conversão customizado. example: subscription_created status: type: string enum: - pending - approved - voided - refunded description: >- Status da conversão. `pending`: aguardando revisão (ex.: travada por fraude). `approved`: aprovada e elegível a comissão. `voided`: anulada (manualmente ou por confirmação de fraude). `refunded`: estornada após reembolso do cliente. example: approved amountCents: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Valor da conversão em centavos. Ex.: 1990 = R$ 19,90. example: 1990 currency: type: string description: Moeda da conversão. example: BRL customerId: type: string description: Identificador do cliente na loja. example: cust_8842 customerEmailHash: anyOf: - type: string - type: 'null' description: >- Hash SHA-256 do e-mail do cliente (`null` quando não informado). productId: anyOf: - type: string - type: 'null' description: Produto vendido (`null` quando não informado). example: plan_pro_monthly sourceEventId: type: string description: >- Identificador do evento de origem usado na deduplicação. example: order_2026-0001 source: type: string enum: - api - manual - webhook - script description: >- Origem do registro. `api`: enviada pela sua integração servidor-a-servidor. `manual`: criada por um operador. `webhook`: recebida do seu gateway de pagamento. `script`: disparada pelo tracker client-side no browser. example: api matchMethod: type: string enum: - click_id - visitor_id - email_hash - fingerprint - coupon - manual description: >- Método usado para atribuir a conversão a um afiliado. `click_id`: clique identificado. `visitor_id`: visitante rastreado. `email_hash`: hash de e-mail do cliente. `fingerprint`: impressão digital do dispositivo. `coupon`: cupom de afiliado. `manual`: atribuição manual por operador. example: click_id commissionSkippedReason: anyOf: - type: string enum: - program_paused - affiliate_paused - self_referral - product_not_applicable - pending_confirmation description: >- Motivo pelo qual a comissão não foi gerada. `program_paused`: programa pausado. `affiliate_paused`: afiliado pausado. `self_referral`: autoindicação. `product_not_applicable`: produto fora dos `applicableProductIds` da regra vigente. `pending_confirmation`: conversão client-side aguardando confirmação via S2S (org não confia no client-side). example: affiliate_paused - type: 'null' description: >- Motivo de a comissão não ter sido gerada (`null` quando a comissão foi gerada normalmente). fraudDecision: type: string enum: - approve - monitor - review - cleared - confirmed description: >- Decisão antifraude. `approve`: score abaixo do limite, aprovada automaticamente. `monitor`: aprovada, porém monitorada. `review`: travada para revisão manual. `cleared`: revisão manual concluiu falso positivo. `confirmed`: fraude confirmada (conversão anulada). example: approve voidReason: anyOf: - type: string - type: 'null' description: >- Motivo da anulação (`null` quando a conversão não foi anulada). example: Reembolso solicitado pelo cliente attributionSnapshot: type: object properties: model: type: string enum: - first_click - last_click - linear - time_decay - position_based description: >- Modelo de atribuição aplicado. `first_click`: primeiro clique. `last_click`: último clique. `linear`: peso igual entre cliques. `time_decay`: peso maior para cliques recentes. `position_based`: peso maior nas pontas. example: last_click windowDays: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Janela de atribuição em dias considerada no matching. example: 30 matchMethod: type: string enum: - click_id - visitor_id - email_hash - fingerprint - coupon - manual description: >- Método usado para atribuir a conversão a um afiliado. `click_id`: clique identificado. `visitor_id`: visitante rastreado. `email_hash`: hash de e-mail do cliente. `fingerprint`: impressão digital do dispositivo. `coupon`: cupom de afiliado. `manual`: atribuição manual por operador. example: click_id gclid: type: string description: >- Google Click Identifier capturado na atribuição. example: Cj0KCQiA_gclid_example couponPolicy: type: string enum: - coupon_wins - click_wins - split_50_50 description: >- Política de desempate entre cupom e clique. `coupon_wins`: cupom prevalece. `click_wins`: clique prevalece. `split_50_50`: divide 50/50. example: click_wins candidates: type: array items: type: object properties: clickId: type: string description: Clique candidato avaliado na atribuição. example: clk_01J9Z3K8N2QF4T7B9XP0WMD5RC affiliateId: type: string description: Afiliado dono do clique candidato. example: aff_01J9Z3K8N2QF4T7B9XP0WMD5RC occurredAt: type: string description: >- Data/hora do clique candidato (ISO-8601). example: '2026-06-10T09:30:00.000Z' required: - clickId - affiliateId - occurredAt additionalProperties: false description: >- Cliques candidatos avaliados durante a atribuição. winners: type: array items: type: object properties: clickId: anyOf: - type: string - type: 'null' description: >- Clique vencedor (`null` quando a atribuição não veio de clique). example: clk_01J9Z3K8N2QF4T7B9XP0WMD5RC affiliateId: type: string description: Afiliado premiado pela atribuição. example: aff_01J9Z3K8N2QF4T7B9XP0WMD5RC weightBps: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Peso da atribuição em basis points (10000 = 100% para o vencedor único). example: 10000 required: - clickId - affiliateId - weightBps additionalProperties: false description: >- Afiliados vencedores e seus pesos de atribuição. required: - model - windowDays - matchMethod - candidates - winners additionalProperties: false description: >- Snapshot da decisão de atribuição registrada na conversão. ruleSnapshot: anyOf: - type: object properties: precedence: type: string enum: - custom - tier - default description: >- Origem da regra aplicada por precedência. `custom`: regra do afiliado. `tier`: regra do tier. `default`: regra padrão do programa. example: tier ruleId: type: string description: >- Identificador da regra de comissão aplicada. example: comm_01J9Z3K8N2QF4T7B9XP0WMD5RC version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Versão da regra vigente no momento da conversão. example: 3 type: type: string enum: - percentage - fixed - tiered description: >- Tipo da regra. `percentage`: percentual sobre o valor. `fixed`: valor fixo. `tiered`: por faixas de volume. example: percentage percentageBps: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: >- Percentual da comissão em basis points. Ex.: 1500 = 15%. example: 1500 fixedAmountCents: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: >- Valor fixo da comissão em centavos. Ex.: 1990 = R$ 19,90. example: 1990 recurrence: type: object properties: kind: type: string enum: - one_time - lifetime - months - decreasing description: >- Modo de recorrência da comissão. `one_time`: paga uma vez. `lifetime`: enquanto o cliente permanecer. `months`: por N ciclos. `decreasing`: percentual decrescente por ciclo. example: one_time months: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Número de ciclos pagos quando `kind` é `months`. example: 12 steps: type: array items: type: object properties: cycle: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Ciclo de cobrança (1 = primeiro ciclo). example: 1 percentageBps: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Percentual do ciclo em basis points. Ex.: 1500 = 15%. example: 1500 required: - cycle - percentageBps additionalProperties: false description: >- Percentuais por ciclo quando `kind` é `decreasing`. required: - kind additionalProperties: false description: >- Configuração de recorrência da regra de comissão. tiers: anyOf: - type: array items: type: object properties: minCount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Quantidade mínima de conversões para a faixa (a faixa base é 0). example: 0 percentageBps: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Percentual da faixa em basis points. Ex.: 2000 = 20%. example: 2000 fixedAmountCents: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Valor fixo da faixa em centavos. example: 5000 required: - minCount additionalProperties: false - type: 'null' description: >- Faixas da regra quando `type` é `tiered` (`null` caso contrário). applicableProductIds: anyOf: - type: array items: type: string - type: 'null' description: >- Produtos aos quais a regra se aplica. `null` significa todos os produtos. example: - plan_pro_monthly - plan_pro_yearly required: - precedence - ruleId - version - type - percentageBps - fixedAmountCents - recurrence - tiers - applicableProductIds additionalProperties: false description: >- Snapshot da regra de comissão aplicada na conversão. - type: 'null' description: >- Snapshot da regra de comissão aplicada (`null` quando nenhuma comissão foi gerada). fraudSnapshot: type: object properties: score: type: number description: >- Score de risco da conversão entre 0 (baixo) e 1 (alto). example: 0.12 decision: type: string enum: - approve - monitor - review - cleared - confirmed description: >- Decisão antifraude. `approve`: score abaixo do limite, aprovada automaticamente. `monitor`: aprovada, porém monitorada. `review`: travada para revisão manual. `cleared`: revisão manual concluiu falso positivo. `confirmed`: fraude confirmada (conversão anulada). example: approve signals: type: array items: type: object properties: key: type: string description: >- Identificador do sinal antifraude avaliado. example: ip_velocity weight: type: number description: Peso do sinal na composição do score. example: 0.3 triggered: type: boolean description: >- Indica se o sinal foi disparado para esta conversão. example: false detail: type: string description: Detalhe textual do sinal disparado. example: 3 conversões do mesmo IP em 1h required: - key - weight - triggered additionalProperties: false description: Sinais antifraude avaliados e seus pesos. policy: type: object properties: approveBelow: type: number description: >- Score abaixo do qual a conversão é aprovada automaticamente. example: 0.3 reviewAbove: type: number description: >- Score acima do qual a conversão é travada para revisão manual. example: 0.7 required: - approveBelow - reviewAbove additionalProperties: false description: >- Bandas de decisão antifraude vigentes no momento da avaliação. required: - score - decision - signals - policy additionalProperties: false description: >- Snapshot da avaliação antifraude registrada na conversão. occurredAt: description: Data/hora em que a conversão ocorreu (ISO-8601). example: '2026-06-13T12:00:00.000Z' type: string format: date-time createdAt: description: Data/hora de criação do registro (ISO-8601). example: '2026-06-13T12:00:05.000Z' type: string format: date-time updatedAt: description: Data/hora da última atualização (ISO-8601). example: '2026-06-13T12:00:05.000Z' type: string format: date-time required: - id - organizationId - programId - affiliateId - clickId - couponId - parentConversionId - type - status - amountCents - currency - customerId - customerEmailHash - productId - sourceEventId - source - matchMethod - commissionSkippedReason - fraudDecision - voidReason - attributionSnapshot - ruleSnapshot - fraudSnapshot - occurredAt - createdAt - updatedAt additionalProperties: false - type: 'null' description: >- Conversão criada (`null` quando nada foi atribuído/persistido). required: - attributed - deduplicated - replayed - reconciled - conversion additionalProperties: false security: [] components: securitySchemes: bearerAuth: type: http scheme: bearer description: >- Chave de API (prefixo `rstr_`) enviada como `Authorization: Bearer rstr_...`. apiKeyAuth: type: apiKey in: header name: x-api-key description: Chave de API (prefixo `rstr_`) enviada no header `x-api-key`. ````