returns — E-Ticaret API

GET/api/shop/v1/admin/returns

Admin list

Oturum

İstek

curl -X GET "https://{slug}.shop.blesyum.app/api/shop/v1/admin/returns" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"

Yanıt

{
  "data": "…",
  "trace_id": "01JC…"
}

GET/api/shop/v1/admin/returns/{id}

Admin detail

OturumYol parametresi: id

İstek

curl -X GET "https://{slug}.shop.blesyum.app/api/shop/v1/admin/returns/<id>" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"

Yanıt

{
  "data": "…",
  "trace_id": "01JC…"
}

POST/api/shop/v1/admin/returns/{id}/attachments

Add attachment

OturumYol parametresi: id

İstek

curl -X POST "https://{slug}.shop.blesyum.app/api/shop/v1/admin/returns/<id>/attachments" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"

Yanıt

{
  "data": "…",
  "trace_id": "01JC…"
}

GET/api/shop/v1/admin/returns/{id}/attachments

List attachments

OturumYol parametresi: id

İstek

curl -X GET "https://{slug}.shop.blesyum.app/api/shop/v1/admin/returns/<id>/attachments" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"

Yanıt

{
  "data": "…",
  "trace_id": "01JC…"
}

GET/api/shop/v1/admin/returns/{id}/attachments/{attachment_id}/file

Satıcı (staff) iade kanıtını GÖRÜNTÜLER. Public medya ucu `returns/` anahtarını sunmaz;

OturumYol parametresi: idattachment_id

dosya yalnız buradan, kimlik + tenant guard'ıyla okunur.

İstek

curl -X GET "https://{slug}.shop.blesyum.app/api/shop/v1/admin/returns/<id>/attachments/<attachment_id>/file" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"

Yanıt

{
  "data": "…",
  "trace_id": "01JC…"
}

POST/api/shop/v1/admin/returns/{id}/decision

Decision

OturumYol parametresi: id

İstek

curl -X POST "https://{slug}.shop.blesyum.app/api/shop/v1/admin/returns/<id>/decision" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"

Yanıt

{
  "data": "…",
  "trace_id": "01JC…"
}

POST/api/shop/v1/admin/returns/{id}/exchange

İade → komisyon geri-alma (admin).

OturumYol parametresi: id

İstek

curl -X POST "https://{slug}.shop.blesyum.app/api/shop/v1/admin/returns/<id>/exchange" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"

Yanıt

{
  "data": "…",
  "trace_id": "01JC…"
}

POST/api/shop/v1/admin/returns/{id}/inspect

RMA-lifecycle: incele (received→inspected). Yanlış-durum → 409. BLE-6199.

OturumYol parametresi: id

İstek

curl -X POST "https://{slug}.shop.blesyum.app/api/shop/v1/admin/returns/<id>/inspect" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"

Yanıt

{
  "data": "…",
  "trace_id": "01JC…"
}

POST/api/shop/v1/admin/returns/{id}/items/{item_id}/decide

Kısmi-onay: iade-kalemini onayla/reddet (refund yalnız-onaylı-kalemleri hesaplar). BLE-6204.

OturumYol parametresi: iditem_id

İstek

curl -X POST "https://{slug}.shop.blesyum.app/api/shop/v1/admin/returns/<id>/items/<item_id>/decide" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"

Yanıt

{
  "data": "…",
  "trace_id": "01JC…"
}

POST/api/shop/v1/admin/returns/{id}/label

Admin iade rotaları — admin düzlemine (require_shop_staff) merge edilir.

OturumYol parametresi: id

TF8 · iade-kargo-etiketi: onaylı (approved|refunded) talebe taşıyıcı-registry'den etiket (return-id-idempotent). Kayıtlı olmayan taşıyıcı → 409. Etiket talebe yazılır (müşteri storefront listesinde görür — kutuya koyacağı iade-kodu/etiket).

İstek

curl -X POST "https://{slug}.shop.blesyum.app/api/shop/v1/admin/returns/<id>/label" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"

Yanıt

{
  "data": "…",
  "trace_id": "01JC…"
}

POST/api/shop/v1/admin/returns/{id}/note

İnceleme iç-notunu yaz (BLE-6217). Müşterinin `reason` metni DEĞİŞTİRİLMEZ; bu ayrı bir

OturumYol parametresi: id

operatör alanıdır ve storefront yanıtında yer almaz. Talep yoksa 404.

İstek

curl -X POST "https://{slug}.shop.blesyum.app/api/shop/v1/admin/returns/<id>/note" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"

Yanıt

{
  "data": "…",
  "trace_id": "01JC…"
}

POST/api/shop/v1/admin/returns/{id}/receive

RMA-lifecycle: fiziksel teslim-al (approved→received). Yanlış-durum → 409. BLE-6199.

OturumYol parametresi: id

İstek

curl -X POST "https://{slug}.shop.blesyum.app/api/shop/v1/admin/returns/<id>/receive" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"

Yanıt

{
  "data": "…",
  "trace_id": "01JC…"
}

POST/api/shop/v1/admin/returns/{id}/refund

İade → komisyon geri-alma (admin).

OturumYol parametresi: id

İstek

curl -X POST "https://{slug}.shop.blesyum.app/api/shop/v1/admin/returns/<id>/refund" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"

Yanıt

{
  "data": "…",
  "trace_id": "01JC…"
}

GET/api/shop/v1/admin/returns/{id}/tracking

İade-kargo takip timeline'ı (admin, eski→yeni). BLE-6439.

OturumYol parametresi: id

İstek

curl -X GET "https://{slug}.shop.blesyum.app/api/shop/v1/admin/returns/<id>/tracking" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"

Yanıt

{
  "data": "…",
  "trace_id": "01JC…"
}

POST/api/shop/v1/storefront/returns/webhook/{carrier}

İade-kargo webhook'u (fail-closed HMAC — forward tracking deseni): imza

Herkese açıkYol parametresi: carrier

`x-shop-webhook-signature` = HMAC-SHA256(settings `shipping.webhook_secret`, raw-body); secret yoksa 401. Body: {event_id, tracking_number, status, description?}. İade (label_carrier + label_tracking) ile bulunur; yok → 404 (olay tüketilmez). Replay → no-op ack. `delivered` → iade approved→received ilerletir (guarded, best-effort; zaten received/inspected/refunded ise no-op). received refund AÇMAZ (admin_refund precondition approved|inspected) → money-safe. Canlı-carrier webhook-secret → TF21. BLE-6439.

İstek

curl -X POST "https://{slug}.shop.blesyum.app/api/shop/v1/storefront/returns/webhook/<carrier>" \
  -H "Accept: application/json"

Yanıt

{
  "data": "…",
  "trace_id": "01JC…"
}