Atlas API

Beställningar via API

API för Stadsnät:
API för Tjänsteleverantörer:

Flödeschema för TL

När en slutkund lägger en order via Tjänsteguiden så skapas en order per tjänst. Det går ett mail till Tjänsteleverantören med en länk för manuell hantering, samt en maskinellt läsbar info-del med ett Order-ID som kan användas för att hämta data om ordern via API. Vår rekommendation är att för att automatisera detta så ignorera mailet och använd metoden orders för att hämta orders sen senast ni kontrollerade.

sequenceDiagram %%{init: {"theme":"base","themeVariables":{"actorBkg":"#ff8700","actorTextColor":"#000000","labelTextColor":"#303030","signalTextColor":"#303030","loopTextColor":"#303030"}}}%% participant A as Kund participant B as Tjänsteguiden participant C as Tjänsteleverantör participant D as ON-API hos Stadsnät A->>B: Jag vill beställa Tjänst 100/100 B->>A: Vad är din adress? A->>B: Demogatan 123, Demostad note over A, B: Vilket är accessId AB123 enligt Marknadsdatabasen B->>B: Spara kund och order i databas B->>A: Tack för din beställning B-->>C: Ny beställning note over C: Detta skickas som ett mail med
information för att hämta via API alt Tjänsteleverantör agerar på mailet C->>B: Hämta beställningen C->>D: Aktivera Tjänst AB100100
på accessId AB123 end alt Tjänsteleverantör hämtar periodiskt nya beställningar C-->>B: Nya beställningar? B-->>C: Dessa är de nya beställningarna C->>D: Aktivera Tjänst AB100100
på accessId AB123 end

För TL så använder ni alltså orders för att se senast inkomna ordrar. Där ser ni ett ID per order, då använder ni order_info för att hämta information om ordern, samt customer_info för att hämta info om kunden.

När TL har hämtat ordern så använder TL metoden set_status för att sätta status till "received", på så sätt kan TL hålla reda på vilka ordrar som redan är inlästa, plus att både TL och KO kan se att ordern är mottagen. TL använder sedan set_status för att reflektera orderns status tills dess att status är "delivered".

Om ordern har status "delivered" när den läses in av TL så betyder det att tjänsten är direktaktiverad och TL behöver bara läsa in data i sitt ordersystem och hantera kunden därifrån.

Vid problem med en order så används metoden add_message för att spara ett logmeddelande på ordern med rätt typ. När ni använder status via set_status så sparas det även ett log-meddelande om att ni ändrat status. Använd add_message för att meddela KO om några problem vid den automatiska hanteringen - lita dock inte på detta som en meddelandefunktion som KO's tekniska avdelning har koll på. Var noga med att flagga ordern internt att den kan behöva manuell uppföljning.

Flödesschema för KO

I de flesta fall så är KO inte inblandad i orderhanteringen utan den är upp till TL att hantera. I vissa fall så har KO slutkundsrelation och kan därmed via sitt API hämta samma information som TL om order och kund.

Även KO har tillgång till set_status och add_message för att hantera information kring en order, samt kan se loggen och den information som TL har lagt till. KO kan till exempel sätta status till "active" när dom fått förfrågan från TL om aktivering, eller "cancelled" om något fel uppstår vid hantering av ordern.

Methods

customer_info
orders
customers
set_status
order_info
order_log
add_message

API Endpoint: XSP Beställningar

Endpoint URL https://www.stadsnatsportalen.se/plain/serviceguide_log

This API does not require granted privileges, and is open to any user API key

Method: customer_info
Request Parameters

1 hash string ABC123 Login hash from api_login()

2 id int 1234 ID of customer

Endpoint example:
GET: https://www.stadsnatsportalen.se/plain/serviceguide_log?method=customer_info&hash=ABC123&id=1234

success response

   <customer_info>
      <response>
         <customer>
            <id>10573</id>
            <socket>KC0101A06</socket>
            <serial>19700101010101</serial>
            <firstname>Susanne</firstname>
            <surname>Testqvist</surname>
            <email>testqvist@epost.se</email>
            <address>Testgatan10b</address>
            <zip>64430</zip>
            <city>Torshälla</city>
         </customer>
         <data>
            <phone>0708530013</phone>
            <premise>1002</premise>
         </data>
      </response>
      <status>success</status>
   </customer_info>

Method: orders
Request Parameters

1 hash string ABC123 Login hash from api_login()

2 date string 2018-01-04 The date from which to show new orders

Endpoint example:
GET: https://www.stadsnatsportalen.se/plain/serviceguide_log?method=orders&hash=ABC123&date=2018-01-04

success response

   <orders>
      <response>
         <order>
            <id>72713</id>
            <uid>NORRSRV22018011172713</uid>
            <type>order</type>
            <date>2018-01-11 00:20:28</date>
            <status>delivered</status>
            <service>2225</service>
            <delivery>2018-01-12 00:00:00</delivery>
            <customer>57333</customer>
            <citynet>ServaNet</citynet>
         </order>
         <order>
            <id>72723</id>
            <uid>MNCMSN2018011172723</uid>
            <type>order</type>
            <date>2018-01-11 12:11:15</date>
            <status>new</status>
            <service>3860</service>
            <delivery>asap</delivery>
            <customer>57341</customer>
            <citynet>Fibra</citynet>
         </order>
      </response>
      <status>success</status>
   </orders>

Method: customers
Request Parameters

1 hash string ABC123 Login hash from api_login()

2 date string 2018-01-04 Date from which to show new customers

Endpoint example:
GET: https://www.stadsnatsportalen.se/plain/serviceguide_log?method=customers&hash=ABC123&date=2018-01-04

