> ## 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. # Cria uma comissão de bônus avulsa > Cria uma comissão de bônus avulsa para um afiliado, sem vínculo com conversão (`type=bonus`). Idempotente via header `Idempotency-Key`. ## OpenAPI ````yaml /openapi.json post /commissions/bonus 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: /commissions/bonus: post: tags: - Commissions summary: Cria uma comissão de bônus avulsa description: >- Cria uma comissão de bônus avulsa para um afiliado, sem vínculo com conversão (`type=bonus`). Idempotente via header `Idempotency-Key`. operationId: createBonusCommission requestBody: required: true content: application/json: schema: type: object properties: affiliateId: type: string pattern: ^aff_[0-9A-HJKMNP-TV-Z]{26}$ description: Identificador do afiliado que receberá o bônus. example: aff_01J9Z3K8QXY4M2N6P7R0S1T2V3 amountCents: type: integer minimum: 1 maximum: 9007199254740991 description: >- Valor do bônus em centavos (ex.: 5000 = R$50,00). Deve ser positivo. example: 5000 description: type: string minLength: 1 maxLength: 500 description: >- Descrição do bônus (motivo/campanha), registrada na memória de cálculo. example: Bônus de campanha de junho required: - affiliateId - amountCents - description responses: '201': description: Default Response content: application/json: schema: type: object properties: id: type: string description: Identificador único da comissão (prefixo `comm_` + ULID). example: comm_01J9Z3K8QXY4M2N6P7R0S1T2V3 organizationId: type: string description: Identificador da organização (tenant) dona da comissão. example: org_01J9Z3K8QXY4M2N6P7R0S1T2V3 programId: type: string description: >- Identificador do programa de afiliados ao qual a comissão pertence. example: prog_01J9Z3K8QXY4M2N6P7R0S1T2V3 affiliateId: type: string description: Identificador do afiliado que recebe a comissão. example: aff_01J9Z3K8QXY4M2N6P7R0S1T2V3 conversionId: anyOf: - type: string - type: 'null' description: >- Identificador da conversão que originou a comissão. `null` para bônus avulsos. example: conv_01J9Z3K8QXY4M2N6P7R0S1T2V3 type: type: string enum: - standard - clawback - bonus - adjustment description: >- Tipo da comissão. `standard`: comissão padrão gerada por uma conversão. `clawback`: estorno (valor negativo) por reembolso/chargeback. `bonus`: comissão avulsa concedida manualmente. `adjustment`: ajuste (delta) aplicado a uma comissão já paga quando ela é recalculada. example: standard status: type: string enum: - pending - approved - paid - voided description: >- Situação da comissão. `pending`: aguardando o fim do período de hold. `approved`: liberada e elegível para payout. `paid`: já incluída em um payout pago. `voided`: cancelada/anulada. example: pending underReview: type: boolean description: >- Indica se a comissão está retida em revisão (ex.: afiliado sob suspeita de fraude/ban). example: false billingCycle: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: >- Ciclo de cobrança (1-based) para comissões recorrentes. `null` quando não recorrente. example: 1 amountCents: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Valor da comissão em centavos. Pode ser negativo em estornos (clawback). example: 298 currency: type: string description: Moeda da comissão (ISO 4217). example: BRL calculation: type: object properties: basis: type: string enum: - gross - net_of_gateway_fees description: >- Base de cálculo da comissão. `gross`: sobre o valor bruto cobrado. `net_of_gateway_fees`: sobre o valor líquido, descontando as taxas do gateway. example: gross chargedAmountCents: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Valor cobrado do cliente, em centavos (ex.: 1990 = R$19,90). example: 1990 gatewayFeeCents: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Taxa do gateway descontada, em centavos. Presente quando `basis` é `net_of_gateway_fees`. example: 99 baseAmountCents: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Valor base efetivamente usado no cálculo da comissão, em centavos. example: 1990 weightBps: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Peso aplicado ao valor base, em basis points (ex.: 10000 = 100%). example: 10000 rule: type: object properties: ruleId: type: string description: Identificador da regra de comissão aplicada. example: cmrl_01J9Z3K8QXY4M2N6P7R0S1T2V3 version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Versão da regra de comissão aplicada (regras são imutáveis/versionadas). example: 1 precedence: type: string enum: - custom - tier - default description: >- Origem da regra que prevaleceu. `custom`: regra customizada do afiliado. `tier`: regra do tier. `default`: regra padrão do programa. example: default type: type: string enum: - percentage - fixed - tiered description: >- Modalidade de cálculo. `percentage`: percentual sobre a base. `fixed`: valor fixo por conversão. `tiered`: faixas progressivas por contagem de conversões. example: percentage required: - ruleId - version - precedence - type additionalProperties: false description: >- Regra de comissão aplicada (e sua versão) no momento do cálculo. appliedPercentageBps: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Percentual efetivamente aplicado, em basis points (ex.: 1500 = 15%). example: 1500 appliedFixedAmountCents: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Valor fixo efetivamente aplicado, em centavos. example: 500 recurrenceKind: type: string enum: - one_time - lifetime - months - decreasing description: >- Modelo de recorrência da comissão. `one_time`: paga uma única vez. `lifetime`: paga em toda renovação. `months`: paga por um número limitado de meses. `decreasing`: percentual decrescente a cada ciclo. example: one_time tier: type: object properties: minCount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Contagem mínima de conversões da faixa que prevaleceu. example: 0 approvedConversionsCount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Quantidade de conversões aprovadas do afiliado usada para escolher a faixa. example: 12 required: - minCount - approvedConversionsCount additionalProperties: false description: >- Faixa (tier) aplicada quando a regra é do tipo `tiered`. splitRemainderCents: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Resto (em centavos) não distribuído ao arredondar o split entre afiliados. example: 1 refund: type: object properties: refundedAmountCents: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Valor reembolsado ao cliente, em centavos. example: 1990 chargedAmountCents: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Valor originalmente cobrado, em centavos. example: 1990 originalCommissionAmountCents: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Valor da comissão original que está sendo estornada, em centavos. example: 298 chargeback: type: boolean description: >- Indica se o estorno decorre de um chargeback (true) ou de um reembolso comum (false). example: false required: - refundedAmountCents - chargedAmountCents - originalCommissionAmountCents - chargeback additionalProperties: false description: >- Detalhamento do estorno (presente em comissões do tipo `clawback`). reprocess: type: object properties: jobId: type: string description: >- Identificador do job de reprocessamento que originou o ajuste. example: job_01J9Z3K8QXY4M2N6P7R0S1T2V3 originalAmountCents: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Valor da comissão antes do recálculo, em centavos. example: 298 recalculatedAmountCents: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Valor da comissão após o recálculo, em centavos. example: 350 required: - jobId - originalAmountCents - recalculatedAmountCents additionalProperties: false description: Referência do recálculo que gerou este ajuste. description: type: string description: 'Descrição livre do cálculo (ex.: motivo de um bônus).' example: Bônus de campanha de junho required: - basis - chargedAmountCents - baseAmountCents - weightBps additionalProperties: false description: >- Memória de cálculo da comissão (regra aplicada, base, percentuais e detalhes específicos do tipo). holdUntil: anyOf: - type: string format: date-time - type: 'null' description: >- Data/hora (ISO-8601) até quando a comissão fica em hold antes de poder ser aprovada. example: '2026-07-13T12:00:00.000Z' sourceEventId: anyOf: - type: string - type: 'null' description: Identificador do evento de origem que gerou a comissão. example: evt_01J9Z3K8QXY4M2N6P7R0S1T2V3 originalCommissionId: anyOf: - type: string - type: 'null' description: >- Identificador da comissão original referenciada por um estorno ou ajuste. example: comm_01J9Z3K8QXY4M2N6P7R0S1T2V3 voidReason: anyOf: - type: string - type: 'null' description: >- Motivo informado ao anular a comissão. `null` quando não anulada. example: Pedido cancelado pelo cliente payoutId: anyOf: - type: string - type: 'null' description: >- Identificador do payout em que a comissão foi paga. `null` enquanto não paga. example: pay_01J9Z3K8QXY4M2N6P7R0S1T2V3 occurredAt: description: >- Data/hora (ISO-8601) em que o fato gerador da comissão ocorreu. example: '2026-06-13T12:00:00.000Z' type: string format: date-time approvedAt: anyOf: - type: string format: date-time - type: 'null' description: >- Data/hora (ISO-8601) em que a comissão foi aprovada. `null` enquanto pendente. example: '2026-07-13T12:00:00.000Z' createdAt: description: Data/hora (ISO-8601) de criação do registro. example: '2026-06-13T12:00:00.000Z' type: string format: date-time updatedAt: description: Data/hora (ISO-8601) da última atualização do registro. example: '2026-06-13T12:00:00.000Z' type: string format: date-time required: - id - organizationId - programId - affiliateId - conversionId - type - status - underReview - billingCycle - amountCents - currency - calculation - holdUntil - sourceEventId - originalCommissionId - voidReason - payoutId - occurredAt - approvedAt - createdAt - updatedAt 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`. ````