Tích hợp chữ ký điện tử vào stack của bạn
Gửi phong bì, theo dõi chữ ký, nhận webhooks. API REST đơn giản, OpenAPI 3.0, ví dụ curl/Node/Python — mọi thứ để kết nối Certyneo với HRIS, CRM hoặc phần mềm kinh doanh của bạn trong vài giờ.
Bắt đầu nhanh
Ba bước : tạo khóa API từ cài đặt, mã hóa PDF của bạn bằng base64, gửi. Phản hồi chứa `signUrl` mà bạn có thể chia sẻ trực tiếp với người nhận.
# 1. Upload the PDF (multipart) and capture the returned document id.
DOC_ID=$(curl -s -X POST https://certyneo.com/api/v1/documents \
-H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
-F "file=@contrat.pdf" | jq -r .id)
# 2. Create a DRAFT envelope referencing the uploaded document.
ENV_ID=$(curl -s -X POST https://certyneo.com/api/v1/envelopes \
-H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d "{
\"subject\": \"Contrat de prestation\",
\"documentIds\": [\"$DOC_ID\"],
\"recipients\": [
{ \"email\": \"client@example.com\", \"name\": \"Marie Dubois\", \"role\": \"SIGNER\" }
]
}" | jq -r .id)
# 3. Dispatch the envelope — this sends the invitation email/SMS.
curl -X POST https://certyneo.com/api/v1/envelopes/$ENV_ID/send \
-H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"// npm install @certyneo/sdk (or call fetch directly)
const auth = { Authorization: `Bearer ${process.env.CERTYNEO_API_KEY}` };
// 1. Upload the PDF (multipart).
const fd = new FormData();
fd.append("file", new Blob([pdfBuffer], { type: "application/pdf" }), "contrat.pdf");
const doc = await fetch("https://certyneo.com/api/v1/documents", {
method: "POST", headers: auth, body: fd,
}).then((r) => r.json());
// 2. Create the DRAFT envelope.
const envelope = await fetch("https://certyneo.com/api/v1/envelopes", {
method: "POST",
headers: { ...auth, "Content-Type": "application/json" },
body: JSON.stringify({
subject: "Contrat de prestation",
documentIds: [doc.id],
recipients: [
{ email: "client@example.com", name: "Marie Dubois", role: "SIGNER" },
],
}),
}).then((r) => r.json());
// 3. Dispatch — this triggers the invitation channel for every recipient.
await fetch(`https://certyneo.com/api/v1/envelopes/${envelope.id}/send`, {
method: "POST", headers: auth,
});
console.log(envelope.id);import os, requests
auth = {"Authorization": f"Bearer {os.environ['CERTYNEO_API_KEY']}"}
# 1. Upload the PDF (multipart).
with open("contrat.pdf", "rb") as f:
doc = requests.post(
"https://certyneo.com/api/v1/documents",
headers=auth,
files={"file": ("contrat.pdf", f, "application/pdf")},
).json()
# 2. Create the DRAFT envelope.
envelope = requests.post(
"https://certyneo.com/api/v1/envelopes",
headers={**auth, "Content-Type": "application/json"},
json={
"subject": "Contrat de prestation",
"documentIds": [doc["id"]],
"recipients": [
{"email": "client@example.com", "name": "Marie Dubois", "role": "SIGNER"},
],
},
).json()
# 3. Dispatch — this triggers the invitation channel for every recipient.
requests.post(
f"https://certyneo.com/api/v1/envelopes/{envelope['id']}/send",
headers=auth,
)
print(envelope["id"])Phong bì
Tạo, gửi, theo dõi trạng thái, hủy. Một phong bì có thể chứa nhiều tài liệu và nhiều người ký (song song hoặc tuần tự).
Webhooks
Nhận `envelope.created`, `envelope.completed`, `envelope.declined` trên URL của bạn. HMAC SHA-256 trên mỗi payload để xác minh nguồn gốc.
Xác thực đơn giản
Bearer token. Một khóa cho mỗi môi trường (test / prod). Có thể thu hồi tức thì. Giới hạn 100 yêu cầu/phút/khóa, burst 200, 429 sạch sẽ với tiêu đề Retry-After.
Các endpoints có sẵn
12 route bao quát toàn bộ vòng đời: envelopes, documents, webhooks, khóa API. Tất cả các route chấp nhận Bearer token và trả về JSON.
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/account/me | Identity of the authenticated caller (id, email, plan) — scope-less credential probe |
| POST | /api/v1/documents | Upload a PDF (multipart) — returns document id |
| GET | /api/v1/documents | List documents |
| GET | /api/v1/documents/{id} | Fetch document metadata |
| DELETE | /api/v1/documents/{id} | Delete document |
| GET | /api/v1/envelopes | List envelopes (filter with ?status= and ?limit=) |
| POST | /api/v1/envelopes | Create envelope (status: DRAFT) |
| GET | /api/v1/envelopes/{id} | Fetch envelope state |
| PATCH | /api/v1/envelopes/{id} | Update DRAFT envelope |
| DELETE | /api/v1/envelopes/{id} | Void / delete DRAFT envelope |
| POST | /api/v1/envelopes/{id}/send | Dispatch DRAFT — sends invitations |
| GET | /api/v1/envelopes/{id}/audit-trail | Download eIDAS audit-trail PDF |
| GET | /api/v1/envelopes/{id}/signed-document | Download signed PDF (once COMPLETED) |
| GET | /api/v1/templates | List reusable envelope templates |
| GET | /api/v1/webhooks | List webhooks |
| POST | /api/v1/webhooks | Register webhook — returns the signing secret once |
| GET | /api/v1/webhooks/{id} | Fetch webhook subscription |
| PATCH | /api/v1/webhooks/{id} | Update url / events / active state |
| DELETE | /api/v1/webhooks/{id} | Unregister |
| POST | /api/v1/seals | Apply a qualified electronic seal to a document |
| GET | /api/v1/seals/{id} | Fetch seal status |
| GET | /api/v1/seals/{id}/certificate | Download the seal certificate |
| GET | /api/v1/keys | List API keys |
| POST | /api/v1/keys | Create API key — the secret is shown once |
| PATCH | /api/v1/keys/{id} | Rename / revoke key |
| DELETE | /api/v1/keys/{id} | Delete key |
| GET | /api/v1/billing/usage | Current period usage and projected cost |
| GET | /api/v1/status | Service status |
| GET | /api/v1/openapi | Machine-readable OpenAPI specification |
Authentification
Chaque appel porte une clé API dans l'en-tête Authorization. Les clés se génèrent depuis Réglages → Clés API et ne sont affichées qu'une seule fois.
GET /api/v1/account/me HTTP/1.1
Host: certyneo.com
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx
# 200 OK
{ "data": { "id": "usr_…", "email": "you@example.com", "plan": "BUSINESS", "environment": "live" } }- • Format : sk_live_… en production, sk_test_… pour le bac à sable. En-tête : Authorization: Bearer <clé>.
- • Portées : envelopes, documents, webhooks, seals — en lecture (:read) ou écriture (:write). L'écriture implique la lecture ; la portée * donne tous les droits.
- • Les clés sk_test_ créent des ressources en bac à sable, exclues du quota et de la facturation.
- • Erreurs : 401 clé invalide, 403 portée insuffisante, 429 limite de débit dépassée, 402 quota mensuel atteint.
Forme des réponses
Un point à connaître avant d'écrire votre client : les collections sont encapsulées dans un objet data, alors que les ressources unitaires sont renvoyées à plat. Lire response.data.data sur une ressource unitaire renvoie donc undefined.
// GET /api/v1/envelopes
// Collections are WRAPPED in a "data" array.
{
"data": [
{ "id": "env_abc123", "subject": "Contrat", "status": "SENT" }
]
}// GET /api/v1/envelopes/{id}
// Single resources are returned FLAT — no "data" envelope.
{
"id": "env_abc123",
"subject": "Contrat",
"status": "COMPLETED",
"recipients": [ /* … */ ]
}Giới hạn tốc độ
Các giới hạn đảm bảo chất lượng dịch vụ ổn định cho tất cả khách hàng. Nếu bạn cần nhiều hơn, vui lòng liên hệ với chúng tôi.
- • 100 yêu cầu mỗi phút trên mỗi khóa API
- • Burst được phép lên tới 200 yêu cầu trong dưới 10 giây
- • Phản hồi 429 với tiêu đề Retry-After chỉ ra độ trễ tính bằng giây
