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
  • Method: port_status

  • Port information
    infomessage Message to end user about port
    Below data fields adhere to the Marknadsdatabasen specification:
    infonettype
    infomedia
    infoportcapacity
    infocpecapacity
    infococpe
    infodhcpoption
    infoserviceport

    Service information
    servicesserviceid Service ID in system, same as service_uid in Tjänsteguiden
    servicesservicename Service name in system (is used if id can't be mapped to a service_uid)
    servicesservicedate Date for activation
    servicesservicecommitment Date for earliest deactivation
    servicesservicerelease Date for scheduled deactivation
    servicesservicemessage Message about service, shown to customer under "My Pages"

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


       <port_status>
          <response>
             <info>
                <message>Port avstängd på grund av utebliven betalning</message>
                <nettype>LAYER2</nettype>
                <media>FTTH</media>
                <portcapacity>100</portcapacity>
                <cpecapacity>1000</cpecapacity>
                <cocpe>YES</cocpe>
                <dhcpoption>5216010765746820302F31020B31302E</dhcpoption>
                <serviceport>ASAP</serviceport>
             </info>
             <services>
                <service>
                   <id>12</id>
                   <date>2010-12-03</date>
                   <name>T3 50/50 Mbit Privat</name>
                   <commitment>2030-01-01</commitment>
                   <release>0</release>
                   <message>Tjänst aktiverad via BRF Föreningen</message>
                </service>
                <service>
                   <id>13</id>
                   <date>2010-08-21</date>
                   <name>AllTele Telefoni Privat</name>
                   <commitment>2011-06-25</commitment>
                   <release>2030-01-01</release>
                </service>
             </services>
          </response>
          <status>success</status>
       </port_status>
  • Method: service_deactivate

  • 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
    Endpoint example:
    ?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

  • 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)

    "origin" är antingen "customer" eller "service provider" och avser i vilket scenario metoden efterfrågas, antingen via Tjänsteguiden av slutkund (customer) eller av Tjänsteleverantör via API eller Aktiveringskonsollen (service provider).
  • Parameters
    1 socket string green 123-456-ABC UID for the user
    2 service_uid string green 12 UID for the service
    3 origin string green customer origin for the request
    Endpoint example:
    ?method=service_deliverable&socket=123-456-ABC&service_uid=12&origin=customer
  • 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

  • This can be used by the service providers via the direct activation console, in which case data for customer and order may not exist. The provider decides whether or not they want to submit the ID for their customer data in the field "xspcid". Use the "initiator" field to determine whether a customer is making the request or a service provider
  • 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 origin string green customer Who is initiating the activation
    5 customer int 123 ID for the customer, to fecth customer data via API
    6 order int 12345 ID for the complete order, for accessing via API
    7 xspcid int 2938 ID for customer in XSP system, if available
    Endpoint example:
    ?method=service_order&socket=123-456-ABC&service_uid=12&date=2011-02-30&origin=customer&customer=123&order=12345&xspcid=2938
  • success response


       <service_order>
          <status>success</status>
       </service_order>