API Implementation Guide

// Retrieve a single document
async function getDocument(documentId: string): Promise {
  try {
    const document = await client.documents.get(documentId);

    console.log(`Retrieved document: ${document.documentType}`);
    console.log(`Issued by: ${document.issuer.organizationName}`);
    console.log(`Status: ${document.status}`);

    return document;
  } catch (error) {
    if (error instanceof NotFoundError) {
      console.error(`Document ${documentId} not found`);
    } else if (error instanceof UnauthorizedError) {
      console.error('Authentication required or invalid');
    } else if (error instanceof ForbiddenError) {
      console.error('Insufficient permissions to access document');
    } else {
      console.error('Unexpected error:', error);
    }
    throw error;
  }
}

// Retrieve with specific format
const pdfDocument = await client.documents.get(documentId, {
  format: 'pdf'
});

// Save PDF to file
await fs.promises.writeFile('document.pdf', pdfDocument);

from wia_social import PublicDocumentClient
from wia_social.exceptions import DocumentError

client = PublicDocumentClient(
    base_url='https://api.gov.ee/v2',
    api_key=os.environ['GOV_API_KEY']
)

# Batch retrieval
document_ids = ['DOC-001', 'DOC-002', 'DOC-003']

results = client.documents.get_batch(document_ids)

for result in results:
    if result.success:
        doc = result.document
        print(f"✓ Retrieved {doc.document_id}: {doc.document_type}")
    else:
        print(f"✗ Failed to retrieve {result.document_id}: {result.error}")

# List documents with pagination
documents = client.documents.list(
    document_type='passport',
    status='active',
    issued_after='2024-01-01',
    limit=50
)

print(f"Found {documents.total_count} documents")
print(f"Retrieved {len(documents.items)} in this page")

# Iterate through all pages
for document in client.documents.iterate(filters={'type': 'passport'}):
    process_document(document)

import { PublicDocumentClient } from '@wia-social/public-document-sdk';
import { QRScanner } from 'react-native-qr-scanner';

// Initialize verifier (can work offline with embedded public keys)
const verifier = new DocumentVerifier({
  trustedIssuers: await client.verification.getTrustedIssuers(),
  offlineMode: true
});

// Scan QR code
const qrData = await QRScanner.scan();

try {
  // Parse and verify
  const result = await verifier.verifyQRCode(qrData);

  if (result.valid) {
    console.log('✓ Document is authentic');
    console.log(`Type: ${result.document.documentType}`);
    console.log(`Holder: ${result.document.subject.fullName}`);
    console.log(`Issued by: ${result.document.issuer.organizationName}`);
    console.log(`Valid until: ${result.document.validUntil || 'No expiration'}`);

    // Check specific attributes
    if (result.document.documentType === 'DriversLicense') {
      const license = result.document as DriversLicense;
      console.log(`Vehicle classes: ${license.vehicleClasses.join(', ')}`);
      console.log(`Restrictions: ${license.restrictions || 'None'}`);
    }

    // Display verification UI
    showVerificationSuccess(result);

  } else {
    console.error('✗ Document verification failed');
    console.error(`Reason: ${result.failureReason}`);

    showVerificationFailure(result);
  }

} catch (error) {
  console.error('Verification error:', error);
  showVerificationError(error);
}

from wia_social import PublicDocumentClient
from wia_social.models import VerificationLevel

client = PublicDocumentClient(api_key=os.environ['GOV_API_KEY'])

def verify_document(document_id: str, verification_level: str = 'full'):
    """
    Verify document authenticity and status.

    Verification levels:
    - 'basic': Check signature and format only
    - 'standard': Include revocation check
    - 'full': Include issuer confirmation and attribute validation
    """

    result = client.verification.verify(
        document_id=document_id,
        level=VerificationLevel[verification_level.upper()],
        include_history=True
    )

    print(f"Verification Level: {result.level}")
    print(f"Overall Status: {'VALID' if result.valid else 'INVALID'}")
    print(f"Confidence: {result.confidence_score}/100")
    print()

    # Check individual validation results
    checks = result.checks
    print("Validation Checks:")
    print(f"  Signature Valid: {'✓' if checks.signature_valid else '✗'}")
    print(f"  Not Revoked: {'✓' if checks.not_revoked else '✗'}")
    print(f"  Not Expired: {'✓' if checks.not_expired else '✗'}")
    print(f"  Issuer Confirmed: {'✓' if checks.issuer_confirmed else '✗'}")

    if not result.valid:
        print(f"\nFailure Reasons:")
        for reason in result.failure_reasons:
            print(f"  - {reason}")

    # Check verification history
    if result.verification_history:
        print(f"\nPrevious Verifications: {len(result.verification_history)}")
        for entry in result.verification_history[:5]:
            print(f"  {entry.timestamp}: {entry.verifier} - {entry.result}")

    return result

# Example usage
result = verify_document('EE-PASS-2024-987654', verification_level='full')

if result.valid:
    print("\n✓ Document is authentic and currently valid")
else:
    print("\n✗ Document verification failed")
    print("Do not accept this document")

// Register webhook endpoint
await client.webhooks.register({
  url: 'https://myapp.com/webhooks/documents',
  events: [
    'document.issued',
    'document.revoked',
    'document.expiring',
    'verification.completed'
  ],
  secret: 'webhook-signing-secret',
  retryPolicy: {
    maxAttempts: 5,
    backoffMultiplier: 2
  }
});

// Webhook handler (Express.js example)
app.post('/webhooks/documents', async (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = req.body;

  // Verify webhook signature
  if (!verifyWebhookSignature(payload, signature, webhookSecret)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process event
  switch (payload.event) {
    case 'document.issued':
      await handleDocumentIssued(payload.data);
      break;

    case 'document.revoked':
      await handleDocumentRevoked(payload.data);
      break;

    case 'document.expiring':
      await handleDocumentExpiring(payload.data);
      break;
  }

  // Acknowledge receipt
  res.status(200).json({ received: true });
});

import pytest
from wia_social import PublicDocumentClient
from wia_social.testing import MockDocumentClient, create_mock_document

# Use mock client in tests
@pytest.fixture
def client():
    mock = MockDocumentClient()

    # Pre-load mock data
    mock.add_document(create_mock_document(
        document_id='TEST-001',
        document_type='BirthCertificate',
        status='active'
    ))

    return mock

def test_document_retrieval(client):
    # Test retrieves from mock
    doc = client.documents.get('TEST-001')

    assert doc.document_id == 'TEST-001'
    assert doc.document_type == 'BirthCertificate'
    assert doc.status == 'active'

def test_document_not_found(client):
    with pytest.raises(NotFoundError):
        client.documents.get('NON-EXISTENT')

def test_verification_success(client):
    result = client.verification.verify('TEST-001')

    assert result.valid == True
    assert result.confidence_score >= 95

Key Takeaways:

• Multi-Language SDKs: TypeScript, Python, and Java SDKs provide developer-friendly interfaces with language-idiomatic patterns.
• Comprehensive Document Operations: Create, retrieve, update, delete, and batch operations with proper error handling.
• Multi-Level Verification: From basic offline checks to full forensic verification with biometric matching.
• Robust Error Handling: Exponential backoff, circuit breakers, and retry logic ensure resilience.
• Event-Driven Architecture: Webhooks enable real-time notifications for document lifecycle events.
• Testing Support: Mock clients and fixture data enable development without production access.