Developers Hub

البدء

مقدمة

توفر واجهة برمجة تطبيقات Zixso وصولاً آمنًا وقابلًا للتطوير لإنشاء الروابط وتخصيصها وتحليلها، وهي مصممة للمطورين الذين يتكاملون مع الأدوات الداخلية، أو سير عمل التسويق، أو التطبيقات التي تتعامل مع العملاء.يتم تحديد نطاق كل طلب API إلى منظمة (يُطلق عليه مساحة الارتباط في Zixso). باستخدام حسابات الخدمة المرتبطة بمساحة الرابط الخاصة بك، يمكنك إدارة الروابط القصيرة برمجيًا مع دعم العناوين المخصصة والبيانات الوصفية والعلامات وتحليلات النقر في الوقت الفعلي – كل ذلك بأقل تكلفة إضافية.

مصطلحات

في لوحة معلومات Zixso وواجهة المستخدم، نشير إلى مساحة عمل حسابك باعتبارها مساحة رابط. في واجهة برمجة التطبيقات، يُمثَّل هذا المفهوم نفسه بـ منظمة (org_id). في هذه الوثيقة:

  • مساحة الرابط = مساحة عملك في لوحة معلومات Zixso
  • منظمة (org_id) = نفس مساحة العمل عند الوصول إليها عبر واجهة برمجة التطبيقات
  • هذه المصطلحات قابلة للتبادل وتشير إلى نفس الكيان

مجال واجهة برمجة التطبيقات

https://api.zixso.com/

هذا هو النطاق الجذري لجميع طلبات API الخاصة بـ Zixso. يجب أن تُضاف بادئة مسار إصدار مدعوم إلى جميع نقاط النهاية.

إصدارات واجهة برمجة التطبيقات

ملخص

الإصدار الحالي: v0.0.1

استخدامات زيكسو إصدارات تعتمد على URIحيث يتم تحديد كل إصدار من واجهة برمجة التطبيقات في المسار (على سبيل المثال، /v0.0.1/). هذا يضمن استقرار تكاملك وعدم تأثره بالتغييرات المستقبلية.

سياسة الإصدارات

  • الإصدارات المستقرة متوافقة مع الإصدارات السابقة ضمن نفس الإصدار الرئيسي (v1.x.x).
  • تغييرات جذرية سوف يحدث فقط في إصدار رئيسي جديد (على سبيل المثال، v2.0.0).
  • ستظل الإصدارات الأقدم متاحة ومدعومة حتى يتم إيقافها رسميًا. سيتم الإعلان عن مواعيد إيقافها في سجل التغييرات.
  • Zixso يتبع الإصدارات الدلالية: v{MAJOR}.{MINOR}.{PATCH}.

> نقطة نهاية المثال:: > > GET https://api.zixso.com/v0.0.1/orgs/{org_id}/links >

حسابات الخدمة وبيانات الاعتماد

ملخص

لاستخدام واجهة برمجة التطبيقات Zixso، تحتاج إلى مصادقة كل طلب باستخدام حساب الخدمة —هوية آمنة مقتصرة على مساحة الارتباط الخاصة بك (المؤسسة).

يمكن أن يحتوي كل حساب خدمة على حساب واحد أو أكثر أوراق اعتماد، والتي تستخدم لتوقيع أو تفويض مكالمات API.

الخطوة 1: إنشاء حساب خدمة

  1. اذهب الى الإعدادات → حسابات الخدمة في لوحة معلومات Zixso.
  2. Click + Create Account.
  3. Provide a label (e.g., Link Automation Bot).
  4. Select a role (e.g., Super Administrator or a custom role).
  5. Click Create.

Note: This service account will be scoped to your current link space, which corresponds to the org_id in API calls.

Step 2: Generate Credentials

  1. Open the service account you created.
  2. Click + Add Credential.
  3. Choose an Authentication Type:
    • API Key – simple and fast
    • HMAC – signed requests with timestamps
    • Public/Private Key – cryptographic, ideal for partners
  4. Set a rotation period (e.g., 90 or 180 days).
  5. Click Create.

> The secret key will only be shown once — copy and store it securely.

Authentication

Overview

Zixso supports multiple authentication methods, each using your service account credentials. Choose the method that best fits your use case.

Choosing the Right Method

Method Use Case
API Key Internal tools, backend automation
HMAC Signature Webhooks, secure API integrations
Public Key Federated, external, or zero-trust flows

API Key Authentication

Use Case: Internal automation or testing environments

Header Format

Authorization: APIKey .

Example (Python):

headers = {
    "Authorization": "APIKey f1e87dd7-......",
    "Content-Type": "application/json"
}

HMAC Signature Authentication

Use Case: Server-to-server APIs or signed webhooks

Header Format

Authorization: HMAC key="", timestamp="", 
signature=""

