Autenticazione

La SMS API di Agile Telecom accetta due metodi di autenticazione su HTTPS. API Key è consigliata per nuove integrazioni.

API Key (consigliata)

Invia la tua API key nell'header X-Api-Key a ogni richiesta.

Come ottenere l'API key

1. Accedi al portale wholesale.
2. Apri Settings → API Keys.
3. Genera una nuova key o copia quella esistente.
4. Conservala come variabile d'ambiente sul tuo backend — mai committarla nel repository.

Usare l'API Key

cURL

curl -X POST https://wholesale.agiletelecom.com/services/sms/send \
  -H "X-Api-Key: $AGILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "destinations": ["+393351234567"],
        "sender": "Agile",
        "body": "Ciao da Agile Telecom!"
      }
    ]
  }'

Python

import os
import requests

headers = {
    "X-Api-Key": os.environ["AGILE_API_KEY"],
    "Content-Type": "application/json",
}

payload = {
    "messages": [
        {
            "destinations": ["+393351234567"],
            "sender": "Agile",
            "body": "Ciao da Agile Telecom!",
        }
    ]
}

response = requests.post(
    "https://wholesale.agiletelecom.com/services/sms/send",
    json=payload,
    headers=headers,
    timeout=10,
)
print(response.json())

Node.js

const axios = require('axios');

const config = {
  headers: {
    'X-Api-Key': process.env.AGILE_API_KEY,
    'Content-Type': 'application/json',
  },
};

const data = {
  messages: [
    {
      destinations: ['+393351234567'],
      sender: 'Agile',
      body: 'Ciao da Agile Telecom!',
    },
  ],
};

axios
  .post('https://wholesale.agiletelecom.com/services/sms/send', data, config)
  .then((res) => console.log(res.data))
  .catch((err) => console.error(err.response?.data));

Basic Authentication

Se le API key non sono adatte al tuo ambiente, usa credenziali codificate in Base64.

Generare le credenziali Basic Auth

macOS/Linux:

echo -n "username:password" | base64

Windows (PowerShell):

[Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("username:password"))

Usare Basic Auth

cURL

curl -X POST https://wholesale.agiletelecom.com/services/sms/send \
  -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "destinations": ["+393351234567"],
        "sender": "Agile",
        "body": "Ciao da Agile Telecom!"
      }
    ]
  }'

Python

import requests
from requests.auth import HTTPBasicAuth

response = requests.post(
    "https://wholesale.agiletelecom.com/services/sms/send",
    json={
        "messages": [
            {
                "destinations": ["+393351234567"],
                "sender": "Agile",
                "body": "Ciao da Agile Telecom!",
            }
        ]
    },
    auth=HTTPBasicAuth("username", "password"),
    timeout=10,
)

print(response.json())

Node.js

const axios = require('axios');

const auth = { username: 'username', password: 'password' };

const data = {
  messages: [
    {
      destinations: ['+393351234567'],
      sender: 'Agile',
      body: 'Ciao da Agile Telecom!',
    },
  ],
};

axios
  .post('https://wholesale.agiletelecom.com/services/sms/send', data, { auth })
  .then((res) => console.log(res.data))
  .catch((err) => console.error(err.response?.data));

IP Whitelisting

Aggiungi un ulteriore layer di sicurezza limitando l'accesso API a IP specifici. Opzionale ma fortemente consigliato in produzione.

1. Apri Settings → Security sul portale wholesale.
2. Abilita IP whitelist.
3. Aggiungi gli IP pubblici dei tuoi server.
4. Salva.

Le richieste da IP non whitelisted ricevono 403 Forbidden.

Codici di errore

Codice	Significato	Azione
401	Credenziali non valide	Verifica API key o credenziali Basic Auth
403	IP non autorizzato	Verifica che l'IP chiamante sia in whitelist (se abilitata)
429	Rate limit superato	Applica back-off esponenziale, vedi Best Practice

Best practice di sicurezza

1. Mai esporre le API key in codice client-side — Usale solo nel backend.
2. Conserva le key in variabili d'ambiente — Mai hardcoded.
3. Ruota le key periodicamente — Ogni 90 giorni in ambienti ad alta sicurezza.
4. Solo HTTPS — Tutte le richieste devono essere via TLS; dal 15 gennaio 2026 le connessioni non-TLS vengono rifiutate.
5. Usa la IP whitelist quando il backend ha un IP pubblico stabile.
6. Monitora l'utilizzo — Verifica picchi anomali nel portale wholesale.

Hai bisogno di assistenza? Scrivi a help@agiletelecom.com o apri il portale wholesale.