Tích hợp Square API: OAuth, đồng bộ danh mục, đơn hàng, webhook
Hướng dẫn tích hợp Square API với OAuth, đồng bộ danh mục và tồn kho, thanh toán idempotent cùng webhook có chữ ký bằng Python.
Long Nguyen
Lập trình viên Fullstack · Kỹ sư AI · Nhà nghiên cứu
Tích hợp Square API thực sự bao gồm những gì?
Tích hợp Square API kết nối phần mềm của bạn (cửa hàng trực tuyến, ERP, công cụ đặt lịch hoặc ứng dụng di động) với tài khoản Square của người bán qua REST. Square áp dụng một số phiên bản duy nhất cho toàn bộ API, vì vậy Payments, Orders, Catalog và Inventory được cập nhật đồng bộ; hầu hết các tích hợp thực tế đều sử dụng đồng thời bốn hoặc năm API. Bảng dưới đây cho biết API nào đảm nhiệm từng công việc.
| Công việc | API | Cần biết trước |
|---|---|---|
| Kết nối tài khoản người bán | OAuth API | Trả về access token và refresh token. Ứng dụng máy chủ dùng code flow; ứng dụng di động và single-page app dùng PKCE. |
| Danh mục sản phẩm | Catalog API | Danh mục cung cấp dữ liệu cho thư viện mặt hàng trong Square Dashboard và các mặt hàng hiển thị trên Square Point of Sale. |
| Mức tồn kho | Inventory API | Số lượng chỉ được theo dõi ở cấp biến thể sản phẩm, theo từng địa điểm và trạng thái. |
| Đơn hàng và hoàn tất đơn | Orders API | Ghi nhận các dòng sản phẩm, tính tổng tiền, theo dõi việc hoàn tất đơn và cập nhật tồn kho khi đơn hàng hoàn tất hoặc được hoàn tiền. |
| Tiếp nhận thanh toán | Payments API | Thu tiền từ các phương thức thanh toán được thu thập bằng Square Web Payments SDK hoặc In-App Payments SDK. |
| Phản hồi thay đổi | Webhooks | Các thông báo có chữ ký như catalog.version.updated, inventory.count.updated và oauth.authorization.revoked. |
Trước khi viết bất kỳ đoạn mã nào, hãy xác định một câu hỏi: hệ thống nào là nguồn dữ liệu chuẩn cho sản phẩm, giá và tồn kho? Hướng dẫn đồng bộ danh mục của Square cũng bắt đầu từ đây; mọi quyết định tiếp theo (đồng bộ theo hướng nào, nên đẩy số lượng hay các điều chỉnh, cách truyền tải thao tác xóa) đều phụ thuộc vào câu trả lời. Bỏ qua bước này là nguyên nhân khiến các tích hợp ghi đè giá ở cả hai chiều.
Các phần dưới đây đi theo thứ tự của những vấn đề thường phát sinh khi đưa hệ thống vào vận hành: xác thực, môi trường, đồng bộ, thanh toán, webhook và phiên bản.
Tích hợp Square cần OAuth hay personal access token?
Square cung cấp hai cách lấy access token. Personal access token thuộc về chính tài khoản nhà phát triển của bạn, phù hợp khi bạn chỉ tích hợp tài khoản Square của mình. Khi có người bán khác kết nối với ứng dụng, bạn cần OAuth: người bán phê duyệt các quyền cụ thể trên một trang của Square và ứng dụng nhận được các token chỉ áp dụng cho người bán đó. Một số endpoint vẫn chỉ chấp nhận personal token ngay cả trong ứng dụng OAuth; tài liệu OAuth API của Square nêu rõ Webhook Subscriptions API và Events API không chấp nhận OAuth access token.
| Flow | Dùng cho | Refresh token | Client secret |
|---|---|---|---|
| Code flow | Ứng dụng phía máy chủ do bạn kiểm soát việc lưu trữ | Có thể tái sử dụng; vẫn hợp lệ cho đến khi người bán thu hồi quyền truy cập | Bắt buộc |
| PKCE flow | Ứng dụng di động, single-page app và ứng dụng desktop native | Chỉ dùng một lần; hết hạn sau 90 ngày | Không dùng (được thay thế bằng code_verifier) |
Bạn chọn một flow và sử dụng xuyên suốt; tài liệu nêu rõ không thể kết hợp hai flow này. Với hầu hết tích hợp web, đó sẽ là code flow. Những giới hạn dễ gây nhầm lẫn gồm:
- Authorization code hết hạn sau 5 phút và chỉ dùng được một lần, vì vậy hãy đổi code ngay trong request callback thay vì chuyển nó cho queue.
- Redirect URL phải dùng HTTPS. HTTP thuần trên localhost chỉ được phép trong Sandbox.
- Access token hết hạn sau 30 ngày. Bạn gia hạn bằng refresh token.
- Nếu làm mất refresh token, người bán phải thực hiện lại toàn bộ quy trình cấp quyền.
- Một refresh token của code flow có thể tạo ra nhiều access token, mỗi token có thời hạn 30 ngày riêng và có thể bị thu hồi độc lập. Cách này phù hợp với người bán vận hành nhiều cửa hàng trên cùng một website thương mại điện tử.
- Square OAuth không phải là hệ thống đăng nhập. Nó không hỗ trợ OpenID hoặc các giao thức single sign-on khác trên nền OAuth.
Lỗi ảnh hưởng trực tiếp đến khách hàng thường là token hết hạn, bởi nó xảy ra 30 ngày sau khi onboarding, rất lâu sau khi mọi người đã ngừng theo dõi. Hãy gia hạn theo lịch thay vì chờ lần 401 đầu tiên: một tác vụ hằng ngày làm mới mọi token sẽ hết hạn trong tuần tới giúp checkout đang hoạt động không phải là nơi đầu tiên phát hiện token đã hỏng.
import os
import requests
def refresh_access_token(refresh_token):
# Code flow (confidential client). Under PKCE you omit client_secret
# and must store the new single-use refresh token that comes back.
resp = requests.post(
'https://connect.squareup.com/oauth2/token',
json={
'client_id': os.environ['SQUARE_APP_ID'],
'client_secret': os.environ['SQUARE_APP_SECRET'],
'grant_type': 'refresh_token',
'refresh_token': refresh_token,
},
headers={'Square-Version': os.environ['SQUARE_VERSION']},
timeout=30,
)
resp.raise_for_status()
data = resp.json()
return {
'access_token': data['access_token'],
'expires_at': data['expires_at'],
'refresh_token': data.get('refresh_token', refresh_token),
}
Đồng thời, hãy đăng ký oauth.authorization.revoked. Sự kiện này được gửi khi người bán thu hồi mọi token đã cấp cho ứng dụng của bạn. Khi nhận được sự kiện, hãy dừng đồng bộ với merchant đó và xóa các token đã lưu, thay vì để tác vụ làm mới tiếp tục thất bại với tài khoản này mỗi đêm.
Square Sandbox khác production như thế nào?
Sandbox và production là hai môi trường riêng biệt với thông tin xác thực riêng. Việc trộn lẫn chúng sẽ trả về AUTHENTICATION_ERROR với mã UNAUTHORIZED, trông hoàn toàn giống token không hợp lệ. Khi request thất bại với lỗi này, hãy kiểm tra môi trường trước khi kiểm tra scope.
| Production | Sandbox | |
|---|---|---|
| API base URL | https://connect.squareup.com/v2 |
https://connect.squareupsandbox.com/v2 |
| OAuth base URL | https://connect.squareup.com/oauth2 |
https://connect.squareupsandbox.com/oauth2 |
| Application ID và token | ID production và token production | ID Sandbox và token Sandbox; không thể dùng thay thế cho nhau |
| Đăng nhập trên trang cấp quyền | Đăng nhập trực tiếp | Không thể; trước tiên hãy mở Sandbox Dashboard cho tài khoản thử nghiệm trong một tab khác. Tham số session=false không được hỗ trợ. |
| Redirect URL | HTTPS | HTTPS hoặc HTTP trên localhost |
Vì OAuth trên Sandbox khá bất tiện, hãy kiểm thử toàn bộ quy trình cấp quyền một lần, sau đó dùng tài khoản thử nghiệm Sandbox và access token được tạo cho tài khoản đó trong mọi tác vụ còn lại (danh mục, đơn hàng, thanh toán). Square hỗ trợ tạo các token này cho tài khoản thử nghiệm với quyền cụ thể, nhanh hơn nhiều so với việc lặp lại màn hình chấp thuận.
Cách đồng bộ danh mục và tồn kho Square với cửa hàng
Gửi thay đổi từ Square về hệ thống của bạn
Hướng dẫn đồng bộ danh mục với nền tảng bên ngoài của Square mô tả hai trigger: phản hồi webhook catalog.version.updated hoặc polling theo khoảng thời gian cố định. Trong cả hai trường hợp, bạn gọi SearchCatalogObjects với begin_time để Square chỉ trả về những gì đã thay đổi. Ba chi tiết quyết định việc này có hoạt động đúng hay không:
- Lưu timestamp từ sự kiện trước đó, không phải sự kiện hiện tại.
catalog_version.updated_atcủa sự kiện đánh dấu thời điểm phiên bản mới được tạo, vì vậy các thay đổi tạo ra sự kiện nằm sau mốc trước đó. - Thay đổi có thể đến từ mọi nơi: Dashboard, Square Point of Sale và bất kỳ tích hợp nào khác mà người bán đang sử dụng. Logic của bạn không được giả định ứng dụng của mình là bên ghi dữ liệu duy nhất.
- Không gọi
ListCatalogtheo lịch hoặc sau mỗi sự kiện. Tập kết quả sẽ lớn dần và khiến ứng dụng của bạn dễ bị giới hạn tốc độ.
Các thao tác xóa sẽ được trả về trong những lần tìm kiếm sau với is_deleted bằng true, vì vậy hãy yêu cầu cả các object đã xóa và truyền trạng thái đó sang hệ thống của bạn; nếu không, cửa hàng vẫn có thể tiếp tục bán những mặt hàng người bán đã xóa.
import os
import requests
BASE = 'https://connect.squareup.com/v2'
def square_headers(access_token):
return {
'Authorization': f'Bearer {access_token}',
'Square-Version': os.environ['SQUARE_VERSION'],
'Content-Type': 'application/json',
}
def catalog_changes_since(access_token, begin_time):
cursor = None
while True:
body = {
'begin_time': begin_time,
'object_types': ['ITEM', 'ITEM_VARIATION'],
'include_deleted_objects': True,
}
if cursor:
body['cursor'] = cursor
resp = requests.post(f'{BASE}/catalog/search', json=body,
headers=square_headers(access_token), timeout=30)
resp.raise_for_status()
data = resp.json()
yield from data.get('objects', [])
cursor = data.get('cursor')
if not cursor:
break
def on_catalog_version_updated(event, state):
# state['last_sync'] holds the previous event's catalog_version.updated_at
new_marker = event['data']['object']['catalog_version']['updated_at']
for obj in catalog_changes_since(state['access_token'], state['last_sync']):
if obj.get('is_deleted'):
remove_from_store(obj['id']) # your function
else:
upsert_into_store(obj) # your function
state['last_sync'] = new_marker # advance only after success
Gửi thay đổi từ hệ thống của bạn sang Square
Khi nền tảng của bạn là nơi quản lý danh mục chính, hãy đẩy thay đổi bằng các endpoint upsert và delete, đồng thời gom các thao tác tương tự thành từng batch. BatchUpsertCatalogObjects chấp nhận tối đa 10.000 object và chỉ tạo một thông báo webhook thay vì hàng nghìn thông báo, qua đó bảo vệ cả webhook handler của bạn. Lưu external ID trên object Square dưới dạng giá trị custom attribute và lưu Square object ID ở phía bạn, để mọi lần cập nhật sau đều bắt đầu bằng thao tác tra cứu thay vì đối chiếu không chắc chắn.
Đồng bộ hai chiều là cái bẫy thường gặp. Hướng dẫn của Square cảnh báo về rủi ro đồng thời, hợp nhất và xóa trùng, cũng như rủi ro về giá: thay đổi giá trên POS có thể âm thầm ghi đè giá trực tuyến, trong khi người bán có thể muốn mức giá khác nhau cho từng kênh. Nếu bắt buộc phải đồng bộ hai chiều, hãy quy định rõ bên nào được ưu tiên cho từng trường dữ liệu.
Tồn kho là tập hợp các trạng thái, không phải một con số
Inventory theo dõi số lượng chuyển qua các trạng thái như IN_STOCK, SOLD và WASTE tại một địa điểm, thay vì giảm một bộ đếm duy nhất. Chỉ biến thể sản phẩm mới được theo dõi; API không hỗ trợ theo dõi thành phần, nguyên liệu hoặc bộ sản phẩm, vì vậy kit hay sản phẩm theo công thức cần có logic riêng trong hệ thống của bạn. Đọc dữ liệu cần quyền INVENTORY_READ, còn ghi dữ liệu cần INVENTORY_WRITE.
| Object | Lưu trữ | Bên thiết lập |
|---|---|---|
| InventoryCount | Số lượng được tính toán của một biến thể tại một địa điểm, trong một trạng thái | Square, tính lại sau mỗi lần điều chỉnh hoặc kiểm kê thực tế |
| InventoryAdjustment | Số lượng chuyển từ trạng thái này sang trạng thái khác | Bán hàng, nhập kho, hao hụt hoặc ứng dụng của bạn |
| InventoryPhysicalCount | Số lượng đã xác minh từ một lần kiểm kê thủ công hoặc hệ thống đáng tin cậy | Bạn |
| InventoryTransfer | Đã ngừng sử dụng ở phiên bản Square . Việc chuyển giữa các địa điểm hiện là một adjustment, trong đó from_location_id và to_location_id khác nhau. |
Chuyển sang dùng adjustments |
Hệ quả thực tế là một lần kiểm kê thực tế sẽ ghi đè phép tính của Square. Nếu hệ thống của bạn đọc số lượng, mất vài giây xử lý rồi ghi ngược lại dưới dạng physical count, bất kỳ giao dịch bán hàng tại cửa hàng nào xảy ra trong khoảng thời gian đó sẽ bị xóa khỏi số liệu. Quy tắc an toàn là đẩy các adjustment (delta) trong khi Square Point of Sale vẫn đang bán hàng, và chỉ dùng physical count cho đối soát theo lịch hoặc khi hệ thống của bạn thực sự là nơi sở hữu số lượng chuẩn. Hãy đăng ký inventory.count.updated để nhận biết các thay đổi số lượng ngay khi chúng xảy ra.
Đơn hàng, thanh toán và idempotency key
Quy trình phù hợp là tạo đơn hàng trong Orders API, sau đó thanh toán bằng CreatePayment với tham chiếu đến đơn hàng đó. Đơn hàng có thể được tạo từ mặt hàng trong danh mục hoặc từ các dòng sản phẩm tùy ý định nghĩa ngay khi tạo, và bạn có thể tìm kiếm chúng về sau, kể cả theo khách hàng. Khi đơn hàng hoàn tất hoặc được hoàn tiền, Square sẽ cập nhật tồn kho cho các mặt hàng trong đơn; vì vậy nếu bạn cũng ghi inventory adjustment cho cùng giao dịch bán hàng, số lượng sẽ bị trừ hai lần. Hãy quyết định bên nào chịu trách nhiệm giảm tồn kho và duy trì nhất quán.
Mạng có thể gặp lỗi sau khi giao dịch thu tiền đã thành công, và đó chính là lúc một lần thử lại đơn giản có thể thu tiền khách hàng hai lần. Square xử lý vấn đề này bằng idempotency key: gửi lại request với cùng key và cùng body sẽ nhận lại response ban đầu thay vì tạo giao dịch thứ hai. Nếu dùng lại key với body đã thay đổi (chẳng hạn số tiền khác), bạn sẽ nhận lỗi, dù Square lưu ý rằng hành vi này có thể thay đổi tùy API.
Sai lầm phổ biến là tạo UUID ngẫu nhiên mới bên trong vòng lặp retry, khiến cơ chế bảo vệ hoàn toàn mất tác dụng. Thay vào đó, hãy tạo key từ các mã định danh của chính bạn và chỉ thay đổi key khi khách hàng chủ động bắt đầu một lần thanh toán mới, chẳng hạn dùng một thẻ khác.
import os
import uuid
import requests
NAMESPACE = uuid.UUID('6ba7b810-9dad-11d1-80b4-00c04fd430c8') # any fixed UUID
def charge_order(access_token, order_id, location_id, source_token,
amount_cents, attempt=1, currency='USD'):
# Same order + same attempt = same key, so network retries cannot double-charge.
key = str(uuid.uuid5(NAMESPACE, f'payment:{order_id}:{attempt}'))
body = {
'idempotency_key': key,
'source_id': source_token,
'order_id': order_id,
'location_id': location_id,
'amount_money': {'amount': amount_cents, 'currency': currency},
}
resp = requests.post(
'https://connect.squareup.com/v2/payments',
json=body,
headers={
'Authorization': f'Bearer {access_token}',
'Square-Version': os.environ['SQUARE_VERSION'],
'Content-Type': 'application/json',
},
timeout=30,
)
resp.raise_for_status()
return resp.json()['payment']
Có một chi tiết thương mại cần được tính đến ngay từ giai đoạn thiết kế. Tính đến , tài liệu Orders API của Square cho biết không có phí giao dịch đối với đơn hàng được thanh toán bằng Square payments, và có phí 1% cho mỗi giao dịch nếu bạn dùng Orders API với nhà cung cấp thanh toán không phải Square. Hãy xác nhận điều khoản hiện hành với Square trước khi xây dựng quy trình phụ thuộc vào sự khác biệt này.
Cách xác thực Square webhook và xử lý sự kiện trùng lặp
URL nhận thông báo của bạn là public, vì vậy bất kỳ ai cũng có thể gửi request đến đó. Mọi thông báo của Square đều có header x-square-hmacsha256-signature; bạn phải tính lại chữ ký và loại bỏ mọi request không khớp.
| Vấn đề | Square cung cấp |
|---|---|
| Tính xác thực | Chữ ký HMAC-SHA-256 được tạo từ signature key của subscription, notification URL và raw request body |
| So sánh | Dùng phép so sánh constant-time; Square cảnh báo phép so sánh dừng ở khác biệt đầu tiên có thể bị tấn công timing, và khả năng hỗ trợ constant-time khác nhau tùy helper của SDK |
| Sự kiện trùng lặp | Trường event_id trong body, được cung cấp như giá trị idempotency; bỏ qua các sự kiện đã xử lý |
| Tình trạng endpoint | Nếu endpoint không trả về 2xx trong ba tuần, Square sẽ gửi email cảnh báo sau tuần thứ nhất, thứ hai và thứ ba, sau đó vô hiệu hóa subscription |
Vì chữ ký bao phủ notification URL và raw body, hai lỗi thường gây ra phần lớn trường hợp từ chối nhầm. Lỗi đầu tiên là framework phân tích JSON rồi handler tuần tự hóa lại, làm thay đổi các byte. Lỗi thứ hai là proxy hoặc CDN thay đổi scheme hay host, khiến URL mà code dựng lại từ request không còn trùng với URL đã đăng ký. Hãy đọc raw body và lấy notification URL từ cấu hình thay vì dựng lại từ request gửi đến.
import json
from django.conf import settings
from django.core.cache import cache
from django.http import HttpResponse, HttpResponseForbidden
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_POST
from square.utils.webhooks_helper import verify_signature
@csrf_exempt
@require_POST
def square_webhook(request):
body = request.body.decode('utf-8') # raw body, never re-serialized JSON
signature = request.headers.get('x-square-hmacsha256-signature', '')
if not verify_signature(
request_body=body,
signature_header=signature,
signature_key=settings.SQUARE_WEBHOOK_SIGNATURE_KEY,
notification_url=settings.SQUARE_WEBHOOK_URL, # exactly as registered
):
return HttpResponseForbidden()
event = json.loads(body)
# cache.add returns False when the key exists, i.e. we have seen this event
if not cache.add('square:event:' + event['event_id'], 1, timeout=7 * 24 * 3600):
return HttpResponse(status=200)
process_square_event.delay(event) # your task queue; return fast
return HttpResponse(status=200)
Hãy xác nhận trước rồi xử lý sau: xác thực, loại trùng, đưa vào queue và trả về 200. Trong môi trường production, hãy thay bước kiểm tra cache bằng unique constraint trên event_id trong database để cơ chế loại trùng vẫn hoạt động sau khi cache bị xóa.
Ghim phiên bản Square API và lập kế hoạch nâng cấp
Square đánh phiên bản API bằng ngày phát hành theo định dạng YYYY-MM-DD, thường là mỗi tháng một phiên bản; một phiên bản duy nhất áp dụng cho mọi API. Mỗi ứng dụng đăng ký trong Developer Console có một phiên bản mặc định được ghim, hiển thị trên trang Credentials; phiên bản mặc định này được dùng cho mọi request trừ khi bạn ghi đè bằng header Square-Version. Response luôn phản ánh phiên bản đã được sử dụng, vì vậy hãy ghi lại thông tin đó.
| Thay đổi từ Square | Có gây lỗi tương thích? |
|---|---|
| Endpoint mới | Không |
| Trường mới không bắt buộc hoặc chỉ đọc | Không |
| Deprecation | Không, nhưng được đánh phiên bản để bạn nhận biết |
| Trường bắt buộc mới | Có |
| Ngừng cung cấp | Có |
| Đổi tên hoặc thay đổi cấu trúc của trường, kiểu dữ liệu hay hằng chuỗi | Có |
| Mã trạng thái HTTP khác cho một thao tác | Có |
Việc InventoryTransfer bị ngừng cung cấp ở phiên bản là một ví dụ cụ thể: code được ghim ở phiên bản cũ vẫn hoạt động, nhưng chính code đó sẽ hỏng ngay khi bạn chuyển sang sau ngày này. Vì vậy, hãy gửi Square-Version một cách rõ ràng từ cấu hình của chính bạn thay vì phụ thuộc vào phiên bản mặc định trong console, đồng thời nâng cấp có chủ đích. Một lần nâng cấp bao gồm mọi thay đổi kể từ phiên bản trước, vì vậy hãy đọc release note của từng phiên bản trung gian và chạy bộ kiểm thử với header mới trên Sandbox trước khi tác động đến production. Cũng cần lưu ý rằng SDK Java, Ruby, Python và PHP đặt ngày API ở cuối số phiên bản, còn SDK .NET, Node.js và Go thì không; hãy kiểm tra phiên bản API mà một bản phát hành SDK cụ thể hướng tới.
Tự xây tích hợp Square hay dùng connector có sẵn?
Connector có sẵn là lựa chọn phù hợp khi danh mục của bạn nhỏ, một hệ thống rõ ràng là nơi sở hữu dữ liệu chính và bạn chỉ cần sản phẩm, đơn hàng cùng thanh toán đi theo một chiều. Tự xây dựng bắt đầu đáng giá khi hai danh mục phải nhất quán trên nhiều kênh bán hàng, khi tồn kho có những quy tắc mà mô hình Square không thể thể hiện (bundle, kit, hàng giữ chỗ), hoặc khi dữ liệu đơn hàng và khách hàng phải được đưa vào ERP hay CRM cùng logic nghiệp vụ riêng.
Nếu bạn đang kết nối Square với Shopify, WooCommerce, BigCommerce hoặc cửa hàng tùy chỉnh, đồng thời gặp các rủi ro nêu trên (thay đổi giá hai chiều, ghi đè tồn kho, token hết hạn), đó chính là phần việc tích hợp nền tảng và API được đề cập trong dịch vụ tích hợp nền tảng thương mại điện tử và API của Netalith.
Checklist tích hợp Square API trước khi vận hành
- Lưu thông tin xác thực, base URL và token của Sandbox và production trong các cấu hình riêng biệt, tuyệt đối không hard-code.
- Thiết lập tác vụ theo lịch để làm mới token cho mọi người bán đã kết nối, lưu refresh token dưới dạng mã hóa và xử lý
oauth.authorization.revoked. - Gửi
Square-Versionmột cách rõ ràng và ghi lại phiên bản được trả về trong mỗi response. - Tạo idempotency key từ mã đơn hàng và mã lần thử của chính bạn, không tạo từ một giá trị ngẫu nhiên mới ở mỗi lần retry.
- Xác thực chữ ký webhook bằng raw body, loại trùng dựa trên
event_idvà trả về 200 trước khi thực hiện tác vụ chậm. - Lưu external ID trên object Square và Square ID ở phía bạn; ghi dữ liệu theo batch; không bao giờ polling bằng
ListCatalog. - Chủ động lựa chọn giữa inventory adjustment và physical count, đồng thời lên lịch tác vụ đối soát.
- Sử dụng API logs và webhook event logs trong Developer Console khi request hoặc việc gửi sự kiện gặp vấn đề.
Nếu bạn muốn hệ thống được xây dựng và kiểm thử trên chính danh mục cùng các kênh bán hàng của mình, hãy mô tả phạm vi qua biểu mẫu nhận báo giá miễn phí của Netalith.
CÂU HỎI THƯỜNG GẶP
Câu hỏi thường gặp
Tôi cần OAuth cho tích hợp Square API hay personal access token là đủ?
Personal access token là đủ khi bạn chỉ tích hợp tài khoản Square của mình. Nếu người bán khác sẽ kết nối với ứng dụng, bạn cần OAuth để mỗi người bán cấp các quyền cụ thể và ứng dụng nhận token chỉ áp dụng cho người bán đó. Một số endpoint, chẳng hạn Webhook Subscriptions API và Events API, chỉ chấp nhận personal access token ngay cả trong ứng dụng OAuth.
Access token Square OAuth có hiệu lực trong bao lâu?
Access token Square OAuth hết hạn sau 30 ngày. Bạn gia hạn bằng refresh token. Trong code flow, refresh token không hết hạn cho đến khi người bán thu hồi quyền truy cập; trong PKCE flow, refresh token chỉ dùng một lần và hết hạn sau 90 ngày. Hãy làm mới theo lịch trước khi hết hạn thay vì chờ một request thất bại.
Làm thế nào để xác thực Square webhook?
Tính chữ ký HMAC-SHA-256 từ signature key của subscription, notification URL và raw request body, sau đó so sánh bằng constant-time với header x-square-hmacsha256-signature. Từ chối mọi request không khớp. Square SDK có helper hỗ trợ việc này; bạn cũng nên bỏ qua các sự kiện lặp bằng cách kiểm tra event_id trong body.
Làm thế nào để đồng bộ tồn kho Square với cửa hàng trực tuyến?
Trước tiên, hãy xác định hệ thống nào sở hữu số lượng tồn kho chuẩn. Theo dõi inventory.count.updated để nhận các thay đổi từ Square và đẩy thay đổi ngược lại dưới dạng inventory adjustment trong khi Square Point of Sale vẫn đang bán hàng. Chỉ dùng physical count cho việc đối soát theo lịch hoặc khi hệ thống của bạn thực sự sở hữu số lượng, bởi physical count sẽ ghi đè số lượng được Square tính toán.
Square Orders API có phát sinh thêm phí không?
Tính đến ngày 29 tháng 9 năm 2026, tài liệu của Square cho biết không có phí giao dịch đối với đơn hàng được thanh toán bằng Square payments và có phí 1% cho mỗi giao dịch khi bạn dùng Orders API với nhà cung cấp thanh toán không phải Square. Điều khoản có thể thay đổi, vì vậy hãy xác nhận mức phí hiện hành với Square trước khi thiết kế quy trình dựa trên thông tin này.