Matooma API documentation

Version	Date
1.0.2	19-04-2021
1.0.1	12-03-2021
1.0.0	11-01-2021

Version 1.0.2

Remove fields isMatoowan, simcardVersion, history and sms from routes /api/devices and /api/devices/{id}
Remove field scheduledAt from routes /v1/provisioning-requests and /v1/provisioning-requests/{id}
Revert POST /v1/pairing error list in response to its original value

Wrong response

Correct response

{
  "errors": {
    "is-a-duplicate": [],
    "does-not-exist-in-fleet": [],
    "is-not-available": [],
    "is-already-paired": [],
    "wrong-offer-operator": [],
    "incorrect-customer": [],
    "forbidden-sim-version": [],
    "undefined-error": []
  }
}

{
  "errors": {
    "is-a-duplicate": [],
    "does-not-exist-in-fleet": [],
    "is-not-available": [],
    "is-already-paired": [],
    "wrong-operator": [],
    "is-not-a-valid-offer": [],
    "undefined-error": [],
    "generation": []
  }
}

Version 1.0.1

Add new route /token to fit the current API

Note: the existing route /v1/token still works. Both routes /token and /v1/token work the same way

Version 1.0.0

Authentication
Consumptions
Devices
Agencies
Manufacturers
Offers
Operators
Pairing
Profiles
Provisioning
Simcards
SMS

⚠️ Major updates

All current entity identifiers will change
Remove route Manufacturers (/v1/manufacturers)
Remove route Profiles (/v1/profiles) to route Offers (/v1/offers)
Update route Offers (/v1/offers)
Remove attribute manufacturer of every route
Remove attribute profileId of every route
Remove query parameter linked to Manufacturers
Remove query parameter linked to Profiles
Add a new level customer on multiple entities
The level agency is now replaced by the new level customer. The level agency remains as a sub-level of a customer (a customer may have multiple agencies).
An agency always depends on and is always linked to a customer.

Update details

Authentication

POST /v1/token

N/A

Consumptions

GET /v1/consumptions/daily/{iccid}

N/A

GET /v1/consumptions/total/{iccid}

N/A

Devices

GET /v1/devices

Change of the attribute profileName to offerName
Add a new attribute customer of type objet with two attributes: id and name

Previous payload

New payload

[
  {
    "id": 1,
    "reference": "12345",
    "contractNumber": "123456",
    "serialNumber": "123456",
    "apn": "m2minternet",
    "gsmData": null,
    "comment": "",
    "imei": "",
    "msisdn": "+33xxxxxxxxx",
    "profileName": "DATA XXX Ko X SMS Voix Entrante XXX",
    "isMatoowan": true,
    "simcardIccid": "XXXXXXXXXXXXXXXXXXXX",
    "simcardState": "active",
    "simcardVersion": "v1",
    "operatorSlug": "XXX",
    "agency": {
      "id": 2,
      "name": "Agency 2"
    },
    "modelId": 1234,
    "modelName": "Device Model name",
    "manufacturerName": "Manufacturer name",
    "simcardActivationDate": "XXXX-XX-XX XX:XX:XX",
    "simcardTerminationDate": null,
    "networkIp": null,
    "networkLogin": null,
    "networkPassword": null,
    "history": [],
    "sms": {
      "in": [],
      "out": []
    }
  }
]

[
  {
    "id": 1,
    "reference": "12345",
    "contractNumber": "123456",
    "serialNumber": "123456",
    "apn": "m2minternet",
    "gsmData": null,
    "comment": "Comment",
    "imei": "000111222",
    "msisdn": "+33000000000",
    "offerName": "DATA XXX Ko X SMS Voix Entrante XXX",
    "simcardIccid": "01234567890123456789",
    "simcardState": "active",
    "simcardVersion": "v1",
    "isMatoowan": false,
    "operatorSlug": "Operator 1",
    "customer": {
      "id": 1,
      "name": "Customer 1"
    },
    "agency": {
      "id": 2,
      "name": "Agency 2"
    },
    "modelId": 1234,
    "modelName": "Device Model name",
    "manufacturerName": "Manufacturer name",
    "simcardActivationDate": "2021-01-01 00:00:00",
    "simcardTerminationDate": null,
    "networkIp": null,
    "networkLogin": null,
    "networkPassword": null,
    "history": [],
    "sms": {
      "in": [],
      "out": []
    }
  }
]

