Base URL

Use a URL e o token correspondentes ao ambiente:

Ambiente	Base URL
Produção	https://routes.valepix.com.br
Sandbox	https://sandbox-routes.valepix.com.br

Os exemplos desta documentação usam produção. Tokens, identificadores e dados não são compartilhados entre os ambientes.

Os paths das rotas incluem o prefixo /api/v1 (por exemplo, /api/v1/valepix/products). Concatene base + path para montar a URL completa. Configure essa URL no seu serviço ou ferramenta de integração.

export VALEPIX_BASE_URL="https://routes.valepix.com.br"
export VALEPIX_API_TOKEN="<api_token>"
export PRODUCT_ID="<product_id_retornado_pela_api>"
export BENEFIT_ID="<benefit_id_retornado_pela_api>"
export EMPLOYEE_SITUATION="active"

Headers

Para chamadas JSON:

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

Para upload de lote:

Authorization: Bearer <VALEPIX_API_TOKEN>
Accept: application/json

Deixe o cliente HTTP gerar o header Content-Type: multipart/form-data com o boundary. Ao usar curl, basta enviar o arquivo com --form.

Validação inicial

Use uma rota de leitura para validar conectividade e autorização do token.

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

Em seguida, use PRODUCT_ID para criar ou atualizar benefícios e obtenha o BENEFIT_ID. Depois, use a rota de situações para escolher o valor de EMPLOYEE_SITUATION.

curl --request POST \
  --url "$VALEPIX_BASE_URL/api/v1/valepix/benefits" \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "name": "Benefício Flexível",
    "description": "Configuração padrão para colaboradores elegíveis",
    "items": [
      {
        "product_id": "'"$PRODUCT_ID"'",
        "monthly_amount": 50000
      }
    ]
  }'

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

Variáveis úteis

Variável	Origem
VALEPIX_API_TOKEN	Entregue pela ValePix por canal seguro
PRODUCT_ID	Campo id retornado por GET /api/v1/valepix/products
BENEFIT_ID	Campo benefit_id retornado na criação de benefício ou id retornado por GET /api/v1/valepix/benefits
EMPLOYEE_SITUATION	Campo value retornado por GET /api/v1/valepix/employees/situations

Segurança

• Nunca exponha o API token em repositórios, planilhas, prints ou tickets.
• Não registre o token completo em logs.
• Mascare CPF, telefone e demais dados pessoais em logs operacionais.
• Revogue tokens que não estejam mais em uso.