API

There are only 2 main endpoints: coverage and subscribe.

Since every action is handled with a workflow system those 2 endpoints will not answer immediately with the result of the operation, but instead they will put the request provided in the queue to be worked on. For this reason it's important to save the id provided in the response and check the result every N second.

Authentication

To authenticate in the api you'll need to manage Api Keys under Organizations on your administration panel.

Example of the key

tqdoHWo1goN4Pd2U90Qd9wdLkNPTp3VqmTLSBEOPnNdZ5GjYlDTt8aAsAa6XMHCshB

Remember that if you are working in your stage/production environment, the key will change based on Api Keys under your Organization. Please verify that in the administration panel that is accessible from the endpooint /admin

In order to use this token, simply add one header, with the name Authorization

--header 'Authorization: tqdoHWo1goN4POU90QqKdLkNPTp3VqmTLSBEOPnNPZ5GjYlDTt8aAsAa6XMHCshB' \

Coverage

Let's start with a coverage POST /coverage

The usual response would be something like this

{
  "id": 134,
  "action": "fastweb:coverage",
  "status": "pending",
  "payload": {},
  "created_at": "2024-11-18T05:32:09.000000Z",
  "updated_at": "2024-11-18T05:32:09.000000Z"
}

As you can see the status is currently on pending. This means the request has been created, and it's now waiting to be processed. Check here to see the full cycle of actions.

Now you can just ping GET /status/{id} and wait for the field status to change. When the value reaches done it means the address is covered. If instead you see canceled it will mean that something went wrong: either the address was not correct or the area is not covered.

To retrieve the list of products available for the address access to payload.__info.result. Now that you got the name of the products available it's time to subscribe the customer.

To retrieve the list of addons available instead, check payload.__info.data.addons. You can check more details here

Example:

{
  "id": 185,
  "action": "fastweb:coverage",
  "status": "done",
  "payload": {
    "driver": "fastweb",
    "address": {
      "street": "VIA CENERENTOLA",
      "number": 1,
      "city": "BRONTE",
      "province": "CT",
      "zip_code": 33333,
      "full": "VIA CENERENTOLA 1, BRONTE (CT)"
    },
    "__info": {
      "message": "",
      "result": [
        "Fastweb Casa Light",
        "Fastweb Casa",
        "Fastweb Casa Plus",
        "Fastweb Casa Light + Mobile",
        "Fastweb Casa + Mobile",
        "Fastweb Casa Plus + Mobile"
      ],
      "data": {
        "addons": []
      }
    }
  },
  "created_at": "2024-11-18T09:21:36.000000Z",
  "updated_at": "2024-11-18T09:21:36.000000Z"
}

Subscription

Let's continue with the juicy part, the POST /subscription

Similar to the coverage endpoint, this call will return an id for you to check, but there is one big difference:
This endpoint can reach an interrupted status, meaning that some additional data must be provided for the operation to continue.

As usual, you can call GET /status endpoint every N second to verify the status and when you see the interrupted status you must read the
payload.__info.message.

E.g.

{
  "payload": {
    "__info": {
      "message": "OTP is requested"
    }
  }
}

In this case the message means that you need to provide an OTP code to proceed. The sms will be sent to the phone provided in the phone field.

You can use 2 more endpoints to continue: send-otp and reset-otp.

After you send the otp, the operation will keep running. There are currently 3 interruptions:

OTP (OTP is requested, OTP is wrong)

Credid Card (Credit Card is requested, Credit Card is wrong)

Captcha (Credit Card is requested)

OTP

This is pretty straightforward. Use POST /send-otp and /reset-otp to send the otp received or request a new one

Credit card

The credit card is a bit peculiar one, an url will be provided in which the user will have to insert his credit card informations

{
  "payload": {
    "__info": {
      "message": "Credit Card is requested",
      "data": {
        "credit_card": {
          "url": "https://paye.netsgroup.com/FWB_CG_WEB/app/cc/main/show?referenceData=2E915264E06CE76FB6B9F29F36764952",
          "description": "Action will change to `running` when is good",
          "result": "Attenzione, è stata veicolata una richiesta con transazione in corso. Si prega di attendere."
        }
      }
    }
  }
}

