API & tài liệu

Một khóa. Mọi mô-đun.

Hầu hết phần mềm kinh doanh cung cấp cho bạn một API cho mỗi sản phẩm — một cho quầy thu ngân, một cho kho hàng, một cho hóa đơn, mỗi API có xác thực riêng và cách hiểu riêng về ngày tháng. Kardopal chỉ có một. Cùng một khóa, cùng một URL cơ sở và cùng một ngữ pháp truy vấn có thể truy cập 129 tài nguyên trên 29 mô-đun.

29
Mô-đun
129
Tài nguyên
1
Khóa, một URL cơ sở
200
Số dòng tối đa mỗi trang

Lý do nên phát triển trên API này

Sáu điều đúng ở đây nhưng thường không đúng ở nơi khác.

Tự mô tả

Truy cập URL cơ sở và API sẽ trả về danh mục của chính nó — mọi mô-đun mà khóa của bạn có thể thấy, mọi tài nguyên bên trong nó, trường nào có thể tìm kiếm và trường nào có thể lọc. Bạn không cần trang này để viết tích hợp; bạn cần nó để đưa ra quyết định.

Quyền hạn có kiểm soát

Các phạm vi, tuyến đường và quyền trong ứng dụng được tạo từ một danh sách, vì vậy một quyền không thể được cấp trừ khi có một điểm cuối hỗ trợ nó. Một khóa được giới hạn cho mặt hàng lấy các mục — yêu cầu nó về bảng lương sẽ trả về lỗi 403, chứ không phải một trang trống không báo lỗi.

Một ngữ pháp truy vấn, ở mọi nơi

tìm kiếm, từ, cho đến khi, bỏ qua và lấy có ý nghĩa giống nhau trên hóa đơn và trên các giao dịch kho. Chỉ cần học một lần và tất cả 133 tài nguyên đều tuân theo.

Môi trường của bạn, và chỉ của riêng bạn

Mỗi bảng đều có ID người thuê và mọi truy vấn đều được giới hạn trong người thuê của khóa trước khi đến cơ sở dữ liệu. Không có thao tác đọc chéo người thuê nào có thể sai, vì không có tham số nào có thể yêu cầu điều đó.

Các trường dữ liệu tự động kiểm tra tính hợp lệ

Danh sách trường được đọc từ lược đồ trực tiếp khi khởi động thay vì được duy trì thủ công. Một cột mới sẽ tự động hiển thị; một cột bị loại bỏ sẽ không bao giờ để lại tham chiếu lơ lửng trong tài liệu hoặc lỗi 500 khi gọi lần đầu.

Chỉ đọc, có chủ đích.

Khóa chỉ đọc; không bao giờ ghi. Một tích hợp bị lỗi không thể hủy hóa đơn hoặc di chuyển hàng tồn kho. Bất cứ điều gì thay đổi một bản ghi đều phải thông qua ứng dụng hoặc đăng nhập của nhân viên, nơi nó được gán cho một người và ghi vào nhật ký kiểm toán.

Bắt đầu trong một yêu cầu

Mọi thứ đều là GET. Nếu bạn có thể sử dụng curl, bạn có thể sử dụng cái này.

GET /api/v1Toàn bộ danh mục mà khóa của bạn có thể xem
curl https://api.kardopal.com/api/v1 \
  -H "X-API-Key: kp_live_…"
GET /api/v1/meKiểm tra tính hợp lệ — đây là khóa của ai, và nó có thể đọc những gì
{
  "authType": "api_key",
  "tenant": { "name": "Nova Retail", "plan": "pro" },
  "scopes": ["items", "sales", "pos"]
}
GET /api/v1/items?search=lamp&take=2Mọi tài nguyên, cùng một định dạng
{
  "resource": "items",
  "scope": "items",
  "total": 41,
  "skip": 0,
  "take": 2,
  "hasMore": true,
  "data": [ { "id": "…", "name": "Desk Lamp LED" } ]
}
GET /api/v1/meta/countsSố lượng hàng trên mỗi tài nguyên — xem dữ liệu nào thực sự tồn tại.
curl https://api.kardopal.com/api/v1/meta/counts \
  -H "X-API-Key: kp_live_…"

Năm thông số

Tham sốThực hiệnGhi chú
tìm kiếmKhớp không phân biệt chữ hoa chữ thường trên các trường có thể tìm kiếm của tài nguyên.Các trường đó được liệt kê trong /meta
từChỉ các bản ghi từ ngày này trở điÁp dụng cho trường mà tài nguyên sắp xếp theo
cho đến khiChỉ ghi nhận đến ngày nàyKết hợp với từ cho một cửa sổ
bỏ quaBù đắp vào tập kết quả.Mặc định là 0
lấySố dòng trả vềMặc định là 50, tối đa 200

