Adicionar itens

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

Adiciona um ou mais colaboradores a uma distribuição no estado draft.

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
employee_ids	array	Sim	IDs de colaboradores ativos e elegíveis retornados pela API

Exemplo curl

curl --request POST \
  --url "https://routes.valepix.com.br/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\"
    ]
  }"

Response

HTTP 200 OK.

{
  "success": "success",
  "data": {
    "added_count": 1,
    "total_employees": 1,
    "total_amount": 50000
  }
}

total_amount é retornado em centavos.

Validações importantes

• A distribuição precisa estar em draft.
• Cada colaborador precisa estar ativo e ser elegível.
• Um colaborador já incluído não deve ser reenviado.
• Em uma lista mista, colaboradores inválidos, inativos ou já incluídos são ignorados; os válidos são adicionados.

Erros comuns

HTTP	Quando acontece	Ação recomendada
400	Identificador malformado	Corrigir os IDs 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 não encontrada	Conferir o distribution_id
422	Lista vazia, distribuição fora de draft, nenhum colaborador válido para adicionar ou contrato indisponível	Consultar o rascunho e usar colaboradores ativos retornados pela API
429	Limite de chamadas excedido	Reduzir a taxa de chamadas e aplicar backoff
500, 502, 503, 504	Falha temporária	Tentar novamente com backoff

Repetir a mesma lista depois de ela já ter sido adicionada retorna 422. Consulte os itens antes de repetir após timeout.