Envío de datos

HTTPS

Los datos enviados a la plataforma han de firmarse para garantizar la autenticidad de estos. Para ver cómo formatear la trama a enviar puedes consultar aquí. A la hora de especificar el IMEI recomendamos que se preceda de una cadena de texto que identifique tu compañía, ya que nuestra plataforma es multi-tenant y es posible que haya otra organización con el mismo código de dispositivo y si tratas de enviar datos a un dispositivo que ya pertenece a otra organización recibirás un error. Así que si tu organización se llama “Naza” y tu dispositivo es el “0131514589” te recomendemos que uses “NAZA0131514589” como IMEI.

Requisitos

Antes de poder enviar datos necesitarás que te proporcionemos un par de claves pública y privada. Guárdalas y protégelas, si las expusieras podrían enviar datos por ti.

Además de estas claves te proporcionaremos el endpoint al que enviar la petición.

Envío de datos

Una vez tengas toda esta información puedes proceder a preparar la petición para el envío de datos. Se realizará con un POST al endpoint que te proporcionemos, introduciendo la trama JSON en el body y proporcionando las cabeceras X-API-Key con la clave pública y X-Signature con la firma de la petición.

Para calcular la firma hay que cifrar con el algoritmo HMAC-SHA256 usando la clave privada proporcionada la siguiente cadena: POST{ENDPOINT}?{BODY} (cambiando {ENDPOINT} por el endpoint que te hemos proporcionado y {BODY} por el JSON que envías). Por último, codifica el resultado en base64.

A continuación se pueden consultar snippets de cómo hacerlo en JS y Ruby:

import hmacSHA256 from 'crypto-js/hmac-sha256';
import Base64 from 'crypto-js/enc-base64';
 
function signature(endpoint, body, privateKey) {
  return Base64.stringify(hmacSHA256(`POST${endpoint}?${body}`, privateKey));
}

require 'openssl'
require 'base64'
 
def signature(endpoint, body, private_key)
  Base64.strict_encode64(
    OpenSSL::HMAC.digest(
      OpenSSL::Digest.new('sha256'),
      private_key,
      "POST#{endpoint}?#{body}"
    )
  )
end

Por ejemplo, si te proporcionamos estos datos:

Endpoint: https://example.org/input
Clave pública: e358ed88da6ffe6775df67a21804a94c
Clave privada: 9cab5c3ceeaa6ada35581cc45ebe2c9f

Y quieres enviar la siguiente trama: {"HIST":{"VERSION":"TEST","IMEI":"TEST-DEVICE","UTC":1705329888,"DATA":{"VAR_1":3.14159,"VAR_2":"Foo"}}}

La cadena que habría que cifrar sería POSTexample.org/input?{"HIST":{"VERSION":"TEST","IMEI":"TEST-DEVICE","UTC":1705329888,"DATA":{"VAR_1":3.14159,"VAR_2":"Foo"}}} y el resultado de la firma: xdwoPNHlm5n/IPw7BaCcaPqIHttV7T8xBPtTl7QhAsw=

Por tanto habría que realizar la siguiente petición:

curl -X POST \
  https://example.org/input \
  -H "Content-Type: application/json" \
  -H "X-API-Key: e358ed88da6ffe6775df67a21804a94c" \
  -H "X-Signature: xdwoPNHlm5n/IPw7BaCcaPqIHttV7T8xBPtTl7QhAsw=" \
  -d '{"HIST":{"VERSION":"TEST","IMEI":"TEST-DEVICE","UTC":1705329888,"DATA":{"VAR_1":3.14159,"VAR_2":"Foo"}}}'