When you get this message simply take the data.credit_card.url and add a new iframe (or whatever other system you prefer)

No API is needed, since all the information will be handled inside the iframe. When the payment will be confirmed (either with a positive or negative result ), the status will change again as well, so keep in mind to ping always the /status/{id} endpoint.

If you prefer you can also open a new tab, or open a new window if the iframe doesn't suit you.

Addons

In order to retrieve and use the addons you'll have to start from the coverage here. If the driver support addons you'll see a reply like this in the coverage payload

{
    "data": {
        "addons": [
          {
            "product": "FIBER_2022",
            "options": [
              {
                "name": "FIBER_ADDON_STATICIPV4",
                "category": "FIBER_ADDONS",
                "default": false,
                "type": "FIBER_STATICIP",
                "price": 4,
                "incompatibilities": []
              },
              {
                "name": "FIBER_ADDON_VOICE",
                "category": "FIBER_ADDONS",
                "default": false,
                "type": "FIBER_VOICE",
                "price": 4,
                "incompatibilities": []
              },
              {
                "name": "FIBER_ROUTER_FRITZ_7530",
                "category": "FIBER_ROUTER",
                "default": false,
                "type": "FIBER_ROUTER",
                "price": 2.2,
                "incompatibilities": [
                    "FIBER_ADDON_DOWNLOAD2500",
                    "FIBER_ADDON_DOWNLOAD2500_WHITEAREA",
                    "FIBER_ADDON_DOWNLOAD2500_UP1000",
                    "FIBER_ADDON_DOWNLOAD10G_UP2500",
                    "FIBER_ADDON_DOWNLOAD2500_UP1000_WHITEAREA"
                ]
              }
            ]
        }
    ]
}

Once you retrieve them you'll have to play a bit with 2 important things: default and incompatibilities. Default addons are quite simple, they are included already in the product, you can technically even skip them all together as they will be added automatically, but at least you'll be able to show which addons are already added based on the product.

The tricky part are the incompatibilities, not every addon is compatible with each other, you'll be provided with a list of names in which each addon is not compatible with. For example a FIBER_ROUTER might not be compatible with some FIBER_BANDWIDTH (yes, the bandwidth is considered an addon) because of some hardware limitations. The name used in the list of incompatibilities is the same name as the addon. Keep in mind that some addons are exclusive with other addons of the same category, this means for example that an addon of FIBER_BANDWIDTH is not compatible with any other FIBER_BANDWIDTH because you can only pick 1 bandwith (e.g. 100Mbps or 1Gbps)

You can also use the category and type fields to better organize the showed addons

Here's a list of some categories:

FIBER_BANDWIDTH

FIBER_ROUTER

FIBER_YOLO

FIBER_ADDONS (generic addons e.g. voice/static ip)

FIBER_VOUCHER

You are provided with a price as well, which is just a decimal number (not formatted) which will be added to the total cart

Keep in mind that this list might change at anytime since the values are dynamically retrieved from the driver.

Last but not least, some addons will require some extra fields. Right now there are 2 addons that require extra fields:

FIBER_YOLO_CYBERSECPLUS

FIBER_YOLO_HOMEASSISTANCE

Both the list of addons and the extra fields must be sent on the /subscription endpoint. You can check the fields schema here

@Note: This entire configuration for addons works right now only for aruba, the specifics might change in future for future addons of different drivers

Errors

Errors handled by the system can be in 2 forms:

If your request is not correct in any given endpoint the reply will be like this

{
  "error": "Driver with name: 'vercinge' doesn't exists"
}

If instead an error occurs while the process is running you can simply call GET /status/{id} and read the field payload.__info.error. E.g.

{
  "id": 1,
  "action": "fastweb:coverage",
  "status": "canceled",
  "payload": {
    "__info": {
      "error": "no coverage for this address and number"
    }
  },
  "error": "interrupted or timeout by signal",
  "created_at": "2024-11-17T23:35:22.000000Z",
  "updated_at": "2024-11-17T23:35:22.000000Z"
}

Authentication#

Coverage#

Subscription#

OTP#

Credit card#

Addons#