success response

   <customers>
      <response>
         <customer>
            <id>10573</id>
            <socket>KC0101A06</socket>
            <serial>19700101010101</serial>
            <firstname>Susanne</firstname>
            <surname>Testqvist</surname>
            <date>2018-01-01 12:34</date>
         </customer>
         <customer>
            <id>48962</id>
            <socket>CCTW0151B87</socket>
            <serial>190001010202</serial>
            <firstname>Anton</firstname>
            <surname>Testblom</surname>
            <date>2018-01-01 12:34</date>
         </customer>
      </response>
      <status>success</status>
   </customers>

Method: set_status

Valid values for "status" are:

new	order is new and unhandeled
received	order is received by target (xsp)
active	order is being handeled
waiting	order is pending action from other party
cancelled	order has been cancelled
delivered	order has been fulfilled to end customer

Request Parameters

1 hash string ABC123 Login hash from api_login()

2 id int 1234 ID of order

3 status string delivered New status for order

Endpoint example:
GET: https://www.stadsnatsportalen.se/plain/serviceguide_log?method=set_status&hash=ABC123&id=1234&status=delivered

success response

   <set_status>
      <response>
         <message>Status changed to delivered for order 1234</message>
      </response>
      <status>success</status>
   </set_status>

Method: order_info
Request Parameters

1 hash string ABC123 Login hash from api_login()

2 id int 1234 The id for the order to show the info

Endpoint example:
GET: https://www.stadsnatsportalen.se/plain/serviceguide_log?method=order_info&hash=ABC123&id=1234

success response

   <order_info>
      <response>
         <orderinfo>
            <date>2018-01-11 00:20</date>
            <ID>NORRSRV22018011172713</ID>
            <type>order</type>
            <status>delivered</status>
            <delivery>2018-01-12 00:00</delivery>
            <provider>Bredband2</provider>
            <service_id>2225</service_id>
            <spProductId>500500INT</spProductId>
            <service>1/1 Gbit/s</service>
            <category>Privatpersoner: Internet / Via fiber</category>
            <service_uid>DEMO500500</service_uid>
            <coProductId>DEMO500500</coProductId>
            <citynet>ServaNet</citynet>
         </orderinfo>
         <customer>
            <id>57333</id>
            <socket>

            </socket>
            <serial>197001012323</serial>
            <firstname>peter</firstname>
            <surname>Ledin</surname>
            <email>peter@epost.net</email>
            <address>Test Kvarn 456</address>
            <zip>87193</zip>
            <city>Härnösand</city>
            <approve>Jag har läst och godkänner villkoren</approve>
            <phone>07012345678</phone>
            <PUL-godkannande>1</PUL-godkannande>
         </customer>
         <logs>
            <log>
               <date>2018-01-11 00:20:00</date>
               <message>Saved order</message>
               <type>system</type>
            </log>
            <log>
               <date>2018-01-11 00:20:00</date>
               <message>Attaching order to existing customer (197009227831)</message>
               <type>system</type>
            </log>
            <log>
               <date>2018-01-11 00:20:00</date>
               <message>Found email address for XSP associated with service or company: bredband2@obc.bosscrm.se</message>
               <type>

               </type>
            </log>
            <log>
               <date>2018-01-11 00:20:00</date>
               <message>Sent order email to XSP: bredband2@obc.bosscrm.se</message>
               <type>

               </type>
            </log>
            <log>
               <date>2018-01-11 00:20:00</date>
               <message>Sent confirmation email to customer: peter@skugga.net</message>
               <type>

               </type>
            </log>
            <log>
               <date>2018-01-18 09:45:00</date>
               <message>Set status to delivered</message>
               <type>update</type>
            </log>
         </logs>
         <serviceinfo>
            <data>
               <name>invoice type</name>
               <value>Autogiro</value>
            </data>
            <data>
               <name>monthly fee</name>
               <monthly>369</monthly>
            </data>
            <data>
               <name>offer</name>
               <value>3 mån gratis!!!: 100 % billigare i 3 mån och Värde 777 kr (1234567890)</value>
            </data>
            <data>
               <name>offerid</name>
               <value>1234567890</value>
            </data>
         </serviceinfo>
      </response>
      <status>success</status>
   </order_info>

Method: order_log
Request Parameters

1 hash string ABC123 Login hash from api_login()

2 id int 1234 The id for the order to show the log

Endpoint example:
GET: https://www.stadsnatsportalen.se/plain/serviceguide_log?method=order_log&hash=ABC123&id=1234
Method: add_message
Valid values for "type" is:

error This is an error message
alert Important information regarding this order
system System message from XSP order system
log general message
Request Parameters

1 api_user int 1234 API User ID with privileges

2 id int 1234 ID of order

3 message string Port finns ej Member shared between XSP and KO

4 type string Type of message

Endpoint example:
GET: https://www.stadsnatsportalen.se/plain/serviceguide_log?method=add_message&api_user=1234&id=1234&message=Port+finns+ej&type=Type+of+message

1	hash	string		ABC123	Login hash from api_login()
2	id	int		1234	ID of customer

error	This is an error message
alert	Important information regarding this order
system	System message from XSP order system
log	general message

1	api_user	int	1234	API User ID with privileges
2	id	int	1234	ID of order
3	message	string	Port finns ej	Member shared between XSP and KO
4	type	string	Type of message

Atlas API

Beställningar via API

Flödeschema för TL

Flödesschema för KO

Method: customer_info

Method: orders

Method: customers

Method: set_status

Method: order_info

Method: order_log

Method: add_message