Skip to content

Integration Services Module

Overview

This module owns all outbound integrations and external provider orchestration.

Base API route: - /api/v1/integration

Source layers scanned: - app/api/v1/endpoints/integration.py - app/services/integration.py - app/integrations/config/cbs.py - app/integrations/config/bill.py - app/integrations/config/sms.py - app/integrations/config/email.py - app/integrations/config/didit.py - app/integrations/config/firebase.py - app/integrations/config/totp.py - app/integrations/clients/http.py - app/integrations/clients/iso_tcp.py - app/integrations/services/didit.py

Canonical references: - API Route Live Reference - API Route Documentation TODO

Verified Endpoint Coverage (Controller to Service)

Route Method Permission Issuer Client Service Function
/customer/search POST customer_search cbs customer_search_cbs
/account/search POST account_search cbs account_search_cbs
/account/details POST account_details cbs account_details_cbs
/statement/search POST mini_statement cbs mini_statement_cbs
/account/balance POST account_balance cbs account_balance_cbs
/mno/validate POST mno_validate cbs mno_validate_cbs
/dictionary/bank POST bank_dictionary cbs bank_dictionary_cbs
/interbank/account-name POST interbank_account_name cbs interbank_account_name_cbs
/biller/category POST biller_category bill biller_category_bill
/biller/fetch POST biller_fetch bill biller_fetch_bill
/biller/package POST biller_package bill biller_package_bill
/sms/send POST send_sms sms send_sms_message
/email/send POST send_email email send_email_message
/simulator/download GET none n/a generate_simulated_cbs_report

All integration controllers call _release_request_transaction(request) before network I/O.

CBS Integration Deep Dive

Configuration Model

  • IntegrationConfig is the base integration settings model.
  • CBSAPIConfig extends IntegrationConfig and defines CBS URI mappings and simulator behavior.
  • TemporalCBSConfig extends CBSAPIConfig and serves simulated CBS data backed by SIM tables.

Runtime Path

  1. Controller injects client with Depends(get_api_client_with_issuer("cbs")).
  2. get_api_client resolves CBS config and builds APIClient.
  3. Service function in app/services/integration.py calls client.send_request(uri_key=..., method=..., body=...).
  4. APIClient resolves URI from config.uri_map and sends outbound request using httpx.AsyncClient.
  5. Response is mapped back to schema response models in integration endpoint handlers.

Simulation Path

  • When CBS_API_SIMULATE=true, APIClient returns config-driven simulated responses.
  • TemporalCBSConfig simulation can query simulator tables (SIMCustomer, SIMAccount, related models) for realistic local responses.

HTTP Client Stack (app/integrations/clients/http.py)

APIClient capabilities: - URL building from uri_key via provider uri_map. - Auth-header enforcement using required_auth_headers and reject_unauthorized. - SSL context setup with strict or relaxed TLS. - Automatic retries with exponential backoff and jitter. - Optional request encryption/signing. - XML parsing support when configured. - Structured audit trail logging through save_audit task.

Factory functions: - get_api_client(request, issuer): resolves issuer-specific config for cbs, bill, sms, email, push. - get_api_client_with_issuer(issuer): FastAPI dependency wrapper used directly by controllers. - get_api_client_celery(issuer, trace_id): non-request context client factory.

Provider config classes currently used with HTTP client: - CBSAPIConfig / TemporalCBSConfig - BILLAPIConfig - SMSAPIConfig - EmailSMTPConfig - FirebaseFCMConfig - DiditAPIConfig (used by app/integrations/services/didit.py with direct httpx client)

ISO TCP Client Stack (app/integrations/clients/iso_tcp.py)

Implemented primitives: - IsoTcpServer for inbound socket handling with message loop and async handler callback. - IsoTcpClient with connection pool, retries, backoff, and circuit breaker. - ISO8583 packing/unpacking helpers with 2-byte length prefix framing. - TLS context generation, audit hooks, metrics hooks, and demo request handler.

Current status in API flow: - No route in app/api/v1/endpoints/integration.py currently uses IsoTcpClient or IsoTcpServer. - ISO TCP utilities are available as infrastructure for switch/channel integrations but are not yet wired into live integration endpoints.

How to Integrate a New Third-Party API

Use this implementation path to stay consistent with current architecture:

  1. Add provider config class
  2. Create app/integrations/config/.py extending IntegrationConfig.
  3. Implement from_env(prefix) to load URL, headers, timeout, TLS, auth requirements, uri_map.

  4. Add setup_simulated_responses for local/test flows.

  5. Register issuer in HTTP client factory

  6. Update get_api_client and get_api_client_celery in app/integrations/clients/http.py.

  7. Map issuer string to your new config class.

  8. Add service orchestration function

  9. Implement provider call wrapper in app/services/integration.py.
  10. Use client.send_request with uri_key and method.

  11. Normalize HTTPException to CustomException.

  12. Add endpoint controller

  13. Add route in app/api/v1/endpoints/integration.py.
  14. Inject client with Depends(get_api_client_with_issuer("")).
  15. Apply permission_required dependency.

  16. Call _release_request_transaction(request) before external call.

  17. Add schema contracts

  18. Add request/response models in app/db/schemas.py and bind response_model in endpoint.

  19. Add observability and docs

  20. Confirm audit trail from APIClient is sufficient for provider calls.
  21. Add route to API Route Live Reference and module notes.

Security and Reliability Notes

  • Keep reject_unauthorized enabled for providers that must receive auth headers.
  • Keep strict_ssl enabled for production providers unless sandbox constraints require otherwise.
  • Prefer short timeouts and controlled retries to avoid endpoint lock-up.
  • Never log provider secrets or credential values in plaintext.