Partsgate API: Veri Aktarma (Push) Kılavuzu

Bu kılavuz, ERP sisteminiz veya kendi yazılımınız üzerinden Partsgate'e ürün verisi aktarmanızı sağlayan API uç noktalarını (endpoint) açıklar. Ürün ekleme, güncelleme, stok senkronizasyonu ve silme işlemlerini kapsar.

Ön Koşul: Bu API'yi kullanabilmek için Partsgate yönetimi tarafından size verilmiş bir API anahtarı (pg_...) gereklidir. API anahtarı almak için info@partsgate.io adresine başvurun.

1. Kimlik Doğrulama (Authentication)

Tüm isteklerde API anahtarınızı aşağıdaki yöntemlerden biriyle göndermelisiniz:

Yöntem 1: X-Api-Key Header (Önerilen)

GET /api/v1/external/parts
Host: partsgate.io
X-Api-Key: pg_abc123def456...

Yöntem 2: Authorization Header

GET /api/v1/external/parts
Host: partsgate.io
Authorization: Bearer pg_abc123def456...

Güvenlik Uyarıları:

API anahtarınızı asla istemci tarafında (frontend, mobil uygulama) kullanmayın.
Anahtarınızı kaynak kodunda veya versiyon kontrolünde saklamayın. Ortam değişkenleri kullanın.
Anahtarınızın ele geçirildiğinden şüphelenirseniz hemen Partsgate yönetimine bildirin.

2. Tekli Parça Ekleme

Envanterinize yeni bir parça ekler.

POST /api/v1/external/parts

İstek Gövdesi (Request Body)

{
  "name": "Ön Fren Diski",
  "partNumber": "34116792219",
  "brandName": "TRW",
  "categoryName": "Frenler",
  "origin": "equivalent",
  "condition": "new",
  "price": 1250.00,
  "discountedPrice": 1100.00,
  "stockQuantity": 15,
  "description": "BMW 3 Serisi (F30) uyumlu ön fren diski",
  "compatibleVehicles": [
    {
      "make": "BMW",
      "model": "3 SERİSİ",
      "yearFrom": 2012,
      "yearTo": 2019
    }
  ]
}

Başarılı Yanıt (200)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Parca olusturuldu."
}

3. Toplu Parça Ekleme (Bulk Create)

Tek seferde en fazla 500 parça ekleyebilirsiniz.

POST /api/v1/external/parts/bulk

İstek Gövdesi

{
  "items": [
    {
      "name": "Ön Fren Diski",
      "partNumber": "34116792219",
      "brandName": "TRW",
      "categoryName": "Frenler",
      "origin": "equivalent",
      "condition": "new",
      "price": 1250.00,
      "stockQuantity": 15
    },
    {
      "name": "Arka Fren Balatası",
      "partNumber": "34216862202",
      "brandName": "Bosch",
      "categoryName": "Frenler",
      "origin": "equivalent",
      "condition": "new",
      "price": 850.00,
      "stockQuantity": 20
    }
  ]
}

Yanıt

{
  "total": 2,
  "success": 2,
  "errors": 0,
  "results": [
    { "partNumber": "34116792219", "status": "ok", "id": "..." },
    { "partNumber": "34216862202", "status": "ok", "id": "..." }
  ]
}

4. Parça Güncelleme

Mevcut bir parçanın bilgilerini günceller. Sadece değişen alanları gönderin.

PUT /api/v1/external/parts/:id

İstek Gövdesi

{
  "price": 1300.00,
  "stockQuantity": 8,
  "discountedPrice": 1150.00
}

Yanıt

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Parca guncellendi."
}

5. Toplu Stok Güncelleme (Bulk Stock Update)

Parça numarasına göre toplu stok ve fiyat güncellemesi yapar. ERP senkronizasyonu için idealdir. Tek seferde en fazla 500 kayıt.

PUT /api/v1/external/stock/bulk

İstek Gövdesi

{
  "items": [
    { "partNumber": "34116792219", "stockQuantity": 25, "price": 1300.00 },
    { "partNumber": "34216862202", "stockQuantity": 0 },
    { "partNumber": "11427566327", "stockQuantity": 50, "price": 180.00 }
  ]
}

Yanıt

{
  "total": 3,
  "success": 2,
  "notFound": 1,
  "errors": 0,
  "results": [
    { "partNumber": "34116792219", "status": "ok", "updated": 1 },
    { "partNumber": "34216862202", "status": "ok", "updated": 1 },
    { "partNumber": "11427566327", "status": "not_found" }
  ]
}

Not: stockQuantity: 0 göndermek ürünü pasife almaz, sadece stok adedini sıfırlar.price alanı opsiyoneldir; gönderilmezse fiyat değişmez.

6. Parça Silme

Bir parçayı kalıcı olarak siler.

DELETE /api/v1/external/parts/:id

Yanıt

{
  "message": "Parca silindi."
}

7. Alan Referansı (Field Reference)

