PazarCloudDeveloper API v1OpenAPI 3.1 (JSON)Postman collection

PazarCloud Developer API

A server-to-server API for one PazarCloud organisation: read its customers, products, stock and prices, create sales that post to its books, issue the Turkish e-invoice of a sale automatically, and be told about changes through signed webhooks.

The sandbox is https://stg-app.pazarcloud.ir/api/public/v1 (staging; open sign-up, test data only, no legal documents). Production is https://app.pazarcloud.ir/api/public/v1. Keys never work across the two: sandbox keys start with pcl_test_, production keys with pcl_live_.

Getting started

  1. Sign up at the app (the sandbox for testing), create the organisation and activate the Developer API module (and e-Invoice for Türkiye).
  2. Set up the books once in the app: branch, warehouse, the services you sell (e.g. “Uçak bileti”, “Otel konaklama”, “Hizmet bedeli”), tax types, control accounts and, for e-invoices, the provider’s credentials.
  3. In Administration › Integrations › Developer API create an integration with a role that allows exactly what your system needs (a dedicated role is safest), then create a key for one branch (the code mailed to you confirms it). The key is shown once.
  4. Call GET /me to see the organisation, branch, fiscal year, permissions and limits of the key.
  5. Map your master data with the lookups (/services, /tax-types, /payment-methods, /funds, /warehouses, /units) and upsert customers by your own reference.
  6. Post sales with an Idempotency-Key and your external_ref; register a webhook endpoint to be told about e-invoice states.
curl "https://app.pazarcloud.ir/api/public/v1/me" -H "Authorization: Bearer $PAZARCLOUD_KEY"

Authentication and keys

Send the key as Authorization: Bearer pcl_…. Hosts that strip the Authorization header (some PHP/CGI setups) may send X-API-Key: pcl_… instead. A key belongs to one integration — a machine member of the organisation with a role; it never signs in and does not count toward the plan’s user limit. Every request works in the key’s branch; a write’s fiscal year follows its document date, and a read may name a past year with the PazarCloud-Fiscal-Year: <id> header.

Conventions

Idempotency and external references

POST /sales-invoices requires an Idempotency-Key header (your own value, at most 128 characters). Retrying with the same key and body answers the first result again with Idempotent-Replay: true and the e-invoice’s current state — never a second sale and never a second send. The same key with another body answers 422 IDEMPOTENCY_KEY_REUSED. Keys are remembered for 24 hours.

external_ref is your permanent reference (ticket number, order id, customer id): unique per organisation, integration and record type, forever. A second create with the same reference answers 409 EXTERNAL_REF_EXISTS with the existing record’s id — treat it as success. Find records by reference (GET /sales-invoices?external_ref=, GET /customers?external_ref=) and pair existing ones with PUT /external-refs/{entity_type}/{external_ref}. The reference is shown on the document in the app.

curl -X PUT "$BASE/customers/by-ref/CUST-881" \
  -H "Authorization: Bearer $PAZARCLOUD_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Ali Veli", "kind": "person", "tax_number": "11111111111", "email": "ali@example.com",
        "e_invoice_kind": "e_arsiv",
        "address": { "line1": "Bağdat Cad. 1", "district": "Kadıköy", "city": "İstanbul", "postal_code": "34710", "country": "TR" } }'

Errors

An error is {success:false, error:{code, message, localized_message, details}, request_id}. Branch on error.code; localized_message follows Accept-Language (fa, en, tr, ar, de, ru) and can be shown to a person. Common codes: VALIDATION_ERROR (422), INVALID_API_KEY (401), FORBIDDEN (403, the role lacks a right), FEATURE_NOT_AVAILABLE (403, a module is off), NOT_FOUND (404), EXTERNAL_REF_EXISTS (409), FISCAL_YEAR_CLOSED (409), MISSING_CONTROL_ACCOUNT (409, the books need an account set), RATE_LIMITED (429).

Rate limits

