Integration test

You'll need a simple way to test your progress and to make sure your integration works as planned.

To achieve this, you'll be able to access a test environment.

  • You'll be able to trigger different behaviours by using different UUID.
  • You'll have the opportunity to use the same production endpoints.
  • Test environment supports success or error expected responses.


Generic Commands

📘

Info

If you don't remember what a generic command is, visit the Commands guide's page.


UUID table:

UUIDResponse
26c1097a-45d7-4719-a195-595c252a16f7SUCCESS
all UUIDs with a missing or expired o wrong tokenAUTHENTICATION_ERROR
a0d10b22-2575-4f1c-95dd-a287df8114c0GATEWAY_TIMEOUT
c9051717-34fd-49f5-b2aa-2e2093bd2c42VEHICLE_OFFLINE
aae121e9-3d74-4fb6-85b8-179d208b06c4INSUFFICIENT_PERMISSIONS
every UUID different from the previous ones with the right authenticationVEHICLE_NOT_REGISTERED
every UUID different from the previous ones with the right authentication and wrong command nameINVALID_COMMAND_NAME

Successful response format:

{
    “success”: true
}

Authentication error response format:

{
    "code": "AUTHENTICATION_ERROR",
    "errorId": "this_is_an_error_id",
    "details": {
        "cause": "this_is_a_generic_error_cause"
    }
}

Timeout response format:

{
    "success": false,
    "code": "VEHICLE_INTERACTION_ERROR",
    "details": {
        "cause": "GATEWAY_TIMEOUT"
    },
    "errorId": string
}

Vehicle offline response format:

{
    "success": false,
    "code": "VEHICLE_INTERACTION_ERROR",
    "details": {
        "cause": "VEHICLE_OFFLINE"
    },
    "errorId": string
}

Insufficient permissions response format:

{
    "code": "AUTHORIZATION_ERROR",
    "errorId": string,
    "details": {
        "cause": "INSUFFICIENT_PERMISSIONS"
    }
}

Vehicle not registered response format:

{
    "code": "VEHICLE_NOT_FOUND_ERROR",
    "errorId": string,
    "details": {
        "cause": "VEHICLE_NOT_REGISTERED"
    }
}

Invalid command response format:

{
    "code": "VALIDATION_ERROR",
    "errorId": string,
    "details": {
        "cause": "INVALID_COMMAND_NAME"
    }
}


Generic Signals

📘

Info

If you don't remember what a signal is, visit the Signals guide's page.


UUID table:

UUIDResponse
26c1097a-45d7-4719-a195-595c252a16f7
a0d10b22-2575-4f1c-95dd-a287df8114c0
c9051717-34fd-49f5-b2aa-2e2093bd2c42
SUCCESS
all UUIDs with a missing or expired o wrong tokenAUTHENTICATION_ERROR
aae121e9-3d74-4fb6-85b8-179d208b06c4INSUFFICIENT_PERMISSIONS
every UUID different from the previous ones with the right authenticationVEHICLE_NOT_REGISTERED
every UUID different from the previous ones with the right authentication and wrong signal nameINVALID_SIGNAL_NAME

Successful response format:

{
  "timestamp": 1488700800000, //always set to current timestamp
  "data": {
    "latitude": 41.91344,
    "longitude": 12.50113
    },
};


Webhooks

To test your integration, use the specific endpoint to send legitimate events to the provided url.

📘

Info

If you don't remember how the webhooks work in our system, visit the Receiving signals guide's page.


The request body must contain the following parameters:

ParameterDescription
DESTINATION_URLThe server destination URL.
COMPANY_SECRETThe company secret needed to generate the correct signature.

You'll receive an event, and you'll have to manage it

The event body will consist of the following:

e.g. Position webhook

{
    "topic": 'vehicle:26c1097a-45d7-4719-a195-595c252a16f7:generic:position',
    "payload": {
        "timestamp": 1488700800000, //always set to current timestamp
        "data": {
      "latitude": 40.42277527,
      "longitude": -3.69623494
    }
  }
}

Depending on your system handling ,the response from the webhook's request can be a success one or an error one:


Success

If your system responds in the right way, you'll receive the following message:

{
    "success": true,
  "response": {
    "statusCode": number,
    "body": string,
  },
    "timings": { ... } 
}

Error

If your system responds in the wrong way, you'll receive the following message:

{
    "success": false,
    "error": {
        "name": string,
        "code": string,
    },
    "timings": { ... } 
}

Where the "timings" object contains information about the duration of the requests.


Did this page help you?