REST API Verwysing

#Oorsig

Die Geteken API laat jou toe om e-handtekeningkoeverte te skep en te bestuur. Dit is versoenbaar met die PandaDoc v1-koppelvlak — as jy reeds PandaDoc-integrering het, moet jy net die basis-URL verander.

Basisadres	https://geteken.co.za
Weergawe	v1
Protokol	HTTPS only
Inhoudstipe	application/json

#Verifikasie

Alle versoeke vereis ʼn API-sleutel in die Authorization opskrif.

Beide formate word aanvaar:

Authorization: API-Key sk_signing_<your_key>
Authorization: Bearer sk_signing_<your_key>

Kry jou API-sleutel in Instellings → API Sleutels in jou dashboard.

bash

# Example authenticated request
curl https://geteken.co.za/api/public/v1/documents \
  -H "Authorization: API-Key sk_signing_your_key_here"

#Alle Eindpunte

Metode	Pad	Beskrywing
POST	/api/public/v1/documents	Skep koeverte (konsep)
GET	/api/public/v1/documents	Lys koeverte (gepagineer)
GET	/api/public/v1/documents/{id}	Kry koevert detail + status
GET	/api/public/v1/documents/{id}/preview	Voorsku sjabloon (JSON of HTML)
POST	/api/public/v1/documents/{id}/send	Stuur koeverte na ondertekenaars
GET	/api/public/v1/documents/{id}/download	Laai voltooide/bron-PDF af
POST	/api/public/v1/documents/{id}/cancel	Kanselleer (nietig) koevert
GET	/api/public/v1/balance	Beursie-balans (sent + plan)
POST	/api/public/v1/topup	Begin ’n beursie-aanvulling (Paystack-skakel)

#POST/api/public/v1/documents

Skep ʼn nuwe ondertekeningskoevert in konsep-status. Jy kan ʼn sjabloon-UUID of ʼn direkte dokument-URL verskaf. Die koevert is gereed vir stuur nadat dit geskep is.

#Versoekliggaam

Veld	Type	Beskrywing
name*	string	Mensleesbare naam van die koevert.
template_uuid	string	UUID of eksterne ID van ʼn Geteken-sjabloon.
url	string	HTTPS-URL van ʼn PDF om direk te gebruik (as sjabloon_uuid nie verskaf word nie).
recipients*	array	Lys van ondertekenaars. Sien struktuur hieronder.
tokens	object	Sleutel-waarde pare om sjabloontekens voor te vul.
metadata	object	Stoor jou eie ID of verwysing.

#Ontvanger struktuur

Veld	Type	Beskrywing
email*	string	E-posadres van die ontvanger.
first_name	string	Voornaam.
last_name	string	Van.
role	string	Rolnaam wat ooreenstem met ʼn sjabloonrol (bv. "Buyer").
signing_order	integer	Volgorde (1-gebaseer). Ondertekenaars met dieselfde nommer teken parallel.

bash

curl -X POST https://geteken.co.za/api/public/v1/documents \
  -H "Authorization: API-Key sk_signing_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement — Acme Corp",
    "template_uuid": "3a8f1b20-1234-4abc-abcd-000000000001",
    "recipients": [
      {
        "email": "buyer@example.com",
        "first_name": "Jane",
        "last_name": "Smith",
        "role": "Buyer",
        "signing_order": 1
      }
    ],
    "tokens": {
      "company_name": "Acme Corp",
      "contract_date": "2026-06-08"
    },
    "metadata": { "deal_id": "crm-9876" }
  }'

#Reaksie — 201 Created

json

{
  "id": "env_01abc23def456",
  "name": "Service Agreement — Acme Corp",
  "status": "document.draft",
  "date_created": "2026-06-08T10:00:00.000Z",
  "metadata": { "deal_id": "crm-9876" }
}

#GET/api/public/v1/documents

Lys al jou koeverte, gesorteer van nuwer na ouer. Gebruik die ?count= parameter om paginering te beheer (maksimum 100).

#Navraagparameters

Parameter	Type	Verstek / Beskrywing
count	integer	Aantal resultate wat teruggekeer moet word. Verstek: 25, maksimum: 100.

bash

curl https://geteken.co.za/api/public/v1/documents?count=10 \
  -H "Authorization: API-Key sk_signing_..."

json

{
  "results": [
    {
      "id": "env_01abc23def456",
      "name": "Service Agreement — Acme Corp",
      "status": "document.completed",
      "date_created": "2026-06-08T10:00:00.000Z",
      "metadata": {}
    }
  ]
}

#GET/api/public/v1/documents/{id}

Haal koevertbesonderhede op, insluitend ontvangers en hul tekenvordering.

bash

curl https://geteken.co.za/api/public/v1/documents/env_01abc23def456 \
  -H "Authorization: API-Key sk_signing_..."

json

{
  "id": "env_01abc23def456",
  "name": "Service Agreement — Acme Corp",
  "status": "document.sent",
  "date_created": "2026-06-08T10:00:00.000Z",
  "date_completed": null,
  "expiration_date": null,
  "metadata": {},
  "recipients": [
    {
      "email": "buyer@example.com",
      "first_name": "Jane",
      "last_name": "Smith",
      "role": "Buyer",
      "signing_order": 1,
      "status": "sent",
      "signed_at": null,
      "viewed_at": "2026-06-08T11:00:00.000Z"
    }
  ]
}

