> ## 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.
# Criar lote de payouts
> Cria um lote de saques PIX com assinatura HMAC e idempotencia por merchant.
## Caso de uso
Use este endpoint para enviar pagamentos em lote para multiplos recebedores com reserva de saldo e processamento assincrono.
## Autenticacao
Headers obrigatorios:
* `x-client-id`
* `x-client-secret`
* `x-turbofy-timestamp`
* `x-turbofy-signature`
## Pre-condicoes e requisitos
* Merchant precisa ter payouts habilitado.
* `idempotencyKey` entre 8 e 100 caracteres.
* Cada item precisa de `pixKey`, `pixKeyType`, `amountCents` e `recipientName`.
* A assinatura HMAC deve ser recalculada em toda requisicao.
## Request
Campos principais:
* `idempotencyKey`: deduplicacao da operacao.
* `description`: descricao operacional.
* `metadata`: dados auxiliares de conciliacao.
* `items[]`: transferencias individuais do lote.
## Response de sucesso
* `201`: lote criado.
* `200`: replay idempotente com mesmo payload.
Campos de retorno principais:
* `batchId`
* `status`
* `totalAmountCents`
* `totalFeeCents`
* `totalFundingCents`
* `itemsCount`
* `idempotencyReplay`
*O lote nasce com reserva financeira e trilha de auditoria. Use a chave de idempotencia para evitar duplicidade e acompanhe o processamento depois da criacao.*
## Erros comuns reais
201 CREATED
400 PAYOUTS\_NOT\_ENABLED
409 DUPLICATE\_IDEMPOTENCY\_KEY
| HTTP | code | Quando ocorre |
| ----- | -------------------------------- | ---------------------------------------------- |
| `401` | `INVALID_SIGNATURE` | Assinatura HMAC ausente, invalida ou expirada. |
| `401` | `INVALID_CREDENTIALS` | Credenciais ausentes ou invalidas. |
| `400` | `PAYOUTS_NOT_ENABLED` | Merchant sem payout habilitado. |
| `400` | `INSUFFICIENT_AVAILABLE_BALANCE` | Saldo insuficiente para financiar o lote. |
| `409` | `DUPLICATE_IDEMPOTENCY_KEY` | Chave repetida com payload diferente. |
| `409` | `WITHDRAWAL_FROZEN` | Saques/payouts bloqueados temporariamente. |
## Regras de negocio e observacoes operacionais
* A idempotencia e aplicada por merchant.
* O saldo e reservado no momento da criacao.
* Processamento dos itens acontece apos criacao do lote.
* Para auditoria, registre `batchId`, `idempotencyKey` e `traceId`.
## Exemplo de codigo
```bash theme={null}
curl --request POST \
--url https://api.turbofypay.com/v1/payouts/batches \
--header "x-client-id: " \
--header "x-client-secret: " \
--header "x-turbofy-timestamp: 1772805000000" \
--header "x-turbofy-signature: " \
--header "Content-Type: application/json" \
--data '{
"idempotencyKey": "folha-empresa-2026-03-06",
"description": "Folha semanal",
"items": [
{
"pixKey": "recebedor@example.test",
"pixKeyType": "EMAIL",
"amountCents": 250000,
"recipientName": "Recebedor Exemplo",
"recipientDocument": "00000000000",
"referenceId": "payout-001"
}
]
}'
```
## Proximos passos
1. Consulte andamento em [Consultar lote de payouts](/reference/payouts/consultar-lote-payouts).
2. Para troubleshooting de assinatura, revise [Autenticacao](/integracao/autenticacao).
## OpenAPI
````yaml POST /v1/payouts/batches
openapi: 3.0.3
info:
title: Turbofy Public API
version: 2.0.0
description: >-
Especificacao publica da API TurbofyPay para Cobranca PIX, 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.
externalDocs:
description: Documentação completa
url: https://docs.turbofy.com
paths:
/v1/payouts/batches:
post:
tags:
- Payouts
summary: Criar lote de payouts
description: Cria um lote de payouts com validacao de assinatura HMAC e idempotencia.
operationId: createPayoutBatch
parameters:
- $ref: '#/components/parameters/XClientId'
- $ref: '#/components/parameters/XClientSecret'
- $ref: '#/components/parameters/XTurbofyTimestamp'
- $ref: '#/components/parameters/XTurbofySignature'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutBatchCreateRequest'
responses:
'200':
description: Replay de idempotencia para o mesmo payload.
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutBatchCreateResponse'
'201':
description: Lote criado com sucesso.
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutBatchCreateResponse'
'400':
description: Payload invalido ou assinatura incorreta.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Credenciais ou assinatura invalidas.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
description: Conflito de idempotencia ou regra de negocio.
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:
PayoutBatchCreateRequest:
type: object
required:
- idempotencyKey
- items
properties:
idempotencyKey:
type: string
minLength: 8
maxLength: 100
description:
type: string
maxLength: 255
metadata:
type: object
additionalProperties: true
items:
type: array
minItems: 1
items:
type: object
required:
- pixKey
- pixKeyType
- amountCents
- recipientName
properties:
pixKey:
type: string
pixKeyType:
type: string
enum:
- CPF
- CNPJ
- EMAIL
- PHONE
- EVP
amountCents:
type: integer
minimum: 1
recipientName:
type: string
maxLength: 120
recipientDocument:
type: string
referenceId:
type: string
maxLength: 120
PayoutBatchCreateResponse:
type: object
required:
- batchId
- status
- totalAmountCents
- totalFeeCents
- totalFundingCents
- itemsCount
- idempotencyReplay
properties:
batchId:
type: string
status:
type: string
totalAmountCents:
type: integer
totalFeeCents:
type: integer
totalFundingCents:
type: integer
itemsCount:
type: integer
idempotencyReplay:
type: boolean
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.
````