Anasayfa Portal Giriş

E-Arşiv Portal API Dokümanı

Şirket360 E-Arşiv portal API entegrasyonu için gerekli tüm bilgiler

Başlangıç

e-Arşiv Portal API, kullanıcıların sistemde kayıtlı verilerine uzaktan erişim sağlaması ve işlemleri dijital olarak gerçekleştirmesi amacıyla geliştirilmiştir.

API, fatura sorgulama, oluşturma, gönderme ve çeşitli yönetim işlemlerini destekler. Her modül için özel uç noktalar (endpoint) tanımlanmıştır ve bu dökümantasyon üzerinden tüm detaylara ulaşabilirsiniz.

Kimlik Doğrulama

API ile işlem yapabilmek için ilk adım olarak giriş yapmanız gerekmektedir. Bunun için /api/v1/login endpoint’ine e-posta ve şifre bilgilerinizi göndererek access_token almanız gerekir.

Token aldıktan sonra, tüm korumalı (private) endpointlere istek atarken aşağıdaki şekilde Authorization header’ını kullanmalısınız:

Authorization: Bearer JWT_TOKEN_STRING

Uyarı: Her access_token belirli bir süre için geçerlidir (expires_at alanında verilir). Token süresi dolduğunda tekrar giriş yaparak yeni token almalısınız.

Giriş İşlemi

Giriş için aşağıdaki örnek isteği kullanabilirsiniz:

POST /api/v1/login
Host: earsivportal.com
Content-Type: application/json
        
{
    "email": "[email protected]",
    "password": "your_password"
}

Başarılı yanıt:

{
    "status": "success",
    "code": 200,
    "message": "Giriş başarılı!",
    "data": {
    "access_token": "JWT_TOKEN_STRING",
    "token_type": "Bearer",
    "expires_at": "2026-06-27T17:51:29.000000Z"
    }
}

Destek

Modüller ve entegrasyon süreçleri hakkında yaşadığınız sorunlar veya sorularınız için lütfen [email protected] adresine e-posta göndererek uzman destek ekibimizle iletişime geçin.

Müşteri İşlemleri

Müşteri Listesi

GET /api/v1/company/{company_id}/customers

Belirtilen şirkete (company_id) ait müşterileri listeler. Bu endpoint ile sisteme kayıtlı müşterilerin bilgilerine ulaşabilirsiniz.

URL Parametreleri

Parametre Tip Zorunlu Açıklama
company_id integer Evet Firma ID bilgisi

Header Bilgileri

Authorization: Bearer JWT_TOKEN_STRING

Örnek İstek

GET /api/v1/company/1/customers
                Host: earsivportal.com
                Authorization: Bearer your_access_token

Örnek Yanıt

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

{
                    "status": "success",
                    "code": 200,
                    "message": "Müşteri listesi getirildi.",
                    "data": [
                        {
                            "id": 1,
            "tenant_id": 1,
            "user_id": 1,
            "identity_number": "111111113",
            "tax_office": "Ataşehir",
            "title": "Şirket360 Teknoloji Limited Şirketi",
            "first_name": null,
            "last_name": null,
            "invoice_address": "Test adres",
            "country": "Turkey",
            "email": "[email protected]",
            "phone": "5450000000",
            "created_at": "2025-06-22T16:44:22.000000Z",
            "updated_at": "2025-06-26T08:19:50.000000Z",
            "deleted_at": null,
            "country_formatted": "Türkiye",
            "total_invoice_amount": 0,
            "invoices": []
                        },
                        {
                            "id": 2,
                            "tenant_id": 1,
                            "user_id": 1,
                            "identity_number": "11111111111",
                            "tax_office": null,
                            "title": "Ahmet Mehmet",
                            "first_name": "Ahmet",
                            "last_name": "Mehmet",
                            "invoice_address": "",
                            "country": "Turkey",
                            "email": "",
                            "phone": "5530000000",
                            "created_at": "2025-06-22T16:44:22.000000Z",
                            "updated_at": "2025-06-22T16:44:22.000000Z",
                            "deleted_at": null,
                            "country_formatted": "Türkiye",
                            "total_invoice_amount": 0,
                            "invoices": []
                        }
                    ]
                }

Not: Bu endpoint, sadece yetkili kullanıcı token'ı ile çalışır. Token geçersizse 401 Unauthorized hatası döner.

Yeni Müşteri Oluşturma

POST /api/v1/company/{company_id}/customers

Belirtilen firmaya (company_id) ait yeni bir müşteri kaydı oluşturur.

URL Parametreleri

Parametre Tip Zorunlu Açıklama
company_id integer Evet Firma ID bilgisi

Header Bilgileri

Content-Type: application/json
Authorization: Bearer your_access_token

İstek Parametreleri

Parametre Tip Zorunlu Açıklama
identity_number string Evet TCKN veya VKN
tax_office string Hayır Vergi dairesi
title string Hayır Müşteri unvanı
first_name string Hayır Adı (bireysel müşteriler için)
last_name string Hayır Soyadı (bireysel müşteriler için)
invoice_address string Hayır Fatura adresi
country string Hayır Ülke adı
email string Hayır E-posta adresi
phone string Hayır Telefon numarası

Örnek İstek

{
                    "identity_number": "111111114",
                    "tax_office": "Ataşehir",
                    "title": "Şirket360 Teknoloji Limited Şirketi",
                    "first_name": "",
                    "last_name": "",
                    "invoice_address": "Test adres",
                    "country": "Turkey",
                    "email": "[email protected]",
                    "phone": "5450000000"
                }

Örnek Yanıt

Başarılı Yanıt (201 Created)

