Depositar saldo e distribuir benefícios

Este guia percorre o fluxo financeiro completo: preparar colaboradores, gerar e acompanhar um depósito, conferir saldo, criar uma distribuição, revisar valores e finalizar.

Resultado esperado

Ao concluir, você terá:

Dado	Origem	Uso
`employee_id`	Cadastro ou listagem de colaboradores	Incluir uma ou mais pessoas no modo `selected`
`benefit_id`	Criação ou listagem de benefícios	Selecionar convenções no modo `group`
`transaction_id`	Criação de depósito	Consultar pagamento e conciliar transações
`distribution_id`	Criação do rascunho	Revisar, alterar e finalizar a distribuição
`product_id`	Listagem de produtos	Definir valores em centavos

Antes de começar

Configure a base URL, o API token entregue pela ValePix e os identificadores obtidos nas etapas anteriores.

export VALEPIX_BASE_URL="https://routes.valepix.com.br"
export VALEPIX_API_TOKEN="<api_token>"
export EMPLOYEE_ID="<employee_id>"
export BENEFIT_ID="<benefit_id>"
export PRODUCT_ID="<product_id>"

Todas as chamadas JSON usam estes headers:

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

Use um API token ativo e autorizado. Todos os valores monetários enviados e recebidos neste fluxo estão em centavos.

Fluxo recomendado

Ordem	Objetivo	Chamada	Guarde	Documentação completa
1	Preparar colaboradores	`GET /api/v1/valepix/employees`	`employee_id`	Colaboradores
2	Criar depósito	`POST /api/v1/valepix/deposits`	`transaction_id`	Criar depósito
3	Acompanhar depósito	`GET /api/v1/valepix/deposits/{transaction_id}`	Estado do pagamento	Consultar depósito
4	Conferir saldo	`GET /api/v1/valepix/balances`	Saldo disponível	Consultar saldos
5	Criar rascunho	`POST /api/v1/valepix/distributions`	`distribution_id`	Criar rascunho
6	Incluir colaboradores	`POST /api/v1/valepix/distributions/{distribution_id}/items`	Totais atualizados	Adicionar itens
7	Definir valores	`PUT /api/v1/valepix/distributions/{distribution_id}/items/value`	Totais atualizados	Atualizar valor em lote
8	Revisar itens	`GET /api/v1/valepix/distributions/{distribution_id}/items`	Colaboradores e valores	Listar itens
9	Finalizar	`POST /api/v1/valepix/distributions/{distribution_id}/finalize`	Estado da distribuição	Finalizar distribuição
10	Acompanhar	`GET /api/v1/valepix/distributions/{distribution_id}`	Estado final	Consultar distribuição

1. Prepare os colaboradores

Cadastre um colaborador com POST /api/v1/valepix/employees ou use o fluxo de lote. Consulte Cadastrar colaboradores e guarde os employee_id.

Para conferir os IDs:

curl --request GET \
  --url "$VALEPIX_BASE_URL/api/v1/valepix/employees?page=1&limit=100&situation=active" \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Accept: application/json"

2. Crie um depósito

O exemplo gera uma cobrança de R$ 1.000,00:

curl --request POST \
  --url "$VALEPIX_BASE_URL/api/v1/valepix/deposits" \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "amount": 100000,
    "method": "PIX",
    "name": "Empresa Exemplo",
    "document": "12345678000190",
    "transaction_id": "00000000-0000-4000-8000-000000000501"
  }'

Se você enviar transaction_id, use um UUID. Guarde o identificador retornado:

export TRANSACTION_ID="<transaction_id_retornado>"

Referência: Criar depósito.

3. Acompanhe o depósito

curl --request GET \
  --url "$VALEPIX_BASE_URL/api/v1/valepix/deposits/$TRANSACTION_ID" \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Accept: application/json"

Use intervalo e backoff entre consultas. Prossiga somente quando o estado for COMPLETED; FAILED, CANCELLED e EXPIRED são estados finais sem conclusão do crédito.

Referência: Consultar depósito.

4. Confira o saldo

curl --request GET \
  --url "$VALEPIX_BASE_URL/api/v1/valepix/balances" \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Accept: application/json"

Confirme se o valor necessário está disponível. Para conciliação, consulte também:

curl --request GET \
  --url "$VALEPIX_BASE_URL/api/v1/valepix/transactions?page=1&limit=20&type=DEPOSIT" \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Accept: application/json"

5. Escolha o modo e crie o rascunho