Alan	Tip	Zorunlu	Açıklama
name	string	Evet	Ürün adı (örn: "Ön Fren Diski")
price	number	Evet	Liste fiyatı (TL, KDV hariç)
partNumber	string	Hayır	Parça numarası
brandName	string	Hayır	Üretici markası (örn: "Bosch", "TRW")
categoryName	string	Hayır	Kategori adı (örn: "Frenler", "Motor")
origin	string	Hayır	"original" \| "equivalent" \| "aftermarket"
condition	string	Hayır	"new" \| "refurbished"
discountedPrice	number	Hayır	İndirimli fiyat (TL)
stockQuantity	number	Hayır	Stok adedi (varsayılan: 0)
description	string	Hayır	Ürün açıklaması
compatibleVehicles	array	Hayır	Uyumlu araç listesi (aşağıya bakın)

compatibleVehicles Nesnesi:

Alan	Tip	Açıklama
make	string	Araç markası (örn: "BMW", "MERCEDES-BENZ")
model	string	Araç modeli (örn: "3 SERİSİ", "C")
yearFrom	number	Başlangıç model yılı (örn: 2012)
yearTo	number	Bitiş model yılı (örn: 2019)

origin Değerleri:

Değer	Türkçe	Açıklama
original	Orijinal	Araç üreticisinin orijinal parçası
equivalent	Eşdeğer	Orijinale eşdeğer kalitede yan sanayi parça
aftermarket	Aftermarket	Yan sanayi / muadil parça

8. Hata Kodları

HTTP Kodu	Anlam	Örnek
400	Geçersiz istek	Zorunlu alanlar eksik veya hatalı format
401	Yetkisiz	API anahtarı eksik, geçersiz veya süresi dolmuş
403	Yetersiz yetki	Push yetkisi yok (sadece Pull anahtarı)
404	Bulunamadı	Belirtilen parça ID mevcut değil
500	Sunucu hatası	Beklenmeyen bir hata oluştu

Hata Yanıt Formatı

{
  "statusCode": 401,
  "message": "Gecerli bir API anahtari gerekli. Header: X-Api-Key veya Authorization: Bearer pg_...",
  "error": "Unauthorized"
}

9. Entegrasyon Örnekleri

cURL - Tekli Parça Ekleme

curl -X POST https://partsgate.io/api/v1/external/parts \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: pg_abc123def456..." \
  -d '{
    "name": "Ön Fren Diski",
    "partNumber": "34116792219",
    "brandName": "TRW",
    "price": 1250.00,
    "stockQuantity": 15,
    "origin": "equivalent",
    "condition": "new"
  }'

Python - Toplu Stok Güncelleme

import requests

API_KEY = "pg_abc123def456..."   # Ortam değişkeninden alın!
BASE_URL = "https://partsgate.io/api/v1/external"

headers = {
    "Content-Type": "application/json",
    "X-Api-Key": API_KEY,
}

# ERP'den gelen stok verisi
stok_listesi = [
    {"partNumber": "34116792219", "stockQuantity": 25, "price": 1300.00},
    {"partNumber": "34216862202", "stockQuantity": 0},
    {"partNumber": "11427566327", "stockQuantity": 50, "price": 180.00},
]

# 500'lük gruplara böl ve gönder
for i in range(0, len(stok_listesi), 500):
    batch = stok_listesi[i:i+500]
    response = requests.put(
        f"{BASE_URL}/stock/bulk",
        json={"items": batch},
        headers=headers,
    )
    result = response.json()
    print(f"Batch {i//500 + 1}: {result['success']} başarılı, "
          f"{result.get('notFound', 0)} bulunamadı, "
          f"{result['errors']} hata")

JavaScript (Node.js) - Parça Ekleme

const axios = require('axios');

const API_KEY = process.env.PARTSGATE_API_KEY;
const BASE_URL = 'https://partsgate.io/api/v1/external';

const client = axios.create({
  baseURL: BASE_URL,
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': API_KEY,
  },
});

async function addPart(part) {
  const { data } = await client.post('/parts', part);
  console.log('Eklendi:', data.id);
  return data;
}

async function bulkStockUpdate(items) {
  const { data } = await client.put('/stock/bulk', { items });
  console.log(`Sonuç: ${data.success} başarılı, ${data.notFound} bulunamadı`);
  return data;
}

// Kullanım
addPart({
  name: 'Yağ Filtresi',
  partNumber: '11427566327',
  brandName: 'Mann',
  price: 180.00,
  stockQuantity: 50,
  origin: 'equivalent',
  condition: 'new',
});

C# (.NET) - Stok Senkronizasyonu

using System.Net.Http;
using System.Text;
using System.Text.Json;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Api-Key", "pg_abc123def456...");

var payload = new {
    items = new[] {
        new { partNumber = "34116792219", stockQuantity = 25, price = 1300.00 },
        new { partNumber = "34216862202", stockQuantity = 0 },
    }
};

var json = JsonSerializer.Serialize(payload);
var content = new StringContent(json, Encoding.UTF8, "application/json");

var response = await client.PutAsync(
    "https://partsgate.io/api/v1/external/stock/bulk", content);

var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

Yardıma mı ihtiyacınız var?

Teknik destek ve API anahtarı talebi için: info@partsgate.io

Veri Çekme (Pull) Kılavuzu →