Per key: 120 requests a minute (bursts of 60) and 60 writes a minute; per organisation: 600 requests a minute across its keys. Answers carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; a refusal is 429 RATE_LIMITED with Retry-After (seconds). There is no per-request price.

Webhooks

Register up to five HTTPS endpoints per integration (in the app or with POST /webhook-endpoints) and choose events: sales_invoice.created, sales_invoice.updated, sales_invoice.deleted, einvoice.state_changed, customer.created, customer.updated, product.created, product.updated (also when one of its variants is added, changed or removed), stock.changed, price.changed (plus webhook.test). An integration is told only about records its role may view (sales and products with their view rights, stock with the stock list right, prices with the pricing view right). The signing secret is shown once.

stock.changed is coalesced per item, warehouse and fiscal year: its data carries product_id, variant_id (null for an item without variants), warehouse_id, fiscal_year_id (stock is kept per fiscal year; a change to a year other than the current one, such as an opening balance, names that year) and id (the stock position's own id, stable for that item and warehouse within a fiscal year), and it is sent once the first move is a minute old — further moves of the same item in the same warehouse during that minute raise no further event, so an item and warehouse is announced at most once a minute. Read the current quantity with GET /stock?variant_id=…&warehouse_id=… for a variant, else GET /stock?product_id=…&warehouse_id=…, adding the PazarCloud-Fiscal-Year: <fiscal_year_id> header when the event names a year other than the current one. product.updated likewise is not repeated while one about the same product is still waiting to be sent.

price.changed is per product (its variants included) and says “read this product’s prices again”: it is sent when a pricing rule of the product is created, changed or deleted — also when the rule’s dates lie in the future, so you can schedule a dated sale price in advance — and, from a daily pass, on the first day a rule applies and on the day after its last day (in the organisation’s time zone, the timezone of GET /me; within about an hour after its midnight). Its data carries product_id, reason (rule_changed or schedule), channels (ordinary and/or online), general (true when a rule without a customer, customer type or quantity tier is involved — a storefront showing one price per item may skip false) and, for schedule, day. Like stock.changed it is sent a minute after the first change, and further changes of the same product during that minute are folded into it. Re-read with POST /prices/schedule.

Each delivery is a POST of {id, type, created_at, data} — minimal; read the record through the API for its details — with the headers PazarCloud-Signature: t=<unix>,v1=<hex>, PazarCloud-Event-Id and PazarCloud-Event-Type. The signature is HMAC-SHA256(secret, t + "." + raw body); after a secret rotation the old secret signs too for 24 hours (two v1= values). Answer 2xx within 10 seconds. Delivery is at least once and not ordered: de-duplicate by event id and reject a timestamp more than five minutes off. Failures are retried after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h and 24 h; an endpoint failing for three days is switched off (switch it back on in the app or with PATCH). The delivery log keeps 30 days (GET /webhook-deliveries, POST /webhook-deliveries/{id}/redeliver).

Verifying a signature

import crypto from 'node:crypto'

// rawBody: the request body exactly as received (a Buffer), before any JSON parsing.
export function verify(rawBody, header, secret, toleranceSeconds = 300) {
  const sigs = []
  let t = 0
  for (const p of header.split(',')) {
    const [k, v] = p.trim().split('=')
    if (k === 't') t = Number(v)
    if (k === 'v1') sigs.push(v)
  }
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false
  const want = crypto.createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest('hex')
  return sigs.some((s) => s.length === want.length && crypto.timingSafeEqual(Buffer.from(s), Buffer.from(want)))
}
<?php
function pazarcloud_verify(string $rawBody, string $header, string $secret, int $tolerance = 300): bool {
    $t = 0; $sigs = [];
    foreach (explode(',', $header) as $part) {
        [$k, $v] = array_pad(explode('=', trim($part), 2), 2, '');
        if ($k === 't') { $t = (int) $v; }
        if ($k === 'v1') { $sigs[] = $v; }
    }
    if ($t === 0 || abs(time() - $t) > $tolerance) { return false; }
    $want = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
    foreach ($sigs as $s) { if (hash_equals($want, $s)) { return true; } }
    return false;
}
// $raw = file_get_contents('php://input');
// pazarcloud_verify($raw, $_SERVER['HTTP_PAZARCLOUD_SIGNATURE'] ?? '', getenv('PAZARCLOUD_WEBHOOK_SECRET'));
import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    t, sigs = 0, []
    for part in header.split(","):
        k, _, v = part.strip().partition("=")
        if k == "t":
            t = int(v or 0)
        elif k == "v1":
            sigs.append(v)
    if not t or abs(time.time() - t) > tolerance:
        return False
    want = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(want, s) for s in sigs)
