Kargo etiketi API'si

Kargo etiketi API'si, KargoLabel işini kendi uygulamana bağlar: dosyayı gönderirsin, işi sorgularsın, çıktıyı indirirsin. Uçlar sunucuda çalışır; tarayıcı açmak gerekmez.

Hızlı başlangıç

Hesabındaki Geliştirici API'si bölümünden bir anahtar üret; düz metin anahtar yalnızca üretim anında gösterilir.
İsteği https://api.pixepi.com adresine Authorization: Bearer <anahtar> başlığıyla gönder.
Yanıttaki işi GET https://api.pixepi.com/api/v1/jobs/{id} ile sorgula; durum done olunca download_url adresinden çıktıyı indir.

Örnek istek

curl -X POST "https://api.pixepi.com/api/v1/apps/kargo-label/run" \
  -H "Authorization: Bearer $PIXEPI_KEY" \
  -F "[email protected]" \
  -F "options[format]=100x150" \
  -F "options[crop]=sol-ust"

curl -H "Authorization: Bearer $PIXEPI_KEY" "https://api.pixepi.com/api/v1/jobs/42"

Bu aracın uçları

Yöntem	Yol	Ne yapar
`POST`	`/run`	Aracı çalıştırır, işi başlatır ve sonucu döndürür.

Seçenekler

Seçenekler options[<alan>] biçiminde gönderilir; boş bırakılan alan varsayılanını kullanır.

Alan	Değerler	Varsayılan
`options[format]` Çıktı boyutu	100x150 · 80x120	`100x150`
`options[crop]` Etiket alanı	sol-ust · tam-sayfa · ust-yari · orta	`sol-ust`

Ortak uçlar

Yöntem	Yol	Ne yapar
`GET`	`/api/v1/apps`	API kataloğu
`GET`	`/api/v1/apps/kargo-label`	Araç sözleşmesi
`GET`	`/api/v1/jobs/{id}`	İş durumu
`GET`	`/api/v1/jobs/{id}/download`	İş çıktısını indirir
`GET`	`/api/v1/usage`	Kullanım özeti
`GET`	`/api/v1/openapi.json`	OpenAPI 3.1 belgesi

Sınırlar

Dosya başına en fazla 100 MB.
Toplu iş: aynı file alanını birden çok kez gönder.
Kota ve plan bilgisi hesabına bağlıdır; güncel durumu GET /api/v1/usage ile görürsün.

Hata kodları

Kod	Anlamı
`unauthorized`	API anahtarı yok ya da geçersiz.
`forbidden`	Bu işlem bu anahtarla yapılamaz.
`not_found`	Araç, iş ya da kayıt bulunamadı (sahiplik çaprazında da 404).
`invalid_input`	Girdi doğrulamadan geçmedi (eksik/bozuk alan, geçersiz tarih…).
`invalid_request`	İstek biçimi hatalı.
`too_large`	Dosya ya da gövde boyut sınırını aştı.
`unsupported_media`	Dosya türü kabul edilmiyor.
`not_supported`	Bu araç bu uçla çalıştırılamaz (durum tutan app).
`not_ready`	İş henüz tamamlanmadı.
`expired`	Çıktının saklama süresi doldu.
`no_output`	İş için indirilecek çıktı yok.
`invalid_path`	Çıktı yolu geçersiz.
`quota_exceeded`	Kota ya da hız sınırı aşıldı.
`rate_limited`	Kısa sürede çok istek; biraz bekleyip tekrar dene.
`csrf`	Tarayıcı formu doğrulaması başarısız (dış API anahtar kullanır).
`conflict`	İşlem mevcut durumla çakıştı.
`unavailable`	Araç geçici olarak kapalı.
`internal_error`	Beklenmeyen sunucu hatası.

Dokümanlar

Sıkça sorulan sorular

API anahtarını nereden alırım?

Hesabındaki Geliştirici API'si bölümünden anahtar üretirsin; anahtar üretim anında bir kez gösterilir.

İstek nasıl gönderilir?

Uçlar https://api.pixepi.com adresinde çalışır; her isteğe "Authorization: Bearer <anahtar>" başlığı eklenir.

KargoLabel API'si hangi dosyaları kabul eder?

Kabul edilen türler: PDF. Dosya başına sınır 100 MB; seçenekler araç sayfasındakiyle aynıdır.

Hata yanıtı nasıl okunur?

Hata gövdesi {ok:false, error, code, request_id} alanlarını taşır; code değerleri hata kodları tablosundadır.