Criar rascunho

POST /api/v1/valepix/distributions

Cria 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

Esta rota não possui path params.

Body

Campo	Tipo	Obrigatório	Descrição
type	string	Sim	Modo suportado: selected, batch ou group
benefit_convention_ids	array	Somente em group	Uma ou mais convenções disponíveis para a integração
external_reference	string	Não	Identificador definido pelo integrador, único por empresa, com até 128 caracteres e sem caracteres de controle. Torna a criação idempotente; veja Idempotência

Exemplo curl

Rascunho para seleção manual:

curl --request POST \
  --url "https://routes.valepix.com.br/api/v1/valepix/distributions" \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{"type":"selected","external_reference":"f9dd90ee-e36b-4f6e-8b18-31b6a2bbdbde"}'

Rascunho por convenções:

{
  "type": "group",
  "benefit_convention_ids": [
    "00000000-0000-4000-8000-000000000701"
  ],
  "external_reference": "f9dd90ee-e36b-4f6e-8b18-31b6a2bbdbde"
}

Response

HTTP 201 Created.

{
  "success": "success",
  "data": {
    "distribution_id": "00000000-0000-4000-8000-000000000801",
    "external_reference": "f9dd90ee-e36b-4f6e-8b18-31b6a2bbdbde"
  }
}

Em selected, o total começa vazio e os campos de total são omitidos. Em batch e group, os totais aparecem quando maiores que zero e refletem os colaboradores ativos e elegíveis encontrados.

external_reference é devolvido exatamente como foi aceito (espaços nas extremidades são removidos) e omitido quando não foi informado.

Sem external_reference, cada chamada bem-sucedida cria um novo rascunho. Com external_reference, a criação é idempotente por empresa, conforme a seção a seguir.

Idempotência com external_reference

external_reference é um identificador escolhido pelo integrador (por exemplo, o ID da folha ou do pedido no sistema de origem) e único dentro da empresa. A API o utiliza para evitar distribuições duplicadas:

Situação	Resultado
external_reference nunca usado pela empresa	Cria a distribuição normalmente e devolve 201
external_reference já usado com os mesmos dados (type e benefit_convention_ids)	Devolve 201 com a distribuição já existente (distribution_id e totais atuais), sem criar nem reprocessar nada
external_reference já usado com dados divergentes	Devolve 409 com code EXTERNAL_REFERENCE_CONFLICT

Regras:

• Até 128 caracteres; espaços nas extremidades são ignorados; caracteres de controle são rejeitados com 400.
• A comparação é exata e diferencia maiúsculas de minúsculas.
• benefit_convention_ids é comparado como conjunto (a ordem não importa) e só é considerado em group.
• Após timeout ou 5xx, repita a mesma chamada com o mesmo external_reference: se a distribuição já tiver sido criada, você recebe o distribution_id existente em vez de uma duplicata.
• Para criar uma nova distribuição, use um novo external_reference.

Exemplo de resposta 409 (pode incluir trace_id):

{
  "success": "error",
  "message": "External reference already used with different data",
  "code": "EXTERNAL_REFERENCE_CONFLICT",
  "data": {
    "code": "EXTERNAL_REFERENCE_CONFLICT"
  }
}

Validações importantes

• Envie sempre um dos modos suportados em type: selected, batch ou group.
• group exige ao menos um ID de convenção retornado pela API.
• batch e group falham quando não encontram colaboradores elegíveis.
• A resposta sempre cria o recurso em draft.
• external_reference, quando enviado, deve ter até 128 caracteres e ser único por empresa; reutilize-o apenas para repetir exatamente a mesma criação.

Erros comuns

HTTP	Quando acontece	Ação recomendada
400	external_reference com mais de 128 caracteres ou com caracteres de controle	Ajustar o identificador enviado
401	Token ausente, inválido, expirado ou revogado	Conferir o header Authorization
403	Token sem acesso ao recurso solicitado	Confirmar token com a ValePix
409	external_reference já utilizado pela empresa com type ou benefit_convention_ids diferentes (code EXTERNAL_REFERENCE_CONFLICT)	Consultar a distribuição existente pela listagem ou usar um novo external_reference
422	Convenção indisponível, contrato ausente, nenhum colaborador elegível ou outra precondição não atendida	Conferir o modo escolhido e usar identificadores 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