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. - PHP 7.4 o superior con la extensión cURL habilitada.
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 PHP y cURL
El siguiente script envía un SMS y procesa la respuesta. No requiere dependencias externas:
<?php
declare(strict_types=1);
$token = getenv('GTP_SMS_TOKEN');
$payload = json_encode([
'to' => '+525512345678',
'body' => 'Su codigo de verificacion es 482913. Vence en 5 minutos.',
], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
$ch = curl_init('https://api.grupotecnophone.com/prod/v1/sms/send');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $token,
'Content-Type: application/json',
'User-Agent: MiEmpresa/1.0',
],
CURLOPT_POSTFIELDS => $payload,
CURLOPT_TIMEOUT => 30,
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$error = curl_error($ch);
curl_close($ch);
if ($response === false) {
throw new RuntimeException("Error de red: {$error}");
}
$data = json_decode($response, true) ?? [];
if ($httpCode === 200 && ($data['status'] ?? null) === 'success') {
echo "Enviado. SID: {$data['sid']} - segmentos: {$data['num_segments']}\n";
} else {
$code = $data['error']['code'] ?? "HTTP_{$httpCode}";
echo "No enviado ({$code}): " . ($data['error']['message'] ?? $response) . "\n";
}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.
Errores frecuentes
| HTTP | Código | Qué significa |
|---|---|---|
| 400 | ENCRYPTION_REQUIRED | La conexión exige que to y body viajen cifrados con RSA-OAEP |
| 400 | ENCRYPTION_NOT_ALLOWED | La conexión opera en texto plano y se recibió contenido cifrado |
| 400 | INPUT_PHONE_BLACKLISTED | El número de destino está en lista negra |
| 400 | INSUFFICIENT_BALANCE | Saldo 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.
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 Laravel, Python, Node.js y Java. Si necesita credenciales de prueba, contáctenos.
