Cancelar distribuição

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

Cancela uma distribuição quando seu estado ainda permite a operação.

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 da distribuição

Body

Esta rota não possui body.

Exemplo curl

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

Response

HTTP 200 OK.

Para uma distribuição em draft, o recurso e seus itens são excluídos:

{
  "success": "success",
  "data": {
    "success": true,
    "status": "deleted",
    "message": "Draft distribution deleted successfully."
  }
}

Para uma distribuição em processing, o estado passa para cancelled:

{
  "success": "success",
  "data": {
    "success": true,
    "status": "cancelled",
    "message": "Distribution cancelled successfully."
  }
}

Validações importantes

• Cancelar uma distribuição em draft exclui o rascunho; uma repetição encontra o recurso ausente.
• Distribuições em processing podem ser canceladas quando as regras operacionais permitirem.
• Uma distribuição completed não pode ser cancelada por esta rota.
• Uma nova chamada para um recurso em cancelled confirma que o estado continua cancelado.

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	Token sem acesso ao recurso solicitado	Confirmar token com a ValePix
404	Distribuição não encontrada	Conferir o distribution_id e o ambiente
409	Cobrança vinculada já foi paga e não pode ser cancelada	Consultar a distribuição e a transação
422	Estado atual não permite cancelamento	Consultar a distribuição e revisar o estado
429	Limite de chamadas excedido	Reduzir a taxa de chamadas e aplicar backoff
500, 502, 503, 504	Falha temporária	Tentar novamente com backoff