ortakkargo

package module
v0.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 23, 2026 License: MIT Imports: 8 Imported by: 0

README

ortakkar-go

Go Reference

Ortak Kargo Müşteri (cari) API'si için temiz, bağımlılıksız bir Go istemcisi. Standart kütüphane dışında hiçbir bağımlılık kullanmaz.

Kurulum

go get github.com/vahaponur/ortakkar-go@latest

import ortakkargo "github.com/vahaponur/ortakkar-go"

Modül yolu ortakkar-go, paket adı ortakkargo'dur.

Hızlı Başlangıç

package main

import (
	"context"
	"fmt"
	"log"

	ortakkargo "github.com/vahaponur/ortakkar-go"
)

func main() {
	ctx := context.Background()
	c := ortakkargo.NewClient("API_ANAHTARINIZ")

	// Giriş — dönen token istemci içinde saklanır.
	if _, err := c.Login(ctx, "firma@example.com", "sifre"); err != nil {
		log.Fatal(err)
	}

	// Gönderi oluştur
	res, err := c.GonderiOlustur(ctx, ortakkargo.GonderiOlusturRequest{
		AliciAdi:          "Ahmet Yılmaz",
		AliciTelefon:      "5551234567",
		AliciAdres:        "Örnek Mah. Test Sok. No:1 D:5",
		AliciIl:           34,  // İstanbul
		AliciIlce:         441, // Kadıköy
		En:                30,
		Boy:               20,
		Yukseklik:         15,
		Agirlik:           2.5,
		KoliAdet:          1,
		KargoIcerigi:      "Elektronik",
		KapidaOdemeUcreti: 150.00,
		KapidaOdemeTuru:   1,
		SiparisNo:         "SIP-2024-001",
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Barkod:", res.Barkod)
}

Tasarım

Ortak Kargo API'sinin tüm istekleri POST + application/json olup ortak bir zarf yapısı kullanır:

{ "anahtar": "...", "token": "...", "rota": "endpoint", "veri": { ... } }

İstemci bu zarfı sizin yerinize kurar. Token, Login'den sonra otomatik olarak sonraki tüm isteklere eklenir. API durum != "basarili" döndürdüğünde metodlar *ortakkargo.APIError döner (HTTP kodu ve API mesajıyla birlikte).

Kapsanan Endpoint'ler

Metod Rota Açıklama
Login giris Oturum açar, token alır (24 saat geçerli)
IlListesi il_listesi 81 ili listeler
IlceListesi ilce_listesi İle ait ilçeleri listeler
GonderiOlustur gonderi_olustur Yeni kargo kaydı oluşturur
GonderiListesi gonderi_listesi Filtre + sayfalama ile listeler
GonderiDetay gonderi_detay Tek gönderi ayrıntısı
GonderiTakip gonderi_takip Hareket geçmişi
GonderiIptal gonderi_iptal İşleme alınmamış gönderiyi iptal eder
CariRapor cari_rapor Rapor ve istatistikler
Bildirimler bildirimler Son bildirimleri listeler
BildirimOkunduYap bildirim_okundu_yap Bildirimi okundu işaretler
CariBilgileri cari_bilgileri Hesap bilgileri

Yapılandırma

c := ortakkargo.NewClient("ANAHTAR",
	ortakkargo.WithHTTPClient(myHTTPClient), // özel http.Client
	ortakkargo.WithBaseURL("https://test.ortakkargo.com/"),
	ortakkargo.WithToken("kayitli-token"),   // Login olmadan başla
)

Yardımcılar

desi := ortakkargo.Desi(30, 20, 15) // (En × Boy × Yükseklik) / 3000 = 3

Hata Yönetimi

_, err := c.GonderiDetay(ctx, "yok")
var apiErr *ortakkargo.APIError
if errors.As(err, &apiErr) {
	fmt.Println(apiErr.StatusCode, apiErr.Mesaj)
}

Lisans

MIT

Documentation

Overview

Package ortakkargo, Ortak Kargo Müşteri (cari) API'si için temiz ve idiomatic bir Go istemcisidir.

API'nin tüm istekleri POST + application/json formatındadır ve ortak bir zarf (envelope) yapısı kullanır: 

{
  "anahtar": "<API anahtarı>",
  "token":   "<oturum token'ı>",
  "rota":    "<endpoint adı>",
  "veri":    { ... }
}

İstemci bu zarfı sizin yerinize kurar; siz yalnızca anahtarı verir, Login ile oturum açar ve metodları çağırırsınız.

Örnek: 

c := ortakkargo.NewClient("ANAHTAR")
if _, err := c.Login(ctx, "firma@example.com", "sifre"); err != nil {
    log.Fatal(err)
}
iller, err := c.IlListesi(ctx)

Token, Login çağrısından sonra istemci içinde tutulur ve sonraki tüm isteklere otomatik eklenir.

Example 
package main

import (
	"context"
	"fmt"
	"log"

	ortakkargo "github.com/vahaponur/ortakkar-go"
)

func main() {
	c := ortakkargo.NewClient("API_ANAHTARINIZ")

	ctx := context.Background()
	if _, err := c.Login(ctx, "firma@example.com", "sifre"); err != nil {
		log.Fatal(err)
	}

	barkod, err := c.GonderiOlustur(ctx, ortakkargo.GonderiOlusturRequest{
		AliciAdi:          "Ahmet Yılmaz",
		AliciTelefon:      "5551234567",
		AliciAdres:        "Örnek Mah. Test Sok. No:1 D:5",
		AliciIl:           34,
		AliciIlce:         441,
		En:                30,
		Boy:               20,
		Yukseklik:         15,
		Agirlik:           2.5,
		KoliAdet:          1,
		KargoIcerigi:      "Elektronik",
		KapidaOdemeUcreti: 150.00,
		KapidaOdemeTuru:   1,
		SiparisNo:         "SIP-2024-001",
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(barkod.Barkod)
}

Index

Examples

Constants

View Source 
const (
	OdeyecekTarafGonderici = "1" // kargo ücretini gönderici öder
	OdeyecekTarafAlici     = "2" // kargo ücretini alıcı öder
)

krg_odeyecek_taraf değerleri (Ortak Kargo string bekler, int değil).

View Source 
const DefaultBaseURL = "https://api.ortakkargo.com/"

DefaultBaseURL, Ortak Kargo API'sinin varsayılan adresidir.

View Source 
const RolCari = "cari"

RolCari, müşteri (cari) rolü için sabit değerdir. Giriş bu rol ile yapılır.

Variables

This section is empty.

Functions

func Desi 

func Desi(en, boy, yukseklik float64) float64

Desi, bir kolinin desi değerini (En × Boy × Yükseklik) / 3000 formülüyle hesaplar.

Types

type APIError 

type APIError struct {
	// StatusCode, yanıtın HTTP durum kodudur (200, 401, 429 ...).
	StatusCode int
	// Rota, hatanın oluştuğu endpoint adıdır.
	Rota string
	// Durum, yanıttaki "durum" alanıdır (örn. "hata").
	Durum string
	// Mesaj, yanıttaki insan-okunur "mesaj" alanıdır.
	Mesaj string
}

APIError, API "basarili" dışında bir durum döndürdüğünde oluşur.

func (*APIError) Error 

func (e *APIError) Error() string

type Bildirim 

type Bildirim struct {
	ID       int    `json:"id"`
	Baslik   string `json:"baslik"`
	Aciklama string `json:"aciklama"`
	Tarih    string `json:"tarih"`
	Durum    int    `json:"durum"`
}

Bildirim, tek bir bildirimi temsil eder. Durum 0 okunmadı, 1 okundu anlamına gelir.

type BildirimlerSonuc 

type BildirimlerSonuc struct {
	Toplam      int        `json:"toplam"`
	Bildirimler []Bildirim `json:"bildirimler"`
}

BildirimlerSonuc, bildirimler yanıtının "veri" alanıdır.

type CariBilgileriSonuc 

type CariBilgileriSonuc struct {
	KullaniciID  int    `json:"kullanici_id"`
	KullaniciAdi string `json:"kullanici_adi"`
	Rol          string `json:"rol"`
	Ad           string `json:"ad"`
	Telefon      string `json:"telefon"`
	Adres        string `json:"adres"`
}

CariBilgileriSonuc, cari_bilgileri yanıtının "veri" alanıdır (şifre hariç hesap bilgileri).

type CariRaporSonuc 

type CariRaporSonuc struct {
	TarihAraligi       RaporTarihAraligi `json:"tarih_araligi"`
	Ozet               RaporOzet         `json:"ozet"`
	DurumDagilim       json.RawMessage   `json:"durum_dagilim"`
	GunlukDagilim      json.RawMessage   `json:"gunluk_dagilim"`
	IlDagilim          json.RawMessage   `json:"il_dagilim"`
	AylikKarsilastirma json.RawMessage   `json:"aylik_karsilastirma"`
}

CariRaporSonuc, cari_rapor yanıtının "veri" alanıdır. Dağılım alanları, API'nin esnek yapısı nedeniyle ham JSON olarak sunulur.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client, Ortak Kargo API istemcisidir. Eşzamanlı kullanım için güvenlidir, yalnızca Login/SetToken token alanını günceller.

func NewClient 

func NewClient(apiKey string, opts ...Option) *Client

NewClient, verilen API anahtarı ile yeni bir istemci oluşturur.

func (*Client) BildirimOkunduYap 

func (c *Client) BildirimOkunduYap(ctx context.Context, bildirimID int) error

BildirimOkunduYap, verilen ID'li bildirimi okundu olarak işaretler.

func (*Client) Bildirimler 

func (c *Client) Bildirimler(ctx context.Context) (*BildirimlerSonuc, error)

Bildirimler, son bildirimleri (yaklaşık son 30) döndürür.

func (*Client) CariBilgileri 

func (c *Client) CariBilgileri(ctx context.Context) (*CariBilgileriSonuc, error)

CariBilgileri, oturum açmış müşterinin hesap bilgilerini döndürür.

func (*Client) CariRapor 

func (c *Client) CariRapor(ctx context.Context, baslangic, bitis string) (*CariRaporSonuc, error)

CariRapor, verilen tarih aralığı için gönderi raporu ve istatistiklerini döndürür. Tarihler "YYYY-AA-GG" biçiminde verilmelidir.

func (*Client) GonderiDetay 

func (c *Client) GonderiDetay(ctx context.Context, barkod string) (*GonderiDetaySonuc, error)

GonderiDetay, barkoda göre tek bir gönderinin ayrıntılarını döndürür.

func (*Client) GonderiIptal 

func (c *Client) GonderiIptal(ctx context.Context, barkod string) (*GonderiIptalSonuc, error)

GonderiIptal, henüz işleme alınmamış bir gönderiyi iptal eder.

func (*Client) GonderiListesi 

func (c *Client) GonderiListesi(ctx context.Context, req GonderiListesiRequest) (*GonderiListesiSonuc, error)

GonderiListesi, filtreleme ve sayfalama ile gönderileri listeler.

func (*Client) GonderiOlustur 

func (c *Client) GonderiOlustur(ctx context.Context, req GonderiOlusturRequest) (*GonderiOlusturSonuc, error)

GonderiOlustur, yeni bir gönderi oluşturur ve oluşan barkodu döndürür.

func (*Client) GonderiTakip 

func (c *Client) GonderiTakip(ctx context.Context, barkod string) (*GonderiTakipSonuc, error)

GonderiTakip, barkoda göre gönderinin hareket geçmişini döndürür.

func (*Client) IlListesi 

func (c *Client) IlListesi(ctx context.Context) (*IlListesiSonuc, error)

IlListesi, 81 ilin listesini döndürür.

func (*Client) IlceListesi 

func (c *Client) IlceListesi(ctx context.Context, ilID int) (*IlceListesiSonuc, error)

IlceListesi, verilen il ID'sine ait ilçeleri döndürür.

func (*Client) Login 

func (c *Client) Login(ctx context.Context, kullaniciAdi, sifre string) (*LoginResult, error)

Login, kullanıcı adı (e-posta) ve şifre ile oturum açar. Başarılı olursa dönen token istemci içinde saklanır ve sonraki tüm isteklere eklenir.

func (*Client) SetToken 

func (c *Client) SetToken(token string)

SetToken, oturum token'ını elle ayarlar.

func (*Client) Token 

func (c *Client) Token() string

Token, istemcinin o anki oturum token'ını döndürür.

type GonderiDetaySonuc 

type GonderiDetaySonuc struct {
	ID        int          `json:"id"`
	Barkod    string       `json:"barkod"`
	IslemNo   string       `json:"islem_no"`
	Tur       string       `json:"tur"`
	Durum     GonderiDurum `json:"durum"`
	Gonderici Taraf        `json:"gonderici"`
	Alici     Taraf        `json:"alici"`
	Kargo     KargoBilgisi `json:"kargo"`
	Odeme     OdemeBilgisi `json:"odeme"`
	Tarihler  TarihBilgisi `json:"tarihler"`
}

GonderiDetaySonuc, gonderi_detay yanıtının "veri" alanıdır.

type GonderiDurum 

type GonderiDurum struct {
	DurumID       string `json:"durum_id"`
	DurumAdi      string `json:"durum_adi"`
	DurumAciklama string `json:"durum_aciklama"`
}

GonderiDurum, bir gönderinin durum bilgisini temsil eder.

func (*GonderiDurum) UnmarshalJSON added in v0.3.1 

func (g *GonderiDurum) UnmarshalJSON(data []byte) error

UnmarshalJSON: bkz. GonderiOzet.UnmarshalJSON — durum_id burada da (ör. gonderi_detay ucunda) JSON sayı olarak dönebiliyor.

type GonderiIptalSonuc 

type GonderiIptalSonuc struct {
	Barkod string `json:"barkod"`
	Cop    int    `json:"cop"`
}

GonderiIptalSonuc, gonderi_iptal yanıtının "veri" alanıdır.

type GonderiListesiRequest 

type GonderiListesiRequest struct {
	Sayfa          int    `json:"sayfa"`
	Limit          int    `json:"limit"`
	DurumID        string `json:"durum_id,omitempty"`
	BaslangicTarih string `json:"baslangic_tarih,omitempty"`
	BitisTarih     string `json:"bitis_tarih,omitempty"`
	Arama          string `json:"arama,omitempty"`
}

GonderiListesiRequest, gönderi listesini filtrelemek ve sayfalamak için kullanılır. Boş bırakılan filtre alanları gönderilmez.

type GonderiListesiSonuc 

type GonderiListesiSonuc struct {
	Toplam      int           `json:"toplam"`
	Sayfa       int           `json:"sayfa"`
	Limit       int           `json:"limit"`
	ToplamSayfa int           `json:"toplam_sayfa"`
	Gonderiler  []GonderiOzet `json:"gonderiler"`
}

GonderiListesiSonuc, gonderi_listesi yanıtının "veri" alanıdır.

type GonderiOlusturRequest 

type GonderiOlusturRequest struct {
	AliciAdi     string `json:"krg_alici_adi"`
	AliciTelefon string `json:"krg_alici_telefon"`
	AliciAdres   string `json:"krg_alici_adres"`
	AliciIl      int    `json:"krg_alici_il"`
	AliciIlce    int    `json:"krg_alici_ilce"`

	// Koli ölçüleri opsiyoneldir; 0 bırakılırsa istekte hiç gönderilmez (omitempty).
	En        float64 `json:"ilk_en,omitempty"`
	Boy       float64 `json:"ilk_boy,omitempty"`
	Yukseklik float64 `json:"ilk_yukseklik,omitempty"`
	Agirlik   float64 `json:"ilk_agirlik,omitempty"`
	KoliAdet  int     `json:"ilk_koli_adet,omitempty"`

	KargoIcerigi string `json:"krg_kargo_icerigi,omitempty"`
	TeslimatYeri string `json:"krg_teslimat_yeri,omitempty"`

	KapidaOdemeUcreti float64 `json:"krg_kapida_odeme_ucreti,omitempty"`
	KapidaOdemeTuru   int     `json:"krg_kapida_odeme_turu,omitempty"`
	SigortaBedeli     float64 `json:"krg_sigorta_bedeli,omitempty"`

	// OdeyecekTaraf, kargo ücretini ödeyen taraftır. STRING olarak gönderilir (int değil):
	// "1" = gönderici, "2" = alıcı. Kolaylık için OdeyecekTarafGonderici/OdeyecekTarafAlici
	// sabitlerini kullanabilirsiniz.
	OdeyecekTaraf string `json:"krg_odeyecek_taraf,omitempty"`

	SiparisNo string `json:"krg_siparis_no,omitempty"`
	Satici    string `json:"krg_satici,omitempty"`
	SmsGonder int    `json:"sms_gonder,omitempty"`
}

GonderiOlusturRequest, yeni bir gönderi (kargo) oluşturmak için gereken alanları içerir.

type GonderiOlusturSonuc 

type GonderiOlusturSonuc struct {
	Barkod string `json:"barkod"`
}

GonderiOlusturSonuc, gonderi_olustur yanıtının "veri" alanıdır.

type GonderiOzet 

type GonderiOzet struct {
	ID           int     `json:"id"`
	Barkod       string  `json:"barkod"`
	DurumID      string  `json:"durum_id"`
	DurumAdi     string  `json:"durum_adi"`
	AliciAdi     string  `json:"alici_adi"`
	AliciTelefon string  `json:"alici_telefon"`
	AliciIl      string  `json:"alici_il"`
	AliciIlce    string  `json:"alici_ilce"`
	ToplamAdet   int     `json:"toplam_adet"`
	ToplamDesi   float64 `json:"toplam_desi"`
	ToplamFiyat  float64 `json:"toplam_fiyat"`
	KapidaOdeme  float64 `json:"kapida_odeme"`
	EklenmeTarih string  `json:"eklenme_tarih"`
	TeslimTarihi *string `json:"teslim_tarihi"`
}

GonderiOzet, gönderi listesindeki tek bir kaydı temsil eder.

func (*GonderiOzet) UnmarshalJSON added in v0.3.1 

func (g *GonderiOzet) UnmarshalJSON(data []byte) error

UnmarshalJSON: Ortak Kargo bazı uçlarda durum_id'yi JSON sayı, bazılarında JSON string olarak döndürüyor. DurumID alanı her koşulda string olarak kalsın diye burada normalize edilir.

type GonderiTakipSonuc 

type GonderiTakipSonuc struct {
	Gonderi    TakipGonderi `json:"gonderi"`
	Hareketler []Hareket    `json:"hareketler"`
}

GonderiTakipSonuc, gonderi_takip yanıtının "veri" alanıdır.

type Hareket 

type Hareket struct {
	DurumID   string `json:"durum_id"`
	DurumAdi  string `json:"durum_adi"`
	Tarih     string `json:"tarih"`
	Aciklama  string `json:"aciklama"`
	IslemYeri string `json:"islem_yeri"`
}

Hareket, gönderinin takip geçmişindeki tek bir hareketi temsil eder.

func (*Hareket) UnmarshalJSON added in v0.3.1 

func (h *Hareket) UnmarshalJSON(data []byte) error

UnmarshalJSON: bkz. GonderiOzet.UnmarshalJSON.

type Il 

type Il struct {
	ID   int    `json:"id"`
	IlAd string `json:"il_ad"`
}

Il, bir ili temsil eder.

type IlListesiSonuc 

type IlListesiSonuc struct {
	Toplam int  `json:"toplam"`
	Iller  []Il `json:"iller"`
}

IlListesiSonuc, il_listesi yanıtının "veri" alanıdır.

type Ilce 

type Ilce struct {
	ID     int    `json:"id"`
	IlceAd string `json:"ilce_ad"`
}

Ilce, bir ilçeyi temsil eder.

type IlceListesiSonuc 

type IlceListesiSonuc struct {
	Il      Il     `json:"il"`
	Toplam  int    `json:"toplam"`
	Ilceler []Ilce `json:"ilceler"`
}

IlceListesiSonuc, ilce_listesi yanıtının "veri" alanıdır.

type KargoBilgisi 

type KargoBilgisi struct {
	ToplamAdet    int               `json:"toplam_adet"`
	ToplamDesi    float64           `json:"toplam_desi"`
	KoliBilgileri []json.RawMessage `json:"koli_bilgileri"`
}

KargoBilgisi, gönderinin koli/desi bilgilerini temsil eder.

type LoginResult 

type LoginResult struct {
	Token            string   `json:"token"`
	GecerlilikSuresi int64    `json:"gecerlilik_suresi"` // Unix saniye
	KullaniciID      int      `json:"kullanici_id"`
	Rol              string   `json:"rol"`
	Rotalar          []string `json:"rotalar"`
}

LoginResult, başarılı bir giriş yanıtının "veri" alanıdır.

type OdemeBilgisi 

type OdemeBilgisi struct {
	ToplamFiyat       float64 `json:"toplam_fiyat"`
	KapidaOdemeUcreti float64 `json:"kapida_odeme_ucreti"`
}

OdemeBilgisi, gönderinin ödeme bilgilerini temsil eder.

type Option 

type Option func(*Client)

Option, NewClient için isteğe bağlı yapılandırma fonksiyonudur.

func WithBaseURL 

func WithBaseURL(baseURL string) Option

WithBaseURL, varsayılan API adresini değiştirir (örn. test ortamı için).

func WithHTTPClient 

func WithHTTPClient(hc *http.Client) Option

WithHTTPClient, özel bir *http.Client kullanılmasını sağlar.

func WithRol 

func WithRol(rol string) Option

WithRol, giriş rolünü değiştirir. Varsayılan: RolCari.

func WithToken 

func WithToken(token string) Option

WithToken, mevcut bir token ile istemciyi başlatır; böylece Login çağırmadan (token geçerli olduğu sürece) istek yapılabilir.

type RaporOzet 

type RaporOzet struct {
	ToplamGonderi     int     `json:"toplam_gonderi"`
	TeslimEdilen      int     `json:"teslim_edilen"`
	Yolda             int     `json:"yolda"`
	Beklemede         int     `json:"beklemede"`
	Iade              int     `json:"iade"`
	ToplamDesi        float64 `json:"toplam_desi"`
	ToplamTutar       float64 `json:"toplam_tutar"`
	ToplamKapidaOdeme float64 `json:"toplam_kapida_odeme"`
}

RaporOzet, rapor özet istatistiklerini içerir.

type RaporTarihAraligi 

type RaporTarihAraligi struct {
	Baslangic string `json:"baslangic"`
	Bitis     string `json:"bitis"`
}

RaporTarihAraligi, raporun kapsadığı tarih aralığıdır.

type TakipGonderi 

type TakipGonderi struct {
	Barkod   string `json:"barkod"`
	DurumAdi string `json:"durum_adi"`
	AliciAdi string `json:"alici_adi"`
}

TakipGonderi, takip yanıtındaki özet gönderi bilgisidir.

type Taraf 

type Taraf struct {
	Adi     string `json:"adi"`
	Telefon string `json:"telefon"`
	IlAdi   string `json:"il_adi"`
	IlceAdi string `json:"ilce_adi"`
	Adres   string `json:"adres"`
}

Taraf, gönderici veya alıcı bilgilerini temsil eder.

type TarihBilgisi 

type TarihBilgisi struct {
	EklenmeTarih string  `json:"eklenme_tarih"`
	TeslimTarihi *string `json:"teslim_tarihi"`
}

TarihBilgisi, gönderinin tarih bilgilerini temsil eder.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.