Distribuições
Uma distribuição organiza o envio de valores para um ou mais colaboradores. O fluxo começa como rascunho, permite revisar participantes e valores e termina com a finalização.
Base path:
/api/v1/valepix/distributions
Modos de criação
type | Comportamento |
|---|---|
selected | Cria um rascunho vazio; adicione os colaboradores escolhidos depois |
batch | Inclui os colaboradores ativos e elegíveis da empresa |
group | Inclui colaboradores ativos e elegíveis vinculados a uma ou mais convenções informadas em benefit_convention_ids |
Use apenas convenções e colaboradores retornados pelas rotas da integração.
Ciclo de estados
| Estado | Significado | Operações |
|---|---|---|
draft | Rascunho editável | Adicionar/remover colaboradores, atualizar valores e finalizar |
processing | Distribuição finalizada e em processamento | Consultar ou cancelar quando permitido |
completed | Valores concluídos | Consultar |
failed | Processamento falhou | Consultar |
expired | Pagamento expirou | Consultar ou regenerar pagamento |
cancelled | Distribuição cancelada | Consultar |
Adição, remoção e alteração de valores são aceitas somente em draft. Ao cancelar um rascunho, a API exclui a distribuição; o estado cancelled é usado quando uma distribuição em processamento é cancelada.
Métodos de pagamento
| Método | Uso |
|---|---|
PIX | Gera cobrança PIX |
BOLETO | Gera cobrança por boleto |
BALANCE | Usa o saldo disponível da empresa |
BALANCE_WITH_PIX | Combina saldo disponível e PIX |
BALANCE_WITH_BOLETO | Combina saldo disponível e boleto |
Qualquer valor diferente não é aceito pela API.
Rotas disponíveis
| Operação | Método | Rota |
|---|---|---|
| Criar rascunho | POST | /api/v1/valepix/distributions |
| Listar distribuições | GET | /api/v1/valepix/distributions |
| Consultar distribuição | GET | /api/v1/valepix/distributions/{distribution_id} |
| Listar itens | GET | /api/v1/valepix/distributions/{distribution_id}/items |
| Adicionar itens | POST | /api/v1/valepix/distributions/{distribution_id}/items |
| Remover itens | DELETE | /api/v1/valepix/distributions/{distribution_id}/items |
| Atualizar valor em lote | PUT | /api/v1/valepix/distributions/{distribution_id}/items/value |
| Atualizar valor individual | PUT | /api/v1/valepix/distributions/{distribution_id}/items/{employee_id}/value |
| Finalizar | POST | /api/v1/valepix/distributions/{distribution_id}/finalize |
| Cancelar | POST | /api/v1/valepix/distributions/{distribution_id}/cancel |
| Regenerar pagamento | POST | /api/v1/valepix/distributions/{distribution_id}/regenerate-payment |
Todas as rotas exigem um API token ativo e autorizado.
Regras gerais
- Valores monetários são inteiros em centavos, não negativos.
- Use apenas identificadores retornados pelas rotas públicas da integração.
- Confira saldos e itens imediatamente antes de finalizar.
Veja o fluxo ponta a ponta em Depositar saldo e distribuir benefícios.
Envelope de resposta
Em caso de sucesso, as respostas seguem o padrão:
{
"success": "success",
"data": {}
}
Em erros de validação, autenticação ou autorização, consulte Erros.