{
                    "status": "success",
                    "code": 200,
                    "message": "Müşteri başarıyla oluşturuldu.",
                    "data": {
                        "identity_number": "111111114",
                        "tax_office": "Ataşehir",
                        "title": "Şirket360 Teknoloji Limited Şirketi",
                        "first_name": null,
                        "last_name": null,
                        "invoice_address": "Test adres",
                        "country": "Turkey",
                        "email": "[email protected]",
                        "phone": "5450000000",
                        "tenant_id": 1,
                        "user_id": 1,
                        "updated_at": "2025-06-26T15:59:57.000000Z",
                        "created_at": "2025-06-26T15:59:57.000000Z",
                        "id": 282,
                        "country_formatted": "Türkiye",
                        "total_invoice_amount": 0,
                        "invoices": []
                    }
                }

Not: Aynı TCKN/VKN ile birden fazla müşteri kaydı oluşturulamaz. Mevcut bir müşteri varsa 409 Conflict hatası döner.

Müşteri Bilgilerini Güncelleme

PUT /api/v1/company/{company_id}/customers/{customer_id}

Var olan bir müşterinin bilgilerini güncellemek için kullanılır. Bu işlemde yalnızca identity_number zorunludur, diğer alanlar opsiyoneldir ve sadece gönderilen alanlar güncellenir.

URL Parametreleri

Parametre Tip Zorunlu Açıklama
company_id integer Evet Firma ID bilgisi
customer_id integer Evet Güncellenecek müşteri ID'si

Header Bilgileri

Content-Type: application/json
Authorization: Bearer your_access_token

Body Parametreleri

Parametre Tip Zorunlu Açıklama
identity_number string Evet TCKN veya VKN
tax_office string Hayır Vergi dairesi
title string Hayır Müşteri unvanı
first_name string Hayır Adı
last_name string Hayır Soyadı
invoice_address string Hayır Fatura adresi
country string Hayır Ülke
email string Hayır E-posta adresi
phone string Hayır Telefon numarası

Örnek İstek

{
                    "identity_number": "111111114",
                    "tax_office": "Ataşehir",
                    "title": "Şirket360 Teknoloji Limited Şirketi",
                    "first_name": "",
                    "last_name": "",
                    "invoice_address": "Test adres",
                    "country": "Turkey",
                    "email": "[email protected]",
                    "phone": "5450000000"
                }

Örnek Yanıt

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

{
                    "status": "success",
                    "code": 200,
                    "message": "Müşteri güncellendi.",
                    "data": {
                        "id": 282,
                        "tenant_id": 1,
                        "user_id": 1,
                        "identity_number": "111111114",
                        "tax_office": "Ataşehir",
                        "title": "Şirket360 Teknoloji Limited Şirketi",
                        "first_name": null,
                        "last_name": null,
                        "invoice_address": "Test adres",
                        "country": "Turkey",
                        "email": "[email protected]",
                        "phone": "5450000000",
                        "created_at": "2025-06-26T15:59:57.000000Z",
                        "updated_at": "2025-06-26T15:59:57.000000Z",
                        "deleted_at": null,
                        "country_formatted": "Türkiye",
                        "total_invoice_amount": 0,
                        "invoices": []
                    }
                }

Müşteri Detayını Getirme

GET /api/v1/company/{company_id}/customers/{customer_id}

Belirtilen firmaya (company_id) ve müşteri ID'sine (customer_id) ait müşterinin detay bilgilerini getirir.

URL Parametreleri

Parametre Tip Zorunlu Açıklama
company_id integer Evet Firma ID bilgisi
customer_id integer Evet Detayı alınacak müşteri ID'si

Header Bilgileri

Authorization: Bearer your_access_token

Örnek İstek

GET /api/v1/company/1/customers/1
                Host: earsivportal.com
                Authorization: Bearer your_access_token

Örnek Yanıt

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

{
                    "status": "success",
                    "code": 200,
                    "message": "Müşteri detayı listelendi",
                    "data": {
                        "id": 1,
                        "tenant_id": 1,
                        "user_id": 1,
                        "identity_number": "111111113",
                        "tax_office": "Ataşehir",
                        "title": "Şirket360 Teknoloji Limited Şirketi",
                        "first_name": null,
                        "last_name": null,
                        "invoice_address": "Test adres",
                        "country": "Turkey",
                        "email": "[email protected]",
                        "phone": "5450000000",
                        "created_at": "2025-06-22T16:44:22.000000Z",
                        "updated_at": "2025-06-26T08:19:50.000000Z",
                        "deleted_at": null,
                        "country_formatted": "Türkiye",
                        "total_invoice_amount": 0,
                        "invoices": []
                    }
                }

Not: Eğer belirtilen customer_id kayıtlı değilse 404 Not Found hatası döner.

Müşteri İşlemleri

DELETE /api/v1/company/{company_id}/customers/{customer_id}

Müşteri Silme

Belirtilen firmaya (company_id) ve müşteri ID'sine (customer_id) ait müşteriyi sistemden siler.

URL Parametreleri

Parametre Tip Zorunlu Açıklama
company_id integer Evet Firma ID bilgisi
customer_id integer Evet Silinecek müşteri ID'si

Header Bilgileri

Authorization: Bearer your_access_token

Örnek İstek

DELETE /api/v1/company/1/customers/282
                Host: earsivportal.com
                Authorization: Bearer your_access_token

Örnek Yanıt

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

{
                    "status": "success",
                    "code": 200,
                    "message": "Müşteri silindi"
                }

Not: Bu işlem geri alınamaz. Müşteri yumuşak (soft delete) olarak silinir ve ileride geri yüklenebilir.

Ürün İşlemleri

Ürünleri Listeleme

GET /api/v1/company/{company_id}/products

Belirtilen firmaya ait tüm ürünleri listeler.

URL Parametreleri

Parametre Tip Zorunlu Açıklama
company_id integer Evet Firma ID

Header Bilgileri

Authorization: Bearer your_access_token

Örnek İstek

GET /api/v1/company/1/products
            Host: earsivportal.com
            Authorization: Bearer your_access_token

Örnek Yanıt (200 OK)

