Интегрирайте електронния подпис в вашия стек

Бързо начало

Три стъпки: създайте API ключ от настройките, кодирайте вашия PDF в base64, изпратете. Отговорът съдържа `signUrl`, който можете да споделите директно с получателя.

# 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"

// Plain fetch, no SDK to install.
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"])

Опитайте API от вашите инструменти

Колекцията на Postman и картата на RapidAPI се генерират от спецификацията OpenAPI, която документира и тази страница. Трите остават в синхрон с реалния API, endpoint по endpoint, вместо да се разминават при първото добавяне.

Колекция на Postman

25-те заявки организирани по домейн — пликове, документи, шаблони, печати, webhooks — с пример на тяло и отговор за всяка. Вставете вашия ключ в променливата apiKey на колекцията, след това стартирайте GET /health: тя не изисква никаква автентификация и потвърждава, че вашата конфигурация е добра преди първото автентифицирано обаждане.

Отворете в Postman

Картата на RapidAPI

Същият каталог на endpoints, който може да се тества директно от браузъра. Полигонът очаква два различни хедъра: ключът на RapidAPI, който платформата ви издава, и вашия ключ на Certyneo в Authorization — вторият е този, който реално разрешава обаждането.

Вижте на RapidAPI

Налични endpoints

Всички публични маршрути: сметка, документи, пликове, шаблони, webhooks, електронни печати, API ключове и фактуриране. Всички приемат Bearer token и връщат JSON.

Модели на обвързващите документи

Шаблонът регистрира веднъж завинаги PDF, ролите и местоположението на полетата за подписване, след което се преизползва при всяко изпращане: предайте неговия идентификатор в templateId вместо documentIds, и позиционираните полета се копират на създадения плик.

• • Шаблоните се създават от таблото на управление (Шаблони → Нов шаблон), където депозирате документа и позиционирате полетата със мишката — това е най-простият път. API позволява също да ги създавате чрез POST /api/v1/templates, предоставяйки документите, ролите и полетата; внимание, полетата там се позиционират в абсолютни координати (страница, x, y, ширина, височина), така че трябва да знаете оформлението на PDF.
• • На акаунт, който все още не е регистрирал никакъв шаблон, GET /api/v1/templates връща празна списък. Това е нормално поведение, не е дефект в аутентификацията.
• • Списъкът съдържа само шаблони, принадлежащи на потребителя, собственик на ключа API. Шаблон, създаден от колега, не е включен в списъка, дори в рамките на споделено работно пространство: генерирайте ключа от акаунта, който притежава шаблона.
• • templateId и documentIds се взаимно изключват: изпратете един или другия, никога и двата, нито един от тях.
• • Предоставете поне толкова подписващи SIGNER, колкото шаблонът има роли подписващи, в противен случай създаването е отхвърлено с 400. Полето signerCount, върнато от списъка, показва очаквания брой.
• • Нивото на подписване на шаблона се наследява от пликът, освен ако заявката не предава явно signatureLevel.

# 1. Discover the templates saved on this account.
curl -s https://certyneo.com/api/v1/templates \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

# {
#   "data": [
#     { "id": "cmdq7f4k80001s6y2h1xa9pl3", "name": "Contrat de prestation",
#       "signerCount": 2, "documentCount": 1, "signatureLevel": "SIMPLE" }
#   ],
#   "pagination": { "page": 1, "pageSize": 20, "total": 1, "pages": 1 }
# }
#
# An empty "data" array means no template exists on this account yet —
# create one from the dashboard, it is not an authentication problem.

# 2. Create the envelope FROM the template: no documentIds and no field
#    coordinates, both are carried by the template. Pass one SIGNER
#    recipient per signer role, in the template's role order.
curl -X POST https://certyneo.com/api/v1/envelopes \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Contrat de prestation",
    "templateId": "cmdq7f4k80001s6y2h1xa9pl3",
    "recipients": [
      { "email": "client@example.com", "name": "Marie Dubois", "role": "SIGNER" },
      { "email": "legal@example.com", "name": "Paul Martin", "role": "SIGNER" }
    ]
  }'

# 3. The envelope is DRAFT at this point — POST /envelopes/{id}/send
#    dispatches it, exactly as in the quick-start above.

Изпращане на документ: две приемани форми

POST /api/v1/documents приема файла по два начина, по ваш избор. Едни и същи проверки се прилагат и в двата случая: разрешени типове, ограничение от 50 MB, проверка на двоичната подпис и антивирусен анализ.

• • В multipart/form-data, с част, наречена file. Това е класическата форма, тази на curl -F и на повечето библиотеки.
• • В сиров орган: байтовете на файла съставляват органа на заявката, и хедърът Content-Type дава неговия тип (например application/pdf). Полезно е от инструмент, който предава съдържанието както е, без да обвива заявката — това е това, което прави Power Automate конекторът.
• • В сирово тяло, име на файла няма място в органа: посочете го чрез хедър X-File-Name или параметър ?fileName=. Без него документът е назван според неговия тип.
• • Неподдържан тип отговаря с 415, назовавайки двете приемани форми, и орган, заявен като multipart, но нечетлив отговаря с 400. Нито един от двата не е грешка на сървъра.

