Skip to main content

Jurisdiction Settings

Two calls read and replace your organisation's settings for one country's e-invoicing pack:

GET  /api/v1/jurisdictions/{code}/settings
PUT  /api/v1/jurisdictions/{code}/settings

{code} is a two-letter country code, such as OM. Paths below are relative to https://app.goroute.ai/peppol-api.

These calls answer 404 on the production service, for every country

On GoRoute's production service (app.goroute.ai) no country pack is switched on, so both calls answer 404 JURISDICTION_NOT_AVAILABLE whatever code you ask for. That is deliberate and it is not waiting on a release: the production service is configured to keep country packs switched off.

They work on GoRoute's test service (app-test.goroute.ai), where the Oman pack is switched on, and they can be switched on for an in-country Oman service.

Check your own service before you build anything on this. With your API key, call:

curl -i -H "X-API-Key: YOUR_API_KEY" \
  "https://app.goroute.ai/peppol-api/api/v1/jurisdictions/OM/settings"
  • 404 — country packs are not switched on for your service. Nothing is wrong with your API key, and no code you can pass will work. There is nothing here for you yet.
  • 200 — packs are on, and the body is your organisation's stored settings.

If you get a 404 and expected otherwise, it is a question of how your service is configured, not of your credentials or your permissions.

There is one pack today: Oman, and it has a single setting that you cannot change. So even on a service where these calls work, there is very little to do with them. They are documented because they are callable and visible in the generated API reference, and a reader who finds them there deserves to know what they are and why they returned 404.

What a pack's settings are​

A country pack is GoRoute's implementation of one country's e-invoicing regime — Oman's PINT OM rendering, its tax reporting and its validation rules. Your organisation's settings for a pack are stored against your organisation and validated against that pack's own schema, so each country decides what its settings contain.

A pack is either mandated or opt-in:

  • Mandated means the country's rules apply to every matching document without you enrolling, and you cannot switch them off. Oman is mandated.
  • Opt-in means the pack applies only to organisations enrolled in it. There is no opt-in pack on the platform today.

Read your settings​

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://app.goroute.ai/peppol-api/api/v1/jurisdictions/OM/settings"

Needs a valid API key. No special permission.

{
  "code": "OM",
  "settings": {
    "enabled": true
  }
}

settings is an empty object ({}) when your organisation has never stored any. For a mandated pack such as Oman that does not mean the pack is off — a mandated pack applies whether or not you have stored anything.

Replace your settings​

The body is the settings object itself, not wrapped in anything. It replaces what was stored rather than merging into it, so send every key you want to keep.

curl -X PUT \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}' \
  "https://app.goroute.ai/peppol-api/api/v1/jurisdictions/OM/settings"

Needs the settings:manage permission, which is enforced for this call whatever your organisation's other role settings are. The response is the stored settings, as the GET would return them.

The permission is checked before the country code is looked up. A caller without it gets 403 for every code, including codes that are not packs at all, so the status code cannot be used to discover which packs a service has.

The Oman pack's settings​

One field:

FieldTypeDefaultMeaning
enabledbooleantrueWhether the Oman pack applies to your organisation

Any other key is rejected — the schema accepts no extra fields, so a typo is an error rather than a value silently ignored.

Oman is mandated, so enabled cannot be set to false. In practice the only bodies the PUT accepts for OM are {"enabled": true} and {} (which means the same thing, because enabled defaults to true). Anything that would switch Oman off is refused and nothing is stored.

This is why there is nothing to configure here today: the one setting the one pack has is one you are not permitted to change.

Refusals​

Statuserror_codeWhen
401—No API key, or one that is not valid
403INSUFFICIENT_PERMISSIONPUT without the settings:manage permission. Checked before the code, so you get this for any code
404JURISDICTION_NOT_AVAILABLE{code} is not a pack switched on for this service. On the production service this is every code
422JURISDICTION_SETTINGS_INVALIDThe body does not match the pack's schema — a wrong type, or a key the pack does not define. The response carries an issues list naming each problem
422JURISDICTION_MANDATEDThe pack is required by law and the settings would not keep it enabled — for Oman, {"enabled": false}. Nothing was stored

A JURISDICTION_MANDATED refusal is decided before your organisation record is read, so a rejected PUT never changes anything.

Last updated on