generated: '2026-07-25'
method: searched
source: >-
  https://api.claro.com.br/docs (Claro's published HTTP status-code contract for
  every API on the gateway), the Claro Insight product pages and their code
  samples, and the two harvested OpenAPI documents.
description: >-
  How the Claro Brasil API estate behaves across operations. There is no single
  written developer guide — these conventions are reconstructed from the
  gateway's own published status-code contract, the per-product documentation
  tabs, and the sample code. The estate is split into two generations that do
  NOT share conventions: the 2019-vintage "customers" services and the
  2023-2025 GSMA Open Gateway / CAMARA services.

base_urls:
  production: https://api.claro.com.br
  sandbox: https://api-sandbox.claro.com.br
  on_premises: [https://cas.apigw.claro.com.br, https://lpa.apigw.claro.com.br]
api_style: REST over HTTPS, JSON request and response bodies

generations:
- name: Legacy customers services (2019)
  path_prefix: /customers/v1, /customers/v2
  request_envelope: '{"data": {"customer": { ... }}}'
  auth_header: 'x-client-auth: Bearer <access_token>'
  tenant_header: 'X-CustomerID: <partner id>'
  examples: [Claro Alerta, Claro Score, Claro Valida Telefone, Claro Valida Endereço 2.0]
- name: GSMA Open Gateway / CAMARA services (2023-2025)
  path_prefix: /mobile/v1/gsma/gateway/, /gsma/gateway/, /number-recycling/v0.1/
  request_envelope: flat CAMARA payload (phoneNumber, device, area, ...)
  auth_header: 'Authorization: Bearer <access_token>'
  note: >-
    Tenure is the exception — it is CAMARA-named but still uses the legacy
    x-client-auth header and a data{} envelope, evidence of an estate mid-migration.
  examples: [SIM Swap, KYC Match, KYC Fill In, Device Location Retrieval, Geofencing, Number Recycling, Tenure]

authentication:
  scheme: OAuth 2.0 client credentials
  token_endpoint: https://api.claro.com.br/oauth2/v1/token
  token_request: POST application/x-www-form-urlencoded, grant_type=client_credentials
  client_credential_transport: HTTP Basic base64(client_id:client_secret), sent either as Authorization or x-client-auth
  additional_schemes: [HTTP Basic, HTTP Bearer, 'apiKey header X-API-Key']
  three_legged: >-
    None. Neither harvested spec nor any product page documents CIBA, an
    authorization endpoint or any subject-consent flow, even where the product
    copy states that LGPD consent is mandatory (Device Location Verify).
  detail: authentication/america-movil-authentication.yml

idempotency:
  supported: false
  evidence: >-
    No Idempotency-Key header, no idempotency parameter and no replay semantics
    appear in either harvested OpenAPI, in the gateway status-code contract, or
    in any published sample. The estate is dominated by read/verify POSTs, and
    the one creating operation (Geofencing subscriptions) documents no
    idempotency key.

pagination:
  supported: false
  evidence: Every published operation returns a single object; no list endpoints, cursors or page parameters are documented.

versioning:
  schemes:
  - name: gateway document version
    format: '<major>;<yyyy-mm-dd>'
    examples: ['1;2023-06-30', '1;2019-11-06', '1;2019-08-02']
    surfaced_in: OpenAPI info.version AND the apiVersion field of every response body
  - name: CAMARA semantic version
    format: '<major>.<minor>.<patch>'
    examples: ['0.4.0', '0.3.1', '0.2.1', '0.1.0']
  - name: URI path version
    examples: ['/customers/v1', '/customers/v2', '/mobile/v1', '/number-recycling/v0.1']
  detail: lifecycle/america-movil-lifecycle.yml

request_tracing:
  response_field: transactionId
  description: >-
    Every gateway response body carries a transactionId generated by the API
    ("Transaction's tracking identification generated by API") alongside
    apiVersion. There is no documented request-id request header.
  example: Id-34fcb05c6d1923e35cef248d

error_envelope:
  rfc9457: false
  gateway_shape: '{ "apiVersion", "transactionId", "error": { "httpCode", "message", "errorCode", "detailedMessage", "link": { "rel", "href" } } }'
  camara_shape: '{ "status", "code", "message" }'
  error_code_format: 'API-<PROXY NAME>-<HTTP code or NNN>, e.g. API-LBSDEVICESLOCATIONS-422'
  documentation_link: >-
    The error object carries a link.href back to https://api.claro.com.br/docs,
    the published status-code contract.
  detail: errors/america-movil-problem-types.yml
  registry: errors/america-movil-error-codes.yml

rate_limits:
  signal_status: 429
  meaning: >-
    "Identifica que o cliente excedeu a política de requisições adquirida, ou uma
    política de segurança de DDOS foi acionada" — the contracted request policy
    was exceeded, or a DDoS protection rule fired. The LBS API additionally
    documents 429 as "The maximum request limit for this MSISDN has been exceeded".
  headers_documented: false
  detail: rate-limits/america-movil-rate-limits.yml

other_conventions:
- name: Retirement signal
  detail: >-
    HTTP 410 Gone is reserved for retired APIs and retired versions
    ("Deve ser utilizado para API e versões aposentadas"), directing the caller
    to a newer API or version. This is Claro's only published deprecation signal;
    there is no Sunset/Deprecation header (RFC 8594) and no dated policy.
- name: Legal/geographic refusal
  detail: HTTP 451 is used when geolocation, legal or regulatory restrictions block access.
- name: Asynchronous acknowledgement
  detail: 202 Accepted marks the asynchronous variants of POST/PATCH/PUT/DELETE; 200/201/204 mark the synchronous ones.
- name: Billing semantics
  detail: >-
    Billing is per successful query: a call counts once at least one supplied
    field is resolved to true/false. Geofencing bills per fence plus per mobile
    line inside the fence. Published on every product page FAQ.
- name: Data freshness
  detail: Subscriber attributes behind the KYC/identity products are refreshed daily ("Com que frequência o dado é atualizado? Diariamente").
- name: LGPD consent
  detail: >-
    Device Location Verify states that subject consent is mandatory under LGPD,
    but no technical consent mechanism (three-legged OAuth, CIBA) is published —
    consent is contractual, not protocol-enforced.