Use um dos modos:

Modo	Quando usar
`selected`	Selecionar um ou mais colaboradores por `employee_id`
`batch`	Incluir todos os colaboradores ativos e elegíveis
`group`	Incluir colaboradores ativos e elegíveis de convenções específicas

Exemplo selected:

curl --request POST \
  --url "$VALEPIX_BASE_URL/api/v1/valepix/distributions" \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{"type":"selected"}'

Exemplo batch:

{
  "type": "batch"
}

Exemplo group:

{
  "type": "group",
  "benefit_convention_ids": [
    "<benefit_id_retornado>"
  ]
}

Use como benefit_convention_ids os benefit_id retornados pelas rotas de benefícios.

Guarde o identificador:

export DISTRIBUTION_ID="<distribution_id_retornado>"

6. Inclua colaboradores no modo `selected`

Para uma pessoa, envie um ID. Para várias, envie todos no mesmo array:

curl --request POST \
  --url "$VALEPIX_BASE_URL/api/v1/valepix/distributions/$DISTRIBUTION_ID/items" \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data "{
    \"employee_ids\": [
      \"$EMPLOYEE_ID\"
    ]
  }"

Adição, remoção e alteração de valores só podem ocorrer enquanto o estado for draft.

7. Defina os valores

Defina R$ 500,00 para um produto em todos os itens:

curl --request PUT \
  --url "$VALEPIX_BASE_URL/api/v1/valepix/distributions/$DISTRIBUTION_ID/items/value" \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data "{
    \"product_id\": \"$PRODUCT_ID\",
    \"value\": 50000
  }"

Para ajustar somente uma pessoa, use:

PUT /api/v1/valepix/distributions/{distribution_id}/items/{employee_id}/value

8. Revise imediatamente antes de finalizar

curl --request GET \
  --url "$VALEPIX_BASE_URL/api/v1/valepix/distributions/$DISTRIBUTION_ID/items?page=1&limit=100" \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Accept: application/json"

Confira:

estado draft;
todos os colaboradores esperados;
pelo menos um item com valor positivo em centavos;
total_employees e total_amount;
saldo suficiente para a opção de pagamento escolhida.

9. Finalize

Métodos aceitos: PIX, BOLETO, BALANCE, BALANCE_WITH_PIX e BALANCE_WITH_BOLETO.

curl --request POST \
  --url "$VALEPIX_BASE_URL/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"
    }
  }'

Qualquer método diferente retorna HTTP 422.

Não repita automaticamente a chamada após timeout. Consulte GET /api/v1/valepix/distributions/{distribution_id} para determinar o estado atual.

A resposta começa com o lote em PENDING; a distribuição passa para processing. Com BALANCE, transaction_id é omitido.

10. Acompanhe ou trate exceções

Use Consultar distribuição até completed ou outro estado final.
Se a cobrança expirar, use Regenerar pagamento.
Se precisar interromper uma operação elegível, use Cancelar distribuição.

Erros mais comuns neste fluxo

Situação	Possível causa	Como resolver
`400 Bad Request`	Body, identificador, data ou valor inválido	Corrigir os dados enviados conforme a página da rota
`401 Unauthorized`	Token ausente, inválido, expirado ou revogado	Conferir o header `Authorization` e solicitar novo token se necessário
`403 Forbidden`	Token sem acesso ao recurso solicitado	Confirmar a liberação com a ValePix
`404 Not Found`	Identificador não encontrado	Usar IDs retornados pela API e conferir o ambiente
`409 Conflict`	Conflito específico, como cancelamento de cobrança já paga	Consultar a distribuição e a transação antes da próxima ação
`422 Unprocessable Entity`	Estado incompatível, método ou regra de negócio não suportada	Consultar o recurso e corrigir os dados indicados pela rota
`429 Too Many Requests`	Limite de chamadas excedido	Reduzir a frequência e aplicar backoff
`500`, `502`, `503`, `504`	Falha temporária	Consultar o estado do recurso antes de repetir uma mutação

Resultado esperado​

Antes de começar​

Fluxo recomendado​

1. Prepare os colaboradores​

2. Crie um depósito​

3. Acompanhe o depósito​

4. Confira o saldo​

5. Escolha o modo e crie o rascunho​

6. Inclua colaboradores no modo selected​

7. Defina os valores​

8. Revise imediatamente antes de finalizar​

9. Finalize​

10. Acompanhe ou trate exceções​

Erros mais comuns neste fluxo​

Próximas referências​