Các tài nguyên cũng chấp nhận bộ lọc khớp chính xác trên các trường được khai báo của riêng chúng — ?status=paid, ?warehouseId=… — và mỗi cái đều quảng cáo những cái đó là gì. Mọi phản hồi danh sách đều mang theo tổng cộng và có thêm, để phân trang là một vòng lặp, không phải một phỏng đoán.

API có thể truy cập những gì

29 mô-đun, 129 tài nguyên. Mỗi thẻ là một quyền bạn có thể cấp cho một khóa — và thẻ màu xám là nơi các bản ghi tương tự nằm trong ứng dụng trên điện thoại của bạn.

Danh bạ

2

Khách hàng, nhà cung cấp và các phân khúc mà họ thuộc về.

liên hệphân khúc liên hệ
liên hệ Danh bạ

Mặt hàng

7

Danh mục: sản phẩm, biến thể, thương hiệu, bảng giá và đơn vị.

mặt hàngdanh mụcthương hiệubiến thể mặt hàngprice-listsđơn vị+1 nữa
mặt hàng Mặt hàng

Quản lý kho

7

Kho hàng, mức tồn kho, di chuyển hàng hóa, lô hàng, số sê-ri và vị trí lưu trữ.

kho hàngstock-movementsmức tồn khobatchessố sê-rikiểm kê kho+1 nữa
inventory Quản lý kho

Bán hàng

7

Hóa đơn, báo giá, đơn hàng, phiếu ghi nợ và thanh toán.

hóa đơnước tínhđơn hàng bánphiếu ghi nợthanh toánhóa đơn định kỳ+1 nữa
doanh số Bán hàng

POS

11

Máy tính tiền, ca làm việc, biên lai, bàn và mọi giao dịch bán hàng qua quầy.

doanh số POSca-làm-việc-posthiết bị POSngười dùng POSbàn POSkhu vực bàn POS+5 nữa
pos POS

CRM

4

Khách hàng tiềm năng, giao dịch, quy trình và đề xuất.

khách hàng tiềm nănggiao dịchquy trìnhđề xuất
crm CRM

Mua hàng

5

Đơn đặt hàng, yêu cầu, trả hàng, hóa đơn và thanh toán nhà cung cấp.

đơn đặt hàngyêu cầu mua hàngTrả hàng muahóa đơnThanh toán cho nhà cung cấp
mua hàng Mua hàng

Kế toán

5

Chi phí, tài khoản ngân hàng, giao dịch và thuế suất.

chi phídanh mục chi phítài khoản ngân hàngbank-transactionsmức thuế
kế toán Kế toán

Tiếp thị

4

Chiến dịch, người nhận, trang đích và biểu mẫu đã gửi.

chiến dịchngười nhận chiến dịchtrang đíchđơn đã gửi
tiếp thị Tiếp thị

HR

8

Nhân sự, phòng ban, nghỉ phép, phiếu lương, chấm công và tuyển dụng.

nhân viênphòng banleave-requestsphiếu lươngĐiểm danhtin tuyển dụng+2 nữa
hr HR

Bảng chấm công

2

Nhật ký thời gian và các dự án được ghi nhận.

ghi nhận thời giandự án bảng chấm công
bảng chấm công Bảng chấm công

Dự án

3

Dự án, các giai đoạn và chi phí liên quan.

Dự ánproject-phaseschi phí dự án
Dự án Dự án

Đặt lịch

3

Lịch hẹn, dịch vụ có thể đặt trước và nhân viên thực hiện.

đặt lịchdịch vụ đặt lịchđặt lịch nhân viên
đặt lịch Đặt lịch

Dịch vụ hiện trường

7

Công việc, kỹ thuật viên, lệnh làm việc, hợp đồng và thiết bị.

công việc hiện trườngkỹ thuật viênyêu cầu dịch vụhợp đồng dịch vụlệnh sản xuấtphiếu công việc+1 nữa
dịch vụ hiện trường Dịch vụ hiện trường

Hậu cần.

5

Lô hàng, tài xế, phương tiện, khu vực và nhà vận chuyển.

lô hàngtài xếphương tiệnkhu vực giao hàngnhà vận chuyển
hậu cần Hậu cần.

Hỗ trợ

5

Phiếu, chính sách SLA, bài viết trợ giúp và cơ sở tri thức.

phiếuphiếu yêu cầu của khách hàngbài viết trợ giúpcơ sở tri thứcchính-sách-sla
hỗ trợ Hỗ trợ

Hậu mãi

5

Trả hàng, yêu cầu bảo hành, sửa chữa và đăng ký sản phẩm.

rmasyêu cầu bảo hànhwarranty-registrationssửa chữađăng ký sản phẩm
hậu mãi Hậu mãi

Cho thuê

3

Tài sản cho thuê, hợp đồng thuê và các hạng mục liên quan.

tài sảncho thuêdòng thuê
thuê Cho thuê

Nhà hàng

2

Thực đơn và các đơn hàng được đặt theo đó.

