PpOpportunities API Dokümantasyonu

PDF Dokümanı
Genel Bilgiler
Base URL: https://crm.karel.cloud/api/v1/PpOpportunities
Kimlik Doğrulama: Tüm endpoint'ler Bearer Token ile korunmaktadır. Token, Authorization header'ında Bearer {token} formatında gönderilmelidir.
Rol Gereksinimi: Tüm endpoint'ler için PpApiUser rolü gereklidir.

1. Get Opportunity by ID

Açıklama

Belirli bir fırsatın detaylı bilgilerini getirir. Fırsat ID'si ile tek bir fırsatın tüm detaylarına, özel alanlarına ve ilişkili bilgilerine erişilir.

HTTP Metodu

GET

Endpoint

GET /api/v1/PpOpportunities/{id}

Path Parametreleri

Parametre Tip Zorunlu Açıklama Örnek Değer
id integer Evet Fırsat ID'si 12345

Örnek İstek

GET https://crm.karel.cloud/api/v1/PpOpportunities/12345

Headers

Authorization: Bearer {token}

Response

Başarılı bir istek için 200 OK durum kodu döner ve aşağıdaki yapıda bir response gelir:

Response Body

Alan Tip Açıklama
Result PpOpportunityIndexViewModel Fırsat detay bilgileri
ResultMessage string İşlem sonucu mesajı

PpOpportunityIndexViewModel

Alan Tip Açıklama
OpportunityId integer Fırsat ID'si
OpportunityName string Fırsat adı/açıklaması
OpportunityPrice decimal? Fırsat tutarı
OpportunityState byte? Fırsat durumu
OpportunityStartDate DateTime Fırsat başlangıç tarihi
EstimatedEndDate DateTime? Tahmini bitiş tarihi
Period byte Periyot tipi (0: Yok, 1: Günlük, 2: Aylık, 3: Yıllık)
PeriodStartDate DateTime? Periyot başlangıç tarihi
PeriodFinishDate DateTime? Periyot bitiş tarihi
Duration int? Süre (periyot tipine göre)
RefCurrencyId byte Para birimi ID'si
CurrencySymbol string Para birimi sembolü
RefQuotaId int? Kota ID'si
QuotaName string Kota adı
PipelineStageId int? Pipeline aşama ID'si
RefPipelineId int? Pipeline ID'si
CustomerName string Müşteri adı soyadı
RepresentativeNameSurname string Temsilci adı soyadı
Tags string Etiketler (virgülle ayrılmış)
CustomFields array[PpCustomFieldViewModel] Özel alanlar listesi
AddedBy string Ekleyen kullanıcı
AddedDate DateTime Ekleme tarihi
UpdatedBy string Güncelleyen kullanıcı
UpdatedDate DateTime? Güncelleme tarihi

PpCustomFieldViewModel

Alan Tip Açıklama
CustomFieldValueId integer Özel alan değer ID'si
CustomFieldFieldLabel string Özel alan etiketi
CustomFieldFieldType string Özel alan tipi
CustomFieldTextValue string Metin değeri
CustomFieldDateValue DateTime? Tarih değeri
CustomFieldOptionName string Seçenek adı (dropdown için)

Örnek Response

{
    "Result": {
        "OpportunityId": 12345,
        "OpportunityName": "Yeni Proje Fırsatı",
        "OpportunityPrice": 50000.00,
        "OpportunityState": 1,
        "OpportunityStartDate": "2024-06-01T00:00:00",
        "EstimatedEndDate": "2024-12-31T00:00:00",
        "Period": 2,
        "PeriodStartDate": "2024-06-01T00:00:00",
        "PeriodFinishDate": "2024-12-01T00:00:00",
        "Duration": 6,
        "RefCurrencyId": 1,
        "CurrencySymbol": "TRY",
        "RefQuotaId": 10,
        "QuotaName": "2024 Yıllık Kota",
        "PipelineStageId": 5,
        "RefPipelineId": 2,
        "CustomerName": "Ahmet Yılmaz",
        "RepresentativeNameSurname": "Mehmet Demir",
        "Tags": "önemli,acil",
        "CustomFields": [
            {
                "CustomFieldValueId": 100,
                "CustomFieldFieldLabel": "Proje Tipi",
                "CustomFieldFieldType": "Dropdown",
                "CustomFieldTextValue": null,
                "CustomFieldDateValue": null,
                "CustomFieldOptionName": "Yazılım Geliştirme"
            }
        ],
        "AddedBy": "admin@example.com",
        "AddedDate": "2024-06-01T10:00:00",
        "UpdatedBy": "admin@example.com",
        "UpdatedDate": "2024-06-15T14:30:00"
    },
    "ResultMessage": "İşlem başarılı"
}

Örnek Kullanım Senaryosu

Kullanıcı, ID'si 12345 olan fırsatın detaylı bilgilerini (tutar, müşteri, temsilci, özel alanlar vb.) görüntülemek istediğinde bu endpoint kullanılır.

2. Create Opportunity

Açıklama

