Stadsnätsportalen: Atlas API

Atlas 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:

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

sequenceDiagram %%{init: {"theme":"base","themeVariables":{"actorBkg":"#3a88fe","actorTextColor":"#ffffff","labelTextColor":"#000000","signalTextColor":"#000000","loopTextColor":"#000000"}}}%% participant A as Kund participant B as Tjänsteguide participant C as API Server participant D as Aktiveringssystem A->>B: Besöker med IP X.X.X.X B--)A: Skickar till Bounce URL A->>C: Besöker Bounce URL C--)D: Vad är accessId
för IP X.X.X.X? D--)C: AccessId är
AB1234 C->>A: Skickar till Tjänsteguiden A->>B: Besöker Tjänsteguiden
med ?accessId=AB1234 B->>A: Sparar accessId för
framtida beställningar

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.18.*)

sequenceDiagram %%{init: {"theme":"base","themeVariables":{"actorBkg":"#3a88fe","actorTextColor":"#ffffff","labelTextColor":"#000000","signalTextColor":"#000000","loopTextColor":"#000000"}}}%% participant A as Kund participant B as Tjänsteguide participant C as API Server participant D as Aktiveringssystem A->>B: Kan jag få tjänst 100/100? B-->>C: Kan BB100100
aktiveras på AB1234? C-->>D: Kan BB100100
aktiveras på AB1234? D-->>C: Ja C-->>B: Ja B->>A: Du kan aktivera tjänsten A->>B: Jag vill aktivera tjänsten B-->>C: Aktivera BB100100
på AB1234 C-->>D: Aktivera BB100100
på AB1234 D-->>C: Klart C-->>B: Klart B->>A: Tjänsten är aktiverad

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:

Kunden har identifierats som stadsnätskund enligt ovan
Tjänsteleverantören har valt att aktuell tjänst kan direktaktiveras
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:

Skicka service_deliverable() för att säkerställa att aktuell tjänst kan aktiveras på aktuell port.
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
Vid direktaktivering, skicka port_status() för att säkerställa att tjänsten nu är aktiv på porten

Methods

port_status
service_deactivate
service_deliverable
service_order

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

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"
Request Parameters

1 socket string 123-456-ABC User socket

Endpoint example:
?GET: 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
Request Parameters

1 socket string 123-456-ABC UID for the socket

2 service_uid string 12 UID for the service

3 date date 2011-12-23 Date for deactivation

Endpoint example:
?GET: 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).
Request Parameters

1 socket string 123-456-ABC UID for the user

2 service_uid string 12 UID for the service

3 origin string customer origin for the request

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

Request Parameters

1	socket	string	123-456-ABC	UID for the socket
2	service_uid	string	12	UID for the service
3	date	ISO Date	2011-02-30	Date for activation. If date is today, then it should be activated directly
4	origin	string	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:
?GET: 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>