GUÍA PARA DESARROLLADORES

Cómo enviar SMS desde Java con la API de Grupo Tecnophone

Integre el envío de SMS en sus aplicaciones Java con el HttpClient estándar: autenticación por token, IP autorizada y respuesta JSON por cada mensaje.

Antes de empezar

  • Una conexión API creada en el panel web (app.grupotecnophone.com), con su Bearer Token de sandbox o de producción.
  • La IP pública de su servidor registrada como autorizada para ese token.
  • Un User-Agent que identifique a su aplicación, por ejemplo MiEmpresa/1.0.
  • Java 11 o superior (incluye java.net.http.HttpClient).

Guarde el token en una variable de entorno (en estos ejemplos, GTP_SMS_TOKEN) y nunca lo incluya en el código de una app móvil o de un sitio web: las llamadas a la API deben salir siempre de su backend, desde una IP autorizada.

Enviar un SMS con Java

El siguiente ejemplo envía un SMS con el cliente HTTP estándar de Java. Para producción, procese el JSON de respuesta con la librería que ya use su proyecto:

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class EnviarSms {

    private static final String ENDPOINT = "https://api.grupotecnophone.com/prod/v1/sms/send";

    public static void main(String[] args) throws Exception {
        String token = System.getenv("GTP_SMS_TOKEN");
        String json = "{\"to\":\"+525512345678\","
                + "\"body\":\"Su codigo de verificacion es 482913. Vence en 5 minutos.\"}";

        HttpClient client = HttpClient.newBuilder()
                .connectTimeout(Duration.ofSeconds(10))
                .build();

        HttpRequest request = HttpRequest.newBuilder(URI.create(ENDPOINT))
                .timeout(Duration.ofSeconds(30))
                .header("Authorization", "Bearer " + token)
                .header("Content-Type", "application/json")
                .header("User-Agent", "MiEmpresa/1.0")
                .POST(HttpRequest.BodyPublishers.ofString(json))
                .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println("HTTP " + response.statusCode());
        System.out.println(response.body()); // procese el JSON con su libreria habitual (Jackson, Gson)
    }
}

Respuesta de la API

Si el mensaje fue aceptado, la API responde con HTTP 200 y un JSON como este:

{
  "sid": "sms_20261012143201_39bdafbd",
  "status": "success",
  "to": "+525512345678",
  "body": "Su codigo de verificacion es 482913. Vence en 5 minutos.",
  "encoding": "GSM7",
  "num_chars": 56,
  "num_segments": 1,
  "error": null
}

Guarde el sid: es el identificador con el que podrá conciliar el reporte de entrega del mensaje. El campo num_segments indica cuántos segmentos se cobrarán; vea cómo se calculan los segmentos.

Enviar SMS a varios destinatarios con Java

Para enviar SMS masivos desde Java reutilice un solo HttpClient y recorra su lista de números. En producción lea la respuesta con una librería JSON (Jackson o Gson) para guardar el sid y separar los errores.

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.List;

public class EnvioMasivo {
    private static final String ENDPOINT = "https://api.grupotecnophone.com/prod/v1/sms/send";
    private static final String TOKEN = System.getenv("GTP_SMS_TOKEN");
    private static final HttpClient CLIENT = HttpClient.newHttpClient();

    static HttpResponse<String> enviarSms(String to, String body) throws Exception {
        String json = "{\"to\":\"" + to + "\",\"body\":\"" + body.replace("\"", "\\\"") + "\"}";
        HttpRequest req = HttpRequest.newBuilder(URI.create(ENDPOINT))
                .timeout(Duration.ofSeconds(30))
                .header("Authorization", "Bearer " + TOKEN)
                .header("Content-Type", "application/json")
                .header("User-Agent", "MiEmpresa/1.0")
                .POST(HttpRequest.BodyPublishers.ofString(json))
                .build();
        return CLIENT.send(req, HttpResponse.BodyHandlers.ofString());
    }

    public static void main(String[] args) throws Exception {
        List<String> destinatarios = List.of("+525512345678", "+525598765432");
        for (String numero : destinatarios) {
            HttpResponse<String> resp = enviarSms(numero, "Su pedido 1234 ya va en camino.");
            System.out.println(numero + " -> " + resp.statusCode() + " " + resp.body());
            Thread.sleep(100); // ritmo moderado para listas grandes
        }
    }
}

