Aktiverings-API

För att använda Aktiverings-API:et krävs två funktioner i Stadsnätet

Bounce URL

Detta är en URL (adress) som besökarens webbläsare skickas till när dom besöker Tjänsteguiden. Den ska gå till en server i Stadsnätet som kan identifiera kunden med hjälp av ert provisioneringssystem. Läs mer om hur själva identifieringen går till här: documentation Identifiering av kund. Den här URL:en måste vara tillgänglig för alla, både i stadsnätet och från internet

API URL

Om besökaren till Tjänsteguiden kan identifieras enligt ovan så används API URL:en för all kommande kommunikation, detta är en sluten kommunikation som med föredel bör göras över SSL och vara IP-bunden till Tjänsteguidens IP så ingen annan kan komma åt den. Vid access skickar Tjänsteguiden med API Användar-information för verifikation av access om ovanstående inte kan uppnås. Den här URL:en måste vara tillgänglig från Atlas CMS (94.247.170.170) samt vår utvecklingsmiljö (217.78.19.*)

Utveckling och test

För att vi ska kunna hjälpa er komma igång samt felsöka problem så måste er API URL vara tillgänglig för våra IP-adresser, vilket är 217.78.19.*, och det är också viktigt att er Bounce-URL identifierar detta som en riktigt port i ert nät (en fejkport som används för tester är att föredra) där vi kan beställa, aktivera och testa API:et med.

Provisionering

För att besökaren till Tjänsteguiden ska kunna direktaktivera en tjänst så krävs det att en del parametrar har uppnåtts:
  1. Kunden har identifierats som stadsnätskund enligt ovan
  2. Tjänsteleverantören har valt att aktuell tjänst kan direktaktiveras
  3. Stadsnätet har angivit vilket det lokala unika ID't är för tjänsten, så att API:et kan skicka med rätt identifiering för aktuell tjänst

Om ovanstående har uppnåtts så används API:et för att:

  1. Skicka service_deliverable() för att säkerställa att aktuell tjänst kan aktiveras på aktuell port.
  2. Skicka service_order() för att skicka in en beställning till API-servern med aktuell tjänst och aktuell kund, samt kunddata från beställningsformuläret
  3. Vid direktaktivering, skicka port_status() för att säkerställa att tjänsten nu är aktiv på porten

Methods
API Endpoint: Activation
API för direktaktivering av tjänster.

Förklaring:
UID i anrop från Tjänsteguiden avser kundens identifieringssträng. Detta är samma data som skall finnas i Marknadsdatabasens "socket"-fält och bör i de flesta fall avse ett uttags-ID.

SERVICE i anrop från Tjänsteguiden avser tjänstens ID-nummer i provisioneringssystemet som angivits av admin i Tjänsteguiden.

UID i svar från API-servern avser tjänstens ID i provisioneringssystemet. Detta skall vara exakt samma ID som anges av admin i Tjänsteguiden för att koppla samman tjänsterna i stadsnätet med dem i Tjänsteguiden.
Note that this API requires an authenticated user id and IP address Note that this API requires an authenticated user id and IP address

