List coverage

GET/v1/catalog/coveragecatalog:read

Returns a summary of where you can sell. It is the first screen of a destination picker: the customer chooses “Turkey” or “Europe”, and only then do you fetch the plans.

To fetch catalogs and their complete matching package lists together, use List catalogs with packages.

With scope=local (the default) each row is a country.
With scope=regional or scope=global each row is a catalog — a curated group our team assembles, such as “Europe” or “Global Pass”.

Each row tells you how many plans are on sale under it and whether any of them carry voice and SMS. The counts use the same rule as List packages, so a row with plans: 7 lists exactly seven packages when you drill in.

Query parameters

Name	Type	Default	Notes
`scope`	string	`local`	`local`, `regional` or `global`

curl 'https://partner-api.esimfo.com/v1/catalog/coverage?scope=local' \
  -H 'Authorization: Bearer esf_live_at_...'

Response `200`

Field	Type	Notes
`scope`	enum	The scope you asked for
`total_countries`	integer	Countries with at least one plan. `0` for regional and global
`total_plans`	integer	Distinct packages on sale in this scope
`data[].key`	string	What to filter by. A country code when `scope` is `local`, a catalog id otherwise
`data[].name`	string	Country name, or catalog name
`data[].plans`	integer	Packages on sale under this row
`data[].country_count`	integer	Countries covered. Always `1` on local rows
`data[].has_voice`	boolean	`true` when at least one plan carries voice and SMS

{
  "scope": "local",
  "total_countries": 2,
  "total_plans": 11,
  "data": [
    { "key": "TR", "name": "Turkey", "plans": 7, "country_count": 1, "has_voice": true },
    { "key": "DE", "name": "Germany", "plans": 4, "country_count": 1, "has_voice": false }
  ]
}

A regional row looks the same, but key is a catalog id:

{
  "scope": "regional",
  "total_countries": 0,
  "total_plans": 23,
  "data": [
    { "key": "cat_europe", "name": "Europe", "plans": 18, "country_count": 39, "has_voice": true },
    { "key": "cat_balkans", "name": "Balkans", "plans": 5, "country_count": 8, "has_voice": false }
  ]
}

Drilling into a row

key is meant to go straight back into List packages. Which filter it feeds depends on the scope:

# local row → country filter
curl 'https://partner-api.esimfo.com/v1/catalog/packages?country=TR' \
  -H 'Authorization: Bearer esf_live_at_...'

# regional or global row → catalog filter
curl 'https://partner-api.esimfo.com/v1/catalog/packages?catalog=cat_europe' \
  -H 'Authorization: Bearer esf_live_at_...'

Notes

No pagination. The local view has at most one row per country and the regional and global views one row per catalog — a few hundred rows at most.

Rows without plans are omitted. A catalog that is set up but has nothing on sale does not appear, so you never show the customer an empty group.

total_plans counts distinct packages. A package can sit in two regional catalogs; the row counts would add it twice, the total does not.

Cache it briefly. Coverage changes when our team edits catalogs, which is rare. A few minutes is safe; a day is not.

Errors

Status	Code	Cause
403	`insufficient_scope`	Key lacks `catalog:read`