GET /v1/devices/{id}

Change of the attribute profileName to offerName
Add a new attribute customer of type objet with two attributes: id and name

Previous payload

New payload

  {
    "id": 1,
    "reference": "12345",
    "contractNumber": "123456",
    "serialNumber": "123456",
    "apn": "m2minternet",
    "gsmData": null,
    "comment": "",
    "imei": "",
    "msisdn": "+33xxxxxxxxx",
    "profileName": "DATA XXX Ko X SMS Voix Entrante XXX",
    "isMatoowan": false,
    "simcardIccid": "XXXXXXXXXXXXXXXXXXXX",
    "simcardState": "active",
    "simcardVersion": "v1",
    "operatorSlug": "XXX",
    "agency": {
      "id": 2,
      "name": "Agency 2"
    },
    "modelId": 1234,
    "modelName": "Device Model name",
    "manufacturerName": "Manufacturer name",
    "simcardActivationDate": "XXXX-XX-XX XX:XX:XX",
    "simcardTerminationDate": null,
    "networkIp": null,
    "networkLogin": null,
    "networkPassword": null,
    "history": [],
    "sms": {
      "in": [],
      "out": []
    }
  }

  {
    "id": 1,
    "reference": "12345",
    "contractNumber": "123456",
    "serialNumber": "123456",
    "apn": "m2minternet",
    "gsmData": null,
    "comment": "Comment",
    "imei": "000111222",
    "msisdn": "+33000000000",
    "offerName": "DATA XXX Ko X SMS Voix Entrante XXX",
    "isMatoowan": false,
    "simcardIccid": "01234567890123456789",
    "simcardState": "active",
    "simcardVersion": "v1",
    "operatorSlug": "Operator 1",
    "customer": {
      "id": 1,
      "name": "Customer 1"
    },
    "agency": {
      "id": 2,
      "name": "Agency 2"
    },
    "modelId": 1234,
    "modelName": "Device Model name",
    "manufacturerName": "Manufacturer name",
    "simcardActivationDate": "2021-01-01 00:00:00",
    "simcardTerminationDate": null,
    "networkIp": null,
    "networkLogin": null,
    "networkPassword": null,
    "history": [],
    "sms": {
      "in": [],
      "out": []
    }
  }

PATCH /v1/devices/{id}

N/A

GET /v1/devices/models

Deletion of the query parameter operatorSlug as a device model does not depend on a specific operator
Add of a new query parameter customerId to filter on a specific customer identifier

Agencies

GET /v1/agencies

The level agency is now replaced by the new level customer. The level agency remains as a sub-level of a customer (a customer may have multiple agencies).
An agency always depends on and is always linked to a customer.
Deletion of attribute default

Previous payload	New payload
[ { "default": false, "id": "1", "name": "My agency" } ]	[ { "id": 1, "name": "My agency" } ]

Manufacturers

GET ~~/v1/manufacturers~~

Deletion of this route with no replacement

Offers

GET /v1/offers

Deletion of the query parameter agencyId as an offer does not depend on a specific agency anymore but on a specific customer
Deletion of the query parameter deviceModelId as an offer does not depend on a specific device model anymore
Add of a new query parameter customerId as replacement of the query parameter agencyId to filter on a specific customer identifier
Deletion of the attribute profileId as an offer does not depend on a profile anymore
Deletion of the attribute agencyId as an offer does not depend on an agency anymore
Deletion of the attribute agencyName as an offer does not depend on an agency anymore
Add a new attribute customer of type objet with two attributes: id and name

Previous payload	New payload
[ { "id": 2, "profileId": 5, "name": "DATA 500 Ko", "agencyId": 2, "agencyName": "My Agency 2" } ]	[ { "id": 2, "name": "DATA 500 Ko", "customer": { "id": 2, "name": "Customer 2" } } ]

GET /v1/offers/{id}