{
                        "status": "success",
                        "code": 200,
                        "message": "Ürün listesi getirildi.",
                        "data": [
                            {
                                "id": 34,
                                "tenant_id": 1,
                                "user_id": 1,
                                "code": "PRD-001",
                                "name": "Tükenmez Kalem",
                                "unit": "C62",
                                "unit_price": 12.5,
                                "vat_rate": 20,
                                "total_price": 15,
                                "created_at": "2025-06-26T16:29:30.000000Z",
                                "updated_at": "2025-06-26T16:29:30.000000Z",
                                "deleted_at": null,
                                "unit_formatted": "Adet",
                                "unit_price_formatted": "₺12,50",
                                "total_price_formatted": "₺15,00"
                            },
                            {
                                "id": 32,
                                "tenant_id": 1,
                                "user_id": 1,
                                "code": "411297183",
                                "name": "test ürün",
                                "unit": "C62",
                                "unit_price": 100,
                                "vat_rate": 10,
                                "total_price": 110,
                                "created_at": "2025-06-22T16:45:45.000000Z",
                                "updated_at": "2025-06-22T16:45:45.000000Z",
                                "deleted_at": null,
                                "unit_formatted": "Adet",
                                "unit_price_formatted": "₺100,00",
                                "total_price_formatted": "₺110,00"
                            }
                        ]
}

Ürün Oluşturma

POST /api/v1/company/{company_id}/products

Firmaya yeni bir ürün ekler.

URL Parametreleri

Parametre Tip Zorunlu Açıklama
company_id integer Evet Firma ID

Header Bilgileri

Content-Type: application/json
Authorization: Bearer your_access_token

Body Parametreleri

Parametre Tip Zorunlu Açıklama
code string Evet Ürün kodu
name string Evet Ürün adı
unit string Evet Birim kodu
quantity number Hayır (Default: 1) Ürün Adeti
unit_price number Evet Birim fiyat
vat_rate integer Evet KDV oranı

Örnek İstek

{
                "code": "PRD-001",
                "name": "Tükenmez Kalem",
                "unit": "C62",
                "quantity": 1,
                "unit_price": 12.5,
                "vat_rate": 20
            }

Örnek Yanıt (200 OK)

{
                        "status": "success",
                        "code": 200,
                        "message": "Ürün başarıyla oluşturuldu.",
                        "data": {
                            "code": "PRD-003",
                            "name": "Tükenmez Kalem",
                            "unit": "C62",
                            "quantity": 1,
                            "unit_price": 12.5,
                            "vat_rate": 20,
                            "tenant_id": 1,
                            "user_id": 1,
                            "total_price": 15,
                            "updated_at": "2025-06-27T18:44:42.000000Z",
                            "created_at": "2025-06-27T18:44:42.000000Z",
                            "id": 38,
                            "unit_formatted": "Adet",
                            "unit_price_formatted": "₺12,50",
                            "total_price_formatted": "₺15,00"
                        }
                    }

Ürün Güncelleme

PUT /api/v1/company/{company_id}/products/{product_id}

Mevcut bir ürünün bilgilerini günceller.

URL Parametreleri

Parametre Tip Zorunlu Açıklama
company_id integer Evet Firma ID
product_id integer Evet Güncellenecek ürün ID

Header Bilgileri

Content-Type: application/json
Authorization: Bearer your_access_token

Body Parametreleri

Parametre Tip Zorunlu Açıklama
code string Hayır Ürün kodu
name string Hayır Ürün adı
unit string Hayır Birim kodu
quantity number Hayır (Default: 1) Ürün Adeti
unit_price number Hayır Birim fiyat
vat_rate integer Hayır KDV oranı

Örnek İstek

{
                        "code": "PRD-001",
                        "name": "Tükenmez Kalem",
                        "unit": "C62",
                        "quantity": 1,
                        "unit_price": 12.5,
                        "vat_rate": 20
                      }

Örnek Yanıt (200 OK)

{
                        "status": "success",
                        "code": 200,
                        "message": "Ürün güncellendi.",
                        "data": {
                            "id": 33,
                            "tenant_id": 1,
                            "user_id": 1,
                            "code": "PRD-001",
                            "name": "Tükenmez Kalem",
                            "unit": "C62",
                            "quantity": 1,
                            "unit_price": 12.5,
                            "vat_rate": 20,
                            "total_price": 15,
                            "created_at": "2025-06-26T16:24:19.000000Z",
                            "updated_at": "2025-06-26T16:24:19.000000Z",
                            "deleted_at": null,
                            "unit_formatted": "Adet",
                            "unit_price_formatted": "₺12,50",
                            "total_price_formatted": "₺15,00"
                        }
                    }

Ürün Detayı

GET /api/v1/company/{company_id}/products/{product_id}

Belirtilen ürünün detaylı bilgilerini getirir.

URL Parametreleri

Parametre Tip Zorunlu Açıklama
company_id integer Evet Firma ID
product_id integer Evet Ürün ID

Header Bilgileri

Authorization: Bearer your_access_token

Örnek İstek

GET /api/v1/company/1/products/34
            Host: earsivportal.com
            Authorization: Bearer your_access_token

Örnek Yanıt (200 OK)

{
                "status": "success",
                "code": 200,
                "message": "Ürün detayı listelendi",
                "data": { /* Ürün nesnesi */ }
            }

Ürün Silme

DELETE /api/v1/company/{company_id}/products/{product_id}

Belirtilen ürünü sistemden siler.

URL Parametreleri

Parametre Tip Zorunlu Açıklama
company_id integer Evet Firma ID
product_id integer Evet Silinecek ürün ID

Header Bilgileri

Authorization: Bearer your_access_token

Örnek İstek

DELETE /api/v1/company/1/products/33
            Host: earsivportal.com
            Authorization: Bearer your_access_token

Örnek Yanıt (200 OK)

{
                "status": "success",
                "code": 200,
                "message": "Ürün silindi."
            }

Fatura İşlemleri

Faturaları Listeleme

GET /api/v1/company/{company_id}/invoices

