Partners API

The Sencrop API allows a simpler authorization delegation process for its partners program.

The partners API requires you to contact us before being allowed to use it. To do so, please create an account and contact us then.

and

After contacting us, you will get.

  1. your API credentials (application id and application secret) to interact with the partners API endpoint protected via the [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) ([RFC 7617](https://tools.ietf.org/html/rfc7617),
  2. and your API token to interact with the API endpoints protected via the bearer authentication ([RFC 6750](https://tools.ietf.org/html/rfc6750.html#section-2.1)).

Those informations will soon be manageable by your side but in the meanwhile, please contact us to renew it.

Delegation flows

You can obtain a token from our users via 2 distinct flows currently, the SMS flow or the module flow.

Module flow

This flow allows you to directly create tokens for our users. The prerequisite is that the user must have activated at least one of your modules on their Sencrop application.


curl https://api.sencrop.com/v1/partners/{partnerId}}/tokens   -X POST --data '{"email":"nicolas@sencrop.com", "code": "MODULE"}'   -H 'Content-Type: application/json'   -u 'application_id:application_secret'

{
  "userId":1,
  "organisationId":1,
  "token":"aac64190008c7f7b216ce91e7f1dec37ea615f1a3f5630cfc2ded6232badbb703c11a0c8dd2bbd5a8abb10d44427ae21131b3fd43cfe6fcebcc1fc84d89f10b6d6c85cd3f704cffc8486831d35f831f06ec9dd7d3e5c9e8f0fcc3658f1055cfe1516ee159120b964a40af7c462589edcd1243869ccd294144244c9426d3d6dc0",
  "expirationDate":"2018-03-03T08:08:48.062Z"
}

To see the users that enabled one of your modules, your can use the /partners/{partnerId}/devices endpoint.

If you try to create a token for a user with none of your modules activated you will get a E_MODULE_NOT_ACTIVATED error.

SMS flow

You can obtain a token from our users by sending them an SMS with a validation code that allows you to request the users authorization to access their data.

Obtaining a token via this flow involves 4 distinct steps.

First, you must collect the Sencrop user email via your own UI (remember to require the email they used to subscribe to Sencrop).

Then, create a token request. This will trigger an SMS to the user with a 6 chars authorization code.

Finally ask users for that code and call our token claim endpoint. It will provide you a token allowing you to act on the behalf of that user.

Requesting a token

To request a token just call the following endpoint with your API application id and secret:


curl https://api.sencrop.com/v1/partners/{partnerId}}/tokenRequests   -X POST --data '{"email":"nicolas@sencrop.com"}'   -H 'Content-Type: application/json'   -u 'application_id:application_secret'

This will send a SMS to the user with an authorization code.

Creating a token

To create the token just call the following endpoint with your API application id and secret:


curl https://api.sencrop.com/v1/partners/{partnerId}}/tokens   -X POST --data '{"email":"nicolas@sencrop.com", "code": "P6YEES"}'   -H 'Content-Type: application/json'   -u 'application_id:application_secret'

{
  "userId":1,
  "organisationId":1,
  "token":"aac64190008c7f7b216ce91e7f1dec37ea615f1a3f5630cfc2ded6232badbb703c11a0c8dd2bbd5a8abb10d44427ae21131b3fd43cfe6fcebcc1fc84d89f10b6d6c85cd3f704cffc8486831d35f831f06ec9dd7d3e5c9e8f0fcc3658f1055cfe1516ee159120b964a40af7c462589edcd1243869ccd294144244c9426d3d6dc0",
  "expirationDate":"2018-03-03T08:08:48.062Z"
}

That token allows your to access the user data through the API. See our API guide for more information on its usage.

The full endpoints documentation can be found in the API reference under the partners tag.

Listing modules activations

At some point, you will want to know who activated your modules on the Sencrop application and for which devices. You can do so by using the following endpoint:


curl -X GET "https://api.sencrop.com/v1/partners/{partnerId}}/devices?limit=10&start=0"   -H "accept: application/json"
  -H "Authorization: Bearer your_partner_token"

{
  "total": 1,
  "items": [
      1
  ],
  "models": {
      "7": {
          "id": 7,
          "contents": {
              "name": "Raincrop",
              "externalDiameter": 0.206,
              "conception": "France - Lille",
              "manufacturing": "Europe-France",
              "calibration": "Ok",
              "weight": 3.5
          }
      }
  },
  "devicesStatuses": {
      "1": {
          "id": 1,
          "measuresCount": 66502,
          "contents": {
              "firmware": "00-V1.12",
              "signal": 6,
              "battery": 3184,
              "latitude": 48.0654,
              "longitude": 4.40095,
              "altitude": 257,
              "locationPrecision": 0,
              "locationSatellites": 7,
              "lastLocationDate": "2018-06-28T14:52:33.000Z",
              "lastMoveDate": "2018-06-28T11:58:51.000Z",
              "lastStatusUpdateDate": "2018-10-02T08:16:36.000Z",
              "lastRebootDate": "2018-06-06T18:58:04.000Z"
          }
      },
  },
  "devices": {
      "1": {
          "id": 1,
          "accessPeriods": [
              {
                  "id": 31426,
                  "deviceId": 1,
                  "delegatorId": 3,
                  "moduleId": 1,
                  "parameters": {
                      "id": "xxxxx",
                  },
                  "partnerParameters": {
                      "enabled": false,
                  },
                  "type": "partner",
                  "startDate": "2018-05-08T09:59:11.000Z"
              }
          ],
          "modelId": 7,
          "organisationId": 1,
          "previousDevicesIds": [],
          "identification": "RC00XXXX",
          "serial": "ABBACACA",
          "situation": "unknown",
          "contents": {
              "name": "Station champs 1"
          }
      },
  },
  "users": {
      "3": {
          "id": 3,
          "creationDate": "2018-02-21T10:02:00.000Z",
          "lastModificationDate": "2018-08-31T13:54:50.000Z",
          "locale": "fr-FR",
          "timeZone": "Europe/Paris",
          "organisationsIds": [
              1
          ],
          "organisationId": 1,
          "roles": [],
          "signupType": "unknown",
          "emailVerified": true,
          "contents": {
              "firstname": "Michel",
              "lastname": "Delpech",
              "email": "michel@sencrop.com",
              "address": "2 rue Fourier",
              "zipcode": "59000",
              "city": "Lille",
              "country": "FR"
          }
      },
  },
  "organisations": {
      "1": {
          "id": 1,
          "creationDate": "2014-02-21T10:02:01.000Z",
          "lastModificationDate": "2018-09-26T14:59:35.000Z",
          "type": "company",
          "placeIds": [
              1
          ],
          "contents": {
              "name": "Sencrop",
              "locale": "fr-FR",
              "timeZone": "Europe/Paris"
          }
      },
  },
  "places": {
      "1": {
          "id": 1,
          "city": "Lille",
          "country": "FR",
          "organisationId": 1,
          "creationDate": "2018-07-19T12:46:21.000Z",
          "lastModificationDate": "2018-07-19T16:34:43.000Z",
          "contents": {
              "address": "40 Rue de Wattignies, 59000 Lille, France",
              "googlePlaceId": "ChIJd3KeUZbVwkcRgg46S0kvJ48",
              "location": {
                  "lat": 50.6202,
                  "lng": 3.06451
              },
              "type": "principal"
          }
      },
  }
}

You will probably need to check the following values:

  • devices ids: The items property contains the list of the returned devices ids. You can access to those devices in the devices property which is the hash of the actual devices.
  • devices names: the name a user gave to its device can be found at path devices[deviceid].contents.name.
  • devices identifications: a human readable unique id (actually printed on the device itsef) that users can use for every support requests can be found at path devices[deviceid].identification.
  • devices models: the device model id can be found at devices[deviceid].modelIdand the actual model data at models[modelId].
  • devices access: contains the various access to the devices. You want to review the partner type accesses in order to know which modules were activated for this device (see at path devices[deviceId].accessPeriods[type=partner].moduleId.). You probably want to look at the delegatorId which tells you the userId of the user that activated the module on this device. Beware that a endDatecan be present in those access. In this case, you will only have access to the data in the date range formed withstartDate. Also note that a parametersproperty is available to get back the eventual parameters added by the users when activating the module on their device.
  • users: you can user the users hash to pick up informations on the user behind the delegatorId. You will probably pick up their email in order togenerate tokens with the module flow to access the data they shared with you.
  • organisations: and finally, you may want to know which organisations a user is part of by looking in the organisations hash corresponding to the organisationId found at pathusers[delegatorId].organisationsIds.

Manage partner parameters

Dependending on your Sencrop modules you may need to setup some parameters to the devices on which your modules were activated. By example, if you have an activation workflow:


curl -X POST "https://api.sencrop.com/v1/partners/{partnerId}}/users/{delegatorId}/devices/{deviceId}/modules/{moduleId}/parameters"   --data-binary '{ "enabled": true }'
  -H "Content-Type: application/json"
  -H "Authorization: Bearer your_partner_token"