Deletion of the attribute profileId as an offer does not depend on a profile anymore
Deletion of the attribute agencyId as an offer does not depend on an agency anymore
Deletion of the attribute agencyName as an offer does not depend on an agency anymore
Add a new attribute customer of type objet with two attributes: id and name

Previous payload	New payload
{ "id": 2, "profileId": 5, "name": "DATA 500 Ko", "agencyId": 2, "agencyName": "My Agency 2" }	{ "id": 2, "name": "DATA 500 Ko", "customer": { "id": 2, "name": "Customer 2" } }

Operators

GET /v1/operators

Deletion of the query parameter agencyId as an operator does not depend on a specific agency anymore
Deletion of the query parameter manufacturerId as an operator does not depend on a specific manufacturer anymore

Pairing

POST /v1/pairing

Deletion of the attribute templateId
Deletion of the attribute manufacturerId
Deletion of the attribute operatorSlug
Change the name of the attribute profileId to offerId
Add of a new attribute customerId of type integer

Previous payload

New payload

{
  "dry-run": true,
  "agencyId": "XXX",
  "manufacturerId": "XXX",
  "operatorSlug": "XXX",
  "modelId": "XXX",
  "profileId": "XXX",
  "items": [
    {
      "iccid": "XXXXXXXXXXXXXXXXXXXX",
      "serialNumber": "XXXXXXXXXXXXXXXXXXXX",
      "reference": "XXXXXXXXXXXXXXXXXXXX",
      "imei": "XXXXXXXXXXXXXXXXXXXX",
      "comment": "XXXXXXXXXXXXXXXXXXXX"
    }
  ]
}

{
  "dry-run": true,
  "customerId": 1,
  "agencyId": 2,
  "modelId": 3,
  "offerId": 4,
  "items": [
    {
      "iccid": "1234567890123456789",
      "serialNumber": "123456",
      "reference": "abc-1",
      "imei": "123",
      "comment": "Comment 1"
    }
  ]
}

Add the return code 400 if the offer does not exist for the given couple customer/agency or if the offer is not compatible with the given device model

Previous payload	New payload
None	{ "code": "400,", "message": "The offer 1 doesn't have any rattachement for customer Customer 1 and agency 1" }
None	{ "code": "400,", "message": "Sim Card Offer Not Compatible With Device Model" }

GET /v1/pairing/templates

Deletion of the attribute manufacturer
Change of the attribute name profile to the attribute offer with the same attributes
Add a new attribute customer of type objet with two attributes: id and name

Previous payload

New payload

[
  {
    "id": "XXXX",
    "label": "XXXX",
    "agency": {
      "agencyId": "XXXX",
      "agencyName": "XXXX"
    },
    "profile": {
      "profileId": "XXXX",
      "profileName": "XXXX"
    },
    "model": {
      "modelId": "XXXX",
      "modelName": "XXXX"
    },
    "manufacturer": {
      "manufacturerId": "XXXX",
      "manufacturerName": "XXXX"
    },
    "operatorSlug": "XXXX"
  }
]

[
  {
    "id": "1",
    "label": "Pairing template",
    "customer": {
      "id": 1,
      "name": "Customer 1"
    },
    "agency": {
      "id": 2,
      "name": "Agency 2"
    },
    "offer": {
      "id": 3,
      "name": "Offer 3"
    },
    "model": {
      "id": 4,
      "name": "Model 4"
    },
    "operatorSlug": "Operator"
  }
]

POST /v1/pairing/templates

Deletion of the attribute manufacturerId
Change of the attribute name profile to the attribute offer with the same attributes id and name
Add a new attribute customerId of type integer

Previous payload

New payload

{
  "label": "XXXXX",
  "agencyId": "XXXXX",
  "manufacturerId": "XXXXX",
  "operatorSlug": "XXXXX",
  "modelId": "XXXXX",
  "profileId": "XXXXX"
}

{
  "label": "Label",
  "customerId": 1,
  "agencyId": 2,
  "offerId": 3,
  "modelId": 4,
  "operatorSlug": "Operator"
}

GET /v1/pairing/templates/{id}

