nexcon-sim-operations

Nextcon M2M — SIM Cards Operations Workbook

Nextcon is the M2M SIM card provider for all Teltonika GPS tracking devices (TAT140 trailers, FMC650 trucks) used in the Ecotrans fleet platform. SIMs are managed via the Nextcon API and portal.

---

Overview

Property	Value
Provider	Nextcon (M2M SIM cards)
Use case	GPS tracking — Teltonika TAT140 (trailers), FMC650 (tractors)
API base URL	https://app.nexcon.io
Portal	https://app.nexcon.io
API docs	https://nexcon.io/docs
Credential key	nexcon_api_key in .env.local
Workbook last reviewed	2026-06-15

---

Whitelisted IP Addresses

Nextcon API requires server-side IP whitelisting. The following IPs are registered:

IP	Host	Role	Added
217.154.82.162	vps-i1 (IONOS)	Monitoring + Traccar server	2026-06-15
54.36.123.110	bms-4 (OVH ns3101999)	AI agent host + n8n automation	2026-06-15

How to add/verify in Nextcon portal

1. Log in to Nextcon portal → API or Developers section
2. Navigate to Whitelist / IP Management
3. Confirm both IPs above are listed — add any missing ones
4. Changes take effect within minutes

Rule: Any server that calls the Nextcon API (scripts, n8n workflows, audit-engine) must run on one of these two hosts, or the IP must be added to the whitelist first.

---

Credentials

Key	Location	Purpose
nexcon_api_key	.env.local	Bearer token for all API calls
nexcon_api_url	.env.local	https://app.nexcon.io

Secrets live in .env.local on the developer machine. Never commit values to git.

---

SIM Card Inventory

Total: 2 SIMs — both ACTIVATED. Last verified 2026-06-15 via API.

ICCID	MSISDN	Device IMEI	Traccar device	Model	Vehicle	Status
89450100250731069754	+4535799454	861327086022865	id=12 “2865 TAT140 GISV599 Kipper”	TAT140	GISV599 Kipper	ACTIVATED
89450100250731069747	+4535799460	864636069429401	id=14 “HVLET256 9401 FMC650”	FMC650	HVLET256	ACTIVATED

Both Nexcon SIMs belong to **Order 3414. Both Traccar devices were offline / no position at inventory time — SIMs are active but devices may need physical check.

ICCID is readable as AVL ID io11 in Traccar position attributes once the device connects.

---

APN Configuration (for Teltonika Configurator)

Parameter	Value
APN	(from Nextcon portal → SIM details → APN)
APN Login	(from Nextcon — often empty for M2M)
APN Password	(from Nextcon — often empty for M2M)

Enter these in Teltonika Configurator → GPRS tab. See teltonika-device-setup.md for full device config.

---

REST API

All REST calls must originate from a whitelisted host (vps-i1 or bms-4). The API returns an async job envelope: { eventId, data: { results: [...] }, status: "SUCCEEDED" } — actual records are in data.results.

Verified endpoints (2026-06-15)

Method	Path	Returns
GET	/api/v1/sims	All SIMs (job envelope → data.results)
GET	/api/v1/sims/{iccid}	Single SIM detail
POST	/api/v1/sims/{iccid}	Update SIM status/tags
GET	/api/v1/usage?period=current	Account-level totals (data/SMS/call/cost)

List all SIMs

# From vps-i1 or bms-4 — key must be in environment
curl -s -H "Authorization: Bearer $nexcon_api_key" \
  https://app.nexcon.io/api/v1/sims \
  | python3 -m json.tool

Check single SIM status

curl -s -H "Authorization: Bearer $nexcon_api_key" \
  "https://app.nexcon.io/api/v1/sims/{iccid}" \
  | python3 -m json.tool

Check account-level usage

curl -s -H "Authorization: Bearer $nexcon_api_key" \
  "https://app.nexcon.io/api/v1/usage?period=current" \
  | python3 -m json.tool

Returns dataTotal, smsTotal, callTotal, priceTotal (EUR). Unit for dataTotal is unconfirmed — observed value ~0.003 for 2 active SIMs suggests GB, but the API docs do not specify units explicitly.

Per-SIM usage is not available via the REST API. /api/v1/usage always returns account totals regardless of query parameters (?simId=, ?groupBy=sim). Per-SIM breakdown requires the GraphQL API with a session token — see GraphQL API below.

Activate a SIM

curl -s -X POST -H "Authorization: Bearer $nexcon_api_key" \
  -H "Content-Type: application/json" \
  -d '{"operationalStatus": "ACTIVATED"}' \
  "https://app.nexcon.io/api/v1/sims/{iccid}"

Deactivate a SIM (suspend)

curl -s -X POST -H "Authorization: Bearer $nexcon_api_key" \
  -H "Content-Type: application/json" \
  -d '{"operationalStatus": "SUSPENDED"}' \
  "https://app.nexcon.io/api/v1/sims/{iccid}"

---

GraphQL API

Endpoint: https://app.nexcon.io/api/graphql

The Nexcon portal is Nuxt-based and uses Apollo Client for all functionality. The GraphQL API is not intended for third-party automation:

• Introspection is disabled in production — schema cannot be fetched via __schema
• Authentication requires a browser session token (OCID login), not the REST API key — REST key returns 401
• 183 operations were discovered by scanning the Nuxt JS bundle (/_nuxt/CkvkKiDU.js) in June 2026

Key discovered operations

Operation	Purpose
AccountApiKeySetWhitelistIps	Programmatic IP whitelist management
SimActivate / SimDeactivate	SIM lifecycle (mirrors REST API)
InsightDetailedList	Per-SIM data usage breakdown — needs session token
FlowCreate / FlowUpdate	Automation flows (send SMS on event, trigger on SIM state, etc.)
ApnSessionLatest	Most recent APN session — useful for SIM connectivity debugging
SimSearch / SimList	SIM listing with filtering
OrderList	Order history