mục thực đơnđơn hàng thực đơn
nhà hàng F&B

Hàng đợi

5

Phiếu, dịch vụ, quầy, chi nhánh và màn hình hiển thị.

queue-ticketsdịch vụ xếp hàngbộ đếm hàng đợichi nhánh xếp hàngmàn hình hiển thị hàng đợi
hàng đợi Hàng đợi

Khách hàng thân thiết

6

Thành viên, tài khoản, cấp độ, phần thưởng và giao dịch điểm.

loyalty-memberstài khoản khách hàng thân thiếtphần thưởng khách hàng thân thiếtcác cấp độ khách hàng thân thiếtgiao dịch khách hàng thân thiếtloyalty-coupons
khách hàng thân thiết Khách hàng thân thiết

Địa điểm

2

Địa điểm và chi nhánh.

địa điểmchi nhánh
địa điểm Địa điểm

IOT

6

Thiết bị, địa điểm, hộp, cảnh báo, sự kiện và nội dung biển báo.

thiết bị IoTiot-sitescảnh báo IoTsự kiện IoTiot-boxesnội dung biển báo IoT
iot Trung tâm IOT

AI Studio

3

Tài sản đã tạo, các dự án chứa chúng và lịch sử công việc.

tài sản AIdự án AIai-jobs
ai_studio AI Studio

Thương mại

3

Thành viên mạng lưới, yêu cầu báo giá và thu nợ.

thành viên mạng lướiyêu cầu báo giábộ sưu tập
thương mại Thương mại

Chữ ký điện tử

2

Yêu cầu chữ ký và các chữ ký đã thu thập được.

yêu cầu chữ kýchữ ký
chữ ký Ký điện tử

Phê duyệt

2

Yêu cầu phê duyệt và các quy tắc định tuyến chúng.

yêu cầu phê duyệtquy tắc phê duyệt
phê duyệt Phê duyệt

Tệp tin

2

Tệp đã tải lên và tài liệu đã quét.

tệp tinscanned-documents
tệp tin Tệp tin

Hoạt động

3

Bảng tin hoạt động, nhật ký kiểm toán và thông báo.

hoạt độngnhật ký kiểm toánthông báo
Qua điện thoại

Mọi mô-đun mà API đọc, nhóm của bạn đều có thể mở trên thiết bị của họ.

Đây là phần thường không đúng sự thật. Nhiều nền tảng cung cấp API rộng rãi nhưng sau đó chỉ phát hành ứng dụng di động làm ba việc — phê duyệt, xem, thông báo. Ứng dụng của Kardopal là sản phẩm chính, không phải là một ứng dụng phụ trợ: tất cả 29 mô-đun trên đều có giao diện thực tế, và điện thoại là nơi hầu hết công việc được thực hiện.

  • Đọc và thực hiện. Hệ thống tích hợp của bạn lấy mức tồn kho; người cần khắc phục sẽ mở cùng một bản ghi, điều chỉnh và ký tên xác nhận.
  • Quét, chụp, ký. Quét mã vạch, chụp tài liệu và chữ ký điện tử là tính năng gốc của điện thoại — không có phiên bản máy tính để bàn nào đáng để sử dụng.
  • Hoạt động ngoại tuyến tại quầy. Máy tính tiền, màn hình bếp và màn hình xếp hàng vẫn hoạt động khi kết nối bị gián đoạn.
  • Cùng đăng nhập, cùng dữ liệu, 20 ngôn ngữ. Bao gồm cả ngôn ngữ đọc từ phải sang trái, để đội ngũ nói tiếng Ả Rập không phải đọc bố cục bị đảo ngược.
Xem nền tảng.
Ứng dụng Kardopal chạy trên điện thoại

Lấy khóa

Mở ứng dụng, vào Nền tảng → Khóa API.Khóa được tạo bởi chủ sở hữu hoặc quản trị viên trên tài khoản của bạn. Không ai tại Kardopal cấp khóa cho bạn.
Chỉ chọn các mô-đun mà tích hợp cần.Một widget cửa hàng cần mặt hàng. Nó không cần hr. Các khóa hẹp an toàn khi lỗi.
Gửi nó dưới dạng tiêu đề, không bao giờ trong URL.X-API-Key: kp_live_… — chuỗi truy vấn kết thúc trong nhật ký, proxy và lịch sử trình duyệt.
Xoay vòng bằng cách tạo khóa mới trước.Cả hai hoạt động cùng lúc, để bạn có thể chuyển lưu lượng truy cập và thu hồi cái cũ mà không có thời gian ngừng hoạt động.

Xây dựng điều gì đó trên đó

API tự tài liệu hóa: tạo khóa trong ứng dụng, trỏ curl tại URL cơ sở, và nó trả về mọi mô-đun, tài nguyên và trường có thể tìm kiếm mà khóa đó có thể truy cập.

Tạo khóa API