Sealing API

Overview

The Sealing API allows you to seal PDF documents to ensure their integrity and confidentiality. This process adds a digital seal to your documents, providing evidence that they have not been tampered with after sealing.

Getting Started

To seal a document:

1. Prepare your PDF document by converting it to a base64 string
2. Make a POST request to the sealing endpoint with your document and parameters
3. Receive the sealed document in the response

API Endpoint

POST /management/sealing

Authentication

This endpoint requires basic authentication. You need to include your API credentials in the request header:

Authorization: Basic base64(companyKey:ApiKey)

Where base64(companyKey:ApiKey) is the Base64 encoding of your companyKey and ApiKey separated by a colon.

Request Body

Parameter	Type	Required	Description
pdfDocument	string	Yes	Base64 string of the PDF document to seal
flowKey	string	Yes	A valid flowKey provided by Taktikal that can be used for sealing
reason	string	No	Sets the reason to display in the seal
languageType	enum	No	The language type (defaults to Is)
addSealOnAllPages	boolean	No	Set to true to seal the document multiple times. One seal will be added per page

Response Format

The API returns the sealed PDF document directly as binary data.

Content-Type: application/pdf

Response Headers

The API also returns a custom HTTP header:

Header	Description
x-seal-count	Number of seals that were added to the document

This header is particularly useful when using addSealOnAllPages: true to receive the number of pages that were sealed.

Response Codes

• 200 OK: Success. Returns the sealed PDF document.
• 400 Bad Request: If any of the input is invalid. Returns an error message.
• 500 Internal Server Error: Server error. Returns an error message.

Examples

JavaScript

const sealDocument = async () => {
  // Create basic auth credentials
  const credentials = btoa("your_companyKey:your_ApiKey");

  const response = await fetch(
    "https://onboarding.taktikal.is/management/sealing",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Basic ${credentials}`,
      },
      body: JSON.stringify({
        pdfDocument: "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQg...", // Base64 encoded PDF
        flowKey: "722989cac3fx",
        reason: "Document certification",
        languageType: "Is",
      }),
    }
  );

  if (response.ok) {
    // Get the seal count from the header
    const sealCount = response.headers.get("x-seal-count");
    console.log(`Document sealed successfully with ${sealCount} seals`);

    // Get the PDF as a blob
    const pdfBlob = await response.blob();

    // You can now save or process the PDF
    // Example: Create a download link
    const url = URL.createObjectURL(pdfBlob);
    const a = document.createElement("a");
    a.href = url;
    a.download = "sealed-document.pdf";
    a.click();
  } else {
    console.error("Failed to seal document:", await response.text());
  }
};

sealDocument();

C#

using System;
using System.IO;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

public class SealingRequest
{
    public string PdfDocument { get; set; }
    public string FlowKey { get; set; }
    public string Reason { get; set; }
    public string LanguageType { get; set; }
    public bool AddSealOnAllPages { get; set; }
}

public class SealingService
{
    private readonly HttpClient _httpClient;
    private readonly string _baseUrl;
    private readonly string _companyKey;
    private readonly string _apiKey;

    public SealingService(string baseUrl, string companyKey, string apiKey)
    {
        _baseUrl = baseUrl;
        _companyKey = companyKey;
        _apiKey = apiKey;
        _httpClient = new HttpClient();

        // Set up basic authentication
        var authValue = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{_companyKey}:{_apiKey}"));
        _httpClient.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Basic", authValue);
    }

    public async Task<(byte[] SealedPdf, int SealCount)> SealDocumentAsync(SealingRequest request)
    {
        var content = new StringContent(
            JsonConvert.SerializeObject(request),
            Encoding.UTF8,
            "application/json");

        var response = await _httpClient.PostAsync($"{_baseUrl}/management/sealing", content);

        if (response.IsSuccessStatusCode)
        {
            // Get the seal count from the header
            int.TryParse(
                response.Headers.GetValues("x-seal-count").FirstOrDefault() ?? "0",
                out int sealCount);

            // Read the PDF as bytes
            byte[] pdfBytes = await response.Content.ReadAsByteArrayAsync();

            return (pdfBytes, sealCount);
        }
        else
        {
            throw new Exception($"Failed to seal document: {await response.Content.ReadAsStringAsync()}");
        }
    }
}

// Example usage
public async Task SealDocumentExample()
{
    var service = new SealingService(
        "https://onboarding.taktikal.is",
        "your_companyKey",
        "your_ApiKey");

    var request = new SealingRequest
    {
        PdfDocument = "JVBERi0xLjMKJcTl8uXrp...", // Base64 PDF content
        FlowKey = "722989cac3fx",
        Reason = "Document certification",
        LanguageType = "Is",
        AddSealOnAllPages = false
    };

    try
    {
        var (sealedPdf, sealCount) = await service.SealDocumentAsync(request);
        Console.WriteLine($"Document sealed successfully with {sealCount} seals");

        // Save the sealed PDF
        File.WriteAllBytes("sealed-document.pdf", sealedPdf);
    }
    catch (Exception ex)
    {
        Console.Error.WriteLine(ex.Message);
    }
}

cURL

curl -X POST https://onboarding.taktikal.is/management/sealing \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'your_companyKey:your_ApiKey' | base64)" \
  -d '{
    "pdfDocument": "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQg...",
    "flowKey": "722989cac3fx",
    "reason": "Document certification",
    "languageType": "Is",
    "addSealOnAllPages": false
  }' \
  -o sealed-document.pdf

Common Use Cases

Sealing Multiple Pages

If you need to add a seal to every page of your document, set addSealOnAllPages to true in your request:

{
  "pdfDocument": "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQg...",
  "flowKey": "722989cac3fx",
  "reason": "Document certification",
  "addSealOnAllPages": true
}

Different Language Settings

The seal can be displayed in two languages. To change the language of the seal, use the languageType parameter:

• Is - Icelandic (default)
• En - English

{
  "pdfDocument": "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQg...",
  "flowKey": "722989cac3fx",
  "reason": "Document certification",
  "languageType": "En"
}

Error Handling

If an error occurs during the sealing process, the API will return an appropriate error response:

{
  "success": false,
  "message": "Invalid PDF document format",
  "errors": ["The provided PDF document could not be parsed"]
}

For more information about specific errors and troubleshooting, please refer to the complete API specification at: https://onboarding.taktikal.is/api/openapi