🔌 API Overview

Dokumentasi lengkap REST API PintarX untuk integrasi dengan sistem Anda.

🎯 Apa itu PintarX API?

PintarX API adalah REST API yang memungkinkan Anda mengintegrasikan fitur WhatsApp automation dengan aplikasi atau sistem backend Anda.

Use Cases API:

• 🔄 Automasi Workflow - Trigger pesan dari sistem CRM/ERP
• 📊 Sinkronisasi Data - Sync kontak, pesan, logs
• 🤖 Custom Logic - Build automation sesuai kebutuhan
• 🔔 Notifikasi Real-time - Send alerts via WhatsApp
• 📱 Multi-channel Integration - Integrasikan dengan channel lain

🚀 Quick Start

1. Dapatkan API Key

1. Login ke dashboard PintarX
2. Buka menu Settings → API Keys
3. Klik Generate New API Key
4. Copy dan simpan API Key Anda

API Key: pintarx_live_1234567890abcdefghijklmnop

Keamanan

Jangan share API Key ke publik. Simpan dengan aman seperti password.

2. Base URL

Production: https://api.pintarx.space/v1
Sandbox: https://sandbox-api.pintarx.space/v1

3. Authentication

Semua request harus include Bearer Token di header:

Authorization: Bearer pintarx_live_1234567890abcdefghijklmnop

4. Test Connection

Test API Key Anda:

curl -X GET https://api.pintarx.space/v1/auth/me \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": true,
  "data": {
    "sellerId": "uuid-1234",
    "businessName": "Toko Elektronik Jaya",
    "email": "owner@tokojaya.com",
    "plan": "business",
    "apiQuota": {
      "limit": 200000,
      "used": 12345,
      "remaining": 187655
    }
  }
}

📚 API Endpoints

Authentication

• GET /auth/me - Get current user info

WhatsApp Pairing

• GET /whatsapp/devices - List connected WhatsApp numbers
• GET /whatsapp/qr/:deviceId - Get QR code for pairing
• POST /whatsapp/disconnect/:deviceId - Disconnect device

Messages

• POST /messages/send - Send single message
• POST /messages/send-bulk - Send bulk messages
• POST /messages/send-template - Send using template
• GET /messages/:messageId - Get message status
• GET /message-logs - Get message history

Contacts

• GET /contacts - List all contacts
• POST /contacts - Create new contact
• GET /contacts/:contactId - Get contact detail
• PUT /contacts/:contactId - Update contact
• DELETE /contacts/:contactId - Delete contact
• POST /contacts/import - Bulk import contacts

Templates

• GET /templates - List all templates
• POST /templates - Create new template
• GET /templates/:templateId - Get template detail
• PUT /templates/:templateId - Update template
• DELETE /templates/:templateId - Delete template

Auto Reply

• GET /auto-reply/rules - List auto reply rules
• POST /auto-reply/rules - Create auto reply rule
• PUT /auto-reply/rules/:ruleId - Update rule
• DELETE /auto-reply/rules/:ruleId - Delete rule

AI (Coming Soon)

• GET /ai/settings - Get AI configuration
• PUT /ai/settings - Update AI settings
• GET /ai/knowledge - List knowledge base
• POST /ai/knowledge - Add knowledge entry
• POST /ai/test - Test AI response

Webhooks

• GET /webhooks - List webhook configs
• POST /webhooks - Create webhook
• PUT /webhooks/:webhookId - Update webhook
• DELETE /webhooks/:webhookId - Delete webhook

🔐 Authentication

API Key Types

Type	Format	Usage
Live	pintarx_live_xxx	Production environment
Test	pintarx_test_xxx	Development/testing

Header Format

Authorization: Bearer pintarx_live_1234567890abcdefghijklmnop
Content-Type: application/json

Example Request

curl -X POST https://api.pintarx.space/v1/messages/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "uuid-device",
    "to": "6281234567890",
    "message": "Halo dari API!"
  }'

📥 Response Format

Success Response

{
  "success": true,
  "data": {
    // Response data
  },
  "message": "Operation successful",
  "timestamp": "2024-01-15T10:30:45Z"
}

Error Response

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Phone number format invalid",
    "details": {
      "field": "to",
      "issue": "Must start with country code"
    }
  },
  "timestamp": "2024-01-15T10:30:45Z"
}

Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request (invalid parameters)
401	Unauthorized (invalid API key)
403	Forbidden (insufficient permissions)
404	Not Found
429	Rate Limit Exceeded
500	Internal Server Error

🚦 Rate Limiting

Limits by Plan

Plan	Requests/Minute	Requests/Day
Lite	10	1,000
Pro	60	10,000
Business	300	100,000
Enterprise	1,000	Unlimited

Rate Limit Headers

Response headers include rate limit info:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1705315845

Handling Rate Limits

If you exceed the limit:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "API rate limit exceeded",
    "details": {
      "limit": 60,
      "retryAfter": 42
    }
  }
}

Best Practice:

• Implement exponential backoff
• Cache responses when possible
• Batch requests using bulk endpoints