Use the API Credentials module in admin to set up API access for this module
  • Method: port_status

  • Information


    Svaret ger detaljerad information om status på den angivna porten, med en lista av aktiva tjäntser på porten och information relaterat till det.

    Information om porten
    infocapacity Portens kapacitet, i kbits (10000 = 10 Mbit/s)
    infocpe Om CPE finns. 1 = Finns, 2 = Finns ej, 3 = Uppgift saknas
    infocpetype CPE-typ, modelbeteckning t.ex
    infonettype Nättyp, 2 = Layer 2, 3 = Layer 3
    infomedia Anslutning till CPE (1 = Fiber, 2 = Coaxial, 3 = TP, 4 = ADSL)

    Tjänsteinformation
    servicesserviceid Tjänstens ID i systemet
    servicesservicename Tjänstens namn i systemet (Används om tjänsten inte längre finns i Tjänsteguiden)
    servicesservicedate Datum då tjänsten kopplades in
    servicesservicecommitment Datum då tjänsten tidigast kan avbeställas
    servicesservicerelease Datum då tjänsten kommer kopplas ur

  • Parameters
    1 socket string green 123-456-ABC User socket
    Example Query:
    ?method=port_status&socket=123-456-ABC
  • success response


       <port_status>
          <response>
             <info>
                <capacity>10000</capacity>
                <cpe>1</cpe>
                <cpetype>ASL-12345</cpetype>
                <nettype>3</nettype>
                <media>1</media>
             </info>
             <services>
                <service>
                   <id>12</id>
                   <date>2010-12-03</date>
                   <name>T3 50/50 Mbit Privat</name>
                   <commitment>2011-02-03</commitment>
                   <release>2011-02-03</release>
                </service>
                <service>
                   <id>13</id>
                   <date>2010-08-21</date>
                   <name>AllTele Telefoni Privat</name>
                   <commitment>2011-06-25</commitment>
                   <release>0</release>
                </service>
             </services>
          </response>
          <status>success</status>
       </port_status>
  • Method: service_deactivate

  • Information

  • Parameters
    1 socket string green 123-456-ABC UID for the socket
    2 service_uid string green 12 UID for the service
    3 date date green 2011-12-23 Date for deactivation
    Example Query:
    ?method=service_deactivate&socket=123-456-ABC&service_uid=12&date=2011-12-23
  • success response


       <service_deactivate>
          <status>success</status>
       </service_deactivate>
  • Method: service_deliverable

  • Information


    Anger om tjänsten går att aktivera på porten. Koden avgör status

    200: OK
    Tjänsten kan aktiveras på porten

    400: Konflikt
    Om tjänsten inte kan aktiveras för det finns redan en aktiv tjänst som måste avbeställas separat innan denna kan aktiveras. Den tjänst som är i konflikt ska skickas med i svaret som ett eget fält (se exempel nedan) så skapas ett svar utifrån det.

    401: Fel media
    Kunden är ansluten via ett media som inte stödjer tjänsten (tex: TV via ADSL), Både media som krävs och som finns skall skickas med i svaret, och det ska använda de numeriska värden för media som återfinns här och fälten heter current_media och required_media, se exempel nedan

    402: Fel hastighet
    Kunden kan inte aktivera en internettjänst för porten tillåter inte den hastigheten (gigabit-tjänst på 100-port ex). Både nuvarande och krävd hastighet ska skickas med i svaret enligt det numeriska värdet som återfinns här. Fälten heter current_capacity och required_capacity, se exempel nedan.

    403: Utrustning saknas
    Kunden saknar rätt kundutrustning (DRG/CPE) för att aktivera tjänsten, krävd utrustning ska skickas med i fältet hardware, se exempel nedan

    404: Kund/Uttag hittas ej
    Porten har tagits bort ur systemet sedan vi identifierade kunden.

    När någon av dessa felkoder används behövs inget felmeddelande skickas med. Vissa kräver övrig information. Egna felkoder kan läggas in, dom skall då börja med kod 500 och uppåt samt ska ett meddelande skickas med (se exempel nedan)
  • Parameters
    1 socket string green 123-456-ABC UID for the user
    2 service_uid string green 12 UID for the service
    Example Query:
    ?method=service_deliverable&socket=123-456-ABC&service_uid=12
  • failed response 400


       <service_deliverable>
          <status>failed</status>
          <response>
             <code>400</code>
             <service>B2-10-10-VOIP</service>
          </response>
       </service_deliverable>
  • failed response 401


       <service_deliverable>
          <status>failed</status>
          <response>
             <code>401</code>
             <current_media>1</current_media>
             <required_media>2</required_media>
          </response>
       </service_deliverable>
  • failed response 402


       <service_deliverable>
          <status>failed</status>
          <response>
             <code>402</code>
             <current_capacity>50000</current_capacity>
             <required_capacity>100000</required_capacity>
          </response>
       </service_deliverable>
  • failed response 403


       <service_deliverable>
          <status>failed</status>
          <response>
             <code>403</code>
             <hardware>CPE</hardware>
          </response>
       </service_deliverable>
  • failed response


       <service_deliverable>
          <status>failed</status>
          <response>
             <code>500</code>
             <message>Endast studenter kan beställa den tjänsten</message>
          </response>
       </service_deliverable>
  • success response


       <service_deliverable>
          <status>success</status>
          <response>
             <code>200</code>
          </response>
       </service_deliverable>
  • Method: service_order

  • Parameters
    1 socket string green 123-456-ABC UID for the socket
    2 service_uid string green 12 UID for the service
    3 date ISO Date green 2011-02-30 Date for activation. If date is today, then it should be activated directly
    4 firstname string green John
    5 surname string green Appleseed
    6 socialsecurity string green 750218-3429 Social security number
    7 address string green North Street 4
    8 zip int green 12345
    9 city string green Chicago
    10 apartmentnumber string 4B
    11 phone string 021-34 56 78
    12 cell string 070-305 46 57
    13 email string green john@appleseed.com
    14 customer int green 123
    Example Query:
    ?method=service_order&socket=123-456-ABC&service_uid=12&date=2011-02-30&firstname=John&surname=Appleseed&socialsecurity=750218-3429&address=North+Street+4&zip=12345&city=Chicago&apartmentnumber=4B&phone=021-34+56+78&cell=070-305+46+57&email=john%40appleseed.com&customer=123
  • success response


       <service_order>
          <status>success</status>
       </service_order>
#inlineditbutton