func Verify(rawBody []byte, header, secret string, tolerance time.Duration) bool {
	var t int64
	var sigs []string
	for _, p := range strings.Split(header, ",") {
		k, v, _ := strings.Cut(strings.TrimSpace(p), "=")
		switch k {
		case "t":
			t, _ = strconv.ParseInt(v, 10, 64)
		case "v1":
			sigs = append(sigs, v)
		}
	}
	if t == 0 || time.Since(time.Unix(t, 0)).Abs() > tolerance {
		return false
	}
	m := hmac.New(sha256.New, []byte(secret))
	m.Write([]byte(strconv.FormatInt(t, 10) + "."))
	m.Write(rawBody)
	want := hex.EncodeToString(m.Sum(nil))
	for _, s := range sigs {
		if hmac.Equal([]byte(s), []byte(want)) {
			return true
		}
	}
	return false
}

E-invoicing in Türkiye

With "e_invoice": {"send": true} the sale is committed first and then handed to the organisation’s e-invoice provider (e-Fatura for a buyer registered with GİB, else e-Arşiv; an anonymous buyer is TCKN 11111111111). The answer never waits for GİB: e_invoice.state is queued or sending when the provider took it, and failed with send_error when it was refused before hand-over — the sale is kept; fix the data (e.g. the customer’s address) and call POST /sales-invoices/{id}/e-invoice. Follow the state with GET /sales-invoices/{id}/e-invoice (every 30–60 seconds, or the einvoice.state_changed webhook) until delivered, buyer_accepted or buyer_rejected; download the PDF from …/e-invoice/pdf. A sale made on your website is an e-Arşiv internet sale: send internet_sale with the web address, payment means, payment date and the shipment date and carrier.

Recipe: a travel agency

One sale per ticket or booking, the ticket number as external_ref, the PNR as reference_number, passenger and route in notes. The default treatment here is that the full ticket or room amount is the agency’s own sale — one revenue line at the KDV rate and exemption code your accountant (mali müşavir) confirms (typical readings: international flight exempt under KDVK 14/1, code 311; domestic flight 20%; accommodation 10%; a separate service fee 20%). An agency that presents tickets as an intermediary uses services whose revenue account is a payable and a fee line — the same endpoint, different services. Confirm the codes with your accountant; this is not tax advice.

curl -X POST "$BASE/sales-invoices" \
  -H "Authorization: Bearer $PAZARCLOUD_KEY" \
  -H "Idempotency-Key: 6f1c2b0e-3a77-4c5e-9a43-0f3b1c2d4e5f" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "TK-2351234567890",
    "invoice_date": "2026-11-12",
    "customer": { "external_ref": "CUST-881" },
    "reference_number": "PNR ABC123",
    "notes": "IST-FRA 2026-12-01, Ali Veli",
    "lines": [
      { "service_id": "<Uçak bileti service>", "description": "TK1593 IST-FRA",
        "quantity": "1", "unit_price": "8450.00", "tax_type_id": "<the KDV your accountant confirms>" },
      { "service_id": "<Hizmet bedeli service>", "description": "Service fee",
        "quantity": "1", "unit_price": "350.00", "tax_type_id": "<KDV 20%>" }
    ],
    "settlement": { "tenders": [ { "payment_method_id": "<card>", "fund_id": "<bank account>", "amount": "8870.00" } ] },
    "e_invoice": { "send": true,
      "internet_sale": { "web_address": "https://agency.example", "payment_method": "KREDIKARTI/BANKAKARTI",
                         "payment_date": "2026-11-12", "shipment_date": "2026-11-12",
                         "carrier_tax_id": "<VKN>", "carrier_name": "Electronic delivery" } }
  }'

