📡 SMS-server — API

Skicka och ta emot SMS via SMS-servern. Du autentiserar varje anrop med din API-nyckel i headern X-API-Key. Nyckeln (och din webhook_secret för att verifiera inkommande anrop) får du av administratören.

Bas-URL: https://utskick.karlberg.nu

1. Skicka SMS

POST /api/send — ett SMS direkt

Skickar omedelbart och svarar när SMS:et är skickat (eller misslyckats).

curl -s https://utskick.karlberg.nu/api/send \
  -H "X-API-Key: DIN_NYCKEL" \
  -H "Content-Type: application/json" \
  -d '{"number":"+46701234567","message":"Hej från oss!"}'

# Svar:
# {"id": 42, "status": "sent", "router_ip": "10.0.0.3", "attempts": 1}

POST /api/send-bulk — flera mottagare

Köas och skickas med jämna, oregelbundna mellanrum (skonsamt mot operatören). Du får ett id per meddelande — leveransstatus kommer via webhook eller pollning.

curl -s https://utskick.karlberg.nu/api/send-bulk \
  -H "X-API-Key: DIN_NYCKEL" \
  -H "Content-Type: application/json" \
  -d '{"numbers":["+46701234567","+46707654321"],"message":"Kampanjtext"}'

# Svar:
# {"ids":[43,44], "count":2, "status":"queued", "queue":2}

Valfria fält (båda endpoints)

Servern klär normalt meddelandet med en varierad hälsning + ditt tjänstnamn, och skriver om kod-meddelanden till OTP xxxx-format (så mobilen känner igen engångskoden). Du kan styra detta:

• "raw": true — skicka texten exakt som den är, ingen omskrivning.
• "service": "Mitt Företag" — avsändarnamnet i hälsningen (annars härleds det från din nyckel).
• "name": "Johnny" — mottagarens namn för personlig hälsning ("Hej Johnny! …"), endast /api/send.

2. Ta emot leveransrapporter och svar (webhook)

Ge administratören en webhook-URL (din egen endpoint). Dit POST:ar SMS-servern två sorters händelser, som JSON, signerade så att du kan verifiera att de kommer från oss. Du behöver alltså bygga en mottagande endpoint på din sida.

Leveransrapport

POST:as när ett av dina utskick når slutstatus (sent eller failed).

{
  "type": "delivery_report",
  "id": 43,
  "number": "+46701234567",
  "status": "sent",          // sent | failed
  "router_ip": "10.0.0.3",
  "attempts": 1,
  "error": null
}

Inkommande svar

När någon svarar på ett SMS du skickat POST:as svaret till dig (svaret kopplas till dig eftersom du var den som senast skrev till numret).

{
  "type": "inbound_sms",
  "id": 87,
  "from": "+46701234567",
  "message": "Ja tack!",
  "date": "2026-06-04 21:15:00"
}

Verifiera signaturen

Varje webhook-anrop har headern X-SMS-Signature = base64(HMAC_SHA256(rå_body, webhook_secret)). Räkna ut samma värde på din sida och jämför. Verifiera mot den råa bodyn (inte en om-serialiserad JSON).

Node.js (Express):

const crypto = require("crypto");
const SECRET = "DIN_WEBHOOK_SECRET";

// Viktigt: läs den RÅA bodyn — t.ex. express.raw({ type: "application/json" })
app.post("/sms-webhook", express.raw({ type: "*/*" }), (req, res) => {
  const sig = crypto.createHmac("sha256", SECRET).update(req.body).digest("base64");
  if (sig !== req.get("X-SMS-Signature")) return res.sendStatus(401);

  const event = JSON.parse(req.body.toString());
  if (event.type === "delivery_report") { /* ... */ }
  if (event.type === "inbound_sms")     { /* ... svara kunden via /api/send ... */ }
  res.sendStatus(200);
});

Python (Flask):

import base64, hashlib, hmac
from flask import Flask, request, abort
SECRET = b"DIN_WEBHOOK_SECRET"
app = Flask(__name__)

@app.post("/sms-webhook")
def hook():
    raw = request.get_data()                      # rå body
    sig = base64.b64encode(hmac.new(SECRET, raw, hashlib.sha256).digest()).decode()
    if not hmac.compare_digest(sig, request.headers.get("X-SMS-Signature", "")):
        abort(401)
    event = request.get_json()
    # event["type"] == "delivery_report" | "inbound_sms"
    return "", 200

3. Hämta status utan webhook (pollning)

Vill du inte bygga en webhook kan du i stället hämta läget med din nyckel:

curl -s "https://utskick.karlberg.nu/api/my/messages?limit=20" -H "X-API-Key: DIN_NYCKEL"

Fel & gränser

Din nyckels pris/SMS, ev. månadstak och förbrukning denna månad ser du via GET /api/my/info (fälten price_ore, monthly_cap, month_count, month_cost_ore).

Externa nycklar får bara skicka och hämta sina egna data — inte se andras utskick, kontakter eller dashboarden.