> ## 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. # Envio de eventos via API (chave de API) > Envio direto de eventos de cobrança para integrações que não usam um gateway com suporte nativo: conversão, cobrança recorrente (ciclos 2 em diante), estorno/chargeback e cancelamento de assinatura. Reenviar o mesmo `sourceEventId` é tratado como reprocessamento e não duplica o efeito. Autentique com `Authorization: Bearer rstr_...`. ## OpenAPI ````yaml /openapi.json post /ingest/custom 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: /ingest/custom: post: tags: - Ingest summary: Envio de eventos via API (chave de API) description: >- Envio direto de eventos de cobrança para integrações que não usam um gateway com suporte nativo: conversão, cobrança recorrente (ciclos 2 em diante), estorno/chargeback e cancelamento de assinatura. Reenviar o mesmo `sourceEventId` é tratado como reprocessamento e não duplica o efeito. Autentique com `Authorization: Bearer rstr_...`. operationId: ingestCustomGatewayEvent requestBody: required: true content: application/json: schema: oneOf: - 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 emailHash: type: string pattern: ^[a-f0-9]{64}$ description: >- Hash SHA-256 do e-mail do cliente, usado no matching por email_hash. example: >- a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3 fingerprint: type: string pattern: ^[a-f0-9]{64}$ description: >- Hash SHA-256 da impressão digital do dispositivo, usado no matching por fingerprint. example: >- a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3 couponCode: type: string minLength: 1 maxLength: 64 description: >- Código de cupom de afiliado utilizado na compra (matching por coupon). example: MARIA10 gclid: type: string minLength: 1 maxLength: 255 description: >- Google Click Identifier, propagado no snapshot de atribuição. example: Cj0KCQiA_gclid_example kind: type: string description: >- Tipo do evento: `conversion` registra uma nova conversão (venda/assinatura) atribuída a um afiliado. enum: - conversion required: - type - amountCents - customer - sourceEventId - kind - type: object properties: kind: type: string description: >- Tipo do evento: `charge` registra uma cobrança recorrente (ciclos de cobrança 2+ de uma assinatura). enum: - charge conversionId: type: string pattern: ^conv_[0-9A-HJKMNP-TV-Z]{26}$ description: >- ID da conversão alvo (prefixo `conv_` + ULID). Use este OU `customerId` para referenciar a conversão. example: conv_01J9Z3K8N2QF4T7B9XP0WMD5RC customerId: type: string minLength: 1 maxLength: 255 description: >- Identificador do cliente no gateway, usado para localizar a conversão quando `conversionId` não é informado. example: cus_NeffrFeUfNV2Hib amountCents: type: integer minimum: 0 maximum: 9007199254740991 description: 'Valor da cobrança em centavos (ex.: 1990 = R$19,90).' example: 1990 gatewayFeeCents: type: integer minimum: 0 maximum: 9007199254740991 description: >- Taxa cobrada pelo gateway nesta cobrança, em centavos (ex.: 199 = R$1,99). example: 199 currency: default: BRL description: Moeda da cobrança. Atualmente apenas `BRL` (Real). type: string enum: - BRL sourceEventId: type: string minLength: 1 maxLength: 255 description: >- Identificador único do evento no gateway de origem, usado para idempotência de negócio (reprocessar o mesmo `sourceEventId` é um replay). example: evt_3OxyZ1AbCdEfGhIj occurredAt: description: >- Momento em que a cobrança ocorreu (ISO-8601). Default: momento da ingestão. example: '2026-06-13T12:00:00.000Z' required: - kind - amountCents - sourceEventId - type: object properties: kind: type: string description: >- Tipo do evento: `refund` registra um estorno (parcial ou total) de uma cobrança. enum: - refund conversionId: type: string pattern: ^conv_[0-9A-HJKMNP-TV-Z]{26}$ description: >- ID da conversão alvo (prefixo `conv_` + ULID). Use este OU `customerId` para referenciar a conversão. example: conv_01J9Z3K8N2QF4T7B9XP0WMD5RC customerId: type: string minLength: 1 maxLength: 255 description: >- Identificador do cliente no gateway, usado para localizar a conversão quando `conversionId` não é informado. example: cus_NeffrFeUfNV2Hib refundedAmountCents: type: integer minimum: 1 maximum: 9007199254740991 description: 'Valor estornado em centavos (ex.: 1990 = R$19,90).' example: 1990 chargeSourceEventId: type: string minLength: 1 maxLength: 255 description: >- `sourceEventId` da cobrança original a ser estornada. Se ausente, usa-se `billingCycle` como fallback. example: evt_3OxyZ1AbCdEfGhIj billingCycle: type: integer minimum: 1 maximum: 9007199254740991 description: >- Ciclo de cobrança da assinatura a estornar (fallback quando `chargeSourceEventId` não é informado). `1` é a cobrança inicial. example: 2 chargeback: default: false description: >- `true` marca o estorno como chargeback (estorno total + fraude confirmada). Default: `false`. type: boolean sourceEventId: type: string minLength: 1 maxLength: 255 description: >- Identificador único do evento no gateway de origem, usado para idempotência de negócio (reprocessar o mesmo `sourceEventId` é um replay). example: evt_3OxyZ1AbCdEfGhIj occurredAt: description: >- Momento em que o estorno ocorreu (ISO-8601). Default: momento da ingestão. example: '2026-06-13T12:00:00.000Z' required: - kind - refundedAmountCents - sourceEventId - type: object properties: kind: type: string description: >- Tipo do evento: `cancellation` registra o cancelamento de uma assinatura. enum: - cancellation conversionId: type: string pattern: ^conv_[0-9A-HJKMNP-TV-Z]{26}$ description: >- ID da conversão alvo (prefixo `conv_` + ULID). Use este OU `customerId` para referenciar a conversão. example: conv_01J9Z3K8N2QF4T7B9XP0WMD5RC customerId: type: string minLength: 1 maxLength: 255 description: >- Identificador do cliente no gateway, usado para localizar a conversão quando `conversionId` não é informado. example: cus_NeffrFeUfNV2Hib sourceEventId: type: string minLength: 1 maxLength: 255 description: >- Identificador único do evento no gateway de origem, usado para idempotência de negócio (reprocessar o mesmo `sourceEventId` é um replay). example: evt_3OxyZ1AbCdEfGhIj occurredAt: description: >- Momento em que o cancelamento ocorreu (ISO-8601). Default: momento da ingestão. example: '2026-06-13T12:00:00.000Z' required: - kind - sourceEventId responses: '200': description: Default Response content: application/json: schema: type: object properties: outcome: type: string enum: - processed - replayed - unmatched - skipped - ignored description: >- Resultado do processamento. `processed`: evento aplicado com sucesso. `replayed`: já havia sido processado antes (mesmo `sourceEventId` reenviado). `unmatched`: nenhuma conversão correspondente encontrada. `skipped`: reconhecido, mas não aplicado por não atender a uma regra de negócio. `ignored`: evento sem relevância de negócio. example: processed reason: anyOf: - type: string - type: 'null' description: >- Motivo do resultado quando aplicável (ex.: por que foi ignorado ou pulado). `null` quando processado normalmente. example: unsupported event type conversionId: anyOf: - type: string - type: 'null' description: >- ID da conversão afetada (prefixo `conv_` + ULID). `null` quando nenhuma conversão foi correspondida. example: conv_01J9Z3K8N2QF4T7B9XP0WMD5RC commissionIds: type: array items: type: string description: >- IDs das comissões criadas ou afetadas pelo evento (prefixo `comm_` + ULID). example: - comm_01J9Z3K8N2QF4T7B9XP0WMD5RC required: - outcome - reason - conversionId - commissionIds additionalProperties: false 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`. ````