> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turbofypay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Baixar comprovante de payout

> Baixa o PDF TurbofyPay de um item de payout pago, com beneficiario real confirmado.

## Caso de uso

Use este endpoint para baixar o comprovante PDF de um item de payout especifico.
O comprovante e sempre por item, nao por lote, e usa marca TurbofyPay.

Para uso autenticado no painel ou em fluxos seller, o mesmo comprovante tambem
pode ser acessado por `GET /sellers/saques/payout-items/{itemId}/receipt`.

## Autenticacao

Na rota v1, envie:

* `x-client-id`
* `x-client-secret`
* `x-turbofy-timestamp`
* `x-turbofy-signature`

Na rota seller, envie:

* `x-client-id`
* `x-client-secret`

## Pre-condicoes

* O item precisa pertencer ao merchant autenticado.
* O payout precisa estar pago ou concluido.
* O item precisa ter rastreio Pix suficiente para localizar o comprovante.
* O beneficiario real precisa estar completo para gerar o PDF TurbofyPay.

## Beneficiario e instituicao

O comprovante usa `beneficiary` como recebedor real. `declaredRecipient` nunca e
usado como prova de quem recebeu o Pix.

A instituicao do beneficiario deve vir da transacao Pix reconciliada ou do
comprovante oficial usado como evidencia. Nomes de PSP, fornecedor, rota
operacional ou conta de infraestrutura nao devem aparecer como instituicao do
beneficiario.

## Response de sucesso

Em `200`, a API retorna:

* `Content-Type: application/pdf`
* `Content-Disposition: inline`
* `Cache-Control: private, no-store`

```bash theme={null}
curl --request GET \
  --url "https://api.turbofypay.com/v1/payouts/batches/batch-1/items/b892f167-1b3b-4718-a0b4-5ef81fc4d14b/receipt" \
  --header "x-client-id: <client-id>" \
  --header "x-client-secret: <client-secret>" \
  --header "x-turbofy-timestamp: 1772805000000" \
  --header "x-turbofy-signature: <hmac-sha256>" \
  --output comprovante-payout.pdf
```

## Erros comuns reais

| HTTP | code | Quando ocorre |
| - | - | - |
| `401` | `INVALID_CREDENTIALS` | Credenciais ausentes ou invalidas. |
| `401` | `INVALID_SIGNATURE` | Assinatura HMAC ausente, invalida ou expirada na rota v1. |
| `403` | `PAYOUT_ITEM_FORBIDDEN` | O item nao pertence ao merchant autenticado. |
| `404` | `PAYOUT_ITEM_NOT_FOUND` | Item inexistente ou fora do lote informado. |
| `409` | `PAYOUT_ITEM_RECEIPT_UNAVAILABLE` | Comprovante indisponivel ou beneficiario real ainda incompleto. |

## Regras de negocio

* O PDF usa marca TurbofyPay.
* O PDF oficial do provedor pode ser usado internamente como evidencia, mas nao e entregue como brand final por padrao.
* A API nao inventa instituicao a partir de ISPB.
* O comprovante nao deve exibir nome de fornecedor operacional.
* Documento completo e chave Pix completa aparecem somente em contexto autenticado/autorizado.

## Proximos passos

1. Consulte os itens em [Listar itens de payout](https://docs.turbofypay.com/pages/reference/payouts/listar-itens-payouts.md).
2. Para filtros e exportacao operacional, use [Listar payouts de saques](https://docs.turbofypay.com/pages/reference/saques/listar-pixout-payout-items.md).


## OpenAPI

````yaml GET /v1/payouts/batches/{batchId}/items/{itemId}/receipt
openapi: 3.0.3
info:
  title: Turbofy Public API
  version: 2.0.0
  description: >-
    Especificacao publica da API TurbofyPay para Cobranca PIX, Saldo, Saques,
    Webhooks e Payouts.
  contact:
    name: Turbofy Team
    email: suporte@turbofy.com
    url: https://turbofy.com
  license:
    name: Proprietary
    url: https://turbofy.com/terms
servers:
  - url: http://localhost:3030
    description: Development Server
  - url: https://api.turbofypay.com
    description: Production Server
security: []
tags:
  - name: Cobranca PIX
    description: Operacoes de cobranca PIX para integradores.
  - name: Saques
    description: Operacoes de saque para sellers.
  - name: Webhooks
    description: Cadastro e consulta de webhooks.
  - name: Payouts
    description: Gestao de lotes de payout.
  - name: Saldo
    description: Consulta do proprio saldo com credenciais de integracao.
externalDocs:
  description: Documentação completa
  url: https://docs.turbofy.com
paths:
  /v1/payouts/batches/{batchId}/items/{itemId}/receipt:
    get:
      tags:
        - Payouts
      summary: Baixar comprovante do item de payout
      description: >-
        Baixa o comprovante PDF TurbofyPay de um item de payout usando
        autenticacao HMAC.
      operationId: downloadPayoutBatchItemReceipt
      parameters:
        - schema:
            type: string
            minLength: 1
          in: path
          name: batchId
          required: true
          description: Identificador do lote.
        - schema:
            type: string
            minLength: 1
          in: path
          name: itemId
          required: true
          description: Identificador do item de payout.
        - $ref: '#/components/parameters/XClientId'
        - $ref: '#/components/parameters/XClientSecret'
        - $ref: '#/components/parameters/XTurbofyTimestamp'
        - $ref: '#/components/parameters/XTurbofySignature'
      responses:
        '200':
          description: Comprovante PDF gerado.
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '401':
          description: Credenciais ou assinatura invalidas.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Acesso negado ao recibo do item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Item de payout nao encontrado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Comprovante indisponivel ou beneficiario real ainda incompleto.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - clientCredentials: []
          clientSecret: []
components:
  parameters:
    XClientId:
      name: x-client-id
      in: header
      required: true
      schema:
        type: string
      description: Identificador do integrador.
    XClientSecret:
      name: x-client-secret
      in: header
      required: true
      schema:
        type: string
      description: Segredo de autenticacao do integrador.
    XTurbofyTimestamp:
      name: x-turbofy-timestamp
      in: header
      required: true
      schema:
        type: string
      description: Timestamp utilizado na assinatura HMAC.
    XTurbofySignature:
      name: x-turbofy-signature
      in: header
      required: true
      schema:
        type: string
      description: Assinatura HMAC SHA-256 da requisicao.
  schemas:
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: object
              additionalProperties: true
            traceId:
              type: string
  securitySchemes:
    clientCredentials:
      type: apiKey
      in: header
      name: x-client-id
      description: Client ID fornecido pela TurbofyPay.
    clientSecret:
      type: apiKey
      in: header
      name: x-client-secret
      description: Client Secret fornecido pela TurbofyPay.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.