Hoppa till huvudinnehåll

MQTT API

Version 2.0

MQTT-integrationen publicerar data relaterad till en organisation. Även om HTTP API är bra för att hämta historisk data och aktuellt tillstånd, är MQTT API mer lämpat om du omedelbart vill agera på en händelse.

Anslutningsinformation​

  • MQTT Version: 3.1.1
  • Host: mqtt.bintel.se
  • Port: 8883
  • SSL/TLS: Ja, TLS v1.2 eller TLS v1.3
  • Certifikat: CA signerat servercertifikat

Din applikation bör implementeras för att hantera korta avbrott i tjänsten. Server kan starta om utan föregående meddelande under korta perioder för att tillämpa uppdateringar eller ladda om certifikat. För att hantera detta rekommenderas att din applikation har en funktion för automatisk återanslutning.

Om ni har "clean session" inställd på "false" kommer servern att bevara din session och lagra meddelanden i kö på dina QoS 1- och 2-prenumerationer i upp till 24 timmar.

Autentisering​

  • Användarnamn: [Organizations-ID]
  • Lösenord: [API Nyckel]
  • Klient-ID: [Organizations-ID]:*

Ditt Organizations-ID finns under insights.bintel.se/settings, det är också här du hanterar dina API-nycklar.

MQTT Klient-ID måste börja med Organisations-ID följt av :. Detta förhindrar olika användare från att störa varandra genom att använda samma Klient-ID.

Prenumeration​

Meddelanden kommer att skickas med ett ämne med följande basformat:

v2/[Organizations-ID]/

Om ni vill prenumerera på all data för er organisation kan ni prenumerera på

v2/[Organizations-ID]/#

Detta är det mest generiska ämnet som en kund får prenumerera på. Vi rekommenderar dock inte att använda detta ämne eftersom nya meddelandetyper kan tillkomma i framtiden.

Meddelandetyper​

Nedan följer en lista över de olika meddelandetyperna som publiceras av tjänsten. Nyttolasten kommer alltid att vara i JSON-format och följer schemat som refereras till i varje typ nedan.

Alla meddelanden publiceras med QoS 2 men ni kan välja att prenumerera med vilken tjänstkvalitet som bäst passar ditt use-case.

Behållarhändelser​

Skickas av: Server
Ämne: v2/[Organizations-ID]/container/event/[Behållare-ID]/
Schema: container-event.schema.json

Detaljerad beskrivning av händelser från en behållare finns här.

Exempel:

v2/5d7a0b958086466694f5be0e/container/event/5d5575d638817e246cef4d0b
{
  "time": "2021-12-24T08:00:00.000Z",
  "container": {
    "id": "5d5575d638817e246cef4d0b",
    "name": "Example Container",
    "externalId": "CON123",
    "coordinates": { "latitude": 55.716994, "longitude": 13.225053, "altitude": 0 },
    "devices": [
      { "id": "5d7a0b958086466694f5be78", "bintelId": "123456" }
    ],    
  },
  "event": {
    "eventType": "pickup-requested"
  }
}

Behållaruppdateringar​

Skickas av: Server
Ämne: v2/[Organizations-ID]/container/update/[Behållare-ID]
Schema: container-update.schema.json

Detaljerad beskrivning av data från en behållare finns här. Även om flera datauppdateringar sker samtidigt skickas de fortfarande som separata meddelanden.

Exempel:

v2/5d7a0b958086466694f5be0e/container/update/5d5575d638817e246cef4d0b
{
  "time": "2021-12-24T08:00:00.000Z",
  "container": {
    "id": "5d5575d638817e246cef4d0b",
    "name": "Example Container",
    "externalId": "CON123",
    "coordinates": { "latitude": 55.716994, "longitude": 13.225053, "altitude": 0 },
    "devices": [
      { "id": "5d7a0b958086466694f5be78", "bintelId": "123456" }
    ],   
  },
  "update": {
    "tag": "fill-percent",
    "value": 0.6
  }
}

Behållarrapport​

Skickas av: Klient
Ämne: v2/[Organizations-ID]/container/report
Schema: container-report.schema.json

Antingen id eller "externalId måste finnas för att identifiera behållaren.

Tillgängliga rapporttyper kan hittas här.

time bör ange det ögonblick då rapporten ursprungligen skapades.

source är valfritt men rekommenderas. Den används för att ange källan till rapporten. Som i det här exemplet genererades rapporten från ett system i en lastbil som utförde en tömning. Det finns inga hårda begränsningar för detta fält men det bör hållas konsekvent, dvs så länge källan är densamma bör detta värde inte ändras.

weight är också ett valfritt fält och kan användas för att leverera viktinformation till systemet när det är tillgängligt. Vikten ska vara i kilogram. Om ingen viktdata finns tillgänglig bör detta fält utelämnas.

discrepancies är också ett valfritt fält och kan användas för att tillhandahålla avvikelser associerade med upphämtningen. Avvikelsenamnen bör vara konsekventa för samma avvikelsetyp men behöver inte följa en fördefinierad uppsättning. Avvikelser kan rapporteras i samband med alla typer av rapporter.

Exempel:

v2/5d7a0b958086466694f5be0e/container/report
{
  "id": "5d5575d638817e246cef4d0b",
  "time": "2019-12-24T08:00:00.000Z",
  "reportType": "pickup-performed",
  "source": "in-truck-computer",
  "weight": 42.0,
  "discrepancies": ["littering"]
}

eller

v2/5d7a0b958086466694f5be0e/container/report
{
  "externalId": "CON123",
  "time": "2019-12-24T08:00:00.000Z",
  "reportType": "pickup-performed",
  "source": "in-truck-computer",
  "weight": 42.0,
  "discrepancies": ["overfilled"]
}