Zintegruj podpis elektroniczny w swoim stosie technologicznym

Szybki start

Trzy kroki: utwórz klucz API z ustawień, zakoduj swój PDF w base64, wyślij. Odpowiedź zawiera `signUrl`, którą możesz bezpośrednio udostępnić odbiorcy.

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

Spróbuj API za pomocą swoich narzędzi

Kolekcja Postman i karta RapidAPI są generowane ze specyfikacji OpenAPI, która dokumentuje również tę stronę. Wszystkie trzy pozostają wyrównane do rzeczywistego API, endpoint po endpoincie, zamiast rozbiegać się przy pierwszym dodaniu.

Kolekcja Postman

25 żądania podzielone według domenów — koperty, dokumenty, szablony, pieczęcie, webhooki — z przykładem treści i odpowiedzi dla każdego. Wklej swój klucz do zmiennej apiKey w kolekcji, a następnie uruchom GET /health: nie wymaga żadnego uwierzytelnienia i potwierdza, że Twoja konfiguracja jest prawidłowa przed pierwszym uwierzytelnionym wywołaniem.

Otwórz w Postmanie

Karta RapidAPI

Ten sam katalog endpointów, którzy można testować bezpośrednio z przeglądarki. Stanowisko testowe oczekuje dwóch odrębnych nagłówków: klucza RapidAPI przydzielonego przez platformę i twojego klucza Certyneo w Authorization — to drugi klucz faktycznie autoryzuje wywołanie.

Wyświetl na RapidAPI

Dostępne endpointy

52 publicznych tras: konto, dokumenty, koperty, szablony, webhooki, pieczęcie elektroniczne, klucze API i rozliczenia. Wszystkie akceptują token Bearer i zwracają JSON.

Modely obudowa

Szablon zapisuje raz na zawsze plik PDF, role i lokalizację pól podpisu, a następnie jest ponownie używany przy każdym wysłaniu: przekaż jego identyfikator w templateId zamiast documentIds, a umieszczone pola zostaną skopiowane do utworzonej koperty.

• • Szablony są tworzone z pulpitu nawigacyjnego (Szablony → Nowy szablon), gdzie wgrywasz dokument i umieszczasz pola za pomocą myszy — to najprostszy sposób. API umożliwia również ich tworzenie za pośrednictwem POST /api/v1/templates, dostarczając dokumenty, role i pola; uwaga, pola są tam umieszczane we współrzędnych bezwzględnych (strona, x, y, szerokość, wysokość), musisz zatem znać układ PDF.
• • Na koncie, które jeszcze nie zarejestrowało żadnego szablonu, GET /api/v1/templates zwraca pustą listę. To normalne zachowanie, a nie błąd uwierzytelnienia.
• • Lista zawiera tylko szablony należące do użytkownika będącego właścicielem klucza API. Szablon utworzony przez kolegę nie pojawia się na liście, nawet w ramach udostępnionej przestrzeni roboczej: wygeneruj klucz z konta, które posiada szablon.
• • templateId i documentIds wzajemnie się wykluczają: wyślij jeden lub drugi, nigdy oba ani żaden z nich.
• • Podaj co najmniej tyle odbiorców SIGNER, ile ról podpisujących zawiera szablon, w przeciwnym razie utworzenie jest odrzucane z kodem 400. Pole signerCount zwrócone przez listę wskazuje oczekiwaną liczbę.
• • Poziom podpisu szablonu jest dziedziczony przez kopertę, chyba że żądanie wyraźnie przekazuje 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.

Wysyłanie dokumentu: dwie akceptowane formy

POST /api/v1/documents akceptuje plik na dwa sposoby, do wyboru. Te same kontrole mają zastosowanie w obu przypadkach: dozwolone typy, limit 50 MB, weryfikacja sygnatury binarnej i analiza antywirusowa.

• • W multipart/form-data, z częścią o nazwie file. Jest to forma klasyczna, ta z curl -F i większości bibliotek.
• • W surowym korpusie: bajty pliku stanowią treść żądania, a nagłówek Content-Type podaje jego typ (na przykład application/pdf). Przydatne z narzędzia, które przekazuje zawartość jako taką, bez owijania żądania — to właśnie robi łącznik Power Automate.
• • W surowym korpusie nazwa pliku nie ma miejsca w treści: podaj ją poprzez nagłówek X-File-Name lub parametr ?fileName=. Bez niej dokument jest nazwany selon jego typ.
• • Nieobsługiwany typ odpowiada 415 i wymienia dwie akceptowane formy, a korpus ogłoszony jako multipart ale niemożliwy do odczytania odpowiada 400. Żaden z nich nie jest błędem serwera.

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

