Beställningar via API

API för Stadsnät: api Tjänsteguiden: Beställningar
API för Tjänsteleverantörer: api Tjänsteguiden: XSP Beställningar

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.
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
API Endpoint: Beställningar
API för beställningar i Tjänsteguiden
Endpoint URL http://www.example.com/admin/edit/services/plain/orders
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: add_message

  • Valid values for "type" is:
    errorThis is an error message
    alertImportant information regarding this order
    systemSystem message from activation for instance
    loggeneral message
  • Parameters
    1 api_user int green 1234 API User ID with privileges
    2 id int green 1234 ID of order
    3 message string green Port finns ej Member shared between XSP and KO
    4 type string green Type of message
    Endpoint example:
    https://www.example.com/admin/edit/services/plain/orders?method=add_message&api_user=1234&id=1234&message=Port+finns+ej&type=Type+of+message
  • Method: customer_info

  • Parameters
    1 api_user int green 1234 API User ID with privileges
    2 id int green 12 Customer ID, from orders() or customers()
    Endpoint example:
    https://www.example.com/admin/edit/services/plain/orders?method=customer_info&api_user=1234&id=12
  • success response


       <customer_info>
          <customer>
             <id>16745</id>
             <socket>65375</socket>
             <serial>197510116952</serial>
             <firstname>Test direktaktivering</firstname>
             <surname>Test direktaktivering</surname>
             <email>jonas@eklundh.com</email>
             <address>Test direktaktivering</address>
             <zip>12345</zip>
             <city>Test direktaktivering</city>
             <member>1234</member>
          </customer>
          <data>
             <message>TESTBESTÄLLNING</message>
             <phone>0703051947</phone>
             <premise>508-004-06-0302</premise>
          </data>
       </customer_info>
  • Method: customers

  • Parameters
    1 api_user int green 1234 API User ID with privileges
    2 date string green 2015-01-01 Date from when to list new or edited customers
    Endpoint example:
    https://www.example.com/admin/edit/services/plain/orders?method=customers&api_user=1234&date=2015-01-01
  • success response


       <customers>
          <customer>
             <id>16745</id>
             <socket>12345</socket>
             <serial>XXXXXXXXXX</serial>
             <firstname>Kalle</firstname>
             <surname>Testsson</surname>
             <email>test@test.com</email>
          </customer>
          <customer>
             <id>17048</id>
             <serial>XXXXXXXXXXX</serial>
             <firstname>Kalle</firstname>
             <surname>Provsson</surname>
             <email>exempel@exempel.com</email>
          </customer>
       </customers>
  • Method: order_info

  • Parameters
    1 api_user int green 1234 API User ID with privileges
    2 id int green 12 Order ID, obtained by orders()
    Endpoint example:
    https://www.example.com/admin/edit/services/plain/orders?method=order_info&api_user=1234&id=12
  • success response


       <order_info>
          <orderinfo>
             <date>2015-10-06 12:39</date>
             <type>order</type>
             <status>new</status>
             <delivery>2015-10-06 00:00</delivery>
             <provider>T3</provider>
             <service_id>2440</service_id>
             <service>50/50 Mbit/s</service>
             <category>Privatpersoner: Internet / Via fiber</category>
             <service_uid>12345678</service_uid>
             <citynet>Stadsnätsfabriken DEMO</citynet>
          </orderinfo>
          <customer>
             <id>16745</id>
             <socket>65375</socket>
             <serial>197510116952</serial>
             <firstname>Test direktaktivering</firstname>
             <surname>Test direktaktivering</surname>
             <email>jonas@eklundh.com</email>
             <address>Test direktaktivering</address>
             <zip>12345</zip>
             <city>Test direktaktivering</city>
             <message>TESTBESTÄLLNING</message>
             <phone>0703051947</phone>
             <premise>508-004-06-0302</premise>
          </customer>
          <logs>
             <log>
                <date>2015-10-06 12:39:00</date>
                <message>Saved order</message>
                <type>system</type>
             </log>
             <log>
                <date>2015-10-06 12:39:00</date>
                <message>Attaching order to existing customer (197510116952)</message>
                <type>system</type>
             </log>
             <log>
                <date>2015-10-06 12:39:00</date>
                <message>Attempting to add order to API server</message>
                <type>system</type>
             </log>
             <log>
                <date>2015-10-06 12:39:00</date>
                <message>Service order accepted from API server</message>
                <type>system</type>
             </log>
             <log>
                <date>2015-10-06 12:39:00</date>
                <message>User requested direct activation, checking activation status from API server</message>
                <type>system</type>
             </log>
             <log>
                <date>2015-10-06 12:39:00</date>
                <message>API doesn't report the service as activated</message>
                <type>error</type>
             </log>
             <log>
                <date>2015-10-06 12:39:00</date>
                <message>Found email address for XSP associated with service or company: order@t3.se</message>
             </log>
          </logs>
          <serviceinfo>
             <data>
                <name>invoice type</name>
                <value>Autogiro</value>
             </data>
             <data>
                <name>monthly fee</name>
                <monthly>222</monthly>
             </data>
             <data>
                <name>Just nu! Höstkampanj: HALVA PRISET I 6 MÅNADER! In</name>
             </data>
          </serviceinfo>
       </order_info>
  • Method: orders

  • Use to fetch new orders from the system. This only returns the order data, and more info about each order is found via order_info()
  • Parameters
    1 api_user int green 1234 API User with privileges
    2 date string green 2015-10-01 Show orders only from this date and later
    Endpoint example:
    https://www.example.com/admin/edit/services/plain/orders?method=orders&api_user=1234&date=2015-10-01
  • success response


       <orders>
          <response>
             <order>
                <id>19530</id>
                <type>order</type>
                <date>2015-10-06 11:48:00</date>
                <status>new</status>
                <service>2440</service>
                <xsp>31420</xsp>
                <delivery>2015-10-06 00:00:00</delivery>
                <customer>16745</customer>
             </order>
             <order>
                <id>19531</id>
                <type>order</type>
                <date>2015-10-06 11:48:00</date>
                <status>new</status>
                <service>2440</service>
                <xsp>31420</xsp>
                <delivery>2015-10-06 00:00:00</delivery>
                <customer>16746</customer>
             </order>
          </response>
       </orders>
  • Method: set_status

  • Valid values for "status" are:
    neworder is new and unhandeled
    receivedorder is received by target (xsp)
    activeorder is being handeled
    waitingorder is pending action from other party
    cancelledorder has been cancelled
    deliveredorder has been fulfilled to end customer
  • Parameters
    1 api_user int green 1234 API User ID with privileges
    2 id int green 1234 ID of order
    3 status string green delivered New status for order
    Endpoint example:
    https://www.example.com/admin/edit/services/plain/orders?method=set_status&api_user=1234&id=1234&status=delivered
  • success response


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