🔔 Webhooks

Webhook Events

PintarX dapat send webhook ke URL Anda untuk event:

• message.incoming - Pesan masuk
• message.sent - Pesan terkirim
• message.delivered - Pesan delivered
• message.read - Pesan dibaca
• message.failed - Pesan gagal
• device.connected - WhatsApp connected
• device.disconnected - WhatsApp disconnected

Webhook Payload

{
  "event": "message.incoming",
  "timestamp": "2024-01-15T10:30:45Z",
  "data": {
    "messageId": "msg-12345",
    "deviceId": "device-uuid",
    "from": "6281234567890",
    "message": "Halo, ada promo?",
    "messageType": "text",
    "timestamp": "2024-01-15T10:30:45Z"
  }
}

Webhook Security

Verify webhook authenticity using signature:

X-PintarX-Signature: sha256=abcdef1234567890...

Verify signature:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  return `sha256=${hash}` === signature;
}

📖 Code Examples

JavaScript/Node.js

const axios = require('axios');

const apiKey = 'pintarx_live_YOUR_API_KEY';
const baseURL = 'https://api.pintarx.space/v1';

const api = axios.create({
  baseURL,
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  }
});

// Send message
async function sendMessage(deviceId, to, message) {
  try {
    const response = await api.post('/messages/send', {
      deviceId,
      to,
      message
    });
    
    console.log('Message sent:', response.data);
    return response.data;
  } catch (error) {
    console.error('Error:', error.response.data);
    throw error;
  }
}

// Usage
sendMessage('device-uuid', '6281234567890', 'Halo dari API!');

Python

import requests

API_KEY = 'pintarx_live_YOUR_API_KEY'
BASE_URL = 'https://api.pintarx.space/v1'

headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
}

# Send message
def send_message(device_id, to, message):
    url = f'{BASE_URL}/messages/send'
    payload = {
        'deviceId': device_id,
        'to': to,
        'message': message
    }
    
    response = requests.post(url, json=payload, headers=headers)
    
    if response.status_code == 200:
        print('Message sent:', response.json())
        return response.json()
    else:
        print('Error:', response.json())
        raise Exception(response.json())

# Usage
send_message('device-uuid', '6281234567890', 'Halo dari Python!')

PHP

<?php

$apiKey = 'pintarx_live_YOUR_API_KEY';
$baseURL = 'https://api.pintarx.space/v1';

function sendMessage($deviceId, $to, $message) {
    global $apiKey, $baseURL;
    
    $url = $baseURL . '/messages/send';
    
    $data = [
        'deviceId' => $deviceId,
        'to' => $to,
        'message' => $message
    ];
    
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json'
    ]);
    
    $response = curl_exec($ch);
    $statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($statusCode == 200) {
        echo "Message sent: " . $response . "\n";
        return json_decode($response, true);
    } else {
        echo "Error: " . $response . "\n";
        throw new Exception($response);
    }
}

// Usage
sendMessage('device-uuid', '6281234567890', 'Halo dari PHP!');
?>

cURL

# Send message
curl -X POST https://api.pintarx.space/v1/messages/send \
  -H "Authorization: Bearer pintarx_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "device-uuid",
    "to": "6281234567890",
    "message": "Halo dari cURL!"
  }'

🧪 Testing

Postman Collection

Download Postman collection:

• PintarX API Collection.json

Sandbox Environment

Use sandbox for testing:

Sandbox URL: https://sandbox-api.pintarx.space/v1

Sandbox features:

• ✅ Test all endpoints
• ✅ No real messages sent
• ✅ Unlimited requests
• ✅ Mock responses

📊 API Quota

Check Quota

GET /auth/me

Response includes quota:

{
  "apiQuota": {
    "limit": 200000,
    "used": 12345,
    "remaining": 187655,
    "resetAt": "2024-02-01T00:00:00Z"
  }
}

Quota by Plan

Plan	API Calls/Month
Lite	10,000
Pro	100,000
Business	500,000
Enterprise	Unlimited

📌 Langkah Selanjutnya

Pelajari endpoint spesifik:

➡️ Send Message - Kirim pesan via API

➡️ Kembali ke Dokumentasi - Halaman utama dokumentasi

---

❓ FAQ API

Apakah API gratis?

API included dalam semua paket berbayar. Quota sesuai paket yang dipilih.

Apakah ada SDK official?

Belum ada SDK official. Tapi API menggunakan standard REST, bisa digunakan dengan library HTTP apapun.

Bagaimana cara test API tanpa mengirim pesan asli?

Gunakan Sandbox Environment untuk testing tanpa send pesan real.

Apakah API support GraphQL?

Saat ini hanya REST API. GraphQL support sedang dipertimbangkan.

Bagaimana cara report bug atau request feature API?

Email ke: api-support@pintarx.space atau buat ticket di dashboard.

Apakah ada dokumentasi OpenAPI/Swagger?

Ya, akses Swagger UI di: https://api.pintarx.space/docs