WooCommerce plugin

The PazarCloud plugin connects a WooCommerce shop to a PazarCloud organisation: shop orders become sales orders and sales in PazarCloud, and what the merchant records in PazarCloud (payments, shipments, cancellations) reaches the shop. It needs WordPress 6.4 or later, WooCommerce 8.0 or later and PHP 7.4 or later; the organisation needs the Online sales and Developer API modules.

Download the plugin 0.1.1 (.zip)

  1. Download the zip above. Do not unpack it.
  2. In WordPress open Plugins › Add New Plugin › Upload Plugin, choose the zip, then Install Now and Activate.
  3. In PazarCloud open Administration › WooCommerce connection, connect the shop and copy its key — it is shown once.
  4. On the WordPress server connect the plugin with WP-CLI; the key is read from standard input, so it never stays in the shell history:
wp pazarcloud connect --base-url=https://app.pazarcloud.ir/api/public/v1
wp pazarcloud status

Then map the shop’s payment gateways, shipping methods and fees on the connection page in PazarCloud; an order waiting for a mapping is listed there under Needs attention. A newer version installs the same way (WordPress offers to replace the installed one).

WooCommerce notes

API reference

Generated from the API’s own route table — download the full OpenAPI 3.1 document for request and response schemas, or import it into Postman or Insomnia — or start from the ready Postman collection (one request per endpoint; set its base_url and api_key variables). Base URL: https://app.pazarcloud.ir/api/public/v1.

Account

MethodPathWhat it does
GET/meWho the key acts as and what it may do

Customers

MethodPathWhat it does
GET/customersList customers (stable order for sync)
Requires the integration's role to hold: definitions.ofa_customer.list.
GET/customers/{id}Get a customer
Requires the integration's role to hold: definitions.ofa_customer.view.
PUT/customers/by-ref/{external_ref}Create or update a customer by this integration's reference
Requires the integration's role to hold: definitions.ofa_customer.create, definitions.ofa_customer.edit.

Suppliers

MethodPathWhat it does
GET/suppliersList suppliers (stable order for sync)
Requires the integration's role to hold: definitions.ofa_supplier.list.
GET/suppliers/{id}Get a supplier
Requires the integration's role to hold: definitions.ofa_supplier.view.
PUT/suppliers/by-ref/{external_ref}Create or update a supplier by this integration's reference
Requires the integration's role to hold: definitions.ofa_supplier.create, definitions.ofa_supplier.edit.

Lookups

MethodPathWhat it does
GET/fundsList the cash boxes and bank accounts a tender may name (fund_id)
GET/payment-methodsList payment methods
Requires the integration's role to hold: definitions.payment_methods.list.
GET/servicesList services
Requires the integration's role to hold: definitions.services.list.
GET/tax-typesList tax types
Requires the integration's role to hold: definitions.tax_types.list.
GET/titlesList the income / expense titles a slip line names (title_id), of the kinds the role may list
GET/unitsList units
Requires the integration's role to hold: definitions.units.list.
GET/warehousesList warehouses
Requires the integration's role to hold: definitions.warehouses.list.

Products

