ValePix Developers
A API ValePix permite que sistemas de RH, ERPs e plataformas parceiras integrem benefícios, colaboradores, depósitos e distribuições sem depender do portal. A autenticação é feita com API token enviado no header Authorization.
Esta documentação cobre apenas as rotas públicas para clientes. Use um API token autorizado para acessar as rotas de produtos, benefícios, colaboradores, lotes, financeiro e distribuições.
/api/v1/valepix/products
/api/v1/valepix/benefits
/api/v1/valepix/employees/situations
/api/v1/valepix/employees
/api/v1/valepix/deposits
/api/v1/valepix/balances
/api/v1/valepix/transactions
/api/v1/valepix/distributions
Base URL
Os exemplos usam a base URL de produção:
https://routes.valepix.com.br
Os paths das rotas (listados abaixo) incluem o prefixo /api/v1. Para montar a URL completa, concatene base + path, por exemplo: https://routes.valepix.com.br + /api/v1/valepix/products = https://routes.valepix.com.br/api/v1/valepix/products.
Para sandbox e separação de tokens e IDs entre ambientes, consulte Base URL.
Autenticação
Todas as chamadas exigem um API token ativo:
Authorization: Bearer <VALEPIX_API_TOKEN>
Accept: application/json
Content-Type: application/json
Para upload de arquivo em lote, use multipart/form-data no lugar de application/json e deixe o cliente gerar o boundary.
Use o API token autorizado no header Authorization.
Rotas disponíveis
| Operação | Método | Rota |
|---|---|---|
| Listar produtos | GET | /api/v1/valepix/products |
| Criar benefício | POST | /api/v1/valepix/benefits |
| Listar benefícios | GET | /api/v1/valepix/benefits |
| Buscar benefício | GET | /api/v1/valepix/benefits/{benefit_id} |
| Atualizar benefício | PUT | /api/v1/valepix/benefits/{benefit_id} |
| Remover benefício | DELETE | /api/v1/valepix/benefits/{benefit_id} |
| Listar situações de colaboradores | GET | /api/v1/valepix/employees/situations |
| Listar colaboradores | GET | /api/v1/valepix/employees |
| Contar colaboradores ativos | GET | /api/v1/valepix/employees/count |
| Criar colaborador | POST | /api/v1/valepix/employees |
| Buscar colaborador | GET | /api/v1/valepix/employees/{employee_id} |
| Atualizar colaborador | PUT | /api/v1/valepix/employees/{employee_id} |
| Desligar colaborador | DELETE | /api/v1/valepix/employees/{employee_id} |
| Enviar lote | POST | /api/v1/valepix/employees/batch/upload |
| Consultar lote | GET | /api/v1/valepix/employees/batch/{batch_id} |
| Remover itens de lote | DELETE | /api/v1/valepix/employees/batch/{batch_id} |
| Confirmar lote | POST | /api/v1/valepix/employees/batch/{batch_id}/commit |
| Criar depósito | POST | /api/v1/valepix/deposits |
| Consultar depósito | GET | /api/v1/valepix/deposits/{transaction_id} |
| Consultar saldos | GET | /api/v1/valepix/balances |
| Listar transações | GET | /api/v1/valepix/transactions |
| Criar rascunho de distribuição | 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 da distribuição | 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 distribuição | POST | /api/v1/valepix/distributions/{distribution_id}/finalize |
| Cancelar distribuição | POST | /api/v1/valepix/distributions/{distribution_id}/cancel |
| Regenerar pagamento | POST | /api/v1/valepix/distributions/{distribution_id}/regenerate-payment |
Formatos importantes
| Campo | Formato |
|---|---|
employee_id, batch_id, distribution_id | Identificador retornado pela API |
product_id | Use o id retornado por Listar produtos |
benefit_id | Use o benefit_id da criação de benefício ou o id retornado por Listar benefícios |
situation | Use o campo value retornado por Situações de colaboradores |
document | CPF válido do colaborador, preferencialmente somente números |
phone | Telefone brasileiro válido, preferencialmente somente números |
birth_date | YYYY-MM-DD |
admission_date | YYYY-MM-DD |
| Campos monetários | Inteiros em centavos |
transaction_id | UUID retornado pela API ou informado na criação de depósito |
Não envie timestamp ISO completo em birth_date ou admission_date. Use somente data, por exemplo 1990-05-20.
Campos opcionais e valores vazios — como 0, false ou listas sem itens — podem ser omitidos da resposta. Trate a ausência conforme o tipo e a regra descritos em cada rota.
Próximos passos
- Configure a base URL em Base URL.
- Revise as regras de API tokens.
- Siga o fluxo completo em Cadastrar colaboradores.
- Faça uma chamada inicial em Quickstart.
- Liste produtos em Produtos.
- Configure benefícios em Benefícios.
- Implemente as rotas de Colaboradores.
- Revise as rotas do Financeiro.
- Conheça o ciclo de Distribuições.
- Execute o guia Depositar saldo e distribuir benefícios.