Listar distribuições

GET /api/v1/valepix/distributions

Lista as distribuições disponíveis para a integração autorizada.

Autenticação

Envie um API token ativo no header Authorization.

Authorization: Bearer <VALEPIX_API_TOKEN>
Accept: application/json

Path params

Esta rota não possui path params.

Query params

Parâmetro	Tipo	Obrigatório	Descrição
page	number	Não	Página atual; padrão 1
limit	number	Não	Itens por página; padrão 10, máximo 100
status	string	Não	Filtra por draft, processing, completed, failed, cancelled ou expired
start_date	string	Não	Data inicial em ISO 8601
end_date	string	Não	Data final em ISO 8601

Exemplo curl

curl --request GET \
  --url "https://routes.valepix.com.br/api/v1/valepix/distributions?page=1&limit=10&status=draft" \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Accept: application/json"

Response

HTTP 200 OK.

{
  "success": "success",
  "data": {
    "distributions": [
      {
        "id": "00000000-0000-4000-8000-000000000801",
        "name": "Distribuição Manual",
        "status": "draft",
        "external_reference": "f9dd90ee-e36b-4f6e-8b18-31b6a2bbdbde",
        "total_amount": 50000,
        "total_count": 1,
        "created_at": "2026-07-23T12:00:00Z",
        "products": [
          {
            "id": "00000000-0000-4000-8000-000000000201",
            "slug": "alimentacao",
            "total_amount": 50000,
            "total_count": 1
          }
        ]
      }
    ],
    "meta": {
      "total": 1,
      "current_page": 1,
      "last_page": 1,
      "limit": 10
    }
  }
}

Valores monetários são retornados em centavos. Campos opcionais sem valor, como scheduled_for, paid_at, transaction_id e external_reference, são omitidos. external_reference é o identificador informado pelo integrador na criação e permite localizar uma distribuição a partir do identificador do sistema de origem.

Erros comuns

HTTP	Quando acontece	Ação recomendada
401	Token ausente, inválido, expirado ou revogado	Conferir o header Authorization
403	Token sem acesso ao recurso solicitado	Confirmar token com a ValePix
429	Limite de chamadas excedido	Reduzir a frequência das consultas e aplicar backoff
500, 502, 503, 504	Falha temporária na consulta	Tentar novamente com backoff