DCI Integration#

For: developers

Integrate OpenSPP with Digital Convergence Initiative (DCI)-compliant social protection systems — either by exposing OpenSPP registry data through DCI endpoints or by consuming data from external DCI registries (CRVS, IBR, disability registries, etc.).

How to use this section#

  1. Read DCI Overview to understand DCI architecture and the interaction patterns (sync/async search, subscribe/notify)

  2. Read the role-specific guide for your scenario:

  3. Consult DCI Protocol Details for message envelope, HTTP Signature, and endpoint reference

Prerequisites#

  • Familiarity with Odoo module structure and FastAPI

  • Understanding of HTTP Message Signatures (draft-cavage / RFC 9421)

  • Familiarity with Bearer token authentication patterns

  • Basic knowledge of async operations with queue_job

  • Familiarity with the OpenSPP registry structure (res.partner, spp.registry.id)

When do you need DCI?#

Scenario

Module(s) to install

Role

Guide

Expose OpenSPP as a DCI server for external MIS systems

spp_dci, spp_dci_server

Server

OpenSPP as DCI Server

Import births/deaths from a national CRVS

spp_dci, spp_dci_client, spp_dci_client_crvs

Client

OpenSPP as DCI Client

Check for duplicate enrollments in other programs (IBR)

spp_dci, spp_dci_client, spp_dci_client_ibr

Client

OpenSPP as DCI Client

Query a Disability Registry for eligibility targeting

spp_dci, spp_dci_client, spp_dci_client_dr

Client

OpenSPP as DCI Client

Try an end-to-end DCI example out of the box

spp_dci_demo

Demo

Install the module

Understand DCI message formats / protocol details

spp_dci (core)

Either

DCI Protocol Details

Build a custom OpenSPP endpoint that isn't DCI-compliant

—

N/A

Use API V2 instead

OpenSPP DCI modules#

Module

Purpose

Role

spp_dci

Core DCI infrastructure — message envelope, HTTP Signature, JWKS, shared schemas

Foundation

spp_dci_server

DCI server infrastructure — FastAPI app (/dci_api/v1), signature middleware, sender registry, subscriptions, transactions

Server

spp_dci_client

Base DCI client (DCIClient) — synchronous HTTP client with OAuth 2.0 and outbound signature handling

Client

spp_dci_client_crvs

CRVS client (CRVSService) for birth verification and death lookups

Client

spp_dci_client_ibr

IBR client (IBRService) for duplicate enrollment checks

Client

spp_dci_client_dr

Disability Registry client (DRService) for PWD status queries

Client

spp_dci_demo

End-to-end demo layered on spp_mis_demo_v2 — birth verification for child benefit enrollment

Demo

Note

Server-side registry search needs an implementation module. spp_dci_server provides the infrastructure (routers, middleware, models), but the actual search implementation for a given registry type is loaded dynamically. Until an implementation module is installed, search requests receive a rejection response. See OpenSPP as DCI Server for details.

Common integration scenarios#

As a DCI server#

Example: A national MIS queries OpenSPP's Social Registry for beneficiary data.

        graph LR
    A[External MIS] -->|DCI Search Request| B[OpenSPP DCI Server]
    B -->|Query Registry| C[res.partner]
    C -->|Results| B
    B -->|Signed DCI Response| A

See OpenSPP as DCI Server for implementation details.

As a DCI client#

Example: OpenSPP imports birth registrations from a national CRVS.

        graph LR
    A[OpenSPP DCI Client] -->|DCI Search Request| B[National CRVS]
    B -->|Birth Records| A
    A -->|Create Registrants| C[res.partner]

See OpenSPP as DCI Client for implementation details.

See also#