Belirtilen firmaya (company_id) ait tüm e-Arşiv faturaları listeler. Son oluşturulanlar en üstte olacak şekilde sıralanır.

URL Parametreleri

Parametre Tip Zorunlu Açıklama
company_id integer Evet Firma ID bilgisi

Header Bilgileri

Authorization: Bearer your_access_token

Örnek İstek

GET /api/v1/company/1/invoices
                Host: earsivportal.com
                Authorization: Bearer your_access_token

Örnek Yanıt (200 OK)

{
                    "status": "success",
                    "code": 200,
                    "message": "Faturalar listelendi",
                    "data": [
                        {
                            "id": 1,
                            "invoice_number": "384367623",
                            "ettn": "91da6472-d4d8-40af-aa02-5021a4e2f679",
                            "document_number": "GIB2025000000001",
                            "issue_date": "2025-04-27T00:00:00.000000Z",
                            "issue_time": "09:42:39",
                            "invoice_type": "SATIS",
                            "currency": "TRY",
                            "total_amount": 1758.9,
                            "invoice_title": "İskonto",
                            "country": "Türkiye",
                            "title": "Aysu Eğilmez",
                            "product_invoices": [
                                {
                                    "name": "Golden Goose Luxury Sneaker...",
                                    "quantity": 1,
                                    "unit": "C62",
                                    "price": 1617.27,
                                    "vat_rate": 10,
                                    "grand_total": 1683.3
                                },
                                {
                                    "name": "Kargo Bedeli",
                                    "quantity": 1,
                                    "unit": "C62",
                                    "price": 66.58,
                                    "vat_rate": 20,
                                    "grand_total": 75.6
                                }
                            ]
                        }
                    ]
                }

Not: Dönüş verisi içinde fatura kalemleri (product_invoices) de yer alır. Bu alan her fatura için detaylı ürün listesi içerir.

Fatura Oluşturma

POST /api/v1/company/{company_id}/invoices

Belirtilen firmaya (company_id) ait yeni bir e-Arşiv faturası oluşturur. Fatura, taslak (draft) olarak sistemde kayıt edilir. Bu endpoint üzerinden KDV, iskonto ve tevkifat gibi işlemler desteklenmektedir.

URL Parametreleri

Parametre Tip Zorunlu Açıklama
company_id integer Evet Firma ID bilgisi

Header Bilgileri

Content-Type: application/json
Authorization: Bearer your_access_token

Örnek İstek

POST /api/v1/company/1/invoices
                Host: earsivportal.com
                Content-Type: application/json
                Authorization: Bearer your_access_token
                
                {
                    "identity_number": 12345678901,
                    "tax_office": "Ataşehir",
                    "title": "Şirket360 Teknoloji Limited Şirketi",
                    "first_name": "",
                    "last_name": "",
                    "invoice_address": "İstanbul, Türkiye",
                    "country": "Turkey",
                    "email": "[email protected]",
                    "phone": "+905555555555",
                    "invoice_title": "Satış Faturası",
                    "invoice_type": "TEVKIFAT",
                    "issue_date": "2025-06-26",
                    "issue_time": "14:00",
                    "delivery_date": "2025-06-27",
                    "delivery_note_number": "DN-123456",
                    "currency": "TRY",
                    "exchange_rate": 1.0,
                    "products": [
                        {
                            "name": "Yazılım Danışmanlığı",
                            "quantity": 2,
                            "unit": "C62",
                            "price": 1000.0,
                            "vat_rate": 20,
                            "additional_taxes": [
                                {
                                    "tax_code": "V9015", // Bu bir tevkifat
                                    "presentation_code": "603", // Tevkifat kodu
                                    "presentation_rate": 70 // Tevkifat oranı
                                }
                            ]
                        },
                        {
                            "name": "Bakım Hizmeti",
                            "quantity": 1,
                            "unit": "C62",
                            "price": 1500.0,
                            "discount_rate": 0,
                            "vat_rate": 10,
                            "additional_taxes": [
                                {
                                    "tax_code": "V0071", // Bu bir ek vergi
                                    "tax_rate": 5 // Vergi oranı
                                }
                            ]
                        },
                        {
                            "name": "Eğitim Hizmeti",
                            "quantity": 3,
                            "unit": "C62",
                            "price": 750.0,
                            "vat_rate": 10
                            // Hiç additional_taxes girilmedi — geçerli
                        }
                    ]
                }

Örnek Yanıt (200 OK)

{
                            "status": "success",
                            "code": 200,
                            "message": "Fatura oluşturuldu.",
                            "data": {
                                "id": 5,
                                "invoice_number": "TR-0005",
                                "document_number": "GIB2025000000030",
                                "issue_date": "2025-06-26",
                                "invoice_type": "SATIS",
                                "invoice_title": "Yeni Başlık",
                                "currency": "TRY",
                                "identity_number": "111111114",
                                "country": "Turkey",
                                "invoice_address": "Test adres",
                                "product_invoices": [
                                    {
                                        "name": "Yeni Ürün",
                                        "quantity": 2,
                                        "unit": "C62",
                                        "price": 100,
                                        "vat_rate": 18,
                                        "discount_price": 0,
                                        "grand_total": 236
                                    }
                                ]
                            }
                        }

Not: Ürün kalemlerinde tevkifatlı vergi uygulanacaksa, additional_taxes alanı mutlaka doldurulmalıdır. Fatura tipi olarak TEVKIFAT seçilmesi gereklidir. Tevkifat oranları presentation_rate alanıyla belirlenir.

Fatura Detayını Getirme

GET /api/v1/company/{company_id}/invoices/{invoice_id}

Belirtilen firmaya (company_id) ve fatura ID’sine (invoice_id) ait e-Arşiv fatura detaylarını getirir. Dönüş verisinde fatura bilgileri, ürün kalemleri ve varsa ek vergiler detaylı şekilde bulunur.

URL Parametreleri

Parametre Tip Zorunlu Açıklama
company_id integer Evet Firma ID bilgisi
invoice_id integer Evet Detayı alınacak fatura ID'si

