docufykit.com is focused on signed Turkish document verification workflows. It verifies uploaded documents through a configured authority adapter, extracts structured fields from supported document types, and returns terminal results through signed webhooks and REST lookups.

This product is built for Turkish document verification and extraction, not generic file processing.

Base URL and credentials

• Use the base URL assigned to your environment. For production use https://api.docufykit.com.
• Every client app has its own API key.
• Every create request should include an Idempotency-Key so client retries do not create duplicate verification jobs.

First API request

Create a verification first. The API returns a signed upload target for the document bytes.

curl -X POST "https://api.docufykit.com/v1/verifications" \
  -H "X-API-Key: <your-api-key>" \
  -H "Idempotency-Key: 4dd2b36b-8f7c-4f8a-8fb5-1f2d27c3c0f1" \
  -H "Content-Type: application/json" \
  -d '{
    "document_type": "YOK_STUDENT",
    "process_type": "async",
    "external_reference_id": "student-12345",
    "original_filename": "belge.pdf",
    "file_size_bytes": 160585,
    "metadata": {
      "customer_user_id": "usr_12345"
    }
  }'

Important request fields:

• document_type: optional today, but recommended if you know the expected schema
• process_type: sync or async, default is sync
• external_reference_id: your own stable reconciliation id
• original_filename: traceability only
• file_size_bytes: declared upload size
• metadata: free-form JSON echoed back in results and webhooks

Signed upload flow

1. Create the verification and capture verification_id plus the signed upload target.
2. Upload the raw file directly to the signed URL.
3. Confirm upload completion.
4. Receive the terminal result by webhook or fetch it over REST.

Upload the file

curl -X PUT "<signed-upload-url>" \
  --upload-file "/absolute/path/to/belge.pdf"

Confirm upload completion

curl -X POST "https://api.docufykit.com/v1/verifications/<verification_id>/upload-complete" \
  -H "X-API-Key: <your-api-key>"

Fetch the verification

curl "https://api.docufykit.com/v1/verifications/<verification_id>" \
  -H "X-API-Key: <your-api-key>"

What happens after upload

Once upload completion is confirmed, docufykit:

1. reads the uploaded object from storage
2. validates the file
3. runs authenticity verification through the configured authority adapter
4. runs analysis and structured extraction
5. applies deterministic decision rules
6. stores the final result
7. emits a webhook if the app has an enabled endpoint

If the uploaded document cannot pass authenticity checks, it should not be treated as a valid extracted result.

Webhook setup

Webhook configuration is stored per client app. Customers configure the endpoint and signing secret in the portal.

Current terminal events:

• verification.completed
• verification.review_required
• verification.failed

Webhook headers

Every outbound request includes:

• Content-Type: application/json
• User-Agent: docufykit-webhooks/1.0
• X-Webhook-Event
• X-Webhook-Id
• X-Webhook-Timestamp
• X-Webhook-Signature

Webhook signature verification example

The signature format is:

sha256=HMAC_SHA256(secret, timestamp + "." + delivery_id + "." + raw_body)

Verify against the raw request body bytes, not reserialized JSON.

import crypto from "node:crypto";

function verifyDocufykitWebhook({
  secret,
  timestamp,
  deliveryId,
  rawBody,
  signature,
}: {
  secret: string;
  timestamp: string;
  deliveryId: string;
  rawBody: Buffer;
  signature: string;
}) {
  const payload = Buffer.concat([
    Buffer.from(timestamp, "utf8"),
    Buffer.from(".", "utf8"),
    Buffer.from(deliveryId, "utf8"),
    Buffer.from(".", "utf8"),
    rawBody,
  ]);

  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(payload).digest("hex");

  const actual = Buffer.from(signature, "utf8");
  const wanted = Buffer.from(expected, "utf8");

  return (
    actual.length === wanted.length &&
    crypto.timingSafeEqual(actual, wanted)
  );
}

Retry behavior and replay

Webhook delivery depends on the app environment.

Sandbox

• A failed webhook is attempted once only.
• There are no automatic retries.
• There is no dead_letter state.
• Failed deliveries stay in failed until you replay them manually.

Production

If your endpoint does not return a 2xx, the platform retries automatically:

• 30 seconds
• 2 minutes
• 10 minutes
• 1 hour
• 6 hours
• 24 hours

After the final retry, the delivery moves to dead_letter.

Customers can:

• inspect the latest webhook request and response in the portal
• see failed and dead-letter deliveries
• replay a delivery manually from the deliveries page

Reason-code reference

Reason codes are machine-readable explanations of the latest known outcome.

• awaiting_upload: the verification was created and is waiting for upload
• processing: upload completion succeeded and background processing is underway
• source_verifier_not_configured: authenticity verification was required but unavailable
• source_verification_failed: authenticity verification failed before extraction
• authenticity_missing_qrcode: the document QR code was missing or unreadable
• authenticity_source_missing: the document could not be verified by the configured authority adapter
• authenticity_hash_mismatch: the uploaded file did not match the verified authority bytes
• authenticity_lookup_failed: the authenticity lookup failed operationally
• fraud_hash_mismatch: the uploaded PDF differs from the verified authority bytes
• fraud_identity_mismatch: submitted credentials conflict with cached source data
• local_analysis_failed: local analysis failed before decisioning
• document_type_unknown: the platform could not classify the uploaded document
• manual_review_required: the document needs review before a final outcome can be returned
• verified_yok_student: a YOK_STUDENT document passed authenticity, extraction, and decision rules
• yok_student_structured_data_missing: structured extraction for YOK_STUDENT is missing
• yok_student_payload_invalid: structured extraction payload exists but is invalid
• yok_student_schema_invalid: the YOK_STUDENT schema validation failed

Sandbox vs production

sandbox and production use the same document verification and extraction engine, but they do not have the same operational behavior.

• sandbox
  • for integration testing and customer QA
  • one webhook attempt only
  • no automatic webhook retry
  • no dead-letter queue
  • lower quota
  • tighter shared sandbox rate limits across all plans
• production
  • for live traffic
  • automatic webhook retry schedule
  • dead-letter support
  • larger plan-based quota
  • standard plan-based rate limits

Use separate apps, environment-prefixed API keys, and webhook URLs for each environment.