Yeni bir fırsat oluşturur. Bu endpoint, fırsat oluşturma işlemini gerçekleştirir ve özel alanlar da eklenebilir.

HTTP Metodu

POST

Endpoint

POST /api/v1/PpOpportunities

Headers

Authorization: Bearer {token}
Content-Type: application/json

Request Body

Alan Tip Zorunlu Açıklama Örnek Değer
Description string Evet Fırsat açıklaması/adı "Yeni Proje Fırsatı"
RefCustomerCardId integer Evet Müşteri kart ID'si 10148
RefRepresentativeCardId integer Evet Temsilci kart ID'si 8224
OpportunityPrice decimal? Hayır Fırsat tutarı 50000.00
OpportunityState byte? Hayır Fırsat durumu 1
OpportunityStartDate DateTime Hayır Fırsat başlangıç tarihi "2024-06-01T00:00:00"
EstimatedEndDate DateTime? Hayır Tahmini bitiş tarihi "2024-12-31T00:00:00"
Period byte Hayır Periyot tipi (0: Yok, 1: Günlük, 2: Aylık, 3: Yıllık) 2
PeriodStartDate DateTime? Hayır Periyot başlangıç tarihi "2024-06-01T00:00:00"
Duration int? Hayır Süre (periyot tipine göre) 6
RefCurrencyId byte Hayır Para birimi ID'si 1
RefQuotaId int? Hayır Kota ID'si 10
RefProductId int? Hayır Ürün ID'si 5
RefPipelineStageId int? Hayır Pipeline aşama ID'si 5
Tags string Hayır Etiketler (virgülle ayrılmış) "önemli,acil"
CustomFields array[object] Hayır Özel alanlar listesi Aşağıdaki örneğe bakın

CustomFields Objesi

Alan Tip Zorunlu Açıklama Örnek Değer
CustomFieldId integer Evet Özel alan ID'si 20
CustomFieldTextValue string Hayır Metin değeri (metin alanları için) "Özel not"
CustomFieldDateValue DateTime? Hayır Tarih değeri (tarih alanları için) "2024-06-15T00:00:00"
CustomFieldOptionId int? Hayır Seçenek ID'si (dropdown alanları için) 5
Not: Period değeri 0'dan farklı ise, PeriodFinishDate otomatik olarak hesaplanır:
  • Period = 1 (Günlük): PeriodStartDate + Duration gün
  • Period = 2 (Aylık): PeriodStartDate + (Duration * 30) gün
  • Period = 3 (Yıllık): PeriodStartDate + (Duration * 365) gün
Eğer PeriodStartDate boş ise, mevcut tarih kullanılır.

Örnek Request Body

{
    "Description": "Yeni Proje Fırsatı",
    "RefCustomerCardId": 10148,
    "RefRepresentativeCardId": 8224,
    "OpportunityPrice": 50000.00,
    "OpportunityState": 1,
    "OpportunityStartDate": "2024-06-01T00:00:00",
    "EstimatedEndDate": "2024-12-31T00:00:00",
    "Period": 2,
    "PeriodStartDate": "2024-06-01T00:00:00",
    "Duration": 6,
    "RefCurrencyId": 1,
    "RefQuotaId": 10,
    "RefProductId": 5,
    "RefPipelineStageId": 5,
    "Tags": "önemli,acil",
    "CustomFields": [
        {
            "CustomFieldId": 20,
            "CustomFieldTextValue": "Özel not alanı"
        },
        {
            "CustomFieldId": 21,
            "CustomFieldDateValue": "2024-06-15T00:00:00"
        },
        {
            "CustomFieldId": 22,
            "CustomFieldOptionId": 5
        }
    ]
}

Örnek İstek

POST https://crm.karel.cloud/api/v1/PpOpportunities

Response

Başarılı bir istek için 201 Created durum kodu döner ve aşağıdaki yapıda bir response gelir:

Response Body

Alan Tip Açıklama
Result integer Oluşturulan fırsatın ID'si
ResultMessage string İşlem sonucu mesajı

Örnek Response

{
    "Result": 12345,
    "ResultMessage": "İşlem başarılı"
}
Önemli: Eğer OpportunityState değeri gönderilirse, müşteri kartının durumu da otomatik olarak güncellenir.

Hata Durumları

Örnek Kullanım Senaryosu

Kullanıcı, yeni bir fırsat oluşturmak ve özel alanlar eklemek istediğinde bu endpoint kullanılır.

3. Update Opportunity

Açıklama

Mevcut bir fırsatı günceller. Fırsat ID'si ile güncelleme işlemi gerçekleştirilir. Özel alanlar da güncellenebilir.

HTTP Metodu

PUT

Endpoint

PUT /api/v1/PpOpportunities/{id}

Path Parametreleri

Parametre Tip Zorunlu Açıklama Örnek Değer
id integer Evet Güncellenecek fırsat ID'si 12345

Headers

Authorization: Bearer {token}
Content-Type: application/json

Request Body

Request body, Create Opportunity endpoint'i ile aynı yapıdadır. Ayrıca özel alanlar için CustomFieldValueId alanı eklenebilir:

