Sparex

Elixir client for SPAR (Statens personadressregister), the Swedish state population register. Covers two services:

• Sparex.Personsok searches by id number or name/address.
• Sparex.Filtransport uploads id numbers and downloads avisering updates.

Both services use mutual TLS and SPAR customer identifiers. See docs/test-environment.md for test-environment setup, service-specific uppdrag_id values, and its limitations.

Usage

Convert SPAR's PKCS#12 certificate to PEM as described in Sparex.Client's module documentation. Configuration is split in two:

• Sparex.Client — your certificate and KundNrLeveransMottagare. Build once; it's the same for every request your application makes.
• Sparex.Uppdrag — the end customer (KundNrSlutkund), service-scoped UppdragId, and end-user id a specific request is for. Build fresh per request. For a multi-tenant application fetching data on behalf of several SPAR customers through one shared certificate, this is the one value that changes per tenant.

client =
  Sparex.Client.new(
    certfile: "path/to/cert.pem",
    keyfile: "path/to/key.pem",
    kund_nr_leverans_mottagare: "500243",
    env: :test
  )

# Or keep PEM secrets in memory (for example, environment variables).
production_client =
  Sparex.Client.new(
    cert_pem: System.fetch_env!("SPAR_CERT_PEM"),
    key_pem: System.fetch_env!("SPAR_KEY_PEM"),
    kund_nr_leverans_mottagare: "500243",
    env: :prod
  )

uppdrag =
  Sparex.Uppdrag.new(
    uppdrag_id: personsok_uppdrag_id,
    kund_nr_slutkund: "500243",
    slut_anvandar_id: "my-app-user-42"
  )

{:ok, people} = Sparex.Personsok.search_by_id_nummer(client, uppdrag, "195704133106")

{:ok, people} =
  Sparex.Personsok.search_by_name_address(client, uppdrag,
    mellan_efternamn: "Svensson",
    postort: "Solna"
  )

filtransport_uppdrag =
  Sparex.Uppdrag.new(
    uppdrag_id: filtransport_uppdrag_id,
    kund_nr_slutkund: "500243",
    slut_anvandar_id: "my-app-user-42"
  )

{:ok, upload} =
  Sparex.Filtransport.upload_id_nummer(client, filtransport_uppdrag, ["195704133106"])

{:ok, people} = Sparex.Filtransport.download_utfil(client, upload["sparadSom"])

An uppdrag_id is specific to both the SPAR service and customer; do not use the Personsök value for Filtransport, even for the same kund_nr_slutkund.

Choose one complete credential pair: certfile with keyfile, or cert_pem with key_pem. PEM private keys must be unencrypted. In-memory PEM values are decoded for OTP TLS and are never written to temporary files.

Installation

Once published on Hex, add the dependency to mix.exs:

def deps do
  [{:sparex, "~> 0.2.0"}]
end

License

MIT