# a. multipart/form-data — the classic shape.
curl -X POST https://certyneo.com/api/v1/documents \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "file=@contrat.pdf;type=application/pdf"

# b. raw body — the file bytes ARE the body, typed by Content-Type.
#    The filename has nowhere to live in the body, so pass it as a header
#    (or ?fileName=). Without it the document is named after its type.
curl -X POST https://certyneo.com/api/v1/documents \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/pdf" \
  -H "X-File-Name: contrat.pdf" \
  --data-binary "@contrat.pdf"

# Both return the same 201 with the document id to pass as documentIds.

Положение на полетата за подписване

Без шаблон, плик създаден от documentIds няма никакви предварително позиционирани полета: подписващият получава документа без място, където да подпише. Масивът fields, предаден в същия призив за създаване, позиционира всяко поле с точност — това е еквивалентът на страната на API на това, което шаблон записва веднъж завинаги.

• • Координатите са в PDF точки, произход в горния ляв ъгъл на страницата и ос Y надолу (страница A4 е 595 × 842 точки). x и y обозначават горния ляв ъгъл на полето, width и height неговия размер.
• • pageNumber започва от 1, documentIndex започва от 0. Номер на страница отвъд документа не е отхвърлен при създаването: полето се игнорира в момента на подписване и не се появява никъде — това е първото нещо, което трябва да проверите, когато липсва поле при призива.
• • recipientEmail трябва да съответства на един от получателите на същия призив, без разлика на главни и малки букви. В противен случай създаването не успява, като изброява всички дефектни редове, което избягва необходимостта да ги коригирате един по един.
• • fields и templateId се взаимно изключват: шаблон вече носи своя собствена поставка. Масивът fields се използва само с documentIds.
• • Приемани типове: SIGNATURE, INITIALS, DATE_SIGNED, TEXT, CHECKBOX и RADIO_GROUP. required е true по подразбиране; placeholder и dateFormat са по избор, и options се задържа само за RADIO_GROUP.
• • Плик приема най-много 100 полета, 20 документа и 50 получатели — ограниченията на вашия план могат да бъдат по-ниски.

# Ad-hoc envelope WITH pre-placed fields — no template involved.
# Coordinates are PDF points, origin TOP-LEFT of the page, +Y downwards
# (A4 = 595 x 842 pt). x / y are the field box's top-left corner.
#
# The last field is positioned by ANCHOR instead of by eye: the server
# locates "Signature du client" in the PDF and computes the spot. x / y
# stay required there — they are the fallback if the text is not found.
curl -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": ["cmdq7f4k80001s6y2h1xa9pl3"],
    "recipients": [
      { "email": "client@example.com", "name": "Marie Dubois", "role": "SIGNER" }
    ],
    "fields": [
      { "recipientEmail": "client@example.com", "documentIndex": 0,
        "pageNumber": 2, "fieldType": "SIGNATURE",
        "x": 90, "y": 640, "width": 180, "height": 44 },
      { "recipientEmail": "client@example.com", "documentIndex": 0,
        "pageNumber": 2, "fieldType": "DATE_SIGNED",
        "x": 320, "y": 640, "width": 140, "height": 30,
        "dateFormat": "DD/MM/YYYY" },
      { "recipientEmail": "client@example.com", "documentIndex": 0,
        "pageNumber": 2, "fieldType": "TEXT",
        "x": 90, "y": 700, "width": 200, "height": 30,
        "placeholder": "Fonction", "required": false },
      { "recipientEmail": "client@example.com", "documentIndex": 0,
        "pageNumber": 2, "fieldType": "SIGNATURE",
        "anchorText": "Signature du client", "anchorPlacement": "below",
        "anchorIndex": 0,
        "x": 90, "y": 640, "width": 180, "height": 44 }
    ]
  }'

# The envelope is DRAFT at this point — POST /envelopes/{id}/send
# dispatches it, exactly as in the quick-start above.

Аутентифициране

Кожен извик съдържа ключ API в заглавието Authorization. Ключовете се генерират от Настройки → Ключове API и показват се само една по време.

GET /api/v1/account/me HTTP/1.1Host: certyneo.com
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

# 200 OK
{ "data": { "id": "usr_…", "email": "you@example.com", "plan": "BUSINESS", "environment": "live" } }

• • Формат: sk_live_… в производство, sk_test_… за пробно пространство. Заглавие: Authorization: Bearer <ключ>.
• • Области: облекчения, документи, вебхуки, печати — четене (:read) или запис (:write). Пишата се предварително предполага четенето; област * дадава всички права.
• • Ключовете sk_test_ създават ресурси в пробна среда, изключени от квотата и таксуването. На получателя не се изпраща реален имейл, освен ако адресът му не съвпада с имейла на изпращащия акаунт — полезно за тестване на целия процес върху себе си.
• • Грешки: 401 невалиден ключ, 403 недостатъчен достойност, 429 превышена лимит на скоростта, 402 месечна квота достигнала.

Формата на отговорите

Едно нещо да знаете преди да пишете клиентя: колекциите са обръзнати в обект data, а ресурсите единични се връщат плоско. Четене response.data.data на единична ресурса дава следователно 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": [ /* … */ ]
}