Header Bilgileri

Authorization: Bearer your_access_token

Örnek İstek

GET /api/v1/company/1/invoices/1
                Host: earsivportal.com
                Authorization: Bearer your_access_token

Örnek Yanıt (200 OK)

{
                    "status": "success",
                    "code": 200,
                    "message": "Fatura detayı listelendi",
                    "data": {
                        "id": 1,
                        "invoice_number": "384367623",
                        "ettn": "91da6472-d4d8-40af-aa02-5021a4e2f679",
                        "document_number": "GIB2025000000001",
                        "issue_date": "2025-04-27T00:00:00.000000Z",
                        "issue_time": "09:42:39",
                        "invoice_type": "SATIS",
                        "currency": "TRY",
                        "total_amount": 1758.9,
                        "invoice_title": "İskonto",
                        "identity_number": "11111111111",
                        "first_name": "Aysu",
                        "last_name": "Eğilmez",
                        "invoice_address": "Kurtuluş mah. Şükrü torun sk no:28",
                        "note": "...",
                        "created_at": "2025-06-22T16:44:22.000000Z",
                        "updated_at": "2025-06-22T16:44:22.000000Z",
                        "product_invoices": [
                            {
                                "name": "Golden Goose Luxury Sneaker...",
                                "quantity": 1,
                                "unit": "C62",
                                "price": 1617.27,
                                "vat_rate": 10,
                                "sub_total": 1530.27,
                                "vat_total": 153.03,
                                "grand_total": 1683.3
                            },
                            {
                                "name": "Kargo Bedeli",
                                "quantity": 1,
                                "unit": "C62",
                                "price": 66.58,
                                "vat_rate": 20,
                                "sub_total": 63,
                                "vat_total": 12.6,
                                "grand_total": 75.6
                            }
                        ]
                    }
                }

Not: Eğer belirtilen invoice_id kayıtlı değilse 404 Not Found hatası döner. Ürün satırları product_invoices alanı içinde gelir. Her ürün kaleminde KDV ve toplam hesapları ayrı ayrı gösterilir.

Fatura Güncelleme

PUT /api/v1/company/{company_id}/invoices/{invoice_id}

Belirtilen firmaya (company_id) ve fatura ID'sine (invoice_id) ait faturayı günceller. Bu endpoint ile fatura bilgileri ve fatura kalemleri düzenlenebilir. Fatura düzenleme işlemi sadece taslak (draft) durumundaki faturalar için geçerlidir.

URL Parametreleri

Parametre Tip Zorunlu Açıklama
company_id integer Evet Firma ID bilgisi
invoice_id integer Evet Düzenlenecek fatura ID bilgisi

Header Bilgileri

Authorization: Bearer your_access_token
Content-Type: application/json

Örnek İstek

PUT /api/v1/company/1/invoices/5
                Host: earsivportal.com
                Authorization: Bearer your_access_token
                Content-Type: application/json
                
                {
                    "invoice_title": "Yeni Başlık",
                    "identity_number": "111111114",
                    "tax_office": "Ataşehir",
                    "country": "Turkey",
                    "invoice_address": "Test adres",
                    "invoice_type": "SATIS",
                    "currency": "TRY",
                    "issue_date": "2025-06-26",
                    "issue_time": "12:00",
                    "product_invoices": [
                        {
                            "name": "Yeni Ürün",
                            "quantity": 2,
                            "unit": "C62",
                            "price": 100,
                            "vat_rate": 18,
                            "discount_rate": 0,
                            "discount_price": 0,
                            "additional_taxes": []
                        }
                    ]
                }

Örnek Yanıt (200 OK)

{
                    "status": "success",
                    "code": 200,
                    "message": "Fatura güncellendi.",
                    "data": {
                        "id": 5,
                        "invoice_number": "TR-0005",
                        "document_number": "GIB2025000000030",
                        "issue_date": "2025-06-26",
                        "invoice_type": "SATIS",
                        "invoice_title": "Yeni Başlık",
                        "currency": "TRY",
                        "identity_number": "111111114",
                        "country": "Turkey",
                        "invoice_address": "Test adres",
                        "product_invoices": [
                            {
                                "name": "Yeni Ürün",
                                "quantity": 2,
                                "unit": "C62",
                                "price": 100,
                                "vat_rate": 18,
                                "discount_price": 0,
                                "grand_total": 236
                            }
                        ]
                    }
                }

Not: Eğer fatura draft durumunda değilse, güncelleme işlemi yapılamaz ve 400 Bad Request hatası döner.

Fatura Silme

DELETE /api/v1/company/{company_id}/invoices/{invoice_id}

Belirtilen firmaya (company_id) ve fatura ID'sine (invoice_id) ait faturayı kalıcı olarak siler. Bu işlem geri alınamaz. Silme gerekçesi body içinde belirtilmelidir.

URL Parametreleri

Parametre Tip Zorunlu Açıklama
company_id integer Evet Firma ID bilgisi
invoice_id integer Evet Silinecek fatura ID bilgisi

Header Bilgileri

Authorization: Bearer your_access_token
Content-Type: application/json

Body Parametreleri

Alan Tip Zorunlu Açıklama
reason string Evet Fatura silme gerekçesi

Örnek İstek

DELETE /api/v1/company/1/invoices/8
                Host: earsivportal.com
                Authorization: Bearer your_access_token
                Content-Type: application/json
                
                {
                    "reason": "test amaçlıdır"
                }

Örnek Yanıt (200 OK)

{
                    "status": "success",
                    "code": 200,
                    "message": "Fatura kalıcı olarak silindi"
                }

Not: Sadece taslak (draft) durumundaki faturalar silinebilir. GİB’e gönderilmiş faturalar silinemez.

Fatura İmzalama

POST /api/v1/company/{company_id}/invoices/{invoice_id}/sign

