Oddziel katalog publiczny od odbioru prywatnego
Dane publiczne opisują usługę, kraj, cenę i czas trwania. Nie zawierają przydzielonego numeru telefonu ani kodu. Aktywacje należą do konta i zamówienia z oddzielnym prywatnym śledzeniem.
Katalog usług i krajów jest oddzielny od ofert komercyjnych. Umowa integracyjna wymaga katalogu API z autorytatywną ceną i dostępnością dla zamówień.
Katalog i zamawianie
Istniejący kontrakt określa GET /catalog/products i GET /catalog/products/:slug. Backend dostarcza autorytatywne ceny, czas trwania i wyraźną dostępność; brak zapasów pozostaje nieznany.
Zamówienia wysyłają identyfikator produktu z kluczem idempotencji. Serwer sprawdza cenę i stan magazynowy przed rezerwacją lub przydziałem. Odczyt strony nie wywołuje wrażliwych działań.
Stany odbioru
Moduł rozróżnia przydzielanie, oczekiwanie, odebrane, zakończone, anulowane, wygasłe i nieudane. Przydział może być oczekujący bez numeru; rzeczywiste oczekiwanie i odbiór wymagają numeru i terminu ważności backendu.
Każda wiadomość ma stabilny identyfikator, znacznik czasu i tekst. Backend może dostarczyć wyodrębniony kod; interfejs nie powinien zgadywać OTP. Publiczny katalog nie zawiera przydzielonych numerów telefonów ani prywatnych kodów.
Autoryzowane działania i aktualizacje
GET /activations i GET /activations/:id to prywatne odczyty. POST /activations/:id/actions wysyła anulowanie, zakończenie lub ponowne wysłanie z kluczem idempotencji. Backend ogłasza i ponownie sprawdza dozwolone działania.
Prywatne odczyty używają sesji, języka interfejsu i odpowiedniego buforowania. Interwały śledzenia podążają za umową; wygaśnięcie serwera i stan mają pierwszeństwo przed zegarem przeglądarki.
Płatności, przydziały i tajemnice dostawcy
Faktura określa aktywa, sieć, kwotę, adres i termin ważności. Potwierdzenie płatności i przydział numeru to osobne zdarzenia. Backend obsługuje błędy i ponowne próby bez podwójnego przydziału.
Klucze dostawcy i tajne dane płatności pozostają na serwerze. API autoryzuje każde odczytanie konta, definiuje przechowywanie wiadomości i utrzymuje wewnętrzne identyfikatory dostawców w tajemnicy. Ta strona dokumentuje umowę integracyjną i nie ogłasza operacyjnego publicznego API.
Referencja punktu końcowego umowy
| Metoda | Punkt końcowy | Rola |
|---|---|---|
GET | /catalog/products | Katalog publiczny |
GET | /activations | Aktywacje konta |
GET | /activations/:id | Prywatne śledzenie odbioru |
POST | /activations/:id/actions | Autoryzowana akcja |
To istniejące ścieżki frontendowe kontraktów, nieopublikowane punkty końcowe produkcji. Dostawca, uwierzytelnianie i integracja płatności pozostają do podłączenia.