Deletion of the attribute manufacturer
Change of the attribute name profile to the attribute offer with the same attributes id and name
Add a new attribute customer of type objet with two attributes: id and name

Previous payload

New payload

  {
    "id": "XXXX",
    "label": "XXXX",
    "agency": {
      "agencyId": "XXXX",
      "agencyName": "XXXX"
    },
    "profile": {
      "profileId": "XXXX",
      "profileName": "XXXX"
    },
    "model": {
      "modelId": "XXXX",
      "modelName": "XXXX"
    },
    "manufacturer": {
      "manufacturerId": "XXXX",
      "manufacturerName": "XXXX"
    },
    "operatorSlug": "XXXX"
  }

  {
    "id": "1",
    "label": "Pairing template",
    "customer": {
      "id": 1,
      "name": "Customer 1"
    },
    "agency": {
      "id": 2,
      "name": "Agency 2"
    },
    "offer": {
      "id": 3,
      "name": "Offer 3"
    },
    "model": {
      "id": 4,
      "name": "Model 4"
    },
    "operatorSlug": "Operator"
  }

PATCH /v1/pairing/templates/{id}

N/A

DELETE /v1/pairing/templates/{id}

N/A

Profiles

GET ~~/v1/profiles~~

Deletion of this route with no replacement

Provisioning

POST /v1/provisioning-requests

Add the missing action reactivate in documentation

GET /v1/provisioning-requests

Add the missing action reactivate in documentation
Add a new attribute requestedForCustomer of type string
Add a new attribute createdByCustomer of type object with two attributes id and name

Previous payload

New payload

[
  {
    "id": 1234,
    "agencyName": "My Agency",
    "user": "Me",
    "status": "done",
    "action": "activate",
    "createdAt": "XXXX-XX-XX XX:XX:XX",
    "items": {
      "1234": {
        "id": 1234,
        "iccid": "XXXXXXXXXXXXXXXXXXXX",
        "requestAt": "XXXX-XX-XX XX:XX:XX",
        "status": "done",
        "requestedForAgency": "My Agency",
        "operatorSlug": "XXX",
        "processingDate": "XXXX-XX-XX XX:XX:XX"
      }
    },
    "createdByAgency": {
      "id": 1,
      "name": "My Agency"
    },
    "createdByUser": {
      "id": 1,
      "name": "Me"
    }
  }
]

[
  {
    "id": 1234,
    "agencyName": "My Agency",
    "user": "Me",
    "status": "done",
    "action": "activate",
    "createdAt": "2021-01-01 00:00:00",
    "items": [
      {
        "id": 1234,
        "iccid": "01234567890123456789",
        "requestAt": "2021-01-01 00:00:00",
        "status": "done",
        "requestedForCustomer": "My Customer",
        "requestedForAgency": "My Agency",
        "operatorSlug": "Operator 1",
        "processingDate": "2021-01-01 00:00:00"
      }
    ],
    "createdByCustomer": {
      "id": 1,
      "name": "My Customer"
    },
    "createdByAgency": {
      "id": 1,
      "name": "My Agency"
    },
    "createdByUser": {
      "id": 1,
      "name": "Me"
    }
  }
]

GET /v1/provisioning-requests/{id}

Add of the missing action reactivate in documentation
Add a new attribute requestedForCustomer of type string
Add a new attribute createdByCustomer of type object with two attributes id and name

Previous payload

