sparex

# 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`](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.

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

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`.

## Installation

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

```elixir
def deps do
  [{:sparex, "~> 0.1.0"}]
end
```

## License

[MIT](LICENSE)