#GET/api/public/v1/documents/{id}/preview

Kry ʼn gerenderde voorskou van die koevert se sjabloon (tokens vervang) plus die ontvanger- en veldplan — sonder om ʼn tekenteken te benodig. Nuttig vir ʼn pre-stuur voorskou in ʼn Bubble-iframe.

#Navraagparameters

Parameter	Type	Beskrywing
format	"html"	Stuur ruwe gerenderde HTML terug (Content-Type: text/html) vir iframe-inbedding.

bash

# JSON response (default)
curl https://geteken.co.za/api/public/v1/documents/env_01abc23def456/preview \
  -H "Authorization: API-Key sk_signing_..."

# Raw HTML for iframe
curl "https://geteken.co.za/api/public/v1/documents/env_01abc23def456/preview?format=html" \
  -H "Authorization: API-Key sk_signing_..."

#POST/api/public/v1/documents/{id}/send

Stuur die koevert van konsep na gestuur. E-posinooides word gestuur aan alle ondertekenaars met die laagste tekenvolgorde (parallel-ondertekenaars gaan saam). As die koevert reeds gestuur is, kan jy dit herstuur (geen ekstra koste).

#Opsionele versoekliggaam

Veld	Type	Beskrywing
message	string	Persoonlike boodskap wat in die uitnodiging ingesluit word.
subject	string	Onderwerp-lyn vir die uitnodigings-e-pos.

bash

curl -X POST https://geteken.co.za/api/public/v1/documents/env_01abc23def456/send \
  -H "Authorization: API-Key sk_signing_..." \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Please sign: Service Agreement",
    "message": "Hi Jane, please review and sign at your earliest convenience."
  }'

json

{
  "id": "env_01abc23def456",
  "name": "Service Agreement — Acme Corp",
  "status": "document.sent",
  "notified_recipients": 1
}

#GET/api/public/v1/documents/{id}/download

Kry ʼn getekende URL na die PDF. Vir voltooide koeverte is dit die finale gestempelde PDF met die ouditseël. Vir nie-voltooide koeverte is dit die bron-PDF. URL verval na 24 uur.

Parameter	Type	Beskrywing
inline	"1"	Herlei (302) direk na die getekende URL in plaas van JSON.

bash

# Returns JSON with download_url
curl https://geteken.co.za/api/public/v1/documents/env_01abc23def456/download \
  -H "Authorization: API-Key sk_signing_..."

# Redirect directly to the PDF (useful for <a href> or <iframe>)
curl -L "https://geteken.co.za/api/public/v1/documents/env_01abc23def456/download?inline=1" \
  -H "Authorization: API-Key sk_signing_..." \
  -o signed_document.pdf

json

{
  "id": "env_01abc23def456",
  "name": "Service Agreement — Acme Corp",
  "status": "document.completed",
  "download_url": "https://storage.geteken.co.za/signing-documents/...",
  "expires_in_seconds": 86400,
  "final_pdf_hash_sha256": "e3b0c44298fc1c14...",
  "issued_at": "2026-06-08T14:32:00.000Z"
}

#POST/api/public/v1/documents/{id}/cancel

Maak ʼn koevert ongeldig. Ontvangers kan nie meer teken nie. Kan nie op voltooide of reeds ongeldige koeverte gebruik word nie.

bash

curl -X POST https://geteken.co.za/api/public/v1/documents/env_01abc23def456/cancel \
  -H "Authorization: API-Key sk_signing_..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Contract terms changed" }'

json

{
  "id": "env_01abc23def456",
  "name": "Service Agreement — Acme Corp",
  "status": "document.voided"
}

#Status Waardes

Die status-veld volg die PandaDoc-konvensie (document.*).

Status	Betekenis
document.draft	Koevert geskep maar nog nie gestuur.
document.sent	Uitnodigings gestuur na ondertekenaars.
document.viewed	Eerste ontvanger het die dokument oopgemaak.
document.partially_signed	Sommige ondertekenaars het geteken, maar nie almal.
document.completed	Alle ondertekenaars het geteken. Die GOUD SEËL is uitgereik.
document.voided	Koevert gekanselleer via die /cancel eindpunt.
document.declined	ʼn Ontvanger het geweier om te teken.

document.draft→document.sent→document.viewed→document.partially_signed→document.completed

#Foutkodes

Foute kom terug as JSON met ʼn "error" sleutel. Gebruik die HTTP-statuskode vir beheer.

HTTP	error	Wanneer
400	Invalid JSON body	Liggaam is nie geldige JSON.
400	`name` and `recipients[]` are required	Vereiste velde ontbreek.
400	invalid document_url	URL is nie HTTPS of die dokument kon nie afgelaai word.
401	Invalid or missing API key	Authorization opskrif ontbreek of sleutel is ongeldig.
402	insufficient_credits	Balans te laag. upgrade: true is ingesluit in die reaksie.
403	Forbidden	Die hulpbron behoort aan ʼn ander huurder.
404	Not found	Koevert-ID bestaan nie.
409	Cannot cancel envelope in status '...'	Staatoorgang word nie toegelaat.

json

{ "error": "insufficient_credits", "upgrade": true }

#Prysing

R12 per dokument

Een heffing per koevert dek alle ondertekenaars. Jou eerste twee dokumente is gratis. Geen kontrak of maandelikse koste nie — jy betaal net wanneer jy stuur.

Sien volledige pryse →Kry jou gratis API-sleutel →