Cancelar guía

Cancela un envío existente y solicita el reembolso de la etiqueta con la paquetería.

Un envío solo puede cancelarse si no ha sido recolectado, escaneado o ingresado a la red de transporte de la paquetería. La elegibilidad del reembolso depende de la política de cancelación de cada carrier.

Endpoint

POST /shipments/cancel

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
trackingNumber	string	Sí	Número de seguimiento del envío que se desea cancelar.

Ejemplo

{
  "trackingNumber": "794813797842"
}

Respuesta exitosa

HTTP 200 OK

Campo	Tipo	Descripción
status	string	Estado actual del envío después de la cancelación.
trackingNumber	string	Número de seguimiento del envío cancelado.
carrier	string	Paquetería responsable del envío.
service	string	Servicio utilizado para el envío.
balanceRefunded	boolean	Indica si el costo de la guía fue reembolsado.

Ejemplo

{
  "status": "Canceled",
  "trackingNumber": "794813797842",
  "carrier": "jtexpress",
  "service": "ground",
  "balanceRefunded": true
}

El campo balanceRefunded indica si el costo de la guía fue reembolsado después de solicitar la cancelación. Si el valor es true, el saldo fue reembolsado correctamente. Si el valor es false, la guía puede haberse cancelado correctamente, pero el reembolso puede quedar pendiente o depender de la política de la paquetería.

Respuestas de error

HTTP 404 Not Found → Shipment not found

{
  "status": 404,
  "message": "Shipment not found"
}

HTTP 409 Conflict → Shipment cannot be canceled

{
  "status": 409,
  "error": "Invalid status transition"
}

HTTP 400 Bad Request → Invalid Request

{
  "status": 400,
  "message": "Validation error",
  "errors": [
    {
      "code": "invalid_type",
      "expected": "string",
      "received": "undefined",
      "path": [
        "trackingNumber"
      ],
      "message": "Required"
    }
  ]
}

Notas

• Los tiempos de procesamiento del reembolso pueden variar según la paquetería.
• Una vez que el envío ha sido escaneado o recolectado por la paquetería, es posible que ya no pueda cancelarse.