1. Quickstart
TrendTüccar REST API uses standard JSON format in all requests and responses. To access API endpoints, simply generate an API key from Settings > API in your corporate dashboard and route requests directly to your own store domain.
TrendTüccar e-commerce infrastructure supports both your Custom Domain and subdomain with full authority and automatic SSL:
- 1. Your Custom Domain (Enterprise & Recommended):
https://your-store.com/api/v1/tenant/ - 2. Your TrendTüccar Subdomain:
https://{your-store}.trendtuccar.com/api/v1/tenant/
All API requests sent through your store's custom domain (e.g. yourstore.com) are automatically verified and processed directly via a secure HTTPS channel.
Example First API Call (Ping / Health Check):
curl -X GET "https://your-store.com/api/v1/tenant/ping/" \
-H "X-Tenant-Key: YOUR_API_KEY" \
-H "Accept: application/json"
2. Authentication
The TrendTüccar enterprise API layer requires a unique store API key with every request. Two different HTTP header formats are fully supported.
| Method | HTTP Header | Example Value | Usage Context |
|---|---|---|---|
| Custom Header (Recommended) | X-Tenant-Key |
tt_live_5bc60a..._e39f72 |
The most straightforward method for direct ERP, integrator, or server services. |
| Standard Bearer Token | Authorization |
Bearer tt_live_5bc60a..._e39f72 |
For Postman, Insomnia, or standard OpenAPI-compatible clients. |
Raw API keys are never stored in the database; they are secured using the PBKDF2 SHA-256 hashing algorithm. The key is displayed on screen only once upon creation. For lost keys, you can generate a new key using Zero-Downtime Rotation with a 24-hour grace transition period.
3. Security and IP Whitelisting
You can apply the following security guidelines to protect your API keys against unauthorized access and maintain a secure integration:
| Security Rule | Implementation | Description |
|---|---|---|
| 1. IP Whitelist | 192.0.2.1 / 198.51.100.0/24 |
By restricting your API key only to your static server or office IP addresses, you can block calls from unauthorized locations. |
| 2. HTTPS / TLS Encryption | https:// |
All requests must be transmitted via TLS encryption. Plain unencrypted HTTP requests are rejected. |
| 3. Server-Side Storage | .env / Environment |
Do not embed your API key into client-side code (browser or mobile app); store it strictly in your secure backend server. |
4. Defined Permission Scopes (Scopes Matrix)
Assign only the required permissions to your API key based on the Principle of Least Privilege. If a scope is missing, the system immediately returns 403 Forbidden with the 'insufficient_scope' code.
| Scope | Description | Associated Endpoint |
|---|---|---|
orders:read |
Permission to list orders and read order details (Customer personal data is masked). | GET /api/v1/tenant/orders/ |
orders_pii:read |
Critical permission to read customer name, phone, email, shipping address, and tax ID unmasked. | GET /api/v1/tenant/orders/{id}/ |
orders:write |
Permission to update shipping tracking number, carrier, and order delivery status. | PATCH /api/v1/tenant/orders/{id}/shipping/ |
products:read |
Permission to read store product catalog, category tree, variants, and product images. | GET /api/v1/tenant/products/ |
inventory:read |
Permission to read stock quantities and prices of product variants. | GET /api/v1/tenant/inventory/ |
inventory:write |
Permission to synchronize stock quantities instantly or in bulk from external ERP or warehouse software. | POST /api/v1/tenant/inventory/sync/ |
agreements:read |
Permission to list your store's influencer partnerships, commission rates, and sales metrics. | GET /api/v1/tenant/agreements/ |
posts:read |
Permission to read store corporate pages, blog posts, and CMS contents. | GET /api/v1/tenant/posts/ |
customers:read |
Permission to read registered store customers, signup dates, and order summaries. | GET /api/v1/tenant/customers/ |
reports:read |
Permission to read daily/monthly revenue, order volume, and average order value (AOV) reports. | GET /api/v1/tenant/reports/sales/ |
5. Personal Data Masking Policy (KVKK / GDPR)
Customer personal data is protected by default under data privacy regulations (GDPR/KVKK). Integrations with 'orders:read' receive masked data, whereas 'orders_pii:read' is required for operations like invoice or shipping label printing.
| Data Field | With orders:read (Masked) | With orders_pii:read (Unmasked) |
|---|---|---|
customer_name |
Ah*** Yıl*** |
Ahmet Yılmaz |
phone |
+90 532 *** ** 12 |
+90 532 123 45 67 |
email |
ah***@example.com |
[email protected] |
address |
Ata*** Mah. *** Kadıköy / İstanbul |
Atatürk Mah. Karanfil Sok. No:4 Kadıköy / İstanbul |
tax_id |
123*******8 |
12345678901 |
8. Error Codes & Rate Limiting
TrendTüccar returns standard enterprise HTTP status codes. Rate-limit headers are included with every response:
| HTTP Code | Status (Code) | Description |
|---|---|---|
200 OK |
success |
Request was successfully processed and data was returned. |
400 Bad Request |
invalid_payload |
Request body is invalid, JSON is malformed, or required fields are missing. |
401 Unauthorized |
key_not_found / key_inactive |
API key is missing, invalid, or has been deactivated. |
403 Forbidden |
insufficient_scope / domain_mismatch |
Your API key does not have the required permission scope for this operation or the request originated from an invalid domain. |
404 Not Found |
not_found |
The requested record was not found in your store or parameters did not match. |
429 Too Many Requests |
rate_limit_exceeded |
Rate limit quota exceeded per minute. Wait until the epoch time specified in X-RateLimit-Reset. |
Headers returned with every response: X-RateLimit-Limit (Per-minute quota), X-RateLimit-Remaining (Remaining calls), X-RateLimit-Reset (Reset epoch second).
Order List
Lists your store orders in a paginated format with filtering options.
URL Query Parameters
| Parameter | Type | Required? | Description |
|---|---|---|---|
status |
string | Optional | pending, approved, shipped, delivered, cancelled |
page |
integer | Optional | Page number (Default: 1) |
limit |
integer | Optional | Records per page (Default: 50, Maximum: 100) |
Sample Request & JSON Response
curl -X GET "https://your-store.com/api/v1/tenant/orders/?status=approved&limit=2" \
-H "X-Tenant-Key: YOUR_API_KEY"
Order Details & Line Items
Returns all purchased line items, shipping address, and payment breakdown of the specified order.
Sample Request & JSON Response
curl -X GET "https://your-store.com/api/v1/tenant/orders/{order_number}/" \
-H "X-Tenant-Key: YOUR_API_KEY"
Shipping Update
Updates the shipping tracking number and delivery status of the order. Instantly triggers automatic SMS and email notifications to the customer.
Sample Request & JSON Response
curl -X PATCH "https://your-store.com/api/v1/tenant/orders/{order_number}/shipping/" \
-H "X-Tenant-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"carrier": "DHL Express",
"tracking_number": "DHL123456789",
"status": "shipped"
}'
e-Invoice / e-Archive Notification
Notifies TrendTüccar of the invoice number and ETTN (UUID) when your integrator or accounting software (Paraşüt, BizimHesap, Uyumsoft, Logo, etc.) issues an invoice.
Add a unique Idempotency-Key (UUID) to your request header to prevent duplicate invoice generation if the same request is retried during a network disruption or timeout. The system safely returns the previous successful result on duplicate calls with the same key.
Request Body (JSON Payload)
| Parameter | Type | Required? | Description |
|---|---|---|---|
invoice_number |
string | Yes | TRA-compliant 16-digit invoice number (e.g., GIB2026000000042) |
invoice_uuid |
string | Optional | Universal Unique Identifier (ETTN / UUID v4) |
invoice_date |
string (ISO 8601) | Optional | Official issuance date and time of the invoice |
invoice_url |
string (URL) | Optional | Signed PDF / Document link for the customer to download the invoice |
invoice_status |
string | Optional | INVOICED, PENDING_GIB, REJECTED_GIB, REJECTED_BUYER, CANCELLED |
document_type |
string | Optional | SATIS (Default), IADE, GIDER_PUSULASI |
scenario |
string | Optional | TICARIFATURA, TEMELFATURA, EARSIVFATURA, NONE |
envelope_id |
string | Optional | TRA Envelope UUID / Number (e.g., 550e8400-e29b-41d4-a716-446655440000) |
integrator_name |
string | Optional | Integrator service name (e.g., Parasut, BizimHesap, Uyumsoft, Logo) |
integrator_ref |
string | Optional | Integrator internal transaction or invoice reference ID |
currency |
string | Optional | Invoice currency (Default: 'TRY') |
gib_status_code |
integer | Optional | Raw GİB envelope/process code returned by the integrator (1000, 1100, 1195, 1200, 1215, 1230, 1300) |
payable_amount |
decimal | Optional | Total invoice payable amount (reconciled down to the cent with order total) |
tax_exclusive_amount |
decimal | Optional | Tax exclusive subtotal (tax base) |
tax_amount |
decimal | Optional | Total calculated VAT amount |
buyer_einvoice_status |
string | Optional | EINVOICE_USER (e-Invoice Taxpayer), EARSIV_USER (e-Archive User) |
buyer_pk_alias |
string | Optional | Recipient GİB Mailbox Alias (e.g. urn:mail:[email protected]) |
lines |
array | Optional | Itemized invoice line breakdown (kind, name, quantity, unit_price_net, vat_rate, vat_amount, withholding_code, etc.) |
GİB 2026 Envelope & Status Codes Mapping Table
TrendTüccar state machine maps raw GİB codes from integrators into internal statuses. Codes 1000 and 1100 indicate the envelope is queued or in transit; they do not mean the invoice is approved:
| Raw GİB Code | Internal Status (internal_status) | Order Status | Description & Business Rule |
|---|---|---|---|
1000 |
PENDING_GIB | Not Invoiced (Pending) | Envelope added to queue. GİB approval not yet received. |
1100 |
PENDING_GIB | Not Invoiced (Pending) | Envelope processing or dispatched to GİB center. |
1195 |
REJECTED_GIB | Not Invoiced (GİB Rejection) | GİB schema or signature verification failed. Invoice rejected. |
1200 |
PENDING_GIB | Not Invoiced (Pending) | Envelope successfully transmitted to TRA system (Queuing stage; can be marked COMPLETED via EINVOICE_COMPLETED_CODES). |
1215 |
DELIVERY_FAILED | Transmission Failed | Transmission to recipient mailbox attempted 4 times and failed (1215 after 1210). |
1230 |
REJECTED_BUYER | Rejected by Recipient | Recipient returned REJECT application response via system for commercial e-invoice. |
1300 |
COMPLETED | INVOICED | Recipient approved the invoice (Commercial Acceptance) or TRA process completed successfully. |
Pursuant to Article 231/5 of the Tax Procedure Law, invoices must be issued within a maximum of 7 days from delivery of goods or services. Invoices not issued in time are legally considered never issued.
When an order is shipped in TrendTüccar ( SHIPPED ), the system automatically starts shipped_at and the 7-day invoice_deadline timer. Uninvoiced orders are reported in Reconciliation API with days overdue.
Example Request & JSON Response (Advanced GİB e-Invoice Notification)
curl -X POST "https://your-store.com/api/v1/tenant/orders/{order_number}/invoice/" \
-H "X-Tenant-Key: YOUR_API_KEY" \
-H "Idempotency-Key: {idempotency_key}" \
-H "Content-Type: application/json" \
-d '{
"invoice_number": "INV2026000000042",
"invoice_uuid": "e4a5c6d7-8b9a-4c1d-9e2f-3a4b5c6d7e8f",
"envelope_id": "550e8400-e29b-41d4-a716-446655440000",
"integrator_name": "Standard",
"currency": "USD",
"document_type": "SALES",
"scenario": "COMMERCIAL",
"gib_status_code": 1300,
"payable_amount": "1450.00",
"tax_exclusive_amount": "1208.33",
"tax_amount": "241.67",
"buyer_einvoice_status": "EINVOICE_USER",
"buyer_pk_alias": "urn:mail:[email protected]",
"invoice_date": "2026-10-27T17:15:00Z",
"invoice_url": "https://invoices.your-store.com/INV2026000000042.pdf"
}'
Return Invoice & Expense Voucher Notification
When an order is partially or fully refunded, e-Invoice return for corporate clients ( IADE, Basic Invoice scenario), and for individual end consumers Expense Note ( GIDER_PUSULASI ) record is created:
curl -X POST "https://your-store.com/api/v1/tenant/orders/{order_number}/invoice/cancel/" \
-H "X-Tenant-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"document_type": "REFUND",
"reason": "Customer returned 1 item due to size mismatch.",
"parent_invoice_uuid": "e4a5c6d7-8b9a-4c1d-9e2f-3a4b5c6d7e8f",
"invoice_number": "REF2026000000001",
"refund_lines": [
{
"purchase_id": 105,
"quantity": 1,
"refund_amount": "500.00",
"vat_rate": "20.00"
}
]
}'
Invoice Reconciliation & Tax Law (VUK 231) Audit (Reconciliation API)
Synchronizes invoice states between the integrator and TrendTüccar during network interruptions. Reports orders exceeding the 7-day VUK 231 statutory deadline and invoices stuck in PENDING_GIB for more than 48 hours.
curl -X POST "https://your-store.com/api/v1/tenant/invoices/reconciliation/" \
-H "X-Tenant-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"date_from": "2026-10-01",
"date_to": "2026-10-31",
"invoiced_orders": [
{"order_number": "1042", "invoice_number": "INV2026000000042", "invoice_uuid": "uuid-1", "gib_status_code": 1200},
{"order_number": "1043", "invoice_number": "INV2026000000043", "invoice_uuid": "uuid-2", "gib_status_code": 1300}
]
}'
Product Catalog & Variants
Returns all active products, prices, variants, and CDN media URLs of your store.
curl -X GET "https://your-store.com/api/v1/tenant/products/?limit=10" \
-H "X-Tenant-Key: YOUR_API_KEY"
Real-Time Stock Levels (Inventory)
Lists live stock quantities, SKUs, and unit prices of product variants.
Bulk Stock Sync (Batch Sync)
Batch updates stock levels from your ERP or warehouse software matched by SKU or barcode.
curl -X POST "https://your-store.com/api/v1/tenant/inventory/sync/" \
-H "X-Tenant-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"items": [
{"sku": "DRS-BLK-M", "stock_quantity": 45},
{"sku": "DRS-BLK-L", "stock_quantity": 18}
]
}'
Ping & Connection Diagnostics
Tests the validity, scopes, and store connectivity of your API key. Does not consume rate limit quota.
Store Profile & Configuration
Returns your store's domain, configuration, and profile details.
Influencer Deals & Sales Volume
Returns your store's influencer partnerships, commission percentages, and sales metrics.
CMS Pages & Blog Posts
Lists published blog articles, content pages, and announcements.
Customer Directory (Customers)
Lists registered store customers, signup dates, and order counts.
Sales & Financial Reports
Returns the financial summary including daily/monthly revenue, order volume, and average order value (AOV).
7. Webhook Architecture & Operation Logic
Receive instant HTTPS POST JSON notifications directly to your system when an order is placed or inventory drops, eliminating the need for periodic polling.
If your target server responds with anything other than 2xx or times out, the TrendTüccar webhook engine retransmits the notification with exponential backoff intervals.
Supported Webhook Events
You can select any of the following events when configuring your webhook endpoint:
| Event | Trigger Condition |
|---|---|
order.created |
Triggered when a customer creates a new order. |
order.paid |
Triggered when an order payment is successfully confirmed. |
order.shipped |
Triggered when an order is marked as shipped and a tracking number is assigned. |
order.cancelled |
Triggered when an order is cancelled or a return is approved. |
inventory.low_stock |
Triggered when the inventory of a product variant reaches the critical threshold. |
product.updated |
Triggered when product price or specifications are updated. |
agreement.created |
Triggered when a new influencer partnership agreement is established. |
HMAC-SHA256 Signature Verification Code
Every webhook request from TrendTüccar is signed using the raw payload body and your webhook secret. To verify authenticity, validate the HTTP header X-TrendTuccar-Signature value using the code example below:
The value starting with whsec_ is not the signature itself, but the shared secret used to verify the HMAC-SHA256 signature. Use the entire value including the whsec_ prefix for verification.
import hmac
import hashlib
def verify_webhook_signature(raw_payload_bytes, signature_header, webhook_secret):
expected_sig = hmac.new(
webhook_secret.encode('utf-8'),
raw_payload_bytes,
hashlib.sha256
).hexdigest()
# Timing-attack safe comparison
return hmac.compare_digest(expected_sig, signature_header)
2. Custom Domain & Base URL
TrendTüccar e-commerce infrastructure supports your store's custom domain with full authority and automatic SSL/TLS certificates on all REST API calls.
You can run your integrations through either of the following two addresses:
- 1. Your Custom Domain (Enterprise & Recommended):
https://your-store.com/api/v1/tenant/ - 2. Your TrendTüccar Subdomain:
https://{your-store}.trendtuccar.com/api/v1/tenant/
API Usage Steps with Custom Domain:
| Step | Action | Description |
|---|---|---|
| 1. Domain Connection | Admin Panel > Settings > Domain |
Point your custom domain (e.g. yourstore.com) to TrendTüccar DNS nameservers or A record. |
| 2. Automatic SSL | TLS 1.3 / HTTPS |
When your domain is verified, your SSL certificate is automatically issued and API endpoints immediately become active via HTTPS. |
| 3. ERP & Software Configuration | https://your-store.com/api/v1/tenant/ |
Enter your own store domain directly into the Base URL setting of your accounting or ERP software. |
8. Pagination Standards
Standard pagination parameters and metadata responses are provided to retrieve large datasets without performance degradation.
| Parameter | Default | Range | Description |
|---|---|---|---|
page |
1 | 1 .. N | Requested page number (1-based). |
limit |
50 | 1 .. 100 | Maximum records returned per page (max 100). |
Standard Pagination Response Object:
{
"success": true,
"data": [ /* ... */ ],
"pagination": {
"total_count": 1420,
"page": 1,
"limit": 50,
"total_pages": 29,
"has_next": true,
"has_prev": false
}
}
Return & Cancellation Requests
Lists product return, exchange or cancellation requests created by your customers. Required scope: orders:read
Example Request & Response:
curl -X GET "https://your-store.com/api/v1/tenant/returns/" \
-H "X-Tenant-Key: YOUR_API_KEY" \
-H "Accept: application/json"
{
"success": true,
"data": [
{
"id": 14,
"order_number": "ORD-2026-9041",
"product_name": "Slim Fit Cotton Shirt - White / M",
"reason": "Size too small, requesting one size larger replacement.",
"status": "PENDING",
"created_at": "2026-10-26T14:30:00Z"
}
]
}
Get Single Product
Returns all variants, media gallery, pricing and inventory levels for a specific product in a single call. Required scope: products:read
curl -X GET "https://your-store.com/api/v1/tenant/products/{product_id}/" \
-H "X-Tenant-Key: YOUR_API_KEY"
{
"success": true,
"data": {
"id": "a3f124c9-58b2-4d1a-bf41-89d97a612345",
"product_name": "Premium Leather Jacket",
"slug": "premium-leather-jacket",
"category": { "id": 12, "name": "Outerwear" },
"is_active": true,
"is_published": true,
"price": { "unit_price": 3499.90, "compare_price": 3999.00 },
"stock_quantity": 48,
"image": "https://your-store.com/media/products/leather_jacket.jpg",
"created_at": "2026-08-10T12:00:00Z"
}
}
Categories and Hierarchy
Returns main and subcategories defined in your store, URL slugs, and associated product counts. Required scope: products:read
curl -X GET "https://your-store.com/api/v1/tenant/categories/" \
-H "X-Tenant-Key: YOUR_API_KEY"
{
"success": true,
"data": [
{
"id": 1,
"name": "Women's Apparel",
"slug": "womens-apparel",
"parent_id": null,
"product_count": 142
},
{
"id": 5,
"name": "Dresses",
"slug": "dresses",
"parent_id": 1,
"product_count": 68
}
]
}
Variants & Attribute Management
In TrendTüccar product architecture, each variant (Size, Color, Material etc.) is linked to an independent SKU, barcode, and image set.
| Field | Type | Description |
|---|---|---|
size / option |
String | Variant option (e.g. "S", "M", "L", "42", "Red"). |
stock_code / sku |
String | Stock Keeping Unit (SKU) identifying the variant in ERP and warehouse systems. |
barcode |
String | EAN-13, UPC, or internal barcode number. |
stock_quantity |
Integer | Current sellable inventory quantity for the variant. |
Discount Coupons & Campaigns
Returns promotional coupon codes, discount types (percentage or fixed amount), and usage conditions created in your store.
curl -X GET "https://your-store.com/api/v1/tenant/coupons/" \
-H "X-Tenant-Key: YOUR_API_KEY"
{
"success": true,
"data": [
{
"id": 3,
"code": "NEWSEASON20",
"discount_type": "PERCENTAGE",
"discount_amount": 20.00,
"min_purchase_amount": 500.00,
"is_active": true,
"expire_date": "2026-12-31T23:59:59Z",
"created_at": "2026-09-01T10:00:00Z"
}
]
}
Webhook Retry Policy
TrendTüccar Webhook engine uses exponential backoff automatic retry to ensure guaranteed delivery of events to your servers.
| Rule | Value | Description |
|---|---|---|
| Timeout | 5 Saniye |
Your endpoint must return an HTTP 2xx status code within 5 seconds. |
| Max Retries | 5 Kez |
In case of 5xx errors or connection timeouts, events are retried with exponentially increasing intervals. |
| Delay Intervals | 1dk, 5dk, 30dk, 2saat, 6saat |
Event notifications will not be lost during temporary outages on your server. |
API & Webhook Integration with Python
You can copy the ready-to-use Python class below into your project to start communicating with TrendTüccar API immediately.
import requests
class TrendTuccarClient:
def __init__(self, base_url: str, api_key: str):
# e.g. base_url: "https://your-store.com/api/v1/tenant"
self.base_url = base_url.rstrip('/')
self.session = requests.Session()
self.session.headers.update({
"X-Tenant-Key": api_key,
"Accept": "application/json",
"Content-Type": "application/json"
})
def get_orders(self, status: str = None, page: int = 1):
params = {"page": page}
if status:
params["status"] = status
r = self.session.get(f"{self.base_url}/orders/", params=params)
r.raise_for_status()
return r.json()
def update_shipping(self, order_number: str, shipping_id: str, status: str = "SHIPPED"):
payload = {"shipping_id": shipping_id, "status": status}
r = self.session.patch(f"{self.base_url}/orders/{order_number}/shipping/", json=payload)
r.raise_for_status()
return r.json()
def sync_inventory(self, items: list):
# items: [{"sku": "DRS-BLK-M", "stock_quantity": 40}]
r = self.session.post(f"{self.base_url}/inventory/sync/", json={"items": items})
r.raise_for_status()
return r.json()
# Usage:
client = TrendTuccarClient("https://your-store.com/api/v1/tenant", "tt_live_YOUR_API_KEY")
print(client.get_orders(status="approved"))
Node.js & TypeScript Integration Template
Type-safe integration example for modern Node.js (Axios / Fetch) environments.
import axios, { AxiosInstance } from 'axios';
export class TrendTuccarApi {
private client: AxiosInstance;
constructor(baseUrl: string, apiKey: string) {
this.client = axios.create({
baseURL: baseUrl.replace(/\/$/, ''),
headers: {
'X-Tenant-Key': apiKey,
'Accept': 'application/json',
'Content-Type': 'application/json',
},
timeout: 10000,
});
}
async getProducts(limit = 50, page = 1) {
const { data } = await this.client.get('/products/', { params: { limit, page } });
return data;
}
async syncInventory(items: Array<{ sku: string; stock_quantity: number }>) {
const { data } = await this.client.post('/inventory/sync/', { items });
return data;
}
}
// Usage:
const api = new TrendTuccarApi('https://your-store.com/api/v1/tenant', 'tt_live_YOUR_API_KEY');
api.getProducts().then(console.log);