MyVoipCRM External API
X-Api-Key access to customers, products, categories, orders (stages 0–8), quotes (review 0–2), sales, shipments, WhatsApp templates and the single-request POST /orders/complete integration.
# MyVoipCRM External API
REST API documentation for external systems to work securely with customers, products/services, orders, quotes, sales, shipments and WhatsApp templates on MyVoipCRM.
## Contents
1. [Purpose and basic flow](#purpose)
2. [Authentication](#authentication)
3. [Endpoint summary](#endpoints)
4. [Enum reference](#enum-reference)
5. [Product / Service Category API](#product--service-category-api-service-and-product-categories)
6. [Product / Service API](#product--service-api-service-and-products)
7. [Order API](#order-api-orders)
8. [Order Complete API (`/orders/complete`)](#order-complete-api-orderscomplete)
9. [Quote API](#quote-api-biddings)
10. [Sales API](#sales-api-sales)
11. [WhatsApp API](#whatsapp-api)
12. [Shipment API](#shipment-api-shipments)
13. [Commercial module HTTP codes](#commercial-module-http-codes)
14. [Response format](#response-format)
15. [HTTP codes (all modules)](#http-response-codes-standard)
16. [cURL examples](#usage-example-curl)
17. [Security and configuration](#security-and-operations-notes)
## Purpose
- Give external systems controlled access
- Isolate data per company
- Offer secure use through an API key and admin verification
## Basic Flow
1. The external application obtains an API key with an admin username/password.
2. The external application sends that key in the `X-Api-Key` header.
3. The API performs operations within the company scope of that key (customer, product/service, order, quote, sale, WhatsApp template).
### Commercial integration flow (recommended order)
| Step | Endpoint | Purpose |
|------|----------|---------|
| 1 | `POST .../auth/company-api-key` | Get an API key |
| 2 | `GET .../service-and-products` | `serviceAndProductId` plus price/VAT information |
| 3 | `GET .../customers` | `customerId` |
| 4 | `POST .../orders`, `POST .../biddings` or `POST .../sales` | Create the record |
| 5 | `GET/PUT/DELETE` | Follow-up and updates |
### An order in a single request (marketplace / production — recommended)
When the customer, product and category records do not already exist in the CRM, an order can be opened in one call without the separate endpoints:
| Step | Endpoint | Purpose |
|------|----------|---------|
| 1 | `POST .../auth/company-api-key` | Get an API key |
| 2 | `POST .../orders/complete` | Customer + product + category + order in one go |
Step-by-step guide and a Sahibinden example: corporate site **Developer centre** → **Order Complete Integration Guide** (`/en/developers/order-complete-integration`).
### Lead pool
`POST .../campaign-leads` — Details: `/en/developers/lead-pool-integration-en` · PDF: `Docs/lead-pool-integration-en.pdf`
### WhatsApp integration flow (recommended order)
| Step | Endpoint | Purpose |
|------|----------|---------|
| 1 | `GET .../whatsapp/accounts` | Pick the sending line (`whatsappPhoneNumber` → `account`) |
| 2 | `GET .../whatsapp/templates?account=...` | Template list (`metaTemplateId`, `title`, `variableLabels`) |
| 3 | `POST .../whatsapp/templates/send` | Send a template message to the recipient |
## Authentication
### 1) Getting an API key (admin login)
- Endpoint: `POST /api/external/v1/auth/company-api-key`
- Body:
```json
{
"userName": "[email protected]",
"password": "123456"
}
```
A successful example:
```json
{
"success": true,
"message": "API anahtarı getirildi.",
"data": {
"companyName": "ABC Ltd. Şti.",
"apiKey": "crm_xxxxx"
}
}
```
### 2) Customer operations with the API key
- Required header: `X-Api-Key: <crm-api-key>`
- A valid company API key is verified on every request.
## Endpoints
### Auth
- `POST /api/external/v1/auth/company-api-key`
- Verifies the admin username/password and returns the company API key.
### Customers
- `GET /api/external/v1/customers?page=1&pageSize=20`
- Returns a paged customer list.
- `GET /api/external/v1/customers/{id}`
- Returns the customer detail.
- `POST /api/external/v1/customers`
- Creates a new customer.
- `PUT /api/external/v1/customers/{id}`
- Fully updates an existing customer (all required fields must be sent).
- `PATCH /api/external/v1/customers/{id}`
- Partial update; only the fields sent are changed.
- `DELETE /api/external/v1/customers/{id}`
- Deletes the customer (it disappears from the lists).
### Campaign leads (lead pool)
`POST /api/external/v1/campaign-leads` — Adds a record to the lead pool. Sending the same `externalId` again updates the existing record (`wasUpdated: true`).
**Headers:** `X-Api-Key`, `Content-Type: application/json`
**Request**
```json
{
"fullName": "Ahmet Yılmaz",
"phoneNumber1": "5321234567",
"dialCode1": "+90",
"countryCode1": "tr",
"email": "[email protected]",
"leadSource": "Web form",
"externalId": "form-8842",
"leadPriority": 2,
"tags": ["hot"],
"commercialDescription": "Requested a demo",
"expectedRevenue": 1500
}
```
| Field | Required | Note |
|-------|----------|------|
| `fullName` | Yes | |
| `phoneNumber1` | No | Invalid/missing → `leadPoolStatus: 1` |
| `dialCode1`, `countryCode1` | No | Default `+90` / `tr` |
| `email`, `leadSource`, `externalId` | No | |
| `leadPriority` | No | 1 low, 2 medium, 3 high |
| `tags`, `commercialDescription`, `expectedRevenue` | No | |
**Notes**
- `externalId`: POST again → update (`wasUpdated: true`). Send a unique ID from your forms.
- The phone is optional; invalid/missing → `leadPoolStatus: 1` (the number is still written to the `phone` field).
- Valid TR: `5321234567` + `+90` → `905321234567`. An invalid example: `90555555`.
- With a valid phone, a contact (Customer) is looked up by phone (primary or secondary), then by email; if none is found, one is created (`customerId`). The name is not used for matching.
- Duplicates: the same name+phone+email within 5 minutes → `leadPoolStatus: 2` (except for an `externalId` update).
**Response (HTTP 200)**
```json
{
"success": true,
"message": "Lead added to pool successfully.",
"data": {
"id": 12045,
"fullName": "Ahmet Yılmaz",
"phone": "905321234567",
"externalId": "form-8842",
"wasUpdated": false,
"leadPoolStatus": 0,
"leadPoolStatusDisplay": "Geçerli",
"isValidLead": true
}
}
```
| Field | Description |
|-------|-------------|
| `id` | Lead ID |
| `phone` | The stored phone |
| `wasUpdated` | `true` → updated via `externalId` |
| `leadPoolStatus` | `0` valid · `1` invalid phone · `2` duplicate (5 min) |
| `isValidLead` | Whether the lead is valid |
| `customerId` | The contact linked when the phone is valid (may be `null`) |
`leadPoolStatus`: `0` valid · `1` invalid phone · `2` duplicate repeat (same name+phone+email within 5 minutes)
**HTTP codes**
| Code | Meaning |
|------|---------|
| `200` | Success |
| `400` | Validation error |
| `401` | Invalid API key |
| `403` | IP not permitted |
| `409` | `externalId` conflict |
| `429` | Rate limit |
| `500` | Server error |
**Error codes (`code`)**
| Code | HTTP | Description |
|------|------|-------------|
| `FULL_NAME_REQUIRED` | 400 | `fullName` missing |
| `VALIDATION_FAILED` | 400 | Field validation error (length, tag, priority and so on) |
| `INVALID_API_KEY` | 401 | `X-Api-Key` invalid |
| `IP_NOT_ALLOWED` | 403 | Not on the allowed-IP list |
| `EXTERNAL_ID_CONFLICT` | 409 | `externalId` uniqueness conflict |
| `RATE_LIMIT_EXCEEDED` | 429 | Too many requests |
| `UNEXPECTED_ERROR` | 500 | Unexpected error |
Detailed guide: `/en/developers/lead-pool-integration-en` · PDF: `Docs/lead-pool-integration-en.pdf`
### Support tickets
`POST /api/external/v1/support-tickets` — Opens a support ticket. The ticket uses the company's **default workflow and stage**, gets the company's ticket number (`caseNumber`) and triggers "ticket created" automations (the CRM AI assistant and the PBX voice assistant use the same rules).
**Header:** `X-Api-Key`, `Content-Type: application/json`
**Request**
```json
{
"title": "Wrong amount on invoice",
"description": "The November invoice shows a double charge.",
"priority": "high",
"source": "phone",
"customerName": "Ahmet Yılmaz",
"phone": "905321234567",
"email": "[email protected]"
}
```
| Field | Required | Note |
|-------|----------|------|
| `title` | Yes | 3–200 characters |
| `description` | Yes | 3–4000 characters; becomes the ticket's first message |
| `priority` | No | `low` \| `medium` \| `high` (default `medium`) |
| `source` | No | `phone` \| `email` \| `whatsapp` \| `webchat` \| `other` (default `other` = "Staff") |
| `customerId` | No | Known CRM customer id |
| `customerName` | No | If no customer is found, a new customer is created with this name |
| `phone` | No | Max 30 characters; customer is matched on the last 10 digits |
| `email` | No | Valid e-mail; used for matching when the phone does not match |
**Notes**
- Customer resolution: `customerId` → phone (last 10 digits) → e-mail. If nothing matches and **a name plus phone/e-mail** is given, a new customer is created; otherwise the ticket is opened without a customer (phone/e-mail are kept on the ticket).
- Every request opens a new ticket (no duplicate protection); do not resend the same issue.
**Response (HTTP 200)**
```json
{ "success": true, "message": "Support ticket created successfully.", "code": null, "data": { "id": 5012, "caseNumber": "1042", "customerId": 3451 } }
```
| Field | Description |
|-------|-------------|
| `id` | Ticket id |
| `caseNumber` | Company ticket number (the number to give the customer) |
| `customerId` | Linked / created customer; `null` if none |
**HTTP codes**
| Code | Meaning |
|------|---------|
| `200` | Ticket created |
| `400` | Validation error (`VALIDATION_FAILED`: required field, `priority`/`source` value) |
| `401` | Invalid API key (`INVALID_API_KEY`) |
| `403` | IP not allowed (`IP_NOT_ALLOWED`) |
| `429` | Rate limit (`RATE_LIMIT_EXCEEDED`) |
| `500` | Server error (`UNEXPECTED_ERROR`) |
---
`GET /api/external/v1/support-tickets` — Paginated ticket list (read-only).
**Header:** `X-Api-Key`
| Query | Default | Note |
|-------|---------|------|
| `page` | `1` | 1-based |
| `pageSize` | `20` | Max `100`; larger values are clamped |
| `status` | — | `new` \| `in_progress` \| `being_reviewed` \| `waiting_response` \| `closed` \| `cancelled` |
| `priority` | — | `low` \| `medium` \| `high` |
| `source` | — | `phone` \| `email` \| `whatsapp` \| `webchat` \| `other` |
| `categoryId`, `departmentId`, `customerId`, `workflowStageId` | — | Numeric id filters |
| `createdFrom`, `createdTo` | — | ISO 8601; compared in UTC |
**Ordering is by ticket `id`, newest first.** This is deliberate: `createdAt` moves forward when a new call is attached to an open ticket, so paging on it would skip rows. `id` never changes, so page 1 → page N stays consistent.
**Response (HTTP 200)**
```json
{
"success": true,
"data": {
"items": [
{
"id": 5012,
"caseNumber": "1042",
"title": "Wrong amount on invoice",
"status": "new",
"priority": "high",
"source": "phone",
"createdAt": "2026-11-13T07:21:04Z",
"dueDate": null,
"customerId": 3451,
"customerName": "Ahmet Yılmaz",
"customerPhone": "905321234567",
"customerEmail": "[email protected]",
"customerFirmId": 88,
"customerFirmName": "Yılmaz Tekstil A.Ş.",
"customerBranchId": 14,
"customerBranchName": "Head office",
"categoryId": 12,
"categoryName": "Billing",
"departmentId": 4,
"departmentName": "Accounting",
"agentId": "a1b2…",
"agentName": "Mehmet Demir",
"workflowProcessId": 2,
"workflowProcessName": "Support process",
"workflowStageId": 7,
"workflowStageName": "Offer",
"externalCallNumber": "902127001788"
}
],
"currentPage": 1,
"totalPages": 42,
"totalCount": 8312,
"pageSize": 20
}
}
```
Enum fields are returned as text, matching the values `POST` accepts.
**Name fields (added 2026-11-19).** Category, department and the contact's firm/branch **names**
are returned as well, so a report does not have to carry ids. Names are resolved with one batched
query per page, so they add no per-row cost.
| Field | Description |
|-------|-------------|
| `categoryName` | Category name (`null` when `categoryId` is empty) |
| `departmentName` | Department name |
| `customerFirmId`, `customerFirmName` | Firm of the ticket's **contact** |
| `customerBranchId`, `customerBranchName` | Branch of that contact |
Firm and branch are **not stored on the ticket**; they come from the contact. When no contact is
linked, all four are `null`. For deleted ids, or ids belonging to another company, the name stays
`null` while the id is still returned.
---
`GET /api/external/v1/support-tickets/{id}` — Ticket detail with history.
Returns every list field plus:
| Field | Description |
|-------|-------------|
| `description` | Opening message |
| `productOrServiceName` | Linked product / service |
| `callbackAt` | Scheduled call-back time |
| `modifiedAt` | Last modification |
| `closedAtUtc` | When the ticket was last closed (UTC) — see the note below |
| `closedByUserId`, `closedByUserName` | Agent who closed it |
| `conversations[]` | Messages and call records, oldest first: `id`, `createdAt`, `isInbound`, `isInternalNote`, `message`, `authorType`, `authorName`, `createdByUserId`, `createdByUserName`, `callUuid` |
| `stageHistory[]` | Workflow stage transitions, oldest first: `workflowStageId`, `workflowStageName`, `startedAtUtc`, `endedAtUtc`, `changedByUserId`, `changedByUserName` |
| `statusHistory[]` | Status changes, oldest first: `changedAtUtc`, `fromStatus`, `toStatus`, `changedByUserId`, `changedByUserName` |
`isInbound: true` means the message came from the customer. `isInternalNote: true` marks a note that is not shown to the customer.
**Who wrote the record (added 2026-11-19)**
| Field | Description |
|-------|-------------|
| `authorType` | `staff` \| `customer` \| `system` (automatic reply / notification) |
| `authorName` | Display name of the author — one field for both staff and customer |
| `createdByUserId` / `createdByUserName` | CRM user only; empty on a customer record |
`authorName` covers both sides in a single field: a "who wrote it" report column does not have to
branch on `authorType`.
- `staff` → `authorName` is the agent's name and `createdByUserId` is set.
- `customer` → `authorName` is the ticket contact's name; when no contact is linked, the ticket's
email address, or its phone number. `createdByUserId` is **empty** — no CRM user wrote an
inbound record, and that is not missing data.
- `system` → `authorName` is empty. An outbound record with no user (automatic reply, notification).
The customer's name is not stored on the message itself; it comes from the ticket's contact, so
changing the contact later also changes the name shown on older records.
**Status history and close information (added 2026-11-19)**
```json
{
"closedAtUtc": "2026-11-19T14:08:33Z",
"closedByUserName": "Mehmet Demir",
"statusHistory": [
{
"changedAtUtc": "2026-11-18T09:12:40Z",
"fromStatus": "new",
"toStatus": "in_progress",
"changedByUserId": null,
"changedByUserName": null
},
{
"changedAtUtc": "2026-11-19T14:08:33Z",
"fromStatus": "in_progress",
"toStatus": "closed",
"changedByUserId": "a1b2…",
"changedByUserName": "Mehmet Demir"
}
]
}
```
`fromStatus` and `toStatus` use the **same** value set as the list's `status` filter.
`changedByUser*` is empty for automatic paths (inbound email, PBX call event, automation rule):
no user performs the change there.
**IMPORTANT — tickets before 2026-11-19.** Status changes were not recorded anywhere before that
date and cannot be reconstructed. For those tickets `statusHistory` is an **empty array** and
`closedAtUtc` / `closedByUser*` are **`null`**, even when the ticket is closed. An empty list does
**not** mean the status never changed; an estimated close time is deliberately not returned. The
ticket's current status is always in the `status` field.
`closedAtUtc` is filled only while the ticket **is** closed; on a reopened ticket it becomes `null`
and the earlier close stays in `statusHistory`.
**HTTP codes (both GET endpoints)**
| Code | Meaning |
|------|---------|
| `200` | OK |
| `400` | Invalid pagination (`INVALID_PAGINATION`) or filter value (`VALIDATION_FAILED`) |
| `401` | Invalid API key (`INVALID_API_KEY`) |
| `403` | IP not allowed (`IP_NOT_ALLOWED`) |
| `404` | Ticket not found or belongs to another company (`RECORD_NOT_FOUND`) |
| `500` | Server error (`UNEXPECTED_ERROR`) |
### Customer fields (supported)
**`POST` / `PUT` / `PATCH` request body** (with PATCH only the fields sent are updated):
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `fullName` | string | Yes (POST/PUT) | Full name |
| `phoneNumber1` | string | Yes (POST/PUT) | Primary phone (can be sent without a country code; it is joined with `dialCode1`) |
| `dialCode1` | string | No | Default `+90` |
| `countryCode1` | string | No | Default `tr` |
| `phoneNumber2`, `dialCode2`, `countryCode2` | string? | No | Secondary phone |
| `whatsappNumber`, `dialCodeWhatsapp`, `countryCodeWhatsapp` | string? | No | WhatsApp |
| `fax`, `email`, `tckn` | string? | No | |
| `country`, `city`, `district`, `neighborhood`, `street`, `address`, `postalCode` | string? | No | Address |
| `department` | string? | No | |
| `birthDate` | date (`YYYY-MM-DD`) | No | |
| `gender` | int | No | `0` Male, `1` Female, `2` Other |
| `status` | int | No | `0` Active, `1` Passive, `2` BlackList (default Active) |
| `priority` | int | No | `1`–`5` (default Medium) |
| `description` | string? | No | In POST/PUT/PATCH and the detail response |
**`GET /customers` list (`items[]`)** — only the fields below are returned (`description` is **not** in the list response):
`id`, `fullName`, `phoneNumber1`, `dialCode1`, `countryCode1`, `phoneNumber2`, `dialCode2`, `countryCode2`, `whatsappNumber`, `dialCodeWhatsapp`, `countryCodeWhatsapp`, `fax`, `email`, `tckn`, `country`, `city`, `district`, `neighborhood`, `street`, `address`, `postalCode`, `department`, `birthDate`, `gender`, `status`, `priority`
**`GET /customers/{id}` detail** — the list fields plus `description`
### WhatsApp
- `GET /api/external/v1/whatsapp/accounts` — lists the WhatsApp lines
- `GET /api/external/v1/whatsapp/templates` — lists the Meta templates (filter by line with `account`)
- `POST /api/external/v1/whatsapp/templates/send` — sends a template message
Detailed fields, variable mapping and examples: [WhatsApp API](#whatsapp-api).
---
## Enum reference
Requests and responses mostly use **numeric codes**. The values below are the ones valid for the API contract (internal system names are not documented).
### Order and sale — record type
The External API creates and lists only **order** and **sale** records:
| Record | Endpoint |
|--------|----------|
| Order | `POST/GET .../orders` |
| Quote | `POST/GET .../biddings` |
| Sale | `POST/GET .../sales` |
### `status` — order stage (`/orders`)
On order records the `status` field represents the **order stage** (the fulfilment pipeline). It is the same value set as the **Orders** module in the CRM interface.
| Value | Description |
|------:|-------------|
| `0` | New order (default; when `status` is not sent) |
| `1` | Awaiting approval |
| `2` | Approved |
| `3` | Being prepared |
| `4` | Ready to ship |
| `5` | Shipped |
| `6` | Delivered |
| `7` | Completed |
| `8` | Cancelled |
Responses also return `statusDisplayName` (e.g. `"Hazırlanıyor"`).
**To update only the stage:** `PATCH /orders/{id}/status` — body: `{ "status": 3 }` (lines and other fields are unchanged).
### `status` — quote review state (`/biddings`)
On quote records the `status` field is the **review / approval** state (the same as the CRM quote module):
| Value | Description |
|------:|-------------|
| `0` | Awaiting a reply (default; when `status` is not sent) |
| `1` | Accepted |
| `2` | Rejected |
Responses return `statusDisplayName`. **To update only the review state:** `PATCH /biddings/{id}/status` — body: `{ "status": 1 }`.
### `paymentStatus` (order / quote / sale)
| Value | Description |
|------:|-------------|
| `0` | Collected |
| `1` | To be collected |
| `2` | Partially collected |
> The External API does not create collections or cash movements; `paymentStatus` is only an informational field on the record.
### `taxRate` (product and line)
Accepted VAT percentages: `0`, `1`, `8`, `10`, `18`, `20`. When creating a line, `lines[].taxRate` must be consistent with the product.
### Price currency (`salePriceExceptTaxCurrencyType` and similar)
| Value | Unit |
|------:|------|
| `0` | TRY (₺) |
| `1` | USD ($) |
| `2` | EUR (€) |
| `3` | GBP (£) |
### `unitOfMeasurement` (line / product)
A numeric unit code. Common values:
| Value | Unit |
|------:|------|
| `0` | Piece |
| `8` | Gram |
| `9` | Day |
| `13` | Case |
| `14` | Litre |
| `21` | Hour |
| `25` | Kilogram |
| `26` | Metre |
The full list (0–33): `Piece`, `Month`, `Pair`, `Sack`, `Minute`, `Decimetre`, `Decilitre`, `Net`, `Gram`, `Day`, `Week`, `Truck`, `Kilometre`, `Case`, `Litre`, `Cubic metre`, `Milligram`, `Millimetre`, `Package`, `Pallet`, `Bag`, `Hour`, `Crate`, `Second`, `Year`, `Kilogram`, `Metre`, `Square metre`, `Box`, `Roll`, `Dozen`, `Set`, `Tonne`, `Millilitre`.
### `stockTrackingForServiceAndProduct` (product)
| Value | Description |
|------:|-------------|
| `0` | Accounting stock tracking on |
| `1` | Off |
### Customer — `gender`, `status`, `priority`
**`gender`**
| Value | Description |
|------:|-------------|
| `0` | Male |
| `1` | Female |
| `2` | Other |
**`status`**
| Value | Description |
|------:|-------------|
| `0` | Active |
| `1` | Passive |
| `2` | Blacklist |
**`priority`**
| Value | Description |
|------:|-------------|
| `1` | Very low |
| `2` | Low |
| `3` | Medium |
| `4` | High |
| `5` | Very high |
---
## Product / Service Category API (`/service-and-product-categories`)
Used to manage the categories of products/services. Every record is isolated **within the scope of the signed-in company**.
**Base URL example:** `https://externalapi.myvoipcrm.com/api/external/v1/service-and-product-categories`
**Required header:** `X-Api-Key: <crm-api-key>`
### Endpoint summary
| Method | URL | Description |
|--------|-----|-------------|
| `GET` | `/service-and-product-categories` | Paged list |
| `GET` | `/service-and-product-categories/{id}` | Single record detail |
| `POST` | `/service-and-product-categories` | New category |
| `PUT` | `/service-and-product-categories/{id}` | Update a category |
| `DELETE` | `/service-and-product-categories/{id}` | Delete |
### `GET /service-and-product-categories` — List
**Query parameters**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `page` | int | `1` | Page number (≥ 1) |
| `pageSize` | int | `20` | Page size (≥ 1, max **100**) |
| `search` | string | — | Searches the `title` and `description` fields |
**Successful response (`data`)**
| Field | Type | Description |
|-------|------|-------------|
| `items` | array | Category list |
| `currentPage` | int | Current page |
| `pageSize` | int | Page size |
| `totalCount` | int | Total records |
| `totalPages` | int | Total pages |
**`items[]` fields**
| Field | Type | Description |
|-------|------|-------------|
| `id` | int | Category ID |
| `title` | string | Category title |
| `description` | string? | Description |
| `externalId` | string? | External system category ID |
### `POST /service-and-product-categories` — Create
**Content-Type:** `application/json`
```http
POST /api/external/v1/service-and-product-categories
X-Api-Key: crm_xxxxx
Content-Type: application/json
```
**Example body**
```json
{
"title": "Electronics",
"description": "Laptops, phones and so on",
"externalId": "shopify-cat-electronics"
}
```
> `DELETE` is blocked when the category still has active products/services attached.
## Product / Service API (`/service-and-products`)
The `serviceAndProductId` values used on order and sale lines come from these endpoints.
**Base URL example:** `https://externalapi.myvoipcrm.com/api/external/v1/service-and-products`
**Required header:** `X-Api-Key: <crm-api-key>`
### Endpoint summary
| Method | URL | Description |
|--------|-----|-------------|
| `GET` | `/service-and-products` | Paged list |
| `GET` | `/service-and-products/{id}` | Single record detail |
| `POST` | `/service-and-products` | New product/service |
| `PUT` | `/service-and-products/{id}` | Update a product/service |
| `DELETE` | `/service-and-products/{id}` | Delete |
### `GET /service-and-products` — List
**Query parameters**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `page` | int | `1` | Page number (≥ 1) |
| `pageSize` | int | `20` | Page size (≥ 1, max **100**) |
| `search` | string | — | Searches the `name`, `stockCode`, `barcodeNumber` and `externalId` fields (case-insensitive) |
| `categoryId` | int | — | Category ID filter |
**Successful response (`data`)**
| Field | Type | Description |
|-------|------|-------------|
| `items` | array | Product list |
| `currentPage` | int | Current page |
| `pageSize` | int | Page size |
| `totalCount` | int | Total records |
| `totalPages` | int | Total pages |
**`items[]` fields**
| Field | Type | Description |
|-------|------|-------------|
| `id` | int | **Use this for `lines[].serviceAndProductId`** |
| `name` | string | Product/service name |
| `serviceAndProductCategoryId` | int | Category ID |
| `categoryName` | string? | Category name |
| `stockCode` | string? | Stock code |
| `barcodeNumber` | string? | Barcode |
| `externalId` | string? | External system ID (e-commerce and so on) |
| `salePriceExceptTax` | decimal | Sale price excluding tax |
| `salePriceIncludeTax` | decimal | Sale price including tax |
| `salePriceExceptTaxCurrencyType` | int? | `AccountCurrencyType` |
| `salePriceIncludeTaxCurrencyType` | int? | `AccountCurrencyType` |
| `unitOfMeasurement` | int? | `MeasurementUnit` |
| `taxRate` | int? | VAT percentage (18, 20, …) |
| `quantity` | int? | Stock quantity (when defined) |
| `stockTracking` | bool | Simple stock-tracking flag |
**Example request**
```http
GET /api/external/v1/service-and-products?page=1&pageSize=20&search=laptop&categoryId=2
X-Api-Key: crm_xxxxx
```
**Example response**
```json
{
"success": true,
"message": "Records retrieved successfully.",
"data": {
"items": [
{
"id": 10,
"name": "Product A",
"serviceAndProductCategoryId": 2,
"categoryName": "Electronics",
"stockCode": "SKU-001",
"barcodeNumber": "8690000000001",
"externalId": "shopify-1001",
"salePriceExceptTax": 500.0,
"salePriceIncludeTax": 590.0,
"salePriceExceptTaxCurrencyType": 0,
"salePriceIncludeTaxCurrencyType": 0,
"unitOfMeasurement": 0,
"taxRate": 18,
"quantity": 25,
"stockTracking": true
}
],
"currentPage": 1,
"pageSize": 20,
"totalCount": 1,
"totalPages": 1
}
}
```
### `GET /service-and-products/{id}` — Detail
In addition to the list fields:
| Field | Type | Description |
|-------|------|-------------|
| `unitPrice` | string | Unit price (a text field — consistent with the CRM) |
| `description` | string? | Description |
| `codeOfGtip` | string? | GTIP (customs tariff) code |
| `purchasePriceExceptTax` | decimal | Purchase price (excluding) |
| `purchasePriceIncludeTax` | decimal | Purchase price (including) |
| `purchasePriceExceptTaxCurrencyType` | int? | Currency |
| `purchasePriceIncludeTaxCurrencyType` | int? | Currency |
| `salePriceExceptTaxExchangeRate` | decimal? | Sale exchange rate (TRY) |
| `saleOtv` | string? | Sale special consumption tax |
| `oiv` | string? | Special communication tax |
| `stockTrackingForServiceAndProduct` | int? | Stock-tracking mode (`0` / `1`, see the enum) |
### `POST /service-and-products` — Create
**Content-Type:** `application/json`
**Required fields**
| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Product/service name (max 256) |
| `serviceAndProductCategoryId` **or** `category` | int / object | A category ID belonging to the company (> 0) **or** a category resolution object (see below) |
**Category resolution (`category`)** — the category does not have to exist beforehand when creating a product:
```json
{
"name": "Plate holder",
"category": {
"title": "Plate holder products",
"externalId": "sahibinden-category-plate-holder",
"create": {
"title": "Plate holder products",
"description": "Sahibinden plate-holder orders"
}
},
"stockCode": "PLATEHOLDER-STANDARD",
"taxRate": 18
}
```
Category lookup order: `serviceAndProductCategoryId` → `category.id` → `category.externalId` → `category.title` (exact match). If none is found, it is created from `category.create`.
**Optional fields**
| Field | Type | Description |
|-------|------|-------------|
| `description` | string? | Description |
| `unitPrice` | string? | Unit price text (default `"0"`) |
| `quantity` | int? | Stock quantity (≥ 0) |
| `stockCode` | string? | Stock code (required when `stockTracking: true`) |
| `stockTracking` | bool | Simple stock tracking |
| `unitOfMeasurement` | int? | `MeasurementUnit` |
| `taxRate` | int? | VAT %: `0`, `1`, `8`, `10`, `18`, `20` |
| `purchasePriceExceptTax` | decimal | Purchase (excluding) |
| `purchasePriceIncludeTax` | decimal | Purchase (including) |
| `salePriceExceptTax` | decimal | Sale (excluding) |
| `salePriceIncludeTax` | decimal | Sale (including) |
| `purchasePriceExceptTaxCurrencyType` | int? | `AccountCurrencyType` |
| `purchasePriceIncludeTaxCurrencyType` | int? | `AccountCurrencyType` |
| `salePriceExceptTaxCurrencyType` | int? | `AccountCurrencyType` |
| `salePriceIncludeTaxCurrencyType` | int? | `AccountCurrencyType` |
| `salePriceExceptTaxExchangeRate` | decimal? | Sale exchange rate |
| `oiv`, `purchaseOtv`, `saleOtv` | string? | Tax fields |
| `barcodeNumber` | string? | Barcode |
| `codeOfGtip` | string? | GTIP |
| `externalId` | string? | External system ID (unique within the company) |
| `stockTrackingForServiceAndProduct` | int? | Stock-tracking mode (`0` / `1`, see the enum) |
**Example request**
```http
POST /api/external/v1/service-and-products
Content-Type: application/json
X-Api-Key: crm_xxxxx
{
"name": "Product A",
"serviceAndProductCategoryId": 2,
"stockCode": "SKU-001",
"stockTracking": true,
"salePriceExceptTax": 500,
"salePriceIncludeTax": 590,
"taxRate": 18,
"externalId": "shopify-1001"
}
```
**Successful response:** `200` — the `data` field uses the same schema as the detail (`GET /{id}`).
### `PUT /service-and-products/{id}` — Update
The body schema is the same as `POST`. If the record is not found, `404`.
### `DELETE /service-and-products/{id}` — Delete
The record is marked as deleted. If the product is used on an active order or sale line, `400` is returned.
**Example response**
```json
{
"success": true,
"message": "Record deleted successfully."
}
```
> Warehouse movements, photo upload and price history are not managed through this API; use the CRM interface if you need them.
---
## Order API (`/orders`)
Order records are created and updated through the External API; they appear in the CRM interface as the corresponding commercial record.
**Base URL:** `https://externalapi.myvoipcrm.com/api/external/v1/orders`
### Order vs. sale
| | Order (`/orders`) | Quote (`/biddings`) | Sale (`/sales`) |
|--|-------------------|---------------------|-----------------|
| Use | Taking orders, e-commerce | Quote / price offer | A finalised sales invoice |
| Endpoint | `/orders` | `/biddings` | `/sales` |
| `status` | Stage **0–8** | Review **0–2** | None |
| Status PATCH | `PATCH .../orders/{id}/status` | `PATCH .../biddings/{id}/status` | None |
| Extra field | — | `biddingConditions` | — |
### Endpoint summary
| Method | URL | Description |
|--------|-----|-------------|
| `GET` | `/orders` | Paged order list |
| `GET` | `/orders/{id}` | Order detail + lines |
| `POST` | `/orders` | New order |
| `POST` | `/orders/complete` | Customer + product + category + order in one request (see [Order Complete](#order-complete-api-orderscomplete)) |
| `PUT` | `/orders/{id}` | Update the order (lines are rewritten) |
| `PATCH` | `/orders/{id}/status` | Update only the order stage (`status` 0–8) |
| `DELETE` | `/orders/{id}` | Delete |
### `GET /orders` — List
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `page` | int | `1` | Page |
| `pageSize` | int | `20` | Size (max 100) |
| `customerId` | int | — | Only that customer's orders |
**`items[]` fields**
| Field | Type | Description |
|-------|------|-------------|
| `id` | int | Order ID |
| `customerId` | int? | Customer |
| `customerFullName` | string? | Customer name |
| `invoiceFormDate` | datetime | Issue date |
| `dueDate` | datetime | Due date |
| `orderNo` | string? | Order number |
| `orderDate` | datetime? | Order date |
| `total` | string? | Grand total |
| `totalTl` | string? | TRY total |
| `status` | int? | Order stage 0–8 (see [order stage](#status--order-stage-orders)) |
| `statusDisplayName` | string? | Stage label (e.g. `Hazırlanıyor`) |
| `paymentStatus` | int? | Payment status (see the `paymentStatus` enum) |
### `GET /orders/{id}` — Detail
The list fields plus `description`, `invoiceOrderNo`, `invoiceSerialNo`, `subTotal`, `kdvTotal`, `discountTotal`, `grossTotal`, `lines[]`.
**`lines[]` fields**
| Field | Type | Description |
|-------|------|-------------|
| `id` | int | Line ID |
| `serviceAndProductId` | int? | Product ID |
| `quantity` | decimal? | Quantity |
| `unitPrice` | decimal? | Unit price |
| `taxRate` | int? | VAT % |
| `lineTotal` | string? | Line total |
| `discount` | string? | Discount |
| `lineDescription` | string? | Line description |
| `measurementUnit` | int? | Unit |
### `POST /orders` — Create
**Required body fields**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `customerId` | int | Yes | A valid customer ID (same company) |
| `invoiceFormDate` | datetime | Yes | Issue date (ISO 8601) |
| `dueDate` | datetime | Yes | Due date (≥ `invoiceFormDate`) |
| `lines` | array | Yes | At least **1** line |
**Optional header fields**
| Field | Type | Description |
|-------|------|-------------|
| `description` | string? | Description |
| `orderNo` | string? | Order number |
| `orderDate` | datetime? | Order date |
| `invoiceOrderNo` | string? | Invoice series number |
| `invoiceSerialNo` | string? | Invoice sequence number |
| `status` | int? | Order stage 0–8 (default: `0` = New order) |
| `paymentStatus` | int? | Payment status |
| `subTotal` | string? | Subtotal (text) |
| `kdvTotal` | string? | VAT total |
| `discountTotal` | string? | Discount total |
| `grossTotal` | string? | Gross total |
| `total` | string? | Grand total |
| `totalTl` | string? | TRY grand total |
**`lines[]` line fields**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `serviceAndProductId` | int | Yes | `GET /service-and-products` → `id` |
| `quantity` | decimal | No | Default `1` |
| `unitPrice` | decimal? | No | Unit price |
| `taxRate` | int? | No | VAT % (matching the product's `taxRate` is recommended) |
| `lineTotal` | string? | No | Line total |
| `discount` | string? | No | Discount |
| `lineDescription` | string? | No | Description |
| `measurementUnit` | int? | No | Unit code (see the `unitOfMeasurement` enum) |
**Validation rules**
- `customerId` must belong to the company and not be deleted.
- Every `serviceAndProductId` must belong to the company.
- `dueDate` < `invoiceFormDate` → `400`.
- Empty `lines` → `400`.
**Creation example**
```json
{
"customerId": 123,
"description": "E-commerce order #8842",
"invoiceFormDate": "2026-05-26T00:00:00Z",
"dueDate": "2026-06-26T00:00:00Z",
"orderNo": "ORD-8842",
"orderDate": "2026-05-26T10:30:00Z",
"status": 0,
"paymentStatus": 1,
"subTotal": "1000.00",
"kdvTotal": "180.00",
"total": "1180.00",
"totalTl": "1180.00",
"lines": [
{
"serviceAndProductId": 10,
"quantity": 2,
"unitPrice": 500,
"taxRate": 18,
"lineTotal": "1180.00",
"measurementUnit": 0
}
]
}
```
---
## Order Complete API (`/orders/complete`)
For marketplace and production integrations: customer resolution/creation, product resolution/creation (including the category), delivery/billing addresses and the order record — **in a single request**.
**Endpoint:** `POST /api/external/v1/orders/complete`
### Flow summary
1. Customer: `customerId` or `customer` (ID → `externalId` → email → phone; otherwise `customer.create`)
2. Each line: `serviceAndProductId` or `product` (ID → `externalId` → `stockCode` → `barcodeNumber` → `name`; otherwise `product.create`)
3. The category when creating a product: `serviceAndProductCategoryId` or `category` (ID → `externalId` → `title`; otherwise `category.create`)
4. Order: the record is opened with `deliveryAddress`, `billingAddress`, `source`, `status` and `lines[]`
### Required top-level fields
| Field | Description |
|-------|-------------|
| `invoiceFormDate` | Issue date (ISO 8601) |
| `dueDate` | Due date (≥ `invoiceFormDate`) |
| `lines` | At least 1 line |
| `customerId` or `customer` | Customer |
### Response (`data`)
| Field | Description |
|-------|-------------|
| `order` | The created order detail |
| `customer` | `{ id, wasCreated, externalId }` |
| `products` | Per line: `{ lineIndex, id, wasCreated, serviceAndProductCategoryId, categoryWasCreated, ... }` |
**Example (abridged)**
```json
{
"customer": {
"externalId": "sahibinden-12345",
"create": { "fullName": "AHMET YILMAZ", "phoneNumber1": "5321234567", "email": "[email protected]" }
},
"source": 4,
"orderNo": "SB-8842",
"invoiceFormDate": "2026-06-19T00:00:00Z",
"dueDate": "2026-06-26T00:00:00Z",
"subTotal": "500.00",
"kdvTotal": "90.00",
"total": "590.00",
"totalTl": "590.00",
"deliveryAddress": { "city": "İstanbul", "district": "Kadıköy", "address": "Moda Caddesi No:12" },
"billingAddress": { "city": "İstanbul", "district": "Üsküdar", "address": "Barış Sokak No:8" },
"lines": [{
"product": {
"name": "Plate holder",
"create": {
"name": "Plate holder",
"category": { "title": "Plate holder products", "create": { "title": "Plate holder products" } },
"stockCode": "PLATEHOLDER-STANDARD",
"taxRate": 18
}
},
"quantity": 1,
"unitPrice": 500,
"taxRate": 18,
"lineTotal": "590.00",
"description": "MEHMET YILMAZ"
}]
}
```
> For the full field list, the enum tables and the Sahibinden mapping, see the **Order Complete Integration Guide** (Developer centre).
### `PUT /orders/{id}` — Update
The same body as `POST`. The existing lines are removed and the `lines` you send are recreated. The response returns the current detail.
### `PATCH /orders/{id}/status` — Update the stage
For warehouse / shipping integrations: updates only the order's **stage**; the header fields and lines stay unchanged.
**Body**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `status` | int | Yes | 0–8 (the order stage table) |
**Example**
```json
{
"status": 5
}
```
**Successful response:** the current order detail (the same structure as `GET /orders/{id}`).
**Errors**
- Invalid `status` (outside 0–8) → `400`
- The record does not exist or belongs to another company → `404`
### `DELETE /orders/{id}` — Delete
The record is marked as deleted; it disappears from the lists. The related lines count as removed too.
---
## Quote API (`/biddings`)
Quote records are created and updated through the External API; they appear in the CRM **Quotes** module.
**Base URL:** `https://externalapi.myvoipcrm.com/api/external/v1/biddings`
### Endpoint summary
| Method | URL | Description |
|--------|-----|-------------|
| `GET` | `/biddings` | Paged quote list |
| `GET` | `/biddings/{id}` | Quote detail + lines |
| `POST` | `/biddings` | New quote |
| `PUT` | `/biddings/{id}` | Update the quote (lines are rewritten) |
| `PATCH` | `/biddings/{id}/status` | Only the review state (`status` 0–2) |
| `DELETE` | `/biddings/{id}` | Delete |
### `GET /biddings` — List
The same paging as the order list (`page`, `pageSize`, `customerId`). The `items[]` fields are the same as for orders; `status` / `statusDisplayName` here mean the **review state** (0–2).
### `GET /biddings/{id}` — Detail
The list fields plus `description`, `biddingConditions`, the invoice-number fields, the totals and `lines[]`.
### `POST /biddings` — Create
The same required fields as creating an order (`customerId`, `invoiceFormDate`, `dueDate`, `lines`). The extra quote fields:
| Field | Type | Description |
|-------|------|-------------|
| `status` | int? | Review state 0–2 (default: `0`) |
| `biddingConditions` | string? | Quote conditions text |
**Example**
```json
{
"customerId": 123,
"description": "Annual maintenance quote",
"invoiceFormDate": "2026-05-26T00:00:00Z",
"dueDate": "2026-06-26T00:00:00Z",
"status": 0,
"biddingConditions": "Prices are valid for 30 days.",
"total": "1180.00",
"totalTl": "1180.00",
"lines": [
{
"serviceAndProductId": 10,
"quantity": 1,
"unitPrice": 1000,
"taxRate": 18,
"lineTotal": "1180.00"
}
]
}
```
### `PUT /biddings/{id}` — Update
The same body as `POST`; the lines are rewritten.
### `PATCH /biddings/{id}/status` — Update the review state
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `status` | int | Yes | 0–2 ([quote review](#status--quote-review-state-biddings)) |
### `DELETE /biddings/{id}` — Delete
The record is soft-deleted.
---
## Sales API (`/sales`)
Sales records are created with the `/sales` endpoint. The body and response structure are **almost identical** to orders/quotes; **`status` / `statusDisplayName` do not exist on sales**.
**Base URL:** `https://externalapi.myvoipcrm.com/api/external/v1/sales`
### Endpoint summary
| Method | URL | Description |
|--------|-----|-------------|
| `GET` | `/sales` | Paged sales list (the `customerId` filter is optional) |
| `GET` | `/sales/{id}` | Sale detail + lines |
| `POST` | `/sales` | New sales invoice |
| `PUT` | `/sales/{id}` | Update |
| `DELETE` | `/sales/{id}` | Delete |
For the fields, validation rules and the `lines` structure, see the [Order API](#order-api-orders) section; **do not send `status` in a sale POST/PUT body**, and the `status` field is not returned in the list/detail response either.
**Example sale creation**
```json
{
"customerId": 123,
"description": "Retail sale",
"invoiceFormDate": "2026-05-26T00:00:00Z",
"dueDate": "2026-05-26T00:00:00Z",
"invoiceOrderNo": "A",
"invoiceSerialNo": "000124",
"paymentStatus": 0,
"total": "2360.00",
"totalTl": "2360.00",
"lines": [
{
"serviceAndProductId": 10,
"quantity": 4,
"unitPrice": 500,
"taxRate": 18,
"lineTotal": "2360.00"
}
]
}
```
### Stock deduction (order / sale) — deliberately off
When you create an order, quote or sale through the External API, **the warehouse stock quantity is not deducted automatically**. The `quantity` field on the product card is not updated by the operation either. Stock movements and warehouse integration are managed only through the CRM interface.
> If your integration needs stock tracking, after creating the order/sale record with the External API you must handle the stock deduction separately, either in your own system or inside the CRM.
### Out of scope for the External API (orders/sales)
The following exist in the CRM's own interface; the External API **does not support them at present**:
- Automatic warehouse stock deduction
- Creating collections and cash movements
- Converting a quote into a sale
- Delivery-note linkage
- E-adisyon / e-invoice integration
---
## WhatsApp API
WhatsApp Business accounts, the Meta-approved template list and template message sending. `X-Api-Key` is required on every request. A WhatsApp Business integration must be defined in the CRM.
**Base URL example:** `https://externalapi.myvoipcrm.com/api/external/v1/whatsapp`
**Required header:** `X-Api-Key: <crm-api-key>`
### Endpoint summary
| Method | URL | Description |
|--------|-----|-------------|
| `GET` | `/whatsapp/accounts` | Lists the defined WhatsApp lines |
| `GET` | `/whatsapp/templates` | Lists the templates (filter by line with `account`) |
| `POST` | `/whatsapp/templates/send` | Sends a template message |
### `GET /whatsapp/accounts` — Account list
**Query parameters**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `page` | int | `1` | Page number (≥ 1) |
| `pageSize` | int | `20` | Page size (≥ 1, max **100**) |
| `search` | string | — | Searches `whatsappPhoneNumber`, `title` or `appName` |
**`items[]` fields**
| Field | Type | Description |
|-------|------|-------------|
| `id` | int | The CRM WhatsApp settings record ID |
| `whatsappPhoneNumber` | string | The line number — used as `account` in the template list and when sending |
| `title` | string? | Account title |
| `appName` | string? | Application name |
| `whatsAppBusinessAccountId` | string? | The Meta WABA ID |
| `isConfigured` | bool | Whether the access token and phone ID are defined |
### `GET /whatsapp/templates` — Template list
**Query parameters**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `page` | int | `1` | Page number |
| `pageSize` | int | `20` | Page size (max **100**) |
| `search` | string | — | Searches `title`, `bodyText` or `metaTemplateId` |
| `approvedOnly` | bool | `true` | Only Meta-approved (`APPROVED`) templates |
| `account` | string | — | The `whatsappPhoneNumber` from the `/whatsapp/accounts` response; when given, only the Meta templates on that line |
**`items[]` fields**
| Field | Type | Description |
|-------|------|-------------|
| `id` | int | The CRM template record ID |
| `metaTemplateId` | string | The Meta template ID — `templateId` when sending |
| `title` | string | The Meta template name — `title` when sending |
| `bodyText` | string? | Template body text |
| `headerText` | string? | Header text |
| `footerText` | string? | Footer |
| `category` | string? | Template category |
| `language` | string? | Language code (e.g. `tr`) |
| `messageType` | string? | Message type |
| `metaTemplateStatus` | string? | Meta approval state |
| `metaTemplateStatusReason` | string? | Meta's rejection reason code for a rejected template: `INCORRECT_CATEGORY`, `INVALID_FORMAT`, `PROMOTIONAL`, `TAG_CONTENT_MISMATCH`, `ABUSIVE_CONTENT`, `SCAM`; `NONE` if no reason was given |
| `variableLabelsJson` | string? | Variable labels (JSON) |
| `variableLabels` | object? | Parsed labels: `{ "1": "ADSOYAD", "2": "TARİH" }` |
### `POST /whatsapp/templates/send` — Send a template
**Content-Type:** `application/json`
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `phoneNumber` | string | Yes | The recipient's WhatsApp number |
| `templateId` | string | Yes | The `metaTemplateId` from the list response |
| `title` | string | Yes | The `title` from the list response |
| `variables` | object? | No | Values keyed by label name (`ADSOYAD`) or index (`"1"`, `"2"`) |
| `bodyText` | string? | No | Body text; when omitted the template's own text is used |
| `url` | string? | No | A file URL when the header requires media |
| `buttonUrl` | string? | No | Value for `{{1}}` when the template has a dynamic URL button (`https://site.com/{{1}}`); either the full address (`https://site.com/cart/123`) or just the suffix (`cart/123`). Not needed for static URL buttons |
| `otpCode` | string? | No | One-time code for an authentication (`AUTHENTICATION`) template (max 15 characters). Fills `{{1}}` in the body and the "Copy code" button; same effect as `variables: {"1": "…"}` |
| `customerName` | string? | No | The recipient's name |
| `account` | string? | No | `/whatsapp/accounts` → `whatsappPhoneNumber`; recommended when you have several lines |
**Variable mapping:** you can use either the label names inside `variableLabels` (`ADSOYAD`, `TARİH`) or the Meta placeholder indexes (`"1"`, `"2"`). The API converts label names to indexes automatically.
**Successful response example**
```json
{
"success": true,
"message": "WhatsApp şablon mesajı gönderildi.",
"data": {
"phoneNumber": "905510018946",
"templateId": "2038448583379082",
"title": "test_randevu",
"account": "908502551913"
}
}
```
---
## Shipment API (`/shipments`)
Send shipments from your own system to the CRM, update their status, list and delete them. The **Shipping** module must be enabled for the company (otherwise `403 MODULE_NOT_ENABLED`). Full guide: corporate site **Developer centre** → **Shipment API** (`/en/developers/kargo-entegrasyon`) · source: `Docs/shipment-integration-en.md`.
| Method | Path | Description |
|---|---|---|
| `GET` | `/shipments` | List (`externalId(s)`, `customerId`, `customerExternalId`, `status`, `carrier`, `direction`, `trackingNumber`, `shipmentFrom/To`, `updatedFrom/To`) |
| `GET` | `/shipments/meta` | Value lists for status, carrier, etc. |
| `GET` | `/shipments/{id}` · `/shipments/by-external-id/{externalId}` | Single record |
| `POST` | `/shipments` | Create; if the `externalId` exists, update only the fields sent |
| `POST` | `/shipments/bulk-upsert` | Up to 100 items; `externalId` required on each |
| `PUT` | `/shipments/{id}` · `/shipments/by-external-id/{externalId}` | Replace all fields |
| `PATCH` | `/shipments/{id}` · `/shipments/by-external-id/{externalId}` | Only fields in the body (`null` clears) |
| `PATCH` | `/shipments/{id}/status` · `/shipments/by-external-id/{externalId}/status` | Status and delivery info |
| `DELETE` | `/shipments/{id}` · `/shipments/by-external-id/{externalId}` | Delete (CRM trash) |
Enum fields accept a name (`"Delivered"`) or a number. Dates without a time zone are treated as Turkey time (UTC+3). CRM shipment automations (SMS, WhatsApp, e-mail, webhook) run on status changes.
---
## Commercial module HTTP codes
### Product / service
| Code | Endpoint | Meaning |
|------|----------|---------|
| `200` | GET/POST/PUT/DELETE | Success |
| `400` | GET list | Invalid `page` / `pageSize` |
| `400` | POST/PUT | Validation (category, VAT, stock code and so on) |
| `400` | DELETE | Used on an order/sale line |
| `401` | All | Invalid/missing API key |
| `403` | All | API key valid, IP not permitted |
| `404` | GET/PUT/DELETE `{id}` | Product not found |
| `409` | POST/PUT | `externalId` conflict |
| `500` | All | Server error |
### Product / service categories
| Code | Endpoint | Meaning |
|------|----------|---------|
| `200` | GET/POST/PUT/DELETE | Success |
| `400` | GET list | Invalid `page` / `pageSize` |
| `400` | POST/PUT | Validation (`title` and so on) |
| `400` | DELETE | The category is used by products/services |
| `401` | All | Invalid/missing API key |
| `403` | All | API key valid, IP not permitted |
| `404` | GET/PUT/DELETE `{id}` | Record not found |
| `500` | All | Server error |
### WhatsApp
| Code | Endpoint | Meaning |
|------|----------|---------|
| `200` | GET accounts/templates, POST send | Success |
| `400` | GET/POST | Invalid paging, missing field, missing integration, send failure |
| `401` | All | Invalid or missing API key |
| `403` | All | IP not permitted |
| `404` | GET templates, POST send | Template or WhatsApp account not found |
| `500` | All | Unexpected error |
### Orders and sales (shared)
| Code | Endpoint | Meaning |
|------|----------|---------|
| `200` | GET/POST/PUT/DELETE | Success |
| `400` | POST/PUT | Validation (customer, product, date, empty lines) |
| `400` | GET list | Invalid paging |
| `401` | All | Invalid API key |
| `403` | All | IP blocked |
| `404` | GET/PUT/DELETE `{id}` | Record not found |
| `500` | All | Server error |
## Response Format
Every endpoint returns a standard body:
```json
{
"success": true,
"message": "İşlem mesajı",
"code": null,
"data": {}
}
```
On an error, `success: false` and the `code` field is filled in (integrations can handle it with a `switch`):
```json
{
"success": false,
"message": "A customer with this email already exists.",
"code": "DUPLICATE_EMAIL",
"data": null
}
```
### Error codes (`code`)
| Code | Description |
|------|-------------|
| `RATE_LIMIT_EXCEEDED` | Rate limit exceeded (default: 120 requests/min per API key) |
| `INVALID_API_KEY` | Invalid or missing `X-Api-Key` |
| `IP_NOT_ALLOWED` | API key valid, but the IP is not permitted or no allowed-IP list is defined |
| `VALIDATION_FAILED` | General validation error |
| `INVALID_PAGINATION` | Invalid `page` / `pageSize` |
| `RECORD_NOT_FOUND` | Record not found |
| `DUPLICATE_EMAIL` | A customer with the same email already exists |
| `DUPLICATE_PHONE` | A customer with the same primary phone already exists |
| `EXTERNAL_ID_CONFLICT` | `externalId` is in use on another product |
| `CATEGORY_IN_USE` | The category cannot be deleted (products attached) |
| `PRODUCT_IN_USE` | The product cannot be deleted (on an order/sale line) |
| `INVALID_TAX_RATE` | Invalid VAT percentage |
| `STOCK_CODE_REQUIRED` | `stockCode` is required when `stockTracking: true` |
| `CUSTOMER_NOT_FOUND` | Customer not found for the order/sale |
| `LINE_ITEMS_REQUIRED` | At least one line is required |
| `DUE_DATE_INVALID` | The due date cannot be earlier than the invoice date |
| `FULL_NAME_REQUIRED` | The customer name is required |
| `PHONE_REQUIRED` | A valid primary phone is required |
| `UNEXPECTED_ERROR` | Server error (500) |
| `TEMPLATE_NOT_FOUND` | WhatsApp template not found |
| `WHATSAPP_ACCOUNT_NOT_FOUND` | WhatsApp account not found |
| `WHATSAPP_NOT_CONFIGURED` | The WhatsApp integration is missing or Messenger is not configured |
| `WHATSAPP_SEND_FAILED` | The template could not be sent through Meta |
| `SERVICE_USER_NOT_FOUND` | There is no admin user for the company to act as |
| `MODULE_NOT_ENABLED` | The related CRM module (e.g. Shipping) is disabled for the company (403) |
| `EXTERNAL_ID_REQUIRED` | A bulk shipment item has no `externalId` |
| `USER_NOT_FOUND` | `receivedByUserId` does not belong to the company |
| `TOO_MANY_ITEMS` | More items than allowed in a bulk request |
### Rate limit
A default of **120 requests / minute** per API key (or IP) applies to all `/api/external/v1/*` endpoints (auth has its own separate limit). On exceeding it, `429` with `code: RATE_LIMIT_EXCEEDED` is returned. The limit values can be changed in the server configuration.
## HTTP Response Codes (standard)
### Common codes
- `200 OK`: the operation completed successfully
- `400 Bad Request`: missing/invalid request data
- `401 Unauthorized`: authentication failed (wrong username/password or API key)
- `403 Forbidden`: insufficient permission (no admin role)
- `404 Not Found`: the requested resource was not found
- `409 Conflict`: a conflicting record (e.g. a customer email/phone or a product `externalId`)
- `500 Internal Server Error`: an unexpected server error
### Response codes per endpoint
#### `POST /api/external/v1/auth/company-api-key`
- `200`: the API key was returned successfully
- `400`: `userName` or `password` empty
- `401`: wrong username/password
- `403`: the user is not an admin/super admin
- `404`: the company or the company API key was not found
- `500`: unexpected error
#### `POST /api/external/v1/customers`
- `200`: the customer was created (`data` returns `id` and all customer fields)
- `400`: a required field/phone format or model validation is invalid
- `401`: the API key is invalid or missing
- `403`: the API key is valid but the IP is not on the allow list
- `409`: `DUPLICATE_EMAIL` or `DUPLICATE_PHONE`
- `429`: `RATE_LIMIT_EXCEEDED`
- `500`: unexpected error
#### `PUT /api/external/v1/customers/{id}`
- `200`: the customer was updated
- `400`: a required field/phone format or model validation is invalid
- `401`: the API key is invalid or missing
- `403`: the API key is valid but the IP is not on the allow list
- `404`: customer not found
- `409`: `DUPLICATE_EMAIL` or `DUPLICATE_PHONE`
- `429`: `RATE_LIMIT_EXCEEDED`
- `500`: unexpected error
#### `PATCH /api/external/v1/customers/{id}`
- `200`: the partial update succeeded (only the JSON fields sent are changed)
- `400`: invalid field or phone format
- `404`: customer not found
- `409`: `DUPLICATE_EMAIL` or `DUPLICATE_PHONE` (if the email/phone was updated)
- `429`: `RATE_LIMIT_EXCEEDED`
**Example**
```http
PATCH /api/external/v1/customers/123
Content-Type: application/json
X-Api-Key: crm_xxxxx
{
"email": "[email protected]",
"city": "Istanbul"
}
```
#### `GET /api/external/v1/customers`
- `200`: the customer list was returned
- `400`: invalid page/page size
- `401`: the API key is invalid or missing
- `403`: the API key is valid but the IP is not on the allow list
- `500`: unexpected error
#### `GET /api/external/v1/customers/{id}`
- `200`: the customer detail was returned
- `401`: the API key is invalid or missing
- `403`: the API key is valid but the IP is not on the allow list
- `404`: customer not found
- `500`: unexpected error
#### `GET /api/external/v1/support-tickets` and `GET /api/external/v1/support-tickets/{id}`
- `200`: the ticket list or detail was returned
- `400`: `INVALID_PAGINATION` (page/pageSize) or `VALIDATION_FAILED` (status/priority/source value)
- `401`: the API key is invalid or missing
- `403`: the API key is valid but the IP is not on the allow list
- `404`: ticket not found or owned by another company (`RECORD_NOT_FOUND`) — detail endpoint only
- `500`: unexpected error
#### `DELETE /api/external/v1/customers/{id}`
- `200`: the customer was deleted
- `401`: the API key is invalid or missing
- `403`: the API key is valid but the IP is not on the allow list
- `404`: customer not found
- `500`: unexpected error
## Usage Example (cURL)
The `X-Api-Key` header is required on every commercial request (auth excepted).
### 1) Get an API key
```bash
curl -X POST "https://externalapi.myvoipcrm.com/api/external/v1/auth/company-api-key" \
-H "Content-Type: application/json" \
-d "{\"userName\":\"[email protected]\",\"password\":\"123456\"}"
```
### 2) Product list
```bash
curl -X GET "https://externalapi.myvoipcrm.com/api/external/v1/service-and-products?page=1&pageSize=20&search=product" \
-H "X-Api-Key: crm_xxxxx"
```
### 3) Product detail
```bash
curl -X GET "https://externalapi.myvoipcrm.com/api/external/v1/service-and-products/10" \
-H "X-Api-Key: crm_xxxxx"
```
### 3b) Create a product
```bash
curl -X POST "https://externalapi.myvoipcrm.com/api/external/v1/service-and-products" \
-H "X-Api-Key: crm_xxxxx" \
-H "Content-Type: application/json" \
-d "{\"name\":\"Product A\",\"serviceAndProductCategoryId\":2,\"salePriceExceptTax\":500,\"salePriceIncludeTax\":590,\"taxRate\":18,\"externalId\":\"shopify-1001\"}"
```
### 3c) Update a product
```bash
curl -X PUT "https://externalapi.myvoipcrm.com/api/external/v1/service-and-products/10" \
-H "X-Api-Key: crm_xxxxx" \
-H "Content-Type: application/json" \
-d "{\"name\":\"Product A (updated)\",\"serviceAndProductCategoryId\":2,\"salePriceExceptTax\":520,\"salePriceIncludeTax\":613.6,\"taxRate\":18}"
```
### 3d) Delete a product
```bash
curl -X DELETE "https://externalapi.myvoipcrm.com/api/external/v1/service-and-products/10" \
-H "X-Api-Key: crm_xxxxx"
```
### 4) Create a customer
```bash
curl -X POST "https://externalapi.myvoipcrm.com/api/external/v1/customers" \
-H "Content-Type: application/json" \
-H "X-Api-Key: crm_xxxxx" \
-d "{\"fullName\":\"Ahmet Yılmaz\",\"phoneNumber1\":\"5321234567\",\"dialCode1\":\"+90\",\"countryCode1\":\"tr\",\"email\":\"[email protected]\",\"status\":0,\"priority\":3}"
```
### 5) Create a quote
```bash
curl -X POST "https://externalapi.myvoipcrm.com/api/external/v1/biddings" \
-H "Content-Type: application/json" \
-H "X-Api-Key: crm_xxxxx" \
-d "{\"customerId\":123,\"invoiceFormDate\":\"2026-05-26T00:00:00Z\",\"dueDate\":\"2026-06-26T00:00:00Z\",\"status\":0,\"biddingConditions\":\"Valid for 30 days.\",\"total\":\"1180.00\",\"lines\":[{\"serviceAndProductId\":10,\"quantity\":1,\"unitPrice\":1000,\"taxRate\":18,\"lineTotal\":\"1180.00\"}]}"
```
### 6) Create an order
```bash
curl -X POST "https://externalapi.myvoipcrm.com/api/external/v1/orders" \
-H "Content-Type: application/json" \
-H "X-Api-Key: crm_xxxxx" \
-d "{\"customerId\":123,\"invoiceFormDate\":\"2026-05-26T00:00:00Z\",\"dueDate\":\"2026-06-26T00:00:00Z\",\"orderNo\":\"ORD-1001\",\"total\":\"1180.00\",\"totalTl\":\"1180.00\",\"lines\":[{\"serviceAndProductId\":10,\"quantity\":2,\"unitPrice\":500,\"taxRate\":18,\"lineTotal\":\"1180.00\"}]}"
```
### 6b) Order complete (customer + product + category in one request)
```bash
curl -X POST "https://externalapi.myvoipcrm.com/api/external/v1/orders/complete" \
-H "Content-Type: application/json" \
-H "X-Api-Key: crm_xxxxx" \
-d "{\"customer\":{\"externalId\":\"sahibinden-12345\",\"create\":{\"fullName\":\"AHMET YILMAZ\",\"phoneNumber1\":\"5321234567\"}},\"source\":4,\"orderNo\":\"SB-8842\",\"invoiceFormDate\":\"2026-06-19T00:00:00Z\",\"dueDate\":\"2026-06-26T00:00:00Z\",\"lines\":[{\"product\":{\"name\":\"Plate holder\",\"create\":{\"name\":\"Plate holder\",\"category\":{\"title\":\"Plate holder products\",\"create\":{\"title\":\"Plate holder products\"}},\"stockCode\":\"PLATEHOLDER-STANDARD\",\"taxRate\":18}},\"quantity\":1,\"description\":\"MEHMET YILMAZ\"}]}"
```
### 7) Create a sale
```bash
curl -X POST "https://externalapi.myvoipcrm.com/api/external/v1/sales" \
-H "Content-Type: application/json" \
-H "X-Api-Key: crm_xxxxx" \
-d "{\"customerId\":123,\"invoiceFormDate\":\"2026-05-26T00:00:00Z\",\"dueDate\":\"2026-05-26T00:00:00Z\",\"total\":\"1180.00\",\"totalTl\":\"1180.00\",\"lines\":[{\"serviceAndProductId\":10,\"quantity\":2,\"unitPrice\":500,\"taxRate\":18,\"lineTotal\":\"1180.00\"}]}"
```
### 8) Update the quote review state (PATCH)
```bash
curl -X PATCH "https://externalapi.myvoipcrm.com/api/external/v1/biddings/12/status" \
-H "Content-Type: application/json" \
-H "X-Api-Key: crm_xxxxx" \
-d "{\"status\":1}"
```
### 9) Order list (by customer)
```bash
curl -X GET "https://externalapi.myvoipcrm.com/api/external/v1/orders?page=1&pageSize=20&customerId=123" \
-H "X-Api-Key: crm_xxxxx"
```
### 10) Update the order stage (PATCH)
```bash
curl -X PATCH "https://externalapi.myvoipcrm.com/api/external/v1/orders/45/status" \
-H "Content-Type: application/json" \
-H "X-Api-Key: crm_xxxxx" \
-d "{\"status\":5}"
```
`5` = Shipped. For the other stages, see the [order stage](#status--order-stage-orders) table.
### 11) Update an order (PUT)
```bash
curl -X PUT "https://externalapi.myvoipcrm.com/api/external/v1/orders/45" \
-H "Content-Type: application/json" \
-H "X-Api-Key: crm_xxxxx" \
-d "{\"customerId\":123,\"invoiceFormDate\":\"2026-05-26T00:00:00Z\",\"dueDate\":\"2026-06-26T00:00:00Z\",\"orderNo\":\"ORD-1001-REV\",\"status\":3,\"total\":\"1200.00\",\"lines\":[{\"serviceAndProductId\":10,\"quantity\":2,\"unitPrice\":500,\"taxRate\":18,\"lineTotal\":\"1200.00\"}]}"
```
### 12) Delete an order
```bash
curl -X DELETE "https://externalapi.myvoipcrm.com/api/external/v1/orders/45" \
-H "X-Api-Key: crm_xxxxx"
```
### 13) WhatsApp accounts
```bash
curl -X GET "https://externalapi.myvoipcrm.com/api/external/v1/whatsapp/accounts?page=1&pageSize=20" \
-H "X-Api-Key: crm_xxxxx"
```
### 14) WhatsApp template list (by account)
```bash
curl -X GET "https://externalapi.myvoipcrm.com/api/external/v1/whatsapp/templates?page=1&pageSize=20&account=908502551913&approvedOnly=true" \
-H "X-Api-Key: crm_xxxxx"
```
### 15) Send a WhatsApp template
```bash
curl -X POST "https://externalapi.myvoipcrm.com/api/external/v1/whatsapp/templates/send" \
-H "Content-Type: application/json" \
-H "X-Api-Key: crm_xxxxx" \
-d "{\"phoneNumber\":\"905510018946\",\"templateId\":\"2038448583379082\",\"title\":\"test_randevu\",\"account\":\"908502551913\",\"variables\":{\"ADSOYAD\":\"Osman\",\"TARİH\":\"10:00\"},\"customerName\":\"OSMAN\"}"
```
## Security and Operations Notes
- In production, allow access over `HTTPS` only.
- Do not keep the API key in clear text on the client side.
- If an API key leaks, generate a new key in the CRM and revoke the old one.
- Records removed with `DELETE` disappear from the lists; data recovery is handled through CRM processes.
- A defined **allowed-IP list is mandatory**; requests from IPs not on the list — or arriving while the list is empty — are rejected (`403`, `IP_NOT_ALLOWED`).
## Security Layers in Place
- `Auth Rate Limit`: the login endpoint is limited to 5 requests per minute per IP.
- `Auth Lockout`: repeated failed attempts on the same IP + username combination trigger a lockout.
- **Request auditing**: API calls are recorded for security and operational purposes (IP, path, duration, result code and so on); the schema details are not documented.
- **Key revocation / expiry**: revoked or expired API keys are rejected in the deployment environment.
## Allowed-IP list (a CRM company setting)
The allowed-IP list defined for the company in the CRM admin panel is applied to external API requests as a **hard requirement**:
- Format: IP addresses separated by commas, semicolons or newlines
- Example: `203.0.113.10,198.51.100.22`
- If the list is **empty or undefined**: all requests are rejected (`403`, `IP_NOT_ALLOWED`)
- The `"*"` wildcard is **not supported**; if it appears in the list it is ignored
## Versioning
This project actively uses the `v1` route structure:
- `/api/external/v1/...`