Nome da tab
Apresentação
Título
O que é?
Text

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).

Ícone
Título
Fácil Integração
Text

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.

Ícone
Título
Aumento de Segurança
Text

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.

Ícone
Título
Principais ganhos
Text

• 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!

Título
Dúvidas frequentes

Como funciona a cobrança da API Geofencing?

Será cobrado um custo por cerca criada, e o adicional de cada linha móvel cadastrada dentro da cerca.

Como é feita a integração?

A integração é feita por meio de API e toda a documentação está disponível aqui no portal! 

Quando a API Geofencing envia notificações?

Sempre que um evento de entrada ou saída da cerca ocorrer.

Posso monitorar dispositivos de pessoas físicas nessa API?

Não, a API apenas valida dispositivos M2M.

Com que frequência o dado é atualizado?

Diariamente.

Título
Documentação
Text

Nome da tab
Documentação
Título
API Geofencing Subscriptions
Text

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.

Título
Passo a passo
Text

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.

Título
CURL
Text
#!/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"
  }'
Título
PHP
Text
 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;
?>
Título
JAVA
Text
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);
  }
}
Título
PYTHON
Text
#!/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.
A melhor escolha para o seu negócio. Após testar nossa trial, você passa a cons…