Consultar distribuição

GET /api/v1/valepix/distributions/{distribution_id}

Retorna uma distribuição disponível 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

Parâmetro	Tipo	Obrigatório	Descrição
distribution_id	string	Sim	Identificador retornado na criação ou listagem

Exemplo curl

curl --request GET \
  --url "https://routes.valepix.com.br/api/v1/valepix/distributions/$DISTRIBUTION_ID" \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Accept: application/json"

Response

HTTP 200 OK.

{
  "success": "success",
  "data": {
    "distribution": {
      "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
        }
      ]
    }
  }
}

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; distribuições criadas sem ele não trazem o campo.

Use status para decidir a próxima operação conforme o ciclo de estados.

Erros comuns

HTTP	Quando acontece	Ação recomendada
400	distribution_id inválido	Conferir o identificador enviado na URL
401	Token ausente, inválido, expirado ou revogado	Conferir o header Authorization
403	Distribuição não disponível para a integração	Conferir o distribution_id, o ambiente e o token
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