Umieszczenie pól podpisu

Bez szablonu koperta utworzona z documentIds nie ma żadnych wstępnie umieszczonych pól: podpisujący otrzymuje dokument bez miejsca do podpisu. Tablica fields, przesłana w tym samym wywołaniu tworzenia, umieszcza każde pole z dokładnością do punktu — jest to odpowiednik API tego, co szablon zapisuje raz na zawsze.

• • Współrzędne są w punktach PDF, początek w lewym górnym rogu strony i oś Y w dół (strona A4 ma wymiary 595 × 842 punktów). x i y oznaczają lewy górny róg pola, width i height jego rozmiar.
• • pageNumber zaczyna się od 1, documentIndex zaczyna się od 0. Numer strony poza dokumentem nie jest odrzucany podczas tworzenia: pole jest ignorowane w momencie podpisywania i nigdzie się nie pojawia — to pierwsza rzecz do sprawdzenia, gdy pole brakuje w wywołaniu.
• • recipientEmail musi odpowiadać jednemu z odbiorców z tego samego wywołania, bez rozróżniania wielkości liter. W przeciwnym razie tworzenie nie powiedzie się, wymieniając wszystkie błędne wiersze, co pozwala uniknąć korygowania ich pojedynczo.
• • fields i templateId się wzajemnie wykluczają: szablon nosi już własny układ. Tablica fields jest zatem używana tylko z documentIds.
• • Akceptowane typy: SIGNATURE, INITIALS, DATE_SIGNED, TEXT, CHECKBOX i RADIO_GROUP. required jest domyślnie true; placeholder i dateFormat są opcjonalne, a options jest brane pod uwagę tylko dla RADIO_GROUP.
• • Koperta akceptuje maksymalnie 100 pól, 20 dokumentów i 50 odbiorców — limity planu mogą być niższe.

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

Podpis zintegrowany: podpisuj bez opuszczania aplikacji

Twój klient przegląda i podpisuje dokument w Twojej własnej aplikacji. Ceremonia otwiera się w oknie nad Twoją stroną i automatycznie powraca do Ciebie po zakończeniu. Po stronie serwera nic się nie zmienia: tworzysz kopertę jak zwykle, podając redirectUrl, a następnie powierzasz SDK adres URL podpisu adresata.

• • Wywołaj Certyneo.sign() bezpośrednio w programie obsługi kliknięcia i przekaż swoje wywołanie serwera przez getUrl. Await przed sign() wychodzi z gestu użytkownika: Safari i Firefox wówczas blokują okno. SDK otwiera je od razu i ładuje, gdy obietnica się rozwiąże.
• • redirectUrl to kanał powrotny. Odsyłamy do niego sygnatariusza, dodając certyneo_status (completed lub declined) i certyneo_envelope. Załaduj ten sam skrypt na tej stronie powrotnej: to on powiadamia okno portalu pozostawione otwarte w tle.
• • W trybie zintegrowanym nasze własne wezwania do działania są usuwane. Twój klient nigdy nie widzi zaproszenia do utworzenia konta Certyneo.
• • Jeśli przeglądarka odrzuci okno, SDK automatycznie przechodzi do pełnostronicowego przekierowania. Przebieg jest identyczny dla sygnatariusza, a Twoja strona powrotna otrzymuje dokładnie te same parametry.
• • Celowo nie istnieje callback "użytkownik porzucił": stan okna nie jest czytelny z Twojej strony, a taki callback wyzwoliłby się błędnie. Podpis, który się nie pojawi, pozostaje oczekujący aż do webhooka.

// 1. Your server creates and sends the envelope, then hands the browser the
//    recipient's signing URL. Nothing new on the API side:
//      POST /api/v1/envelopes        { …, "redirectUrl": "https://your-app.com/quote/42/signed" }
//      POST /api/v1/envelopes/{id}/send   → recipients[].accessToken
//      signingUrl = "https://certyneo.com/sign/" + accessToken

// 2. On your quote page — load the SDK once:
//      <script src="https://certyneo.com/embed.js"></script>

document.querySelector("#sign").addEventListener("click", () => {
  Certyneo.sign({
    // Called AFTER the window is already open, so no popup blocker ever
    // sees a delay between the click and window.open.
    getUrl: () =>
      fetch("/api/quote/42/signature", { method: "POST" })
        .then((r) => r.json())
        .then((d) => d.signingUrl),

    onCompleted: (e) => showConfirmation(e.envelopeId),
    onDeclined: () => showDeclined(),
    onError: (e) => showError(e),
  });
});