Fatura imzalama işlemi iki aşamalıdır: send_sms adımında kullanıcıya SMS gönderilir, verify_sms adımında SMS doğrulama yapılır. Doğrulama başarılı olursa fatura imzalanır ve GİB sistemine gönderilir.

URL Parametreleri

Parametre Tip Zorunlu Açıklama
company_id integer Evet Firma ID bilgisi
invoice_id integer Evet İmzalanacak fatura ID bilgisi

Header Bilgileri

Authorization: Bearer your_access_token
Content-Type: application/json

Body Parametreleri

Alan Tip Zorunlu Açıklama
step string Evet send_sms veya verify_sms olarak gönderilmelidir.
token string Hayır (send_sms için) send_sms yanıtında dönen token, verify_sms adımında gönderilmelidir.
sms_code string Hayır (send_sms için) Kullanıcının telefonuna gelen doğrulama kodu. verify_sms adımında zorunludur.

1. Aşama: SMS Gönderimi

POST /api/v1/company/1/invoices/8/sign
                Host: earsivportal.com
                Authorization: Bearer your_access_token
                Content-Type: application/json
                
                {
                    "step": "send_sms"
                }

Yanıt (200 OK)

{
                    "status": "success",
                    "code": 200,
                    "message": "SMS başarıyla gönderildi",
                    "data": {
                        "token": "wK8nP7..."
                    }
                }

2. Aşama: SMS Doğrulama

POST /api/v1/company/1/invoices/8/sign
                Host: earsivportal.com
                Authorization: Bearer your_access_token
                Content-Type: application/json
                
                {
                    "step": "verify_sms",
                    "token": "wK8nP7...",   // SMS gönderiminden dönen token
                    "sms_code": "123456"    // Kullanıcının telefonuna gelen kod
                }

Yanıt (200 OK)

{
                    "status": "success",
                    "code": 200,
                    "message": "Fatura başarıyla imzalandı ve gönderildi"
                }

Not: Bu işlem sadece taslak (draft) durumundaki faturalar için geçerlidir.

Fatura İtiraz Talebi Oluşturma

POST /api/v1/company/{company_id}/invoices/{invoice_id}/objection

Bir faturaya itiraz etmek için bu endpoint kullanılır. İtiraz bilgileri GİB sistemine iletilir ve ilgili fatura itiraz edilmiş olarak işaretlenir.

URL Parametreleri

Parametre Tip Zorunlu Açıklama
company_id integer Evet Firma ID bilgisi
invoice_id integer Evet İtiraz edilecek fatura ID bilgisi

Header Bilgileri

Authorization: Bearer your_access_token
Content-Type: application/json

Body Parametreleri

Alan Tip Zorunlu Açıklama
document_number string Evet İtiraz belgesinin numarası
document_date string (YYYY-MM-DD) Evet İtiraz belgesinin tarihi
method string Evet İtiraz yöntemi. Kabul edilen değerler: NOTER, TAAHHUTLU_MEKTUP, TELGRAF, KEP
description string Evet İtirazın açıklaması

Örnek İstek

POST /api/v1/company/1/invoices/8/objection
                Host: earsivportal.com
                Authorization: Bearer your_access_token
                Content-Type: application/json
                
                {
                    "document_number": "123456",
                    "document_date": "2025-06-27",
                    "method": "NOTER",
                    "description": "Faturadaki ürün miktarı hatalıdır."
                }

Yanıt (200 OK)

{
                    "status": "success",
                    "code": 200,
                    "message": "İtiraz talebi başarıyla oluşturuldu"
                }

Not: Yalnızca durumu approved olan faturalar için itiraz yapılabilir.

Fatura İptal Etme

POST /api/v1/company/{company_id}/invoices/{invoice_id}/cancel

Oluşturulmuş ve onaylanmış bir faturayı iptal etmek için kullanılır. Gerekçeyle birlikte GİB sistemine bildirim yapılır ve fatura durumu cancelled olarak güncellenir.

URL Parametreleri

Parametre Tip Zorunlu Açıklama
company_id integer Evet Firma ID bilgisi
invoice_id integer Evet İptal edilecek fatura ID bilgisi

Header Bilgileri

Authorization: Bearer your_access_token
Content-Type: application/json

Body Parametreleri

Alan Tip Zorunlu Açıklama
reason string Evet Faturanın iptal edilme gerekçesi

Örnek İstek

POST /api/v1/company/1/invoices/8/cancel
                Host: earsivportal.com
                Authorization: Bearer your_access_token
                Content-Type: application/json
                
                {
                    "reason": "Müşteri hatası nedeniyle fatura iptal edilmiştir."
                }

Yanıt (200 OK)

{
                    "status": "success",
                    "code": 200,
                    "message": "Fatura iptal edildi"
                }

Not: Yalnızca approved durumundaki faturalar iptal edilebilir. İptal işlemi geri alınamaz.

Fatura PDF Çıktısını Alma

GET /api/v1/company/{company_id}/invoices/{invoice_id}/pdf

Belirtilen faturaya ait PDF çıktısını döner. Yanıt doğrudan application/pdf içeriğiyle gelir. Tarayıcıda gösterilebilir ya da indirilebilir şekilde kullanılabilir.

URL Parametreleri

Parametre Tip Zorunlu Açıklama
company_id integer Evet Firma ID bilgisi
invoice_id integer Evet PDF çıktısı alınacak fatura ID bilgisi

Header Bilgileri

Authorization: Bearer your_access_token

Örnek İstek

GET /api/v1/company/1/invoices/8/pdf
                Host: earsivportal.com
                Authorization: Bearer your_access_token

Yanıt

Yanıt doğrudan PDF çıktısıdır. Content-Type: application/pdf ile gelir. Tarayıcıda yeni sekmede gösterilebilir ya da dosya olarak indirilebilir.

Yardımcı Fonksiyonlar

Fatura oluşturma işlemi sırasında sistemde kullanılan bazı sabit veriler (ülkeler, para birimleri, birimler, KDV oranları vs.) aşağıdaki yardımcı endpointler ile alınabilir. Bu endpointler frontend form doldurma, seçim listeleri oluşturma ve validasyon destekli arayüz geliştirme süreçlerinde kullanılmak üzere tasarlanmıştır.

