01 / Guía
Anulación, reembolso y devolución no son lo mismo
La anulación invalida una guía que todavía no debe continuar. El reembolso es el crédito que esa anulación devuelve al saldo. Una devolución ocurre cuando un paquete necesita viajar de regreso y requiere una guía nueva.
Separar estos conceptos evita buscar un endpoint de reembolso que no existe: la operación pública correcta es anular la guía.
02 / Guía
Cuándo puede anularse una guía
La guía es elegible mientras el envío está en LABEL_PURCHASED o READY_FOR_PICKUP. Si el paquete ya avanzó fuera de esos estados, la API rechaza la anulación y debes revisar el caso antes de continuar.
Consulta el estado actual y confirma que el shipmentId corresponde al pedido que quieres cancelar. No intentes sustituir la anulación con una eliminación del registro.
Confirma el pedido y el shipmentId.
Revisa que la guía siga en un estado elegible.
Evita entregar el paquete después de solicitar la anulación.
Conserva la respuesta para conciliar el saldo y el estado del pedido.
03 / Guía
Envía la solicitud de anulación
Usa el endpoint de la guía dentro del envío. Idempotency-Key sigue siendo opcional y puede ayudar a repetir de forma segura una solicitud interrumpida por la red.
POST /v1/shipments/:id/label/void
X-API-Key: sk_test_...04 / Guía
Qué debes verificar después
Una anulación correcta marca la guía como anulada, cancela el envío y acredita el importe completo al mismo saldo utilizado en la compra. En modo de prueba, el movimiento afecta únicamente el saldo virtual.
La guía ya no se usa para entregar un paquete.
El envío aparece cancelado.
El saldo refleja el crédito correspondiente.
Tu ecommerce o sistema actualiza el pedido para evitar preparación o entrega accidental.
Siguiente paso
Completa la tarea.
Preguntas frecuentes
Respuestas rápidas.
¿Existe un endpoint separado de reembolsos?
No. El reembolso de una guía se solicita anulándola con POST /v1/shipments/:id/label/void.
¿Anular una guía crea una devolución?
No. Una devolución física es un envío nuevo que regresa al remitente y necesita su propia guía.
¿A dónde regresa el saldo?
Al mismo saldo, real o de prueba, utilizado para comprar la guía original.
¿Puedo probar la anulación sin saldo real?
Sí. Compra y anula una guía en modo de prueba para verificar el flujo con saldo virtual.