MethodPathWhat it does
POST/prices/quotePrice lines by the pricing rules (channel ordinary or online)
Requires the integration's role to hold: sales.pricing.view.
POST/prices/scheduleGeneral price timeline per item: today's price and dated changes (no customer, quantity 1)
Requires the integration's role to hold: sales.pricing.view.
GET/productsList products (with updated_since: the changed ones, stable order for sync)
Requires the integration's role to hold: definitions.products.list.
GET/products/{id}Get a product with its variants
Requires the integration's role to hold: definitions.products.view.
GET/stockCurrent stock per item and warehouse
Requires the integration's role to hold: sales.current_stock.list. Needs the organisation's inventory module.
GET/storefront-groupsOnline-store groups with their products (what a shop sells and its categories)
Requires the integration's role to hold: settings.storefront_groups.list. Needs the organisation's ecommerce module.

Sales invoices

MethodPathWhat it does
GET/sales-invoicesList the sales of the fiscal year (stable order for sync), or find one by this integration's reference
Requires the integration's role to hold: sales.invoices.list. Needs the organisation's sales module.
POST/sales-invoicesCreate a sale (optionally send its e-invoice)
Requires the integration's role to hold: sales.invoices.create. Needs the organisation's sales module.
GET/sales-invoices/{id}Get a sale
Requires the integration's role to hold: sales.invoices.view. Needs the organisation's sales module.
POST/sales-invoices/{id}/share-linkThe sale's live share link (the invoice page, 30 days; minted when none is live, else the same link)
Requires the integration's role to hold: sales.invoices.view. Needs the organisation's sales module.
POST/sales-invoices/previewTotals of a would-be sale or sales order (nothing is written, no number is taken)
Requires the integration's role to hold: sales.invoices.create. Needs the organisation's sales module.

E-invoices (Türkiye)

MethodPathWhat it does
GET/sales-invoices/{id}/e-invoiceThe sale's e-invoice state
Requires the integration's role to hold: tr_tax.documents.view. Needs the organisation's e_invoice module.
POST/sales-invoices/{id}/e-invoiceSend (or re-send) the sale's e-invoice
Requires the integration's role to hold: tr_tax.documents.send, tr_tax.documents.edit. Needs the organisation's e_invoice module.
GET/sales-invoices/{id}/e-invoice/pdfThe e-invoice PDF (once handed over to GİB)
Requires the integration's role to hold: tr_tax.documents.view. Needs the organisation's e_invoice module.

Sales returns

MethodPathWhat it does
GET/sales-returns/{id}Get a sales return (lines with the sale lines they return; refunds only with treasury.payments.list and treasury.payments.view, else [])
Requires the integration's role to hold: sales.invoices.view. Needs the organisation's sales module.

Payments

MethodPathWhat it does
GET/paymentsList the receipts and payments of the fiscal year (stable order for sync), or find one by this integration's reference
Requires the integration's role to hold: treasury.payments.list.
POST/paymentsRecord a stand-alone receipt or payment (cash, transfer or card rows; held for a second signature above the threshold)
Requires the integration's role to hold: treasury.payments.create.
DELETE/payments/{id}Delete a receipt or payment (its entry and references go with it)
Requires the integration's role to hold: treasury.payments.delete.
GET/payments/{id}Get a receipt or payment (lines: method, fund, amount; the document it was recorded for)
Requires the integration's role to hold: treasury.payments.view.

Purchase invoices

MethodPathWhat it does
GET/purchase-invoicesList the purchases of the fiscal year (stable order for sync), or find one by this integration's reference
Requires the integration's role to hold: purchases.invoices.list.
POST/purchase-invoicesRecord a purchase (posted with its entry in the same transaction)
Requires the integration's role to hold: purchases.invoices.create.
DELETE/purchase-invoices/{id}Delete a purchase (its stock, entry and references go with it)
Requires the integration's role to hold: purchases.invoices.delete.
GET/purchase-invoices/{id}Get a purchase
Requires the integration's role to hold: purchases.invoices.view.

Income and expense slips