Using GraphQL (manual, session token)

1. Log in to https://app.nexcon.io in a browser
2. Extract session token from DevTools → Network → any GraphQL request → Authorization: Bearer <token>
3. Use that token in Authorization: Bearer <session_token> for GraphQL requests
4. Session tokens are short-lived — not suitable for automation

If per-SIM usage data becomes a monitoring requirement, ask Nexcon support for a REST endpoint or documented GraphQL token flow.

---

Prometheus Exporter (nexcon-exporter)

A custom exporter scrapes the Nexcon REST API every 5 minutes and exposes Prometheus metrics.

Property	Value
Container	nexcon-exporter
Port	:9231
Host	vps-i1 (monitoring Docker Compose)
Poll interval	300 s (5 min)
Prometheus job	nexcon_exporter (5 min scrape interval)
Source	monitoring/exporters/nexcon-exporter/

Exposed metrics

Metric	Type	Labels	Description
nexcon_sim_info	Gauge (1)	icc, msisdn, imei, operational_status, system_status, imei_locked, tags	Info vector — 1 per SIM
nexcon_sim_activated	Gauge	icc, msisdn, imei	1 if ACTIVATED, 0 otherwise
nexcon_sims_total	Gauge	operational_status	Count of SIMs by status
nexcon_account_data_usage_total	Gauge	—	Account data usage (unit TBC — likely GB)
nexcon_account_sms_total	Gauge	—	Account SMS sent
nexcon_account_call_total	Gauge	—	Account call minutes
nexcon_account_price_eur	Gauge	—	Account cost EUR (current period)
nexcon_exporter_scrape_errors_total	Counter	endpoint	Scrape errors by endpoint
nexcon_exporter_last_scrape_success_timestamp	Gauge	—	Unix timestamp of last successful poll

Environment variables

Variable	Default	Description
NEXCON_API_KEY	(required)	Bearer token — read from monitoring/.env
NEXCON_BASE_URL	https://app.nexcon.io	API base URL
POLL_INTERVAL_S	300	Poll interval in seconds
PORT	9231	HTTP port for /metrics and /health

---

Grafana Dashboard

Dashboard Nexcon SIM Cards is provisioned automatically from: monitoring/grafana/provisioning/dashboards/nexcon-sim.json

Property	Value
Dashboard UID	nexcon-sim-v1
Live URL	https://grafana.vps-i1.infra.zintegrowana.online/d/nexcon-sim-v1
Datasource	Prometheus (Thanos Query)
Refresh	5 min

Panels

Panel	Type	Shows
Active SIMs	Stat	Count where nexcon_sim_activated == 1
Total SIMs	Stat	count(nexcon_sim_info)
Data used	Stat	nexcon_account_data_usage_total
SMS sent	Stat	nexcon_account_sms_total
Cost EUR	Stat	nexcon_account_price_eur
Last scrape age	Stat	Seconds since last successful poll
SIM Card Status	Table	ICC, MSISDN, IMEI, status colour-coded (green=ACTIVATED, yellow=SUSPENDED, red=TERMINATED)
Data usage over time	Time series	nexcon_account_data_usage_total trend
SMS & cost over time	Time series	SMS + cost EUR over time
Per-SIM activated status	Time series	nexcon_sim_activated per ICC/IMEI
Scrape errors	Time series	nexcon_exporter_scrape_errors_total

---

Data Usage Monitoring

The nexcon-exporter polls every 5 minutes; Grafana dashboard nexcon-sim-v1 shows account-level usage trends. Per-SIM breakdown is not available via the REST API (see GraphQL API above).

Quick check for a device that stopped reporting:

1. Look up ICCID from Traccar — GET /api/positions?deviceId={id} → attributes.io11
2. Check nexcon_sim_activated{icc="<iccid>"} in Grafana — should be 1
3. Check APN session via portal → SIM → APN Sessions (or GraphQL ApnSessionLatest)
4. If SIM SUSPENDED → re-activate via portal or REST API (see above)
5. If data quota exhausted → contact Nexcon support to top up or switch plan

---

Troubleshooting

Device stopped sending GPS positions

Check	How
SIM activated?	Grafana nexcon-sim-v1 → SIM Card Status table; or Nexcon portal
Data quota?	Grafana nexcon-sim-v1 → Data used stat (account total); Nexcon portal for plan details
APN session?	Nexcon portal → SIM → APN Sessions — confirms device connected recently
APN config correct?	Teltonika Configurator → GPRS → APN must match Nexcon APN from portal
Server reachable from SIM?	Teltonika Configurator → Device status → Server Status: Connected

API call returns 403 / Unauthorized

The calling server IP is not on the Nextcon whitelist. Add the IP in Nextcon portal → API → Whitelist. Current whitelisted IPs: 217.154.82.162 (vps-i1), 54.36.123.110 (bms-4).

API call returns 401

NEXCON_API_KEY is invalid or expired. Regenerate in Nextcon portal → API Keys, update .env.local, and re-sync to vps-i1.

---

Password / Key Rotation

Credential	Frequency	How to rotate
NEXCON_API_KEY	90 days (or on suspected exposure)	Nextcon portal → API Keys → Regenerate → update .env.local → re-sync to vps-i1 → update GitHub Secret if used in CI

---

Related Docs

• teltonika-device-setup.md — Teltonika Configurator: APN, server IP, AVL IDs, device registration
• traccar-operations.md — Traccar GPS server: devices, positions, API
• cloud-services-operations.md — Other external SaaS dependencies
• nexcon-exporter — Prometheus exporter source
• nexcon-sim.json — Grafana dashboard definition