Integration Guidelines

Best practices for secure and reliable FIRS e-invoicing integration

API DocumentationAPI Explorer

Access Model & Authentication

Platform Keys (Recommended)

  • • x-api-key - Public identifier
  • • x-api-secret - Private secret
  • • Used for all /api/firs/** endpoints
  • • Safe to store in server environment
  • • Can be rotated without FIRS involvement

FIRS Credentials (Protected)

  • • FIRS portal email & password
  • • Used only for initial authentication
  • • Stored securely in Felcy infrastructure
  • • Never exposed to client applications
  • • Required for background sync operations

Critical Security Rule

Never expose FIRS credentials to client-side code. Always use platform API keys for client applications and store FIRS credentials only on secure servers or through Felcy's proxy authentication.

Secrets Management

Storage Best Practices

✅ Do

  • • Store in environment variables
  • • Use secure key management services
  • • Encrypt at rest and in transit
  • • Implement access logging
  • • Rotate secrets regularly (monthly)

❌ Don't

  • • Hardcode in source code
  • • Store in client-side applications
  • • Share via email or chat
  • • Use in development/staging
  • • Log secrets in application logs

Secret Rotation Example

# Rotate API secret
curl -X POST https://api.felcytech.com.ng/api/v1/auth/rotate-secret \
  -H "x-api-key: your_current_api_key" \
  -H "x-api-secret: your_current_api_secret" \
  -H "Content-Type: application/json"

# Response includes new secret
{
  "newSecret": "mbs_proxy_secret_new_xyz789",
  "expiresAt": "2024-02-15T10:30:00Z"
}

Error Handling & Resilience

FIRS Error Surfacing

Always surface FIRS error payloads to help users understand validation failures:

{
  "code": 400,
  "error": {
    "type": "firs_validation_error",
    "message": "Invoice validation failed",
    "details": [
      {
        "field": "accountingSupplierParty.tin",
        "code": "INVALID_TIN_FORMAT",
        "message": "TIN must be in format XXXXXXXX-XXXX"
      }
    ],
    "upstream": {
      "firsCode": "VAL_001",
      "firsMessage": "Supplier TIN validation failed"
    }
  }
}

Retry Strategy

Exponential Backoff Pattern

  • • 5xx errors: Retry with exponential backoff (1s, 2s, 4s, 8s)
  • • 429 Rate Limit: Respect Retry-After header
  • • Network timeouts: Retry up to 3 times
  • • 4xx errors: Do not retry (fix request first)
  • • Max retries: 3 attempts with circuit breaker

Rate Limiting Best Practices

Rate Limit Handling
# Check rate limit headers
curl -I https://api.felcytech.com.ng/api/v1/invoice/validate \
  -H "x-api-key: your_api_key" \
  -H "x-api-secret: your_api_secret"

# Response headers:
# X-RateLimit-Limit: 1000
# X-RateLimit-Remaining: 999
# X-RateLimit-Reset: 1642694400

Invoice Lifecycle Management

Workflow Sequence

1

Validate Invoice Reference Number

Check reference number format and business association

POST /api/v1/invoice/reference/validate
2

Validate Invoice

Comprehensive business rules and structure validation

POST /api/v1/invoice/validate
3

Sign Invoice

Apply digital signature for authenticity

POST /api/v1/invoice/sign
4

Transmit to FIRS

Submit to FIRS system for processing

POST /api/v1/exchange/transmit
5

Confirm Delivery

Verify successful processing by FIRS

GET /api/v1/invoice/confirm/{referenceNumber}

Status Definitions

Confirm vs Delivered

  • • Confirmed: FIRS received and acknowledged
  • • Delivered: Successfully processed and stored
  • • Rejected: Failed validation or processing
  • • Pending: In FIRS processing queue

When to Check Status

  • • Immediately after transmission
  • • Every 5 minutes for first hour
  • • Every 30 minutes thereafter
  • • Stop checking after 24 hours

Synchronization Strategy

Sync Frequency Recommendations

Login Sync

Full sync on first login, incremental on subsequent logins

Scheduled Sync

Every 15-30 minutes during business hours

Manual Sync

User-triggered sync for immediate updates

CRON Implementation Examples

Sync Optimization Tips
  • • Use incremental sync with lastModified timestamps
  • • Implement sync queues for high-volume operations
  • • Cache frequently accessed data locally
  • • Monitor sync performance and adjust frequency
  • • Handle sync conflicts with business rules
Data Retention & Privacy
Audit Logs
  • • Retention: 7 years (FIRS compliance)
  • • Scope: All API calls, status changes
  • • Access: Authorized personnel only
  • • Format: Structured JSON with timestamps
  • • Backup: Daily encrypted backups
PII Handling
  • • Masking: Email, phone, address fields
  • • Encryption: AES-256 at rest
  • • Access: Role-based permissions
  • • Deletion: Right to be forgotten
  • • Consent: Explicit user consent required
Data Masking Example
Original:
john.doe@company.com
Masked:
j***@c******.com
Environment Management
Sandbox Environment
  • • URL: sandbox.api.felcytech.com.ng
  • • Purpose: Development and testing
  • • Data: Mock FIRS responses
  • • Rate Limits: Relaxed (1000/hour)
  • • Reset: Daily data cleanup
Production Environment
  • • URL: api.felcytech.com.ng
  • • Purpose: Live FIRS integration
  • • Data: Real FIRS system
  • • Rate Limits: Standard (500/hour)
  • • SLA: 99.9% uptime guarantee
Environment Configuration
# .env.development
FELCY_API_URL=https://sandbox.api.felcytech.com.ng
FELCY_API_KEY=sandbox_key_xxx
FELCY_API_SECRET=sandbox_secret_xxx

# .env.production  
FELCY_API_URL=https://api.felcytech.com.ng
FELCY_API_KEY=prod_key_xxx
FELCY_API_SECRET=prod_secret_xxx
Quick Links & Resources
API Documentation
Complete endpoint reference
API Explorer
Interactive testing tool
Manage Credentials
API keys and secrets