MethodPathWhat it does
GET/expense-slipsList the expense slips of the fiscal year, or find one by this integration's reference
Requires the integration's role to hold: treasury.expense_slips.list.
POST/expense-slipsRecord an expense slip (lines on expense titles, taxes by tax type; held for a second signature above the threshold when paid from funds)
Requires the integration's role to hold: treasury.expense_slips.create.
DELETE/expense-slips/{id}Delete an expense slip (its entry and references go with it; linked payments stay)
Requires the integration's role to hold: treasury.expense_slips.delete.
GET/expense-slips/{id}Get an expense slip
Requires the integration's role to hold: treasury.expense_slips.view.
GET/income-slipsList the income slips of the fiscal year, or find one by this integration's reference
Requires the integration's role to hold: treasury.income_slips.list.
POST/income-slipsRecord an income slip (lines on income titles; no taxes)
Requires the integration's role to hold: treasury.income_slips.create.
DELETE/income-slips/{id}Delete an income slip (its entry and references go with it; linked payments stay)
Requires the integration's role to hold: treasury.income_slips.delete.
GET/income-slips/{id}Get an income slip
Requires the integration's role to hold: treasury.income_slips.view.

Sales orders

MethodPathWhat it does
GET/sales-ordersFind the sales order of this integration's reference
Requires the integration's role to hold: sales.invoices.view. Needs the organisation's sales module.
POST/sales-ordersCreate a reserving sales order (a shop order placed; customer by this integration's reference)
Requires the integration's role to hold: sales.invoices.create. Needs the organisation's sales module.
GET/sales-orders/{id}Get a sales order (invoiced and remaining per line, the sales made from it)
Requires the integration's role to hold: sales.invoices.view. Needs the organisation's sales module.
POST/sales-orders/{id}/cancelCancel a sales order with nothing invoiced (a shop order abandoned); idempotent
Requires the integration's role to hold: sales.invoices.edit. Needs the organisation's sales module.
POST/sales-orders/{id}/invoiceInvoice the sales order (a shop order paid): a sale of every remaining line at the order's prices
Requires the integration's role to hold: sales.invoices.create. Needs the organisation's sales module.
POST/sales-orders/by-ref/{external_ref}/invoiceInvoice the sales order of this integration's reference
Requires the integration's role to hold: sales.invoices.create. Needs the organisation's sales module.

External references

MethodPathWhat it does
GET/external-refsFind the record of a reference
DELETE/external-refs/{entity_type}/{external_ref}Unpair a reference (the record stays)
PUT/external-refs/{entity_type}/{external_ref}Pair an existing record with a reference

Webhooks

MethodPathWhat it does
GET/webhook-deliveriesDelivery log (30 days)
POST/webhook-deliveries/{id}/redeliverDeliver again
GET/webhook-endpointsThis integration's webhook endpoints
POST/webhook-endpointsRegister an endpoint (the signing secret is shown once)
DELETE/webhook-endpoints/{id}Remove an endpoint
PATCH/webhook-endpoints/{id}Change an endpoint
POST/webhook-endpoints/{id}/rotate-secretNew signing secret (the previous one stays valid 24 h)
POST/webhook-endpoints/{id}/testSend a webhook.test event

WooCommerce connector

MethodPathWhat it does
DELETE/connector/issues/{key}Clear an issue once its action succeeded
Needs the organisation's ecommerce module.
PUT/connector/issues/{key}Report a refused or failed shop action (needs attention); params never hold shopper personal data
Needs the organisation's ecommerce module.
PUT/connector/remote-itemsReport shop products / variations that matched nothing (one batch, up to 500), and remove the ones no longer unmatched
Needs the organisation's ecommerce module.
GET/connector/settingsThe connection's settings the merchant keeps in the app (warehouses, buffer, rounding, gateway and service mappings)
Needs the organisation's ecommerce module.
PUT/connector/siteReport the connected shop (versions, time zone, currency, gateways, shipping methods, fees); mappings keep their targets
Needs the organisation's ecommerce module.