Công thức tích hợp

#n8n

• Gọi API: node HTTP Request → Authentication Generic Credential Type → Header Auth, Name Authorization, Value Bearer dpk_xxx. URL dạng https://<domain>/api/v1/....
• Nhận sự kiện: node Webhook (POST), bật Options → Raw Body. Copy Production URL rồi đăng ký bằng POST /api/v1/webhooks. Kiểm tra chữ ký bằng node Crypto (HMAC, SHA256, hex) trên chuỗi <X-Deplao-Timestamp>.<body gốc>.
• Ví dụ: đơn hàng mới (Webhook từ web bán hàng) → HTTP Request POST /api/v1/accounts/{account_id}/conversations/{thread_id}/messages với body {"text": "Cảm ơn bạn đã đặt đơn #{{$json.order_id}}"}.

#Make (Integromat)

• Gọi API: module HTTP → Make a request, header Authorization: Bearer dpk_xxx, Body type Raw, Content type JSON (application/json).
• Nhận sự kiện: Webhooks → Custom webhook, copy địa chỉ rồi đăng ký webhook Deplao với events cần thiết. Nếu kịch bản không tự kiểm tra chữ ký được, hãy giữ bí mật địa chỉ webhook (Make sinh địa chỉ ngẫu nhiên dài) và chỉ dùng HTTPS.

#Google Apps Script / Google Sheets

Apps Script không đọc được header của request gửi đến (không kiểm tra được chữ ký) và trả 302 cho POST, nên không dùng webhook. Hãy dùng polling với trình kích hoạt theo thời gian (Triggers → Time-driven → mỗi phút):

const BASE = 'https://<domain>/api/v1';

function pollDeplao() {
  const props = PropertiesService.getScriptProperties();
  const key = props.getProperty('DEPLAO_KEY');
  const since = Number(props.getProperty('since') || 0);
  const res = UrlFetchApp.fetch(BASE + '/events?types=message.received&limit=200&since=' + since, {
    headers: { Authorization: 'Bearer ' + key },
    muteHttpExceptions: true,
  });
  const body = JSON.parse(res.getContentText());
  if (!body.success) throw new Error(body.error.code + ': ' + body.error.message);
  const sheet = SpreadsheetApp.getActive().getSheetByName('Tin nhắn');
  body.data.forEach(function (ev) {
    const conv = ev.data.conversation || {};
    const msg = ev.data.message || {};
    sheet.appendRow([new Date(ev.ts), ev.account_id, conv.display_name, msg.text]);
  });
  props.setProperty('since', String(body.pagination.next_since));
}

#Worker hoặc server riêng (gọi API)

const res = await fetch('https://<domain>/api/v1/accounts/0501234567/conversations/8765432109876/messages', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.DEPLAO_KEY,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-1001-shipped', // gửi lại cùng key → không tạo tin trùng
  },
  body: JSON.stringify({ text: 'Đơn hàng #1001 đã giao cho shipper', thread_type: 'user' }),
});
const out = await res.json();
if (!out.success) console.error(out.error.code, out.error.message);

• Idempotency-Key được nhớ 24 giờ (cho tới khi app khởi động lại). Gửi lại cùng key trả nguyên kết quả lần đầu.
• Nhóm chat: "thread_type": "group".

#Sinh SDK và công cụ

npx @openapitools/openapi-generator-cli generate -i http://127.0.0.1:9900/api/v1/openapi.json -g typescript-fetch -o deplao-sdk

• Postman, Insomnia, Bruno: Import → URL http://127.0.0.1:9900/api/v1/openapi.json.
• openapi.json mặc định xem được không cần key. Nếu đã tắt "Tài liệu công khai", thêm header Authorization khi import từ xa.