Agrello dla deweloperów

Twórz procesy podpisywania dokumentów z API Agrello

Twórz dokumenty, uzupełniaj szablony danymi, zapraszaj do podpisania, odbieraj zdarzenia przez webhooki i pobieraj podpisane dokumenty z własnej aplikacji lub systemu wewnętrznego.

Uwierzytelnianie i adresy URL

Co przygotować przed pierwszym żądaniem

Bazowy adres URL APIhttps://api.agrello.io/public
Uwierzytelnianie

OAuth 2.0 Client Credentials. Wyślij nagłówek Authorization: Bearer $TOKEN.

Ważność tokena

Tokeny dostępu wygasają po 24 godzinach. Po odpowiedzi 401 pobierz nowy token.

Wersja API

Używaj punktów końcowych /v3. Swagger oznacza API v2 jako przestarzałe.

Podstawowy przebieg

Minimalny proces podpisywania od początku do końca

Skopiuj przykład do wykorzystania w aplikacji serwerowej. Poniżej znajdziesz kolejność operacji. Pełna dokumentacja API jest dostępna w Swaggerze.

Podstawowy proces przesłania pliku i podpisaniaToken OAuth → obszar roboczy → folder → kontener → plik wynikowy
# Pobierz obszar roboczy
GET /v3/workspace

# Utwórz lub wybierz folder
POST /v3/folders
{ "name": "Dokumenty testowe API" }

# Prześlij plik PDF i udostępnij go do podpisu
POST /v3/folders/{folderId}/containers
Content-Type: multipart/form-data

request={
  "name": "Umowa testowa API",
  "outputType": "PDF",
  "signers": ["signer@example.com"],
  "viewers": ["legal@example.com"],
  "variables": [],
  "immediatePublish": true,
  "metadata": { "external_id": "CRM-12345" }
}
file=@contract.pdf

# Monitoruj postęp i pobierz dokument po podpisaniu
GET /v3/containers/{containerId}
GET /v3/containers/{containerId}/output
Podstawowy model danych

Poznaj najważniejsze pojęcia

Obszar roboczy

└── Folder

├── Szablon i zmienne

└── Kontener

├── uczestnicy i zaproszenia

├── podpisy

└── podpisany dokument

Folder

Porządkuje dokumenty według zespołu, klienta, procesu lub projektu. Niektóre odpowiedzi API mogą nadal zawierać starsze pole spaceId.

Szablon

Dokument źródłowy wielokrotnego użytku ze zmiennymi. Aby wprowadzić zmiany, utwórz nową wersję jako osobny szablon.

Kontener

Pakiet dokumentów wysyłanych do podpisu wraz z plikami, zaproszeniami, uczestnikami, podpisami, metadanymi i plikiem wynikowym.

Tworzenie dokumentów

Dopasuj proces do miejsca, w którym powstaje dokument

Wariant A – prześlij własny plik

Twój system generuje plik, a Agrello obsługuje podpisywanie.

GET/v3/workspace
POST/v3/folders
POST/v3/folders/{folderId}/containers
GET/v3/containers/{containerId}/output

Wariant B – utwórz dokument z szablonu

Zmienne szablonu Agrello są uzupełniane danymi z Twojej aplikacji lub systemu wewnętrznego.

POST/v3/folders/{folderId}/templates
GET/v3/templates/{templateId}
POST/v3/folders/{folderId}/containers
POST/v3/webhooks
Przykład zmiennych szablonudokładne dopasowanie
{
  "templateId": "template-uuid",
  "variables": [
    { "name": "employee_name", "value": "Jane Smith" },
    { "name": "start_date", "value": "2026-06-01" },
    { "name": "employee_signature", "value": "jane@example.com" }
  ],
  "signers": []
}

Formaty pliku wynikowego

  • PDF — podpisany plik PDF.
  • ASICE — unijny format kontenera dla podpisów XAdES.
  • EDOC — łotewski kontener podpisu elektronicznego.
  • ADOC_B — litewski kontener podpisu elektronicznego.
  • ZIP — archiwum z plikami wynikowymi, jeśli ma zastosowanie.
Za pomocą cURL, Postmana lub kodu przetestuj przesyłanie danych jako multipart/form-data. Interfejs Swagger UI nie jest przeznaczony do tego testu.
Nazwy zmiennych muszą być identyczne, włącznie z wielkością liter i białymi znakami.
Unikaj dodawania tej samej osoby zarówno przez zmienną podpisu PDF, jak i tablicę signers.
Kontenery nie obsługują aktualizacji częściowych. Zbierz wszystkie dane przed utworzeniem kontenera.
Webhooki i status

Sprawdzaj, kiedy dokument zostanie podpisany

Używaj webhooków w integracjach opartych na zdarzeniach. Odpytuj kontener o szczegóły tylko wtedy, gdy potrzebujesz rozwiązania awaryjnego albo chcesz sprawdzić zgodność danych.

Rejestracja webhookaDOCUMENT_SIGNED
{
  "event": "DOCUMENT_SIGNED",
  "url": "https://your-app.com/webhooks/agrello/document-signed"
}
Przykładowe dane zdarzeniaprzykład
{
  "containerId": "container-uuid",
  "userId": "last-signer-uuid",
  "signerCount": 2
}
Aby sprawdzić, czy podpisywanie się zakończyło, porównaj zebrane podpisy z listą oczekiwanych osób podczas odpytywania kontenera.
Udokumentowane zdarzenia webhook: DOCUMENT_SIGNATURE_ADDED, DOCUMENT_SIGNED, REMINDER_CREATED.
Gwarancje dotyczące ponawiania wysyłki i podpisywania żądań webhook wymagają potwierdzenia w dokumentacji.
Publiczny adres URL piaskownicy nie jest wymieniony. Korzystaj z testowego obszaru roboczego, chyba że Agrello udostępni osobne środowisko testowe.
Konsultacja techniczna

Pokaż nam swój proces, a pomożemy Ci wdrożyć go z API

Omów dane uwierzytelniające, szablony, format pliku wynikowego, role osób podpisujących, obsługę webhooków i najszybszą drogę do podpisania dokumentu testowego.