A API de Geofencing permite que os usuários criem cercas geográficas para dispositivos, possibilitando que recebam notificações sempre que uma linha móvel entrar ou sair da área predefinida. A solução é o recurso ideal para rastrear o movimento de ativos, aprimorando a segurança por meio do monitoramento em tempo real de bens de alto valor.
O uso desta API é exclusivo para dispositivos M2M (máquina a máquina).
A nossa API é “restful”, ou seja, o nosso protocolo de comunicação foi criado de uma forma que pode interpretar qualquer linguagem de programação. Isso torna o processo de integração do lado dos nossos clientes e parceiros mais flexível e de fácil entendimento. Na página de documentação deixamos alguns exemplos de linguagem, caso seja necessário.
Os retornos fornecidos, quando vinculados a outras medidas, podem se tornar meios eficazes de evitar que sejam praticadas fraudes, minimizando assim, o seu impacto no ambiente de negócios.
• Validação em tempo real dos dados fornecidos.
• Acesso a informações verificadas pela Operadora.
• Garantia de precisão e segurança nos processos de verificação.
• Total conformidade com as regulamentações de privacidade.
Melhore a qualidade dos dados, reduza fraudes e ofereça uma experiência mais confiável para seus usuários com a nossa solução robusta e eficiente. Integre facilmente e eleve o nível de confiabilidade do seu serviço!
Versão: 0.2.1
Criada por: Claro | GSMA Opengateway
Data: 02/12/2025
Passo a passo
Caso ainda tenha duvidas, baixe o PDF abaixo com o tutorial de integração da API Geofencing. Ele te explica passo a passo como utilizá-la.
200 -A solicitação foi bem-sucedida. A resposta contém o resultado da validação dos dados do cliente.
400 - A solicitação não pôde ser entendida pelo servidor devido à sintaxe incorreta ou parâmetros inválidos. O cliente deve corrigir e reenviar a requisição.
401 - A solicitação requer autenticação. O token de acesso está ausente, inválido ou expirado.
500- Erro interno do servidor. Um problema inesperado ocorreu no processamento da solicitação.
504 - O servidor não conseguiu receber uma resposta a tempo para completar a solicitação. Recomenda-se tentar novamente.
Caso ainda restem dúvidas, baixe o PDF que contém o tutorial de consumo da API, que explica passo a passo como utiliza-la.
#!/bin/bash
# ==============================
# OAUTH2 - OBTENÇÃO DO TOKEN
# ==============================
url_token="https://api.claro.com.br/oauth2/v1/token"
# Credenciais da aplicação
key="SUA_CLIENT_ID"
secret="SEU_CLIENT_SECRET"
# Geração do Basic Auth (Base64)
basic_auth=$(echo -n "$key:$secret" | base64)
# Requisição para obter o access token
token=$(curl -s -X POST "$url_token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Basic $basic_auth" \
-d "grant_type=client_credentials" | jq -r .access_token)
# ==============================
# GEOfencing - CREATE SUBSCRIPTION
# ==============================
url_geofencing="https://api.claro.com.br/mobile/v1/gsma/gateway/geofencing/subscriptions"
curl -X POST "$url_geofencing" \
-H "Authorization: Bearer $token" \
-H "X-API-Key: SUA_API_KEY" \
-H "Content-Type: application/json" \
-H "cache-control: no-cache" \
-d '{
"webhook": {
"notificationUrl": "https://application-server.com",
"notificationAuthToken": "c8974e592c2fa383d4a3960714"
},
"subscriptionDetail": {
"device": {
"phoneNumber": "+5511999999999",
"networkAccessIdentifier": "123456789@domain.com",
"ipv4Address": {
"publicAddress": "84.125.93.10",
"publicPort": 4958
},
"ipv6Address": "2001:db8:85a3:8d3:1319:8a2e:370:7344"
},
"area": {
"areaType": "CIRCLE",
"center": {
"latitude": -23.5505,
"longitude": -46.6333
},
"radius": 2000
},
"type": "org.camaraproject.geofencing.v0.area-entered"
},
"subscriptionExpireTime": "2025-08-18T14:06:15.589Z"
}'
true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Content-Type: application/x-www-form-urlencoded",
"Authorization: Basic $basicAuth"
],
CURLOPT_POSTFIELDS => "grant_type=client_credentials"
]);
$response = curl_exec($ch);
curl_close($ch);
$tokenData = json_decode($response, true);
$accessToken = $tokenData["access_token"] ?? null;
if (!$accessToken) {
die("Erro ao obter access token");
}
// ==============================
// GEOFENCING - CREATE SUBSCRIPTION
// ==============================
$geofencingUrl = "https://api.claro.com.br/mobile/v1/gsma/gateway/geofencing/subscriptions";
$payload = [
"webhook" => [
"notificationUrl" => "https://application-server.com",
"notificationAuthToken" => "c8974e592c2fa383d4a3960714"
],
"subscriptionDetail" => [
"device" => [
"phoneNumber" => "+5511999999999",
"networkAccessIdentifier" => "123456789@domain.com",
"ipv4Address" => [
"publicAddress" => "84.125.93.10",
"publicPort" => 4958
],
"ipv6Address" => "2001:db8:85a3:8d3:1319:8a2e:370:7344"
],
"area" => [
"areaType" => "CIRCLE",
"center" => [
"latitude" => -23.5505,
"longitude" => -46.6333
],
"radius" => 2000
],
"type" => "org.camaraproject.geofencing.v0.area-entered"
],
"subscriptionExpireTime" => "2025-08-18T14:06:15.589Z"
];
$ch = curl_init($geofencingUrl);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $accessToken",
"X-API-Key: SUA_API_KEY",
"Content-Type: application/json",
"cache-control: no-cache"
],
CURLOPT_POSTFIELDS => json_encode($payload)
]);
$result = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
// Resultado
echo "HTTP Status: " . $httpCode . PHP_EOL;
echo "Response: " . $result;
?>import java.io.IOException;
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.util.Base64;
public class GeofencingCreateSubscription {
// ======== CONFIG =========
private static final String TOKEN_URL = "https://api.claro.com.br/oauth2/v1/token";
private static final String GEOFENCING_URL = "https://api.claro.com.br/mobile/v1/gsma/gateway/geofencing/subscriptions";
private static final String CLIENT_ID = "SUA_CLIENT_ID";
private static final String CLIENT_SECRET = "SEU_CLIENT_SECRET";
private static final String API_KEY = "SUA_API_KEY";
public static void main(String[] args) throws IOException, InterruptedException {
HttpClient client = HttpClient.newHttpClient();
// ==============================
// OAUTH2 - OBTENÇÃO DO TOKEN
// ==============================
String basicAuth = Base64.getEncoder()
.encodeToString((CLIENT_ID + ":" + CLIENT_SECRET).getBytes(StandardCharsets.UTF_8));
String tokenBody = "grant_type=" + URLEncoder.encode("client_credentials", StandardCharsets.UTF_8);
HttpRequest tokenRequest = HttpRequest.newBuilder()
.uri(URI.create(TOKEN_URL))
.header("Content-Type", "application/x-www-form-urlencoded")
.header("Authorization", "Basic " + basicAuth)
.POST(HttpRequest.BodyPublishers.ofString(tokenBody))
.build();
HttpResponse tokenResponse = client.send(tokenRequest, HttpResponse.BodyHandlers.ofString());
String accessToken = extractJsonString(tokenResponse.body(), "access_token");
if (accessToken == null || accessToken.isBlank()) {
throw new RuntimeException("Erro ao obter access_token. Response: " + tokenResponse.body());
}
// ==============================
// GEOFENCING - CREATE SUBSCRIPTION
// ==============================
String payloadJson = """
{
"webhook": {
"notificationUrl": "https://application-server.com",
"notificationAuthToken": "c8974e592c2fa383d4a3960714"
},
"subscriptionDetail": {
"device": {
"phoneNumber": "+5511999999999",
"networkAccessIdentifier": "123456789@domain.com",
"ipv4Address": {
"publicAddress": "84.125.93.10",
"publicPort": 4958
},
"ipv6Address": "2001:db8:85a3:8d3:1319:8a2e:370:7344"
},
"area": {
"areaType": "CIRCLE",
"center": { "latitude": -23.5505, "longitude": -46.6333 },
"radius": 2000
},
"type": "org.camaraproject.geofencing.v0.area-entered"
},
"subscriptionExpireTime": "2025-08-18T14:06:15.589Z"
}
""";
HttpRequest geoRequest = HttpRequest.newBuilder()
.uri(URI.create(GEOFENCING_URL))
.header("Authorization", "Bearer " + accessToken)
.header("X-API-Key", API_KEY)
.header("Content-Type", "application/json")
.header("cache-control", "no-cache")
.POST(HttpRequest.BodyPublishers.ofString(payloadJson))
.build();
HttpResponse geoResponse = client.send(geoRequest, HttpResponse.BodyHandlers.ofString());
System.out.println("HTTP Status: " + geoResponse.statusCode());
System.out.println("Response: " + geoResponse.body());
}
// Extrator simples (sem libs) pra pegar "access_token" do JSON.
// Em produção, prefira Jackson/Gson.
private static String extractJsonString(String json, String key) {
if (json == null) return null;
String needle = "\"" + key + "\"";
int k = json.indexOf(needle);
if (k < 0) return null;
int colon = json.indexOf(":", k);
if (colon < 0) return null;
int firstQuote = json.indexOf("\"", colon + 1);
if (firstQuote < 0) return null;
int secondQuote = json.indexOf("\"", firstQuote + 1);
if (secondQuote < 0) return null;
return json.substring(firstQuote + 1, secondQuote);
}
}
#!/usr/bin/env python3
import base64
import json
import sys
import urllib.parse
import requests
# ==============================
# OAUTH2 - OBTENÇÃO DO TOKEN
# ==============================
TOKEN_URL = "https://api.claro.com.br/oauth2/v1/token"
GEOFENCING_URL = "https://api.claro.com.br/mobile/v1/gsma/gateway/geofencing/subscriptions"
CLIENT_ID = "SUA_CLIENT_ID"
CLIENT_SECRET = "SEU_CLIENT_SECRET"
API_KEY = "SUA_API_KEY"
def get_access_token() -> str:
basic = base64.b64encode(f"{CLIENT_ID}:{CLIENT_SECRET}".encode("utf-8")).decode("utf-8")
headers = {
"Content-Type": "application/x-www-form-urlencoded",
"Authorization": f"Basic {basic}",
}
data = urllib.parse.urlencode({"grant_type": "client_credentials"})
r = requests.post(TOKEN_URL, headers=headers, data=data, timeout=30)
r.raise_for_status()
payload = r.json()
token = payload.get("access_token")
if not token:
raise RuntimeError(f"access_token não veio na resposta: {payload}")
return token
def create_subscription(access_token: str) -> dict:
payload = {
"webhook": {
"notificationUrl": "https://application-server.com",
"notificationAuthToken": "c8974e592c2fa383d4a3960714"
},
"subscriptionDetail": {
"device": {
"phoneNumber": "+5511999999999",
"networkAccessIdentifier": "123456789@domain.com",
"ipv4Address": {
"publicAddress": "84.125.93.10",
"publicPort": 4958
},
"ipv6Address": "2001:db8:85a3:8d3:1319:8a2e:370:7344"
},
"area": {
"areaType": "CIRCLE",
"center": {"latitude": -23.5505, "longitude": -46.6333},
"radius": 2000
},
"type": "org.camaraproject.geofencing.v0.area-entered"
},
"subscriptionExpireTime": "2025-08-18T14:06:15.589Z"
}
headers = {
"Authorization": f"Bearer {access_token}",
"X-API-Key": API_KEY,
"Content-Type": "application/json",
"cache-control": "no-cache",
}
r = requests.post(GEOFENCING_URL, headers=headers, json=payload, timeout=30)
# Sucesso esperado: 201 Created
# Se der erro, a API deve responder com ErrorInfo (status, code, message)
try:
body = r.json() if r.text else {}
except json.JSONDecodeError:
body = {"raw": r.text}
return {"http_status": r.status_code, "response": body}
def main():
try:
token = get_access_token()
result = create_subscription(token)
print("HTTP Status:", result["http_status"])
print("Response:")
print(json.dumps(result["response"], indent=2, ensure_ascii=False))
# se não for 201, falha no exit code (útil pra pipeline)
if result["http_status"] != 201:
sys.exit(1)
except requests.HTTPError as e:
print("HTTPError:", str(e))
sys.exit(1)
except Exception as e:
print("Erro:", str(e))
sys.exit(1)
if __name__ == "__main__":
main()
Plano Pay Per Use
Contrate agora!
- A sua melhor escolha!
- Faça consultas sob demanda e pague apenas pelo o que usar.