New payload

  {
    "id": 1234,
    "agencyName": "My Agency",
    "user": "Me",
    "status": "done",
    "action": "activate",
    "createdAt": "XXXX-XX-XX XX:XX:XX",
    "items": {
      "1234": {
        "id": 1234,
        "iccid": "XXXXXXXXXXXXXXXXXXXX",
        "requestAt": "XXXX-XX-XX XX:XX:XX",
        "status": "done",
        "requestedForAgency": "My Agency",
        "operatorSlug": "XXX",
        "processingDate": "XXXX-XX-XX XX:XX:XX"
      }
    },
    "createdByAgency": {
      "id": 1,
      "name": "My Agency"
    },
    "createdByUser": {
      "id": 1,
      "name": "Me"
    }
  }

  {
    "id": 1234,
    "agencyName": "My Agency",
    "user": "Me",
    "status": "done",
    "action": "activate",
    "createdAt": "2021-01-01 00:00:00",
    "items": [
      {
        "id": 1234,
        "iccid": "01234567890123456789",
        "requestAt": "2021-01-01 00:00:00",
        "status": "done",
        "requestedForCustomer": "My Customer",
        "requestedForAgency": "My Agency",
        "operatorSlug": "Operator 1",
        "processingDate": "2021-01-01 00:00:00"
      }
    ],
    "createdByCustomer": {
      "id": 1,
      "name": "My Customer"
    },
    "createdByAgency": {
      "id": 1,
      "name": "My Agency"
    },
    "createdByUser": {
      "id": 1,
      "name": "Me"
    }
  }

Simcards

GET /v1/simcards

Add a new attribute customer of type object with two attributes id and name

Previous payload

New payload

[
  {
    "id": 1,
    "agency": {
      "agencyId": 2,
      "agencyName": "My Agency 2"
    },
    "deviceId": 1,
    "simcardState": "in-stock",
    "simcardIccid": "XXXXXXXXXXXXXXXXXXXX",
    "simcardVersion": "sav",
    "operatorSlug": "orange",
    "simcardOrderId": 1,
    "simcardOrderDate": "XXXX-XX-XX XX:XX:XX",
    "orderedBy": "Me",
    "simcardRequest": null
  }
]

[
  {
    "id": 1,
    "customer": {
      "id": 2,
      "name": "My Customer 2"
    },
    "agency": {
      "id": 2,
      "name": "My Agency 2"
    },
    "deviceId": 1,
    "simcardState": "in-stock",
    "simcardIccid": "01234567890123456789",
    "simcardVersion": "sav",
    "operatorSlug": "orange",
    "simcardOrderId": 1,
    "simcardOrderDate": "2021-01-01 00:00:00",
    "orderedBy": "John Doe",
    "simcardRequest": 123456
  }
]

GET /v1/simcards/{id}

Add a new attribute customer of type object with two attributes id and name

Previous payload

New payload

  {
    "id": 1,
    "agency": {
      "agencyId": 2,
      "agencyName": "My Agency 2"
    },
    "deviceId": 1,
    "simcardState": "in-stock",
    "simcardIccid": "XXXXXXXXXXXXXXXXXXXX",
    "simcardVersion": "sav",
    "operatorSlug": "orange",
    "simcardOrderId": 1,
    "simcardOrderDate": "XXXX-XX-XX XX:XX:XX",
    "orderedBy": "Me",
    "simcardRequest": null
  }

  {
    "id": 1,
    "customer": {
      "id": 2,
      "name": "My Customer 2"
    },
    "agency": {
      "id": 2,
      "name": "My Agency 2"
    },
    "deviceId": 1,
    "simcardState": "in-stock",
    "simcardIccid": "01234567890123456789",
    "simcardVersion": "sav",
    "operatorSlug": "orange",
    "simcardOrderId": 1,
    "simcardOrderDate": "2021-01-01 00:00:00",
    "orderedBy": "John Doe",
    "simcardRequest": 123456
  }

SMS

POST /v1/sms

Deletion of return code 200 as it was never used

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
README.md		README.md
matooma-external-api.postman_collection.json		matooma-external-api.postman_collection.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Matooma API documentation

Version 1.0.2

Version 1.0.1

Version 1.0.0

⚠️ Major updates

Update details

Authentication

Consumptions

Devices

Agencies

Manufacturers

Offers

Operators

Pairing

Profiles

Provisioning

Simcards

SMS

About

Uh oh!

Releases

Packages

Contributors 2

Uh oh!

matooma/api-doc

Folders and files

Latest commit

History

Repository files navigation

Matooma API documentation

Version 1.0.2

Version 1.0.1

Version 1.0.0

⚠️ Major updates

Update details

Authentication

Consumptions

Devices

Agencies

Manufacturers

Offers

Operators

Pairing

Profiles

Provisioning

Simcards

SMS

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Packages