Message Format (for signing)

\n\n\n\n

Example (Python):

import time, hmac, hashlib, base64

key_id = "a83e6f48-..."
secret = "your_hmac_secret"
timestamp = str(int(time.time()))
method = "POST"
path = "/v0.0.1/orgs/{org_id}/links"
body = '{"destination_url":"https://example.com"}'

message = f"{key_id}\n{timestamp}\n{method}\n{path}\n{body}"
signature = base64.b64encode(hmac.new(secret.encode(), message.encode(), hashlib.sha256).digest()).decode()

headers = {
    "Authorization": f'HMAC key="{key_id}", timestamp="{timestamp}", signature="{signature}"',
    "Content-Type": "application/json"
}

Public/Private Key Authentication

Zixso supports asymmetric cryptographic authentication using a private-public key pair. This method is recommended for high-trust integrations, federated services, and zero-trust environments.

Header Format

Authorization: PublicKey key="{credential_id}", timestamp="{unix_ts}", 
algorithm="rsa4096", signature="{base64_signature}"
  • key: UUID of the public key credential (e.g., a83e6f48-...)
  • timestamp: Unix timestamp in seconds (±5 minutes drift allowed)
  • algorithm: Only rsa4096 is supported (as per current backend)
  • signature: Base64-encoded digital signature created from request body and metadata

Message Format for Signature

The following string is constructed exactly as-is and signed with your private RSA key:

\n\n\n\n
  • No extra whitespace
  • BODY must match the actual POST/PUT/PATCH payload (empty string for GET/DELETE)
  • PATH must be relative (e.g., /v0.0.1/orgs/abc123/links)

Python Example (Using cryptography)

import base64
import time
import requests
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding
from cryptography.hazmat.backends import default_backend

# Inputs
credential_id = "f8fcdc8f-db61-4bbb-94b5-4e7d65aae382"
private_key_path = "./private.pem"
timestamp = str(int(time.time()))
method = "POST"
path = "/v0.0.1/orgs/abc123/links"
body = '{"destination_url":"https://example.com"}'

# Build message
message = f"{credential_id}\n{timestamp}\n{method}\n{path}\n{body}".encode("utf-8")

# Load private key
with open(private_key_path, "rb") as key_file:
    private_key = serialization.load_pem_private_key(key_file.read(), password=None)

# Sign
signature = private_key.sign(
    message,
    padding.PKCS1v15(),
    hashes.SHA256()
)
signature_b64 = base64.b64encode(signature).decode()

# Headers
headers = {
    "Authorization": (
        f'PublicKey key="{credential_id}", '
        f'timestamp="{timestamp}", '
        f'algorithm="rsa4096", '
        f'signature="{signature_b64}"'
    ),
    "Content-Type": "application/json"
}

# Make request
response = requests.post("https://api.zixso.com" + path, data=body, headers=headers)
print(response.status_code, response.text)

Notes & Tips

  • The timestamp must be within ±5 minutes of server time (300s skew allowed)
  • signature must be base64-encoded
  • The algorithm must be rsa4096 — other values (e.g., rsa2048, ecdsa) will be rejected
  • Make sure the body string is exactly what will be sent (including spaces and formatting)

API Basics

Overview

Zixso APIs follow standard REST principles with predictable resource-oriented URLs, structured JSON request/response bodies, and conventional HTTP status codes.

All APIs are versioned and accept authenticated requests scoped to a specific organization (link space).

Authentication

All requests must include a valid Authorization header using one of the supported credential types (API Key, HMAC, or Public Key).

Base URL

All API requests are made to:

https://api.zixso.com/v0.0.1/

> Always include the correct version prefix (/v0.0.1/) in your path.

Success Response Format

Most successful responses return a 2xx status code and a structured JSON body:

{
  "id": "2aaf13fc-22a7-4cbb-a7f2-c1be3d9a0dd4",
  "url": "https://example.com"
}

List views follow a consistent pagination structure:

{
  "meta": {
    "pagination": {
      "page": 1,
      "page_size": 10,
      "no_of_records": 53
    }
  },
  "results": [
    { ... }, { ... }
  ]
}

Error Response Format

All error responses follow a consistent structure:

{
  "field_name": [
    "This field is required."
  ]
}

Other examples:

{
  "detail": "Authentication credentials were not provided."
}

Content-Type

All requests and responses use JSON:

Content-Type: application/json
Accept: application/json

HTTP Methods

Method Description
GET Retrieve resources
POST Create new resources
PATCH Update partial fields
PUT Replace entire object
DELETE Delete a resource

Pagination

Paginated endpoints accept:

  • ?page=1
  • ?page_size=25

Default page_size is 10, and max allowed is 100.

Filtering & Query Parameters

Some endpoints support filtering via query parameters (e.g. ?tag=campaign, ?created_after=2025-01-01). Specific filters are documented under each endpoint.