Para listas muy grandes procese en lotes y reintente solo los errores temporales. Sin programar, también puede enviar SMS masivos desde Excel o CSV.

Enviar un código OTP con Java

Para códigos de verificación use SecureRandom, nunca Random, y guarde solo el hash del código con su vencimiento.

import java.security.SecureRandom;

SecureRandom random = new SecureRandom();
String codigo = String.format("%06d", random.nextInt(1_000_000));
enviarSms("+525512345678", "Su codigo de verificacion es " + codigo + ". Vence en 5 minutos.");
// Guarde solo el hash del código y su fecha de vencimiento

Más detalles del flujo en la guía de autenticación OTP por SMS.

Errores frecuentes

HTTPCódigoQué significa
400ENCRYPTION_REQUIREDLa conexión exige que to y body viajen cifrados con RSA-OAEP
400ENCRYPTION_NOT_ALLOWEDLa conexión opera en texto plano y se recibió contenido cifrado
400INPUT_PHONE_BLACKLISTEDEl número de destino está en lista negra
400INSUFFICIENT_BALANCESaldo insuficiente para el envío
401—Token ausente o inválido
403—La IP de origen no está autorizada para el token
500—Error interno no esperado

En los errores 400 la respuesta incluye un objeto error con code, code_num y message.

Spring Boot: un servicio reutilizable para enviar SMS

Si su aplicación usa Spring Boot 3.2 o posterior, puede encapsular el envío en un servicio con RestClient. Los records mapean el JSON de la petición y de la respuesta sin código adicional:

import java.net.http.HttpClient;
import java.time.Duration;

import org.springframework.http.MediaType;
import org.springframework.http.client.JdkClientHttpRequestFactory;
import org.springframework.stereotype.Service;
import org.springframework.web.client.RestClient;

record SmsRequest(String to, String body) {}
record SmsResponse(String sid, String status, String to, String encoding,
                   int num_segments, String error) {}

@Service
public class SmsService {

    private final RestClient client;

    public SmsService() {
        HttpClient http = HttpClient.newBuilder()
                .connectTimeout(Duration.ofSeconds(10))
                .build();
        JdkClientHttpRequestFactory factory = new JdkClientHttpRequestFactory(http);
        factory.setReadTimeout(Duration.ofSeconds(30));

        this.client = RestClient.builder()
                .requestFactory(factory)
                .baseUrl("https://api.grupotecnophone.com/prod/v1")
                .defaultHeader("Authorization", "Bearer " + System.getenv("GTP_SMS_TOKEN"))
                .build();
    }

    public SmsResponse send(String to, String body) {
        return client.post()
                .uri("/sms/send")
                .contentType(MediaType.APPLICATION_JSON)
                .body(new SmsRequest(to, body))
                .retrieve()
                .body(SmsResponse.class);
    }
}

Inyecte SmsService donde lo necesite y guarde el sid de cada respuesta para conciliar el reporte de entrega. Reintente solo errores de red y respuestas 5xx, con una espera creciente entre intentos; un error 4xx indica un problema en la petición que no se corrige reintentando.

Probar en sandbox

Cambie el endpoint por https://api.grupotecnophone.com/test/v1/sms/send y use el token de sandbox. Ese entorno valida token, IP, payload y cifrado con la misma lógica que producción, pero no envía SMS reales.

Buenas prácticas

  • Defina un timeout y registre cada respuesta con su sid.
  • Ante un error de red sin respuesta, no reenvíe a ciegas: verifique primero para no duplicar el mensaje al usuario.
  • Reintente solo errores 500, con espera progresiva y un número máximo de intentos.
  • Encole los envíos masivos en lugar de enviarlos en el ciclo de una petición web.
  • Si el contenido es sensible, active el cifrado de la conexión; la documentación de la API incluye un ejemplo de cifrado RSA en PHP sin librerías externas.

Vea también la API SMS México, la conexión SMPP y las guías para PHP, Laravel, Python, Node.js, C# (.NET) y cURL. Si necesita credenciales de prueba, contáctenos.

Preguntas frecuentes: Enviar SMS con Java

Scroll al inicio