// 3. On https://your-app.com/quote/42/signed — your return page — load the
//    same script and render a short confirmation. It relays the outcome to
//    the portal window behind it, then closes itself.

// Mode cadre : la cérémonie s'affiche DANS votre page.
//
// 1. Déclarez votre site une fois pour toutes dans Réglages → Signature
//    intégrée, et publiez l'enregistrement DNS qu'on vous y donne.
//
// 2. À chaque signature, votre serveur demande une URL fraîche. Elle porte
//    l'autorisation qui permet au navigateur d'afficher la cérémonie chez
//    vous, et vaut deux heures :
//
//      POST /api/v1/envelopes/{id}/embed-url
//      { "origin": "https://portail.exemple.fr" }
//      -> { "signingUrl": "…", "expiresAt": "…" }

Certyneo.sign({
  mode: "iframe",
  el: "#zone-signature",        // sélecteur ou nœud de votre page

  getUrl: () =>
    fetch("/api/devis/42/signature", { method: "POST" })
      .then((r) => r.json())
      .then((d) => d.signingUrl),

  onCompleted: (e) => afficherConfirmation(e.envelopeId),
  onDeclined: () => afficherRefus(),
});

// Le cadre parle à votre page par postMessage — pas besoin de page de retour,
// contrairement au mode fenêtre.

POST /api/v1/envelopes

{
  "subject": "Mandat de gestion",
  "documentIds": ["doc_8f2c1a4b9e7d"],
  "recipients": [
    {
      "email": "client@exemple.fr",
      "name": "Camille Client",
      "role": "SIGNER",
      "notificationChannel": "NONE"
    },
    {
      "email": "notaire@exemple.fr",
      "name": "Maître Notaire",
      "role": "SIGNER"
    }
  ]
}

// La réponse rend le lien de chaque signataire :
//
//   "recipients": [
//     { "email": "client@exemple.fr",  "accessToken": "…",
//       "notificationChannel": "NONE"  },
//     { "email": "notaire@exemple.fr", "accessToken": "…",
//       "notificationChannel": "EMAIL" }
//   ]
//
// Le client ne reçoit rien : vous l'emmenez sur sa signature depuis votre
// portail. Le notaire, lui, reçoit son invitation comme d'habitude.

POST /api/v1/envelopes

{
  "subject": "Devis 2026-118",
  "documentIds": ["doc_8f2c1a4b9e7d"],
  "recipients": [
    { "email": "client@exemple.fr", "name": "Camille Client", "role": "SIGNER" }
  ],
  "sender": {
    "name": "1.2.3. Panneaux Solaires",
    "email": "devis@123-panneaux-solaires.fr"
  }
}

Autoryzacja

Każde wywołanie zawiera klucz API w nagłówku Authorization. Klucze generuje się z poziomu Ustawienia → Klucze API i są wyświetlane tylko raz.

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

• • Format: sk_live_… w produkcji, sk_test_… dla piaskownicy. Nagłówek: Authorization: Bearer <clé>.
• • Zakresy: envelopes, documents, webhooks, seals — do odczytu (:read) lub zapisu (:write). Zapis implikuje odczyt; zakres * udziela wszystkich uprawnień.
• • Klucze sk_test_ tworzą zasoby w piaskownicy, wyłączone z limitu i rozliczeń. Żaden prawdziwy e-mail nie jest wysyłany do odbiorcy, chyba że jego adres pokrywa się z adresem e-mail konta wysyłającego — przydatne do przetestowania całego przepływu na sobie.
• • Błędy: 401 nieprawidłowy klucz, 403 niewystarczający zakres, 429 przekroczony limit szybkości, 402 osiągnięty miesięczny limit.

Forma odpowiedzi

Ważny punkt do zapamiętania przed napisaniem klienta: kolekcje są hermetyzowane w obiekcie data, podczas gdy zasoby jednostkowe są zwracane płasko. Odczyt response.data.data na zasobie jednostkowym zwraca zatem 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": [ /* … */ ]
}

Dowiedz się więcej

• API podpisu elektronicznego: ceny i dokumentacja
• Natywne integracje (HubSpot, Zapier, Make, Power Automate…)
• Masowe wysyłanie dokumentów do podpisania bez kodu
• Odkryj rozwiązanie podpisu elektronicznego Certyneo