Skip to main content

Third-Party Integrations

Integration Overview​

Identity Services​

Nafath Integration​

nafath:
  environment:
    production: https://api.nafath.sa
    staging: https://stg-api.nafath.sa
    
  authentication:
    type: oauth2
    client_id: ${NAFATH_CLIENT_ID}
    client_secret: ${NAFATH_CLIENT_SECRET}
    
  endpoints:
    verify_identity:
      method: POST
      path: /v1/verify
      required_params:
        - national_id
        - otp
        
    check_status:
      method: GET
      path: /v1/status/{request_id}

Yakeen Integration​

yakeen:
  environment:
    production: https://api.yakeen.sa
    staging: https://stg-api.yakeen.sa
    
  authentication:
    type: certificate
    cert_path: /path/to/yakeen.crt
    key_path: /path/to/yakeen.key
    
  endpoints:
    verify_business:
      method: POST
      path: /v1/business/verify
      required_params:
        - cr_number
        - business_name

Credit Services​

SIMAH Integration​

simah:
  environment:
    production: https://api.simah.com
    staging: https://stg-api.simah.com
    
  authentication:
    type: api_key
    header: X-SIMAH-API-KEY
    
  endpoints:
    credit_report:
      method: POST
      path: /v2/reports/credit
      required_params:
        - national_id
        - report_type
        
    credit_score:
      method: GET
      path: /v2/scores/{national_id}

Banking Services​

RiyadBank Integration​

riyadbank:
  environment:
    production: https://api.riyadbank.com
    staging: https://stg-api.riyadbank.com
    
  authentication:
    type: oauth2
    client_id: ${RB_CLIENT_ID}
    client_secret: ${RB_CLIENT_SECRET}
    
  endpoints:
    fund_transfer:
      method: POST
      path: /v1/transfers
      required_params:
        - source_account
        - destination_account
        - amount
        
    account_inquiry:
      method: GET
      path: /v1/accounts/{account_number}

Document Services​

Contracts.sa Integration​

contracts_sa:
  environment:
    production: https://api.contracts.sa
    staging: https://stg-api.contracts.sa
    
  authentication:
    type: jwt
    secret: ${CONTRACTS_SECRET}
    
  endpoints:
    generate_contract:
      method: POST
      path: /v1/contracts
      required_params:
        - template_id
        - contract_data
        
    sign_contract:
      method: POST
      path: /v1/contracts/{contract_id}/sign
      required_params:
        - signer_id
        - signature_type

Integration Flow​

Error Handling​

Error Codes​

error_handling:
  identity:
    1001: Invalid national ID
    1002: OTP expired
    1003: Verification failed
    
  credit:
    2001: No credit history
    2002: Report unavailable
    2003: Service unavailable
    
  banking:
    3001: Insufficient funds
    3002: Invalid account
    3003: Transfer failed

Monitoring​

Monitoring Configuration​

monitoring:
  health_check:
    interval: 1m
    timeout: 5s
    failure_threshold: 3
    
  metrics:
    response_time:
      threshold: 2s
      percentile_95: 1s
      
    error_rate:
      threshold: 5%
      window: 5m

Best Practices​

Integration​

  1. Secure communication
  2. Proper authentication
  3. Request validation
  4. Response handling

Error Handling​

  1. Retry mechanisms
  2. Circuit breakers
  3. Fallback options
  4. Error logging

Monitoring​

  1. Health checks
  2. Performance metrics
  3. Error tracking
  4. Alert configuration

Security​

  1. Data encryption
  2. Access control
  3. Audit logging
  4. Compliance checks