Aktywacja kart SIM przez API ThingSIM

Jeśli instalujesz urządzenia u klientów albo składasz je na stole montażowym, ręczna aktywacja każdej karty w portalu szybko staje się uciążliwa. API ThingSIM wykonuje to samo z poziomu twoich narzędzi: włącza kartę SIM, gdy jej urządzenie zostaje zainstalowane, nadaje etykietę, żeby łatwo ją potem znaleźć, i pobiera kody eSIM bez skanowania kodu QR. Ten poradnik pokazuje podstawowy przebieg.

Zanim zaczniesz

API to jeden punkt końcowy HTTPS, https://partners.netavo.com/api/v1, zwracający JSON. To samo API, z którego korzysta portal. Utwórz klucz w portalu w sekcji API keys i wybierz potrzebne zakresy; w tym poradniku są to iot.sims:read, iot.sims:write oraz, dla eSIM, iot.esim:read. Klucz jest wyświetlany tylko raz, więc zapisz go w bezpiecznym miejscu. Szczegóły znajdziesz w przeglądzie dla deweloperów i dokumentacji API (w języku angielskim).

export THINGSIM_API_KEY="your key"

Wyświetl listę kart SIM

Karty identyfikuje ICCID, numer nadrukowany na karcie. Wyświetl listę, żeby znaleźć tę, którą instalujesz:

curl "https://partners.netavo.com/api/v1/iot/sims?limit=5" \
  -H "Authorization: Bearer $THINGSIM_API_KEY"

Listę możesz filtrować po status lub tag albo użyć search.

Aktywuj kartę, gdy urządzenie zaczyna pracę

Karty przychodzą nieaktywne, a opłaty nalicza się od dnia włączenia każdej z nich (albo automatycznie po 30 dniach od wysyłki, z e-mailem co najmniej 5 dni wcześniej), więc naturalnym momentem aktywacji jest instalacja i test urządzenia. Z każdą aktywacją wysyłaj unikalny Idempotency-Key, a przy ponowieniu użyj tej samej wartości, żeby zerwane połączenie nigdy nie aktywowało karty dwa razy:

curl -X POST "https://partners.netavo.com/api/v1/iot/sims/8944000000000000000/activate" \
  -H "Authorization: Bearer $THINGSIM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Nadaj etykietę, póki wiesz, gdzie trafiła karta

Każda karta może mieć etykietę i tagi. Ustaw je przy instalacji, żeby później łatwo znaleźć i filtrować kartę:

curl -X PATCH "https://partners.netavo.com/api/v1/iot/sims/8944000000000000000" \
  -H "Authorization: Bearer $THINGSIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "Unit 4 gate camera", "tags": ["site-leeds", "camera"]}'

Pobierz kod eSIM bez skanowania QR

Dla urządzeń z eSIM kod aktywacyjny jest dostępny bezpośrednio, więc skrypt wdrożeniowy może wgrać go do urządzenia:

curl "https://partners.netavo.com/api/v1/iot/sims/8944000000000000000/esim" \
  -H "Authorization: Bearer $THINGSIM_API_KEY"

Inne przydatne funkcje

To samo API wstrzymuje i wznawia karty, zmienia pakiety (POST .../plan z identyfikatorem pakietu z GET /v1/iot/plans), odczytuje zużycie i sesje oraz dezaktywuje wycofane karty. Dezaktywacja wymaga osobnego zakresu, iot.sims:cease, więc klucz używany przez aplikację instalatora nie dezaktywuje karty na stałe przez pomyłkę. Każdemu kluczowi dawaj tylko potrzebne zakresy.

Jeśli wolisz dostawać informacje o zdarzeniach zamiast ich odpytywać, na przykład o aktywacji karty lub zbliżaniu się do limitu, skorzystaj z webhooków: zobacz webhooki zużycia. O porządku we flocie przeczytasz w poradniku zarządzanie małą flotą kart SIM.

Najczęstsze pytania

Czy API różni się od portalu?

Nie. To samo API, z którego korzysta portal, więc wszystko, co możesz zrobić z kartą w portalu, możesz zautomatyzować.

Co zapobiega podwójnej aktywacji karty przy ponowionym żądaniu?

Nagłówek Idempotency-Key. Z każdą operacją wysyłaj nową unikalną wartość, a przy ponowieniu tę samą, i API wykona operację tylko raz.

Czy klucz API można ograniczyć do wybranych operacji?

Tak. Klucze mają zakresy; dezaktywacja karty wymaga na przykład osobnego zakresu iot.sims:cease, więc każdemu kluczowi dawaj tylko to, czego potrzebuje.