Physical SIM Card Management¶

This section provides detailed information about managing physical SIM cards through the TelcoAPI platform.

Overview¶

Physical SIM card management involves handling traditional plastic SIM cards used in mobile devices. The API provides comprehensive capabilities for managing the lifecycle of physical SIM cards, from provisioning to deactivation.

SIM Card States¶

Physical SIM cards can exist in the following states:

CREATED: Initial state after manufacturing
INVENTORY: In stock, ready for allocation
ALLOCATED: Assigned to a subscriber but not yet activated
ACTIVE: In use by a subscriber
SUSPENDED: Temporarily disabled
BLOCKED: Permanently disabled
EXPIRED: Past its validity period

Data Model¶

interface PhysicalSimCard {
  iccid: string;              // Integrated Circuit Card Identifier
  imsi: string;              // International Mobile Subscriber Identity
  msisdn?: string;           // Mobile phone number (if assigned)
  pin1: string;              // PIN1 code
  pin2: string;              // PIN2 code
  puk1: string;              // PUK1 code
  puk2: string;              // PUK2 code
  state: SimState;           // Current state of the SIM
  vendor: string;            // SIM card manufacturer
  batchId: string;          // Manufacturing batch identifier
  profileType: string;      // Type of profile loaded
  activationDate?: Date;    // Date when the SIM was activated
  expiryDate?: Date;       // Date when the SIM will expire
  lastUpdated: Date;       // Last modification timestamp
}

interface SimAuthentication {
  ki: string;               // Authentication key
  opc: string;             // Operator code
  amf: string;             // Authentication management field
  algorithm: AuthAlgorithm; // Authentication algorithm (COMP128, MILENAGE, etc.)
}

API Operations¶

Provisioning¶

class PhysicalSimManager {
  async provisionSim(simData: PhysicalSimCard): Promise<ProvisioningResult> {
    // Implementation for provisioning a new SIM card
  }

  async updateAuthentication(iccid: string, authData: SimAuthentication): Promise<void> {
    // Implementation for updating SIM authentication data
  }

  async allocateToSubscriber(iccid: string, subscriberId: string): Promise<void> {
    // Implementation for allocating a SIM to a subscriber
  }
}

State Management¶

class SimStateManager {
  async activate(iccid: string): Promise<void> {
    // Implementation for activating a SIM card
  }

  async suspend(iccid: string, reason: SuspensionReason): Promise<void> {
    // Implementation for suspending a SIM card
  }

  async block(iccid: string, reason: BlockingReason): Promise<void> {
    // Implementation for blocking a SIM card
  }

  async unblock(iccid: string): Promise<void> {
    // Implementation for unblocking a SIM card
  }
}

PIN/PUK Management¶

class PinPukManager {
  async verifyPin(iccid: string, pin: string): Promise<boolean> {
    // Implementation for PIN verification
  }

  async changePin(iccid: string, oldPin: string, newPin: string): Promise<void> {
    // Implementation for changing PIN
  }

  async unblockPin(iccid: string, puk: string, newPin: string): Promise<void> {
    // Implementation for unblocking PIN using PUK
  }
}

Error Handling¶

enum PhysicalSimError {
  INVALID_ICCID = 'INVALID_ICCID',
  INVALID_STATE_TRANSITION = 'INVALID_STATE_TRANSITION',
  AUTHENTICATION_FAILED = 'AUTHENTICATION_FAILED',
  PIN_BLOCKED = 'PIN_BLOCKED',
  PUK_BLOCKED = 'PUK_BLOCKED',
  ALREADY_ALLOCATED = 'ALREADY_ALLOCATED',
  NOT_FOUND = 'NOT_FOUND'
}

interface SimErrorResponse {
  error: PhysicalSimError;
  message: string;
  details?: Record<string, any>;
}

Best Practices¶

Batch Operations
Use batch operations for managing multiple SIM cards simultaneously
Implement proper rollback mechanisms for failed batch operations
Security
Store PIN/PUK codes securely using encryption
Implement rate limiting for PIN verification attempts
Log all state changes for audit purposes
Inventory Management
Maintain accurate inventory counts
Implement alerts for low stock levels
Track SIM card age and expiration dates
Performance Optimization
Cache frequently accessed SIM card data
Use bulk operations for batch updates
Implement efficient search indexes