Ülke Listesi

GET /api/v1/company/{company_id}/helpers/countries

Fatura formu için desteklenen ülkelerin listesini döner. Bu endpoint, fatura adresi kısmında ülke seçimi için kullanılır.

URL Parametreleri

Parametre Tip Zorunlu Açıklama
company_id integer Evet Şirket ID

Header Bilgileri

Authorization: Bearer your_access_token

Örnek İstek

GET /api/v1/company/1/helpers/countries
Host: earsivportal.com
Authorization: Bearer your_access_token

Örnek Yanıt (200 OK)

{
    "status": "success",
    "code": 200,
    "message": "Ülkeler listelendi",
    "data": [
        {
            "name": "Turkey",
            "value": "Türkiye"
        },
        {
            "name": "Germany",
            "value": "Almanya"
        },
        {
            "name": "United States",
            "value": "Amerika Birleşik Dev"
        },
        ...
    ]
}

Not: `name` alanı İngilizce ülke adını, `value` ise Türkçe karşılığını içerir. Form seçimlerinde Türkçe `value` gösterilmesi önerilir.

Birim Listesi

GET /api/v1/company/{company_id}/helpers/units

Fatura ürünlerinde kullanılabilecek tüm geçerli birimleri döner. Bu birimler ürün oluşturma veya fatura kalemi tanımlama ekranlarında kullanıcıya seçim sunmak için kullanılır.

URL Parametreleri

Parametre Tip Zorunlu Açıklama
company_id integer Evet Şirket ID bilgisi

Header Bilgileri

Authorization: Bearer your_access_token

Örnek İstek

GET /api/v1/company/1/helpers/units
Host: earsivportal.com
Authorization: Bearer your_access_token

Örnek Yanıt (200 OK)

{
    "status": "success",
    "code": 200,
    "message": "Birimler listelendi",
    "data": [
        { "name": "C62", "value": "Adet" },
        { "name": "PA",  "value": "Paket" },
        { "name": "LTR", "value": "lt" },
        { "name": "KGM", "value": "kg" },
        ...
    ]
}

Not: `name` alanı sistemsel birim kodunu, `value` ise kullanıcıya gösterilecek birim adını içerir. Bu veriler stok sistemleri veya ürün katalogları ile uyumlu çalışacak şekilde hazırlanmıştır.

KDV Oranları

GET /api/v1/company/{company_id}/helpers/vat-rates

Sistemde tanımlı olan geçerli KDV oranlarını listeler. Bu oranlar fatura oluştururken ürün kalemlerine uygulanabilir.

URL Parametreleri

Parametre Tip Zorunlu Açıklama
company_id integer Evet Şirket ID bilgisi

Header Bilgileri

Authorization: Bearer your_access_token

Örnek İstek

GET /api/v1/company/1/helpers/vat-rates
Host: earsivportal.com
Authorization: Bearer your_access_token

Örnek Yanıt (200 OK)

{
    "status": "success",
    "code": 200,
    "message": "KDV oranları listelendi",
    "data": [
        { "name": 0, "value": "0%" },
        { "name": 1, "value": "1%" },
        { "name": 8, "value": "8%" },
        { "name": 10, "value": "10%" },
        { "name": 18, "value": "18%" },
        { "name": 20, "value": "20%" }
    ]
}

Not: `name` alanı sayısal oran değerini (vergi oranı), `value` alanı ise kullanıcıya gösterilecek biçimlendirilmiş hali temsil eder. Ürün kaleminde `vat_rate` alanı ile bu değer kullanılabilir.

Ek Vergi Listesi

GET /api/v1/company/{company_id}/helpers/additional-taxes

Fatura ürünlerinde kullanılabilecek ek vergi türlerini listeler. Tevkifat, ÖTV ve diğer tüm ek vergiler bu endpoint ile alınabilir.

Not: Eğer TEVKIFAT tipi bir fatura oluşturmak istiyorsanız, ürünlere KDV TEVKİFAT (kod: V9015) uygulanmalıdır.

URL Parametreleri

Parametre Tip Zorunlu Açıklama
company_id integer Evet Şirket ID bilgisi

Header Bilgileri

Authorization: Bearer your_access_token

Örnek İstek

GET /api/v1/company/1/helpers/additional-taxes
Host: earsivportal.com
Authorization: Bearer your_access_token

Örnek Yanıt (200 OK)

{
    "status": "success",
    "code": 200,
    "message": "Ek vergiler listelendi",
    "data": [
        { "name": "V0021", "value": "BANKA MUAMELELERİ VER." },
        { "name": "V0061", "value": "KKDF KESİNTİ" },
        { "name": "V0071", "value": "ÖTV 1. LİSTE" },
        { "name": "V9077", "value": "ÖTV 2. LİSTE" },
        { "name": "V9015", "value": "KDV TEVKİFAT" },
        ...
    ]
}

Not: `name` alanı sistemsel vergi kodunu, `value` ise Türkçe vergi adını içerir. V9015 kodlu "KDV TEVKİFAT" seçimi yapıldığında, fatura türü mutlaka TEVKIFAT olmalıdır.

Tevkifat Türleri

GET /api/v1/company/{company_id}/helpers/presentations

Tevkifat tipi fatura oluştururken kullanılabilecek sunum (presentation) kodlarını listeler. Bu değerler, ek vergi olarak KDV TEVKİFAT (V9015) seçildiğinde zorunlu hale gelir ve ilgili ürün satırında presentation_code ile kullanılmalıdır.

URL Parametreleri

Parametre Tip Zorunlu Açıklama
company_id integer Evet Şirket ID bilgisi

Header Bilgileri

Authorization: Bearer your_access_token

Örnek İstek

GET /api/v1/company/1/helpers/presentations
Host: earsivportal.com
Authorization: Bearer your_access_token