Links API

Overview

The Links API lets you create and manage short links with advanced control — including custom aliases, expiration, password protection, redirection rules, cloaking, and tagging. All operations are scoped to your link space (org_id).

Create a Link

POST /orgs/{org_id}/links

Creates a new short link with optional customization. You can provide a custom alias, set expiration, enable cloaking, add password protection, and define redirection rules.

Request Headers

Authorization: APIKey .
Content-Type: application/json

Request Body

{
  "url": "https://www.google.com",
  "alias": "link-to-google",
  "label": "Google Redirect",
  "tags": ["campaign", "summer"],
  "password": "secret123",
  "expiration_time": "2025-12-31T23:59:59Z",
  "cloak": true,
  "redirection_rules": [
    {
      "match": "AND",
      "conditions": [
        { "field": "COUNTRY", "operator": "EQUAL", "value": "IN" }
      ],
      "url": "https://www.google.co.in"
    }
  ]
}

Response

{
    "id": "4c272584-a2ad-4f1c-9996-6fc03de89d1c",
    "url": "https://www.google.com",
    "label": "Google Redirect",
    "domain": null,
    "domain_name": "127.0.0.1:8080",
    "alias": "link-to-google",
    "is_password_protected": true,
    "expiration_time": "2025-12-31T23:59:59Z",
    "cloak": true,
    "redirection_rules": [
        {
            "match": "AND",
            "conditions": [
                {
                    "field": "COUNTRY",
                    "operator": "EQUAL",
                    "value": "IN"
                }
            ],
            "url": "https://www.google.co.in"
        }
    ],
    "tags": [
        "campaign",
        "summer"
    ],
    "created_at": "2025-07-12T12:41:52.174812Z"
}

Key Notes

  • If password is provided, is_password_protected will be true — the actual password is never returned.
  • domain is optional; if omitted, the default domain is used.
  • tags must follow the lowercase-alphanumeric-hyphen format (^[a-z0-9-]{1,30}$) and be unique.
  • redirection_rules must follow strict structure and include either a url or deeplink, not both.

List Links

GET /orgs/{org_id}/links

Retrieve all links under your link space.

Query Parameters

  • page=1 (default: 1)
  • page_size=25 (max: 100)
  • q=keyword (searches alias, domain, and back-half)

Example Response

{
    "meta": {
        "pagination": {
            "page": 1,
            "page_size": 10,
            "no_of_records": 1
        }
    },
    "results": [{
        "id": "4c272584-a2ad-4f1c-9996-6fc03de89d1c",
        "url": "https://www.google.com",
        "label": "Homepage Redirect",
        "domain": null,
        "domain_name": "127.0.0.1:8080",
        "alias": "link-to-google",
        "is_password_protected": true,
        "expiration_time": "2025-12-31T23:59:59Z",
        "cloak": true,
        "redirection_rules": [{
            "url": "https://www.google.co.in",
            "match": "AND",
            "conditions": [{
                "field": "COUNTRY",
                "value": "IN",
                "operator": "EQUAL"
            }]
        }],
        "tags": [
            "campaign",
            "summer"
        ],
        "created_at": "2025-07-12T12:41:52.174812Z"
    }]
}

Get Link Details

GET /orgs/{org_id}/links/{link_id}

Retrieve full metadata, click count, tags, and rules for a specific link.

Update a Link

PATCH /orgs/{org_id}/links/{link_id}

Update one or more fields of an existing link.

Request Body

{
  "url": "https://www.google.co.in",
}

Only supplied fields will be updated.

Delete a Link

DELETE /orgs/{org_id}/links/{link_id}

Deletes a link.

Returns: 204 No Content on success.

Advanced Options

Password Protection

Links can be protected with a password (min 6 characters). End-users must enter the password before redirection. Passwords are securely hashed and never stored in plain text.

Expiration

Set expires_at (ISO8601 format) to automatically deactivate a link after a specific date/time.

Cloaking

Set "cloak": true to hide the final destination from browser address bars. This is useful for embedded or promotional flows.

Redirection Rules

Control how and where users are redirected based on country.

Supported Fields

  • country: ISO 3166-1 alpha-2 codes (e.g. US, AE)
  • os: Android, iOS, macOS/iPadOS, Windows, Linux

Supported Operators

  • EQUAL, NOT_EQUAL, IN, NOT_IN

Redirection Types

  • url: traditional web URL
  • deeplink: opens mobile app or falls back to install page

Example Rule

{
  "match": "AND",
  "conditions": [
    { "field": "country", "operator": "EQUAL", "value": "US" },
    { "field": "os", "operator": "IN", "value": ["iOS", "Android"] }
  ],
  "deeplink": {
    "app_link": "myapp://promo",
    "install_url": "https://example.com/download"
  }
}