Document Archiving API

Overview

The Document Archiving API allows you to add a document timestamp to signed PDF documents, upgrading them to PAdES-B-LTA format. This ensures long-term validation and archival compliance by embedding a trusted timestamp that proves the document existed at a specific point in time.

What is PAdES-B-LTA?

PAdES-B-LTA (PDF Advanced Electronic Signatures - Baseline Long-Term Archival) is a signature format that includes:

• Long-term validation data: Ensures signatures can be verified even after certificates expire
• Document timestamp: Proves the document existed at a specific time
• Archival compliance: Meets requirements for long-term document storage

Getting Started

To archive a document:

1. Prepare your signed PDF document by converting it to a base64 string
2. Make a POST request to the archive endpoint with your document
3. Receive the archived document with the embedded timestamp in the response

API Endpoint

POST /management/archive

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 signed PDF document to archive
fileName	string	Yes	The name of the file being archived

Response Format

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

Content-Type: application/pdf

Response Codes

• 200 OK: Success. Returns the archived PDF document with embedded timestamp.
• 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 archiveDocument = async () => {
  // Create basic auth credentials
  const credentials = btoa("your_companyKey:your_ApiKey");

  const response = await fetch(
    "https://onboarding.taktikal.is/management/archive",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Accept: "application/json",
        Authorization: `Basic ${credentials}`,
      },
      body: JSON.stringify({
        pdfDocument: "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQg...", // Base64 encoded signed PDF
        fileName: "signed-contract.pdf",
      }),
    }
  );

  if (response.ok) {
    console.log("Document archived successfully");

    // 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 = "archived-document.pdf";
    a.click();
  } else {
    console.error("Failed to archive document:", await response.text());
  }
};

archiveDocument();

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 ArchiveRequest
{
    public string PdfDocument { get; set; }
    public string FileName { get; set; }
}

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

    public ArchivingService(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[]> ArchiveDocumentAsync(ArchiveRequest request)
    {
        var content = new StringContent(
            JsonConvert.SerializeObject(request),
            Encoding.UTF8,
            "application/json");

        content.Headers.Add("Accept", "application/json");

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

        if (response.IsSuccessStatusCode)
        {
            // Read the PDF as bytes
            byte[] pdfBytes = await response.Content.ReadAsByteArrayAsync();
            return pdfBytes;
        }
        else
        {
            throw new Exception($"Failed to archive document: {await response.Content.ReadAsStringAsync()}");
        }
    }
}

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

    var request = new ArchiveRequest
    {
        PdfDocument = "JVBERi0xLjMKJcTl8uXrp...", // Base64 signed PDF content
        FileName = "signed-contract.pdf"
    };

    try
    {
        var archivedPdf = await service.ArchiveDocumentAsync(request);
        Console.WriteLine("Document archived successfully");

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

cURL

curl -X POST https://onboarding.taktikal.is/management/archive \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Basic $(echo -n 'your_companyKey:your_ApiKey' | base64)" \
  -d '{
    "pdfDocument": "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQg...",
    "fileName": "signed-contract.pdf"
  }' \
  -o archived-document.pdf

Common Use Cases

Archiving After Signing

After a document has been signed, you can archive it to ensure long-term validity:

{
  "pdfDocument": "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQg...",
  "fileName": "contract-2024-signed.pdf"
}

Compliance Requirements

Many regulations require documents to be archived with timestamps for legal validity over extended periods. The PAdES-B-LTA format ensures:

• Signatures remain verifiable after certificate expiration
• Proof of document existence at a specific time
• Compliance with eIDAS and other electronic signature regulations

Error Handling

If an error occurs during the archiving 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