> ## 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. # Consulta um lote de payout com seus payouts e notas fiscais > Retorna um lote de fechamento. Use `expand=payouts` e/ou `expand=invoices` para incluir os payouts agregados e as notas fiscais vinculadas, e `expand=payable` para o resumo de repasses pagáveis vs. retidos (a mesma regra da autorização do aporte). ## OpenAPI ````yaml /openapi.json get /payout-batches/{batchId} 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: /payout-batches/{batchId}: get: tags: - Payouts summary: Consulta um lote de payout com seus payouts e notas fiscais description: >- Retorna um lote de fechamento. Use `expand=payouts` e/ou `expand=invoices` para incluir os payouts agregados e as notas fiscais vinculadas, e `expand=payable` para o resumo de repasses pagáveis vs. retidos (a mesma regra da autorização do aporte). operationId: getPayoutBatch parameters: - schema: default: [] type: array items: type: string enum: - payouts - invoices - payable in: query name: expand required: false description: >- Relações a expandir na resposta: `payouts`, `invoices` e/ou `payable`. - schema: type: string pattern: ^cyc_[0-9A-HJKMNP-TV-Z]{26}$ example: cyc_01J9Z3K8N2QF4T7B9XP0WMD5RC in: path name: batchId required: true description: Identificador do lote de fechamento (prefixo `cyc_` + ULID). responses: '200': description: Default Response content: application/json: schema: type: object properties: id: type: string description: >- Identificador único do lote de fechamento (prefixo `cyc_` + ULID). example: cyc_01J9Z3K8N2QF4T7B9XP0WMD5RC organizationId: type: string description: Organização (tenant) dona do lote. example: org_01J9Z3K8N2QF4T7B9XP0WMD5RC programId: anyOf: - type: string - type: 'null' description: >- Programa ao qual o fechamento foi restrito. `null` quando o lote cobriu todos os programas. example: prog_01J9Z3K8N2QF4T7B9XP0WMD5RC status: type: string enum: - processing - completed - partial description: Status atual do lote. example: completed closingAt: description: Instante do fechamento do ciclo (ISO-8601). example: '2026-06-01T03:00:00.000Z' type: string format: date-time affiliateCount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Quantidade de afiliados elegíveis pagos neste fechamento. example: 12 totalCents: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Soma dos valores do fechamento em centavos (ex.: 1990 = R$19,90). example: 482310 payoutIds: type: array items: type: string description: Identificadores dos payouts agregados no lote. example: - pay_01J9Z3K8N2QF4T7B9XP0WMD5RC invoiceIds: type: array items: type: string description: >- Identificadores das notas fiscais vinculadas aos payouts do lote. example: - inv_01J9Z3K8N2QF4T7B9XP0WMD5RC createdAt: description: Data de criação do lote (ISO-8601). example: '2026-06-01T03:00:00.000Z' type: string format: date-time updatedAt: description: Data da última atualização do lote (ISO-8601). example: '2026-06-01T03:00:00.000Z' type: string format: date-time payouts: type: array items: type: object properties: id: type: string description: >- Identificador único do payout (prefixo `pay_` + ULID). example: pay_01J9Z3K8N2QF4T7B9XP0WMD5RC organizationId: type: string description: Organização (tenant) dona do payout. example: org_01J9Z3K8N2QF4T7B9XP0WMD5RC affiliateId: type: string description: Afiliado beneficiário do payout. example: aff_01J9Z3K8N2QF4T7B9XP0WMD5RC batchId: anyOf: - type: string - type: 'null' description: >- Lote de fechamento (ciclo) ao qual o payout pertence. `null` em payouts anteriores aos lotes. example: cyc_01J9Z3K8N2QF4T7B9XP0WMD5RC fundingId: anyOf: - type: string - type: 'null' description: >- Aporte (cobrança PIX) que cobre este payout, carimbado na autorização do lote. `null` enquanto o payout não entrou em nenhuma cobrança — sem cobertura ele não é distribuído. example: fund_01J9Z3K8N2QF4T7B9XP0WMD5RC status: type: string enum: - scheduled - processing - completed - failed - canceled description: Status atual do payout. example: scheduled method: type: string enum: - pix description: >- Método de pagamento registrado na criação do payout. Fica fixo a partir desse momento, mesmo que o afiliado altere o método depois. example: pix amountCents: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Valor total do payout em centavos (ex.: 1990 = R$19,90). example: 25000 currency: type: string description: Moeda do payout (código ISO 4217). example: BRL commissionCount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Quantidade de comissões agregadas neste payout. example: 4 destination: type: object properties: method: type: string enum: - pix description: Método de pagamento do destino. example: pix pixKey: type: string description: Chave PIX do destino (quando `method` é `pix`). example: maria@exemplo.com pixKeyType: type: string enum: - cpf - cnpj - email - phone - random description: >- Tipo da chave PIX do destino (quando `method` é `pix`). example: email required: - method additionalProperties: false description: >- Destino do pagamento registrado na criação do payout. Fica fixo a partir desse momento, mesmo que o afiliado altere os dados depois. failureReason: anyOf: - type: string - type: 'null' description: >- Motivo da falha quando `status` é `failed`. `null` caso contrário. example: Chave PIX inválida providerTransactionId: anyOf: - type: string - type: 'null' description: >- ID da transação no provedor de pagamento. `null` enquanto não processado. example: txn_8f3c1a2b9d4e providerReceiptUrl: anyOf: - type: string - type: 'null' description: >- URL do comprovante de pagamento no provedor. `null` enquanto não pago. example: >- https://provedor.exemplo.com/receipts/txn_8f3c1a2b9d4e settlementSource: anyOf: - type: string enum: - provider - manual - type: 'null' description: >- Origem da liquidação. `provider`: transferência via gateway. `manual`: operador marcou como pago. `null` em payouts ainda não liquidados ou históricos. example: manual manualReceiptFileKey: anyOf: - type: string - type: 'null' description: >- Chave do comprovante anexado pelo operador (liquidação manual). Use `GET /payouts/{id}/receipt` para a URL assinada. example: org/org_…/payouts/pay_…/receipt_….pdf markedPaidByUserId: anyOf: - type: string - type: 'null' description: >- Usuário que marcou o payout como pago manualmente. `null` na liquidação via provedor. example: usr_01J9Z3K8N2QF4T7B9XP0WMD5RC scheduledAt: description: Data de agendamento do payout (ISO-8601). example: '2026-06-13T12:00:00.000Z' type: string format: date-time processedAt: anyOf: - type: string format: date-time - type: 'null' description: >- Data em que o payout entrou em processamento (ISO-8601). `null` enquanto agendado. example: '2026-06-13T12:05:00.000Z' paidAt: anyOf: - type: string format: date-time - type: 'null' description: >- Data do pagamento concluído (ISO-8601). `null` enquanto não pago. example: '2026-06-13T12:10:00.000Z' failedAt: anyOf: - type: string format: date-time - type: 'null' description: Data da falha (ISO-8601). `null` quando não falhou. example: '2026-06-13T12:10:00.000Z' canceledAt: anyOf: - type: string format: date-time - type: 'null' description: >- Data do cancelamento (ISO-8601). `null` quando não cancelado. example: '2026-06-13T12:10:00.000Z' createdAt: description: Data de criação do payout (ISO-8601). example: '2026-06-13T12:00:00.000Z' type: string format: date-time updatedAt: description: Data da última atualização do payout (ISO-8601). example: '2026-06-13T12:00:00.000Z' type: string format: date-time affiliateName: anyOf: - type: string - type: 'null' description: Nome do afiliado beneficiário. example: Maria Silva conversionCount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Quantidade de conversões distintas nas comissões do payout. example: 3 invoiceId: anyOf: - type: string - type: 'null' description: NF vinculada ao payout, quando houver. example: inv_01J9Z3K8N2QF4T7B9XP0WMD5RC invoiceStatus: anyOf: - type: string enum: - pending - processing - validated - rejected - canceled description: >- Status da nota fiscal. `pending`: aguardando envio do arquivo da NF. `processing`: arquivo recebido, extração/validação automática em andamento. `validated`: NF aprovada (libera o pagamento). `rejected`: NF recusada na validação (reabre a pendência do pagamento e permite reenvio). `canceled`: NF cancelada. example: validated - type: 'null' description: Status da NF vinculada, quando houver. hasManualReceipt: type: boolean description: Se há comprovante manual anexado pelo operador. required: - id - organizationId - affiliateId - batchId - fundingId - status - method - amountCents - currency - commissionCount - destination - failureReason - providerTransactionId - providerReceiptUrl - settlementSource - manualReceiptFileKey - markedPaidByUserId - scheduledAt - processedAt - paidAt - failedAt - canceledAt - createdAt - updatedAt - affiliateName - conversionCount - invoiceId - invoiceStatus - hasManualReceipt additionalProperties: false description: >- Payouts do lote (com nome do afiliado, conversões e resumo da NF), quando `expand=payouts`. invoices: type: array items: type: object properties: id: type: string description: >- Identificador único da nota fiscal (prefixo `inv_` + ULID). example: inv_01J9Z3K8N2QF4T7B9XP0WMD5RC organizationId: type: string description: Organização (tenant) dona da nota fiscal. example: org_01J9Z3K8N2QF4T7B9XP0WMD5RC affiliateId: type: string description: Afiliado a quem a nota fiscal se refere. example: aff_01J9Z3K8N2QF4T7B9XP0WMD5RC payoutId: type: string description: >- Pagamento (payout) ao qual a nota fiscal está vinculada. example: pay_01J9Z3K8N2QF4T7B9XP0WMD5RC status: type: string enum: - pending - processing - validated - rejected - canceled description: Status atual da nota fiscal. example: validated nfNumber: anyOf: - type: string - type: 'null' description: >- Número da nota fiscal extraído do arquivo. `null` até a extração concluir. example: '12345' nfSeries: anyOf: - type: string - type: 'null' description: >- Série da nota fiscal extraída do arquivo. `null` quando ausente. example: '1' issuerCnpj: anyOf: - type: string - type: 'null' description: >- CNPJ do emissor extraído do arquivo (normalizado a 14 dígitos). `null` até a extração concluir. example: '11222333000181' nfAmountCents: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: >- Valor da NF extraído do arquivo, em centavos (ex.: 1990 = R$19,90). `null` até a extração concluir. example: 25000 recipientName: anyOf: - type: string - type: 'null' description: >- Nome do tomador/destinatário extraído da NF. `null` até a extração concluir. example: Repass Tecnologia LTDA nfAccessKey: anyOf: - type: string - type: 'null' description: >- Chave de acesso da NF (44 dígitos na NF-e; formato próprio na NFS-e Nacional). `null` quando ausente do documento. example: '35260611222333000181550010000001231123456782' nfIssuedAt: anyOf: - type: string format: date-time - type: 'null' description: >- Data de emissão extraída da NF (ISO-8601). `null` quando ausente. example: '2026-06-20T00:00:00.000Z' extractionMethod: anyOf: - type: string enum: - xml_nfe - xml_nfse - ai_pdf - ai_xml description: >- Como os dados da NF foram extraídos do arquivo. `xml_nfe`: parser determinístico de NF-e (modelo 55). `xml_nfse`: parser determinístico de NFS-e Nacional. `ai_pdf`: extração por IA a partir do PDF. `ai_xml`: extração por IA a partir de um XML fora dos layouts conhecidos. example: xml_nfse - type: 'null' description: >- Como os dados foram extraídos do arquivo. `null` até a extração concluir. extractionError: anyOf: - type: string - type: 'null' description: >- Código da falha fatal de extração (ex.: `unreadable_file`). `null` quando a extração leu o arquivo. example: unreadable_file fileKey: anyOf: - type: string - type: 'null' description: >- Referência interna do arquivo da NF armazenado. `null` enquanto não enviado. example: invoices/inv_01J9Z3K8N2QF4T7B9XP0WMD5RC.pdf fileContentType: anyOf: - type: string - type: 'null' description: >- Tipo MIME do arquivo da NF (PDF ou XML). `null` enquanto não enviado. example: application/pdf fileSizeBytes: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: >- Tamanho do arquivo da NF em bytes. `null` enquanto não enviado. example: 204800 validationErrors: anyOf: - type: array items: type: string - type: 'null' description: >- Códigos/mensagens de erro encontrados na validação automática da NF. `null` quando não houve validação ou ela passou. example: - amount_mismatch rejectionReason: anyOf: - type: string - type: 'null' description: >- Motivo da rejeição manual da NF. `null` quando não rejeitada. example: Valor da NF diverge do payout submittedAt: anyOf: - type: string format: date-time - type: 'null' description: >- Momento do envio da NF (ISO-8601). `null` enquanto não enviada. example: '2026-06-13T12:00:00.000Z' validatedAt: anyOf: - type: string format: date-time - type: 'null' description: >- Momento da validação da NF (ISO-8601). `null` quando não validada. example: '2026-06-13T12:00:00.000Z' rejectedAt: anyOf: - type: string format: date-time - type: 'null' description: >- Momento da rejeição da NF (ISO-8601). `null` quando não rejeitada. example: '2026-06-13T12:00:00.000Z' canceledAt: anyOf: - type: string format: date-time - type: 'null' description: >- Momento do cancelamento da NF (ISO-8601). `null` quando não cancelada. example: '2026-06-13T12:00:00.000Z' createdAt: description: Data de criação do registro da NF (ISO-8601). example: '2026-06-13T12:00:00.000Z' type: string format: date-time updatedAt: description: >- Data da última atualização do registro da NF (ISO-8601). example: '2026-06-13T12:00:00.000Z' type: string format: date-time required: - id - organizationId - affiliateId - payoutId - status - nfNumber - nfSeries - issuerCnpj - nfAmountCents - recipientName - nfAccessKey - nfIssuedAt - extractionMethod - extractionError - fileKey - fileContentType - fileSizeBytes - validationErrors - rejectionReason - submittedAt - validatedAt - rejectedAt - canceledAt - createdAt - updatedAt additionalProperties: false description: >- Notas fiscais vinculadas aos payouts do lote, incluídas quando `expand=invoices`. payable: type: object properties: payableCount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Quantidade de repasses que entrariam na cobrança PIX agora. example: 10 payableAmountCents: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Soma dos repasses pagáveis em centavos (ex.: 1990 = R$19,90) — o valor da cobrança antes da folga de taxas. example: 452310 retainedCount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Quantidade de repasses retidos (fora da cobrança). example: 2 retainedAmountCents: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Soma dos repasses retidos em centavos. example: 30000 retained: type: array items: type: object properties: payoutId: type: string description: Repasse retido. example: pay_01J9Z3K8N2QF4T7B9XP0WMD5RC affiliateId: type: string description: Afiliado beneficiário do repasse retido. example: aff_01J9Z3K8N2QF4T7B9XP0WMD5RC amountCents: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Valor do repasse retido em centavos. example: 15000 reason: type: string enum: - missing_pix_key - invoice_pending - invoice_processing - invoice_rejected - invoice_canceled description: >- Motivo pelo qual o repasse fica de fora do aporte: sem chave PIX no destino congelado ou com NF vinculada ainda não validada. example: invoice_pending required: - payoutId - affiliateId - amountCents - reason additionalProperties: false description: Detalhe dos repasses retidos com o respectivo motivo. required: - payableCount - payableAmountCents - retainedCount - retainedAmountCents - retained additionalProperties: false description: >- Resumo de pagáveis do lote (quem entra na cobrança PIX agora vs. retidos), incluído quando `expand=payable`. Mesma regra da autorização do aporte. funding: anyOf: - type: object properties: id: type: string description: Identificador do aporte (prefixo `fund_` + ULID). example: fund_01J9Z3K8N2QF4T7B9XP0WMD5RC batchId: type: string pattern: ^cyc_[0-9A-HJKMNP-TV-Z]{26}$ description: Lote de fechamento do aporte. status: type: string enum: - pending - received - expired - canceled description: >- Status do aporte (funding) do lote. `pending`: QR gerado, aguardando pagamento. `received`: pago, saldo confirmado (distribuição liberada). `expired`: QR venceu sem pagamento. `canceled`: cancelado antes de pagar. example: pending payoutTotalCents: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Total dos repasses pagáveis do lote no momento da autorização, em centavos. example: 25000 feeBufferCents: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Folga somada ao total para cobrir as taxas do provedor, em centavos. example: 0 chargeValueCents: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Valor da cobrança que o gestor paga (total + folga), em centavos. example: 25000 receivedNetCents: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: >- Valor líquido creditado na subconta ao pagar (do PAYMENT_RECEIVED). qrPayload: anyOf: - type: string - type: 'null' description: Copia-e-cola do QR Code PIX (BR Code). qrEncodedImage: anyOf: - type: string - type: 'null' description: Imagem do QR Code em base64. qrExpiresAt: anyOf: - type: string format: date-time - type: 'null' description: Expiração do QR Code. requestedAt: type: string format: date-time receivedAt: anyOf: - type: string format: date-time - type: 'null' createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - id - batchId - status - payoutTotalCents - feeBufferCents - chargeValueCents - receivedNetCents - qrPayload - qrEncodedImage - qrExpiresAt - requestedAt - receivedAt - createdAt - updatedAt additionalProperties: false - type: 'null' description: >- Aporte (cobrança PIX / QR) do lote. `null` enquanto o repasse não foi autorizado. required: - id - organizationId - programId - status - closingAt - affiliateCount - totalCents - payoutIds - invoiceIds - 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`. ````