REST API v1.2.0

ابنِ تطبيقك على
حراج تزايد

مرجع المطورين لربط تطبيقات الويب والموبايل بخدمات الحسابات، الإعلانات، المحادثات، الإشعارات والعمولات.

GET /ads

$ curl "https://haraj.tzaid.sa/wp-json/tz/v1/ads?per_page=2"

HTTP/2 200 OK
{
  "success": true,
  "message": "OK",
  "data": [ ... ]
}

56+Endpoint

JSONاستجابات موحدة

Bearerمصادقة آمنة

RESTويب وموبايل

GET STARTED IN MINUTES

Quick start

Every request starts with this Base URL

Always use HTTPS in production.

https://haraj.tzaid.sa/wp-json/tz/v1

Create an account or sign in

The server returns an independent token for the device or integration.

Store the token securely

The full value is shown when issued. Never commit it to public code.

Send your request

Add the Bearer token to every endpoint that requires authentication.

SECURE ACCESS

Authentication & tokens

After registration or sign-in, send the token in the header of every protected request. One user can have multiple independent sessions.

HTTP headers

Authorization: Bearer tz_your_token_here
Accept: application/json
Content-Type: application/json

Sign-in request

curl -X POST "https://haraj.tzaid.sa/wp-json/tz/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "user@example.com",
    "password": "PASSWORD",
    "device_name": "Flutter iPhone"
  }'

Session lifecycle

/auth/refresh replaces the current token.
/auth/logout revokes only the active session.
Changing the password revokes old sessions.
The default lifetime is 30 days, with a 90-day maximum.

CONSISTENT AND PREDICTABLE

Response format

Success

{
  "success": true,
  "message": "OK",
  "data": {}
}

Error

{
  "success": false,
  "code": "tz_validation_failed",
  "message": "Validation failed.",
  "details": {}
}

List responses include a pagination object containing page, per_page, total, total_pages, and has_more.

COMPLETE REFERENCE

All endpoints

56 endpoints

/

Authentication & Account

POST /auth/register

Create an account and issue a new token

Public

POST /auth/login

Public

POST /auth/refresh

Rotate the token used by the current session

Authenticated

POST /auth/forgot-password

Send a secure password recovery link

Public

POST /auth/logout

Revoke the token used by the current request

Authenticated

GET /auth/me

Get the currently authenticated user

Authenticated

GET /me/profile

Get the complete account profile

Authenticated

PATCH /me/profile

Update profile and privacy settings

Authenticated

POST /me/avatar

Upload a profile picture

Authenticated

PATCH /me/password

Change the password and revoke old sessions

Authenticated

GET /users/{id}

Get a public seller profile

Public

Catalog & Taxonomies

GET /catalog/config

Get app configuration and dynamic fields

Public

GET /categories

Get categories as a tree or flat list

Public

GET /categories/{id}

Get a category and its custom fields

Public

GET /cities

Get the city list

Public

GET /cities/{id}

Get city details

Public

Ads & Images

GET /ads

Search, filter, sort, and paginate published ads

Public

GET /ads/{id}

Get ad details

Public

POST /ads

Create an ad with pending review status

Authenticated

PATCH /ads/{id}

Partially or fully update an ad

Owner

DELETE /ads/{id}

Move an ad to trash

Owner

PATCH /ads/{id}/status

Update sale or visibility status

Owner

GET /me/ads

Get the current user's ads

Authenticated

POST /ads/{id}/images

Upload images using multipart/form-data

Owner

PATCH /ads/{id}/images/order

Reorder an ad's images

Owner

DELETE /ads/{id}/images/{attachment_id}

Remove an image from an ad

Owner

Comments, Chat & Notifications

GET /ads/{id}/comments

Get approved comments for an ad

Public

POST /ads/{id}/comments

Add a comment or reply

Authenticated

DELETE /comments/{id}

Delete a comment

Author

GET /chat/conversations

List the current user's conversations

Authenticated

POST /chat/conversations

Start a conversation for an ad

Authenticated

PATCH /chat/conversations/{id}

Update conversation status

Authenticated

GET /chat/conversations/{id}/messages

Get messages from a conversation

Authenticated

POST /chat/conversations/{id}/messages

Send a message

Authenticated

POST /chat/conversations/{id}/read

Mark a conversation as read

Authenticated

DELETE /chat/messages/{id}

Hide a message for the current user

Authenticated

GET /chat/unread-count

Get the unread message count

Authenticated

GET /notifications

List notifications

Authenticated

GET /notifications/{id}

Get a single notification

Authenticated

PATCH /notifications/{id}

Mark a notification as read or unread

Authenticated

DELETE /notifications/{id}

Delete a notification

Authenticated

POST /notifications/read-all

Mark all notifications as read

Authenticated

GET /notifications/unread-count

Get the unread notification count

Authenticated

Commissions & Invoices

GET /commissions/config

Get the commission rate and calculator

Public

POST /commissions

Record a commission and create an invoice

Public / Authenticated

GET /commissions/{invoice_id}

Get an invoice

Public

GET /me/commissions

Get the current user's invoices

Authenticated

Administration & Moderation

GET /admin/stats

Get system statistics

Admin

GET /admin/ads

List ads across all moderation states

Admin

PATCH /admin/ads/{id}/moderation

Approve, reject, or return an ad to pending

Admin

GET /admin/users

List users

Admin

GET /admin/commissions

Get the commission log

Admin

GET /admin/comments

List comments for moderation

Admin

PATCH /admin/comments/{id}

Moderate a comment

Admin

GET /health

Check service health

Public

GET /core/token-check

Validate an access token

Authenticated

HANDLE EVERY OUTCOME

Errors & rate limits

200Success

201Created

401Authentication required

403Forbidden

404Not found

422Validation error

429Rate limit exceeded

500Service error

Public requests180 / minute

Authenticated requests240 / minute

Admin requests300 / minute

Commission submissions10 / 5 minutes

Security note

Never share tokens in URLs or public repositories. Store them in Keychain or Keystore on mobile devices.

الأقسام الرئيسية

ابنِ تطبيقك علىحراج تزايد

Quick start

Create an account or sign in

Store the token securely

Send your request

Authentication & tokens

Session lifecycle

Response format

All endpoints

No matching endpoints

Errors & rate limits

ابنِ تطبيقك على
حراج تزايد