Monitoring¶

Key metrics to monitor:

Active SIM cards count
SIM card activation success rate
PIN verification attempts
PUK usage statistics
State transition latency
Inventory levels
Failed operations count

Implementation Example¶

Here's a complete example of implementing a physical SIM card manager:

class PhysicalSimCardManager {
  private db: Database;
  private logger: Logger;

  constructor(db: Database, logger: Logger) {
    this.db = db;
    this.logger = logger;
  }

  async provisionBatch(batch: PhysicalSimCard[]): Promise<ProvisioningResult[]> {
    const results: ProvisioningResult[] = [];

    for (const sim of batch) {
      try {
        // Validate ICCID format
        if (!this.validateIccid(sim.iccid)) {
          throw new SimError(PhysicalSimError.INVALID_ICCID);
        }

        // Check for duplicates
        const existing = await this.db.findByIccid(sim.iccid);
        if (existing) {
          throw new SimError(PhysicalSimError.ALREADY_EXISTS);
        }

        // Store SIM data
        await this.db.insertSim({
          ...sim,
          state: SimState.INVENTORY,
          lastUpdated: new Date()
        });

        // Log successful provisioning
        this.logger.info(`SIM card ${sim.iccid} provisioned successfully`);

        results.push({
          iccid: sim.iccid,
          success: true
        });
      } catch (error) {
        this.logger.error(`Failed to provision SIM ${sim.iccid}`, error);

        results.push({
          iccid: sim.iccid,
          success: false,
          error: error.message
        });
      }
    }

    return results;
  }

  async activateAndAllocate(
    iccid: string,
    subscriberId: string,
    msisdn: string
  ): Promise<void> {
    const sim = await this.db.findByIccid(iccid);

    if (!sim) {
      throw new SimError(PhysicalSimError.NOT_FOUND);
    }

    if (sim.state !== SimState.INVENTORY) {
      throw new SimError(PhysicalSimError.INVALID_STATE_TRANSITION);
    }

    // Start transaction
    const transaction = await this.db.startTransaction();

    try {
      // Update SIM state
      await transaction.updateSim(iccid, {
        state: SimState.ACTIVE,
        msisdn,
        subscriberId,
        activationDate: new Date(),
        lastUpdated: new Date()
      });

      // Update subscriber record
      await transaction.updateSubscriber(subscriberId, {
        activeSimIccid: iccid,
        msisdn
      });

      await transaction.commit();

      this.logger.info(`SIM ${iccid} activated and allocated to subscriber ${subscriberId}`);
    } catch (error) {
      await transaction.rollback();
      throw error;
    }
  }

  // Additional methods for other operations...
}

API Endpoints¶

The following REST endpoints are available for physical SIM card management:

// Provisioning endpoints
POST /api/v1/sim/physical/provision
POST /api/v1/sim/physical/batch-provision

// State management endpoints
POST /api/v1/sim/physical/{iccid}/activate
POST /api/v1/sim/physical/{iccid}/suspend
POST /api/v1/sim/physical/{iccid}/block
POST /api/v1/sim/physical/{iccid}/unblock

// PIN/PUK management endpoints
POST /api/v1/sim/physical/{iccid}/verify-pin
POST /api/v1/sim/physical/{iccid}/change-pin
POST /api/v1/sim/physical/{iccid}/unblock-pin

// Query endpoints
GET /api/v1/sim/physical/{iccid}
GET /api/v1/sim/physical/batch/{batchId}
GET /api/v1/sim/physical/subscriber/{subscriberId}

Security Considerations¶

Access Control
Implement role-based access control (RBAC)
Restrict sensitive operations to authorized personnel
Maintain audit logs of all operations
Data Protection
Encrypt sensitive data at rest and in transit
Implement secure key management
Regular security audits
API Security
Use TLS for all API endpoints
Implement rate limiting
Validate all input data
Compliance
Follow GSMA security guidelines
Maintain compliance with local regulations
Regular security assessments