Örnek Yanıt (200 OK)

{
    "status": "success",
    "code": 200,
    "message": "Tevkifat türleri listelendi",
    "data": [
        {
            "name": 601,
            "value": "%40 - Yapım işleri ve mühendislik hizmetleri",
            "rate": 40
        },
        {
            "name": 603,
            "value": "%70 - Makine, teçhizat, demirbaş ve taşıtlara ait tadilat, bakım, onarım",
            "rate": 70
        },
        {
            "name": 606,
            "value": "%90 - İş gücü temin hizmeti",
            "rate": 90
        },
        {
            "name": 650,
            "value": "%0 - Diğer işlemler",
            "rate": 0
        }
        ...
    ]
}

Not: name alanı, fatura gönderiminde kullanılacak presentation_code değeridir. value açıklama metnini içerir. rate ise yüzdelik tevkifat oranıdır. Bu bilgiler yalnızca V9015 - KDV TEVKİFAT koduyla birlikte kullanılmalıdır.

Para Birimleri

GET /api/v1/company/{company_id}/helpers/currencies

Fatura oluşturulurken kullanılabilecek para birimlerinin listesini döner. Sistem çoklu döviz desteği sağlar. Bu endpoint, fatura formu veya döviz kuru hesaplama işlemlerinde kullanılabilir.

URL Parametreleri

Parametre Tip Zorunlu Açıklama
company_id integer Evet Şirket ID bilgisi

Header Bilgileri

Authorization: Bearer your_access_token

Örnek İstek

GET /api/v1/company/1/helpers/currencies
Host: earsivportal.com
Authorization: Bearer your_access_token

Örnek Yanıt (200 OK)

{
    "status": "success",
    "code": 200,
    "message": "Para birimleri listelendi",
    "data": [
        { "name": "USD", "value": "US Dollar" },
        { "name": "EUR", "value": "Euro" },
        { "name": "TRY", "value": "Türk Lirası" },
        { "name": "GBP", "value": "Pound Sterling" },
        { "name": "JPY", "value": "Yen" },
        ...
    ]
}

Not: name alanı döviz kodunu (ISO 4217 standardı), value alanı ise para biriminin tam adını temsil eder. Fatura oluştururken currency alanına USD, TRY gibi değerler gönderilmelidir.

Fatura Türleri

GET /api/v1/company/{company_id}/helpers/invoice-types

Sistem tarafından desteklenen tüm fatura türlerini listeler. Bu değerler fatura oluştururken invoice_type alanında kullanılmalıdır. Her fatura türü farklı kurallara ve hesaplamalara tabidir.

URL Parametreleri

Parametre Tip Zorunlu Açıklama
company_id integer Evet Şirket ID bilgisi

Header Bilgileri

Authorization: Bearer your_access_token

Örnek İstek

GET /api/v1/company/1/helpers/invoice-types
Host: earsivportal.com
Authorization: Bearer your_access_token

Örnek Yanıt (200 OK)

{
    "status": "success",
    "code": 200,
    "message": "Fatura türleri listelendi",
    "data": [
        { "name": "SATIS", "value": "SATIŞ" },
        { "name": "IADE", "value": "GENEL İADE" },
        { "name": "TEVKIFAT", "value": "TEVKİFAT" },
        { "name": "TEVKIFATIADE", "value": "TEVKİFAT İADE" },
        { "name": "ISTISNA", "value": "İSTİSNA" },
        { "name": "OZELMATRAH", "value": "ÖZEL MATRAH" },
        { "name": "IHRACKAYITLI", "value": "İHRAÇ KAYITLI" },
        { "name": "KONAKLAMAVERGISI", "value": "KONAKLAMA VERGİSİ" }
    ]
}

Not: name alanı sistemde gönderilecek fatura tipidir. value alanı ise Türkçe açıklamasıdır. Tevkifatlı fatura oluşturmak için invoice_type = "TEVKIFAT" seçilmelidir.

Birim Tipleri

GET /api/v1/company/{company_id}/helpers/unit-types

Bu endpoint, sistemde kullanılabilecek tüm birim tiplerini listeler. Fatura ürünleri eklenirken unit alanı bu listeden seçilmelidir.

URL Parametreleri

Parametre Tip Zorunlu Açıklama
company_id integer Evet Şirket ID bilgisi

Header Bilgileri

Authorization: Bearer your_access_token

Örnek İstek

GET /api/v1/company/1/helpers/unit-types
Host: earsivportal.com
Authorization: Bearer your_access_token

Örnek Yanıt (200 OK)

{
    "status": "success",
    "code": 200,
    "message": "Birimler listelendi",
    "data": [
        { "name": "DAY", "value": "Gün" },
        { "name": "MON", "value": "Ay" },
        { "name": "ANN", "value": "Yıl" },
        { "name": "HUR", "value": "Saat" },
        { "name": "D61", "value": "Dakika" },
        { "name": "C62", "value": "Adet" },
        { "name": "PA",  "value": "Paket" },
        ...
        { "name": "HAR", "value": "Hektar (ha)" },
        { "name": "LM",  "value": "Metretül (LM)" }
    ]
}

Not: Bu birimler, fatura ürünlerinin tanımında unit alanında gönderilmelidir. Örneğin: "unit": "C62" → "Adet"

Postman API Collection

Tüm e-Arşiv Portal API uç noktalarını içeren hazır Postman Collection dosyasını aşağıdan indirebilirsiniz.

Hata Kodları

Kod Açıklama
400 Geçersiz istek parametreleri
401 Kimlik doğrulama hatası
403 Yetkisiz erişim
404 Kayıt bulunamadı
429 Çok fazla istek
200 Başarılı
500 Sunucu hatası

Entegrasyon Modülleri

Şirket360 API'si ile entegre olabileceğiniz hazır modüller:

+
Daha Fazlası
Yeni entegrasyonlar çok yakında sizlerle olacak.
Sistem sağlayıcısı Şirket360