CustomFields Objesi (Update için)

Alan Tip Zorunlu Açıklama
CustomFieldValueId int? Hayır Mevcut özel alan değer ID'si (güncelleme için). Yoksa yeni kayıt oluşturulur
CustomFieldId integer Evet Özel alan ID'si
CustomFieldTextValue string Hayır Metin değeri
CustomFieldDateValue DateTime? Hayır Tarih değeri
CustomFieldOptionId int? Hayır Seçenek ID'si
Özel Alan Güncelleme Kuralları:
  • Eğer CustomFieldValueId gönderilirse, mevcut kayıt güncellenir
  • Eğer CustomFieldValueId gönderilmezse, yeni bir özel alan değeri oluşturulur
  • Eğer tüm değerler boş/null ise, ilgili özel alan değeri silinir
  • Eğer CustomFields array'i boş gönderilirse, fırsata ait tüm özel alanlar silinir

Örnek Request Body

{
    "Description": "Güncellenmiş Proje Fırsatı",
    "RefCustomerCardId": 10148,
    "RefRepresentativeCardId": 8224,
    "OpportunityPrice": 60000.00,
    "OpportunityState": 2,
    "OpportunityStartDate": "2024-06-01T00:00:00",
    "EstimatedEndDate": "2024-12-31T00:00:00",
    "Period": 2,
    "PeriodStartDate": "2024-06-01T00:00:00",
    "Duration": 6,
    "RefCurrencyId": 1,
    "RefQuotaId": 10,
    "RefProductId": 5,
    "RefPipelineStageId": 6,
    "Tags": "önemli,acil,güncellendi",
    "CustomFields": [
        {
            "CustomFieldValueId": 100,
            "CustomFieldId": 20,
            "CustomFieldTextValue": "Güncellenmiş özel not"
        },
        {
            "CustomFieldId": 23,
            "CustomFieldOptionId": 8
        }
    ]
}

Örnek İstek

PUT https://crm.karel.cloud/api/v1/PpOpportunities/12345

Response

Başarılı bir istek için 200 OK durum kodu döner ve aşağıdaki yapıda bir response gelir:

Response Body

Alan Tip Açıklama
Result integer Güncellenen fırsatın ID'si
ResultMessage string İşlem sonucu mesajı

Örnek Response

{
    "Result": 12345,
    "ResultMessage": "İşlem başarılı"
}
Önemli: Eğer fırsat verisi kilitlenmişse (data locked), güncelleme işlemi yapılamaz ve 400 Bad Request hatası döner.

Hata Durumları

Örnek Kullanım Senaryosu

Kullanıcı, mevcut bir fırsatın bilgilerini (tutar, durum, özel alanlar vb.) güncellemek istediğinde bu endpoint kullanılır.

4. Delete Opportunity

Açıklama

Belirli bir fırsatı siler. Fırsat ID'si ile silme işlemi gerçekleştirilir. Fırsata bağlı görevler, notlar, toplantılar ve teklifler de işleme alınır.

HTTP Metodu

DELETE

Endpoint

DELETE /api/v1/PpOpportunities/{id}

Path Parametreleri

Parametre Tip Zorunlu Açıklama Örnek Değer
id integer Evet Silinecek fırsat ID'si 12345

Query Parametreleri

Parametre Tip Zorunlu Açıklama Örnek Değer
deleteCollection bool Hayır Fırsata bağlı tahsilatları da sil (varsayılan: true) true

Örnek İstek

DELETE https://crm.karel.cloud/api/v1/PpOpportunities/12345?deleteCollection=true

Headers

Authorization: Bearer {token}

Response

Başarılı bir istek için 200 OK durum kodu döner. Response body genellikle boştur.

Örnek Response

200 OK
(Response body boş)
Silme İşlemi Detayları:
  • Fırsata bağlı ürünler silinir
  • Fırsata bağlı görevler iptal edilir ve bağlantıları kaldırılır
  • Fırsata yazılmış notlar silinir
  • Fırsata bağlı toplantıların bağlantıları kaldırılır
  • Fırsata bağlı tekliflerin bağlantıları kaldırılır
  • Fırsata ait tekrarlama kayıtları pasif edilir
  • Sağlık operasyonu bilgileri varsa pasif edilir
  • Tahsilatlar silinir veya bağlantıları kaldırılır (deleteCollection parametresine göre)
  • Fırsat kaydı pasif edilir (soft delete)
Önemli:
  • Eğer fırsat verisi kilitlenmişse (data locked), silme işlemi yapılamaz ve 400 Bad Request hatası döner.
  • Silme işlemi geri alınamaz. Fırsat ve ilişkili veriler kalıcı olarak etkilenir.

Hata Durumları

Örnek Kullanım Senaryosu

Kullanıcı, artık geçerli olmayan bir fırsatı ve ilişkili verilerini sistemden kaldırmak istediğinde bu endpoint kullanılır.

Hata Kodları ve Durum Mesajları

API, standart HTTP durum kodlarını kullanır:

Notlar

Dokümantasyon Tarihi: 2025

API Versiyonu: v1