Finalizar distribuição

POST /api/v1/valepix/distributions/{distribution_id}/finalize

Confirma os colaboradores e valores do rascunho e inicia o pagamento.

Autenticação

Envie um API token ativo no header Authorization.

Authorization: Bearer <VALEPIX_API_TOKEN>
Accept: application/json
Content-Type: application/json

Path params

Parâmetro	Tipo	Obrigatório	Descrição
distribution_id	string	Sim	Identificador da distribuição em draft

Body

Campo	Tipo	Obrigatório	Descrição
description	string	Não	Descrição da distribuição
scheduled_for	string ou null	Não	Data e hora futura em ISO 8601; null processa sem agendamento
payment_method	string	Sim	PIX, BOLETO, BALANCE, BALANCE_WITH_PIX ou BALANCE_WITH_BOLETO
payer_name	string	Não	Nome do pagador; usa os dados da empresa quando omitido
payer_document	string	Não	Documento do pagador; usa os dados da empresa quando omitido
invoice_descriptions	object	Não	Mapa do slug da conta de benefício para uma descrição usada nos documentos da operação

Exemplo curl

curl --request POST \
  --url "https://routes.valepix.com.br/api/v1/valepix/distributions/$DISTRIBUTION_ID/finalize" \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "description": "Benefícios de julho",
    "scheduled_for": null,
    "payment_method": "BALANCE",
    "payer_name": "Empresa Exemplo",
    "payer_document": "12345678000190",
    "invoice_descriptions": {
      "alimentacao": "Benefício alimentação - julho"
    }
  }'

Response

HTTP 200 OK.

{
  "success": "success",
  "data": {
    "batch_id": "00000000-0000-4000-8000-000000000901",
    "status": "PENDING"
  }
}

Quando uma cobrança for necessária, payment_info pode trazer os dados correspondentes:

{
  "success": "success",
  "data": {
    "batch_id": "00000000-0000-4000-8000-000000000901",
    "status": "PENDING",
    "transaction_id": "00000000-0000-4000-8000-000000000902",
    "payment_info": {
      "amount": 50000,
      "pix_copy_paste": "codigo_pix_retornado",
      "pix_qr_code_url": "https://exemplo.test/qr-code",
      "expiration_date": "2026-07-24T23:59:59Z"
    }
  }
}

status é o estado do lote de pagamento. Após a finalização, a distribuição passa para processing, enquanto o lote começa em PENDING. Com BALANCE, transaction_id é omitido; métodos que geram cobrança podem retorná-lo junto de payment_info.

Validações importantes

• A distribuição precisa estar em draft.
• Os colaboradores, produtos e valores precisam estar revisados.
• Valores são inteiros não negativos em centavos.
• Itens cujo total é zero são retirados antes do processamento; deve restar ao menos um item com valor positivo.
• Para BALANCE, o saldo disponível precisa ser suficiente.
• Ao agendar um método que gera cobrança, scheduled_for precisa ficar pelo menos dois dias após o vencimento calculado da cobrança.
• payment_method aceita somente os métodos documentados nesta página.

Erros comuns

HTTP	Quando acontece	Ação recomendada
400	Body, pagador, agendamento ou valores inválidos	Corrigir os dados enviados
401	Token ausente, inválido, expirado ou revogado	Conferir o header Authorization
403	Token sem acesso ao recurso solicitado	Confirmar token com a ValePix
404	Distribuição ou recurso relacionado não encontrado	Conferir os identificadores usados
422	Distribuição fora de draft, item inválido, método não suportado ou saldo insuficiente	Consultar o rascunho e corrigir a condição indicada
429	Limite de chamadas excedido	Reduzir a taxa de chamadas e aplicar backoff
500, 502, 503, 504	Falha temporária antes ou durante o processamento	Consultar a distribuição antes de repetir a chamada

Não repita automaticamente uma finalização após timeout sem antes consultar a distribuição.