Integração da API do IoT Connect
Este artigo explica como começar a integrar as APIs da Transatel para gerenciar sua oferta IoT
Connect.
Resumimos as APIs necessárias e recomendadas, com os links no Transatel Developer Portal e as
referências das APIs.
Quais APIs você deve integrar?
A Transatel oferece várias APIs, mas você pode começar com apenas algumas chamadas principais.
APIs obrigatórias:
- Autenticação
Use esta API para obter tokens de acesso.
- API de Gerenciamento de Conectividade
Estas são as APIs mais importantes — elas permitem:
- ativar SIMs,
- modificar serviços (chamados “opções”) das suas SIMs,
- suspender ou terminar SIMs,
- preencher campos de informação como Referência ou Grupos para organizar sua frota,
- consultar as informações de serviços de uma SIM específica.
Nota importante: Os bundles agrupados (Pooled Bundles) e o modo Pay-Per-Use das ofertas IoT Connect
são Rate Plans gerenciados via APIs de Gerenciamento de Conectividade.
Os serviços aplicados às SIMs são opções também gerenciadas e modificadas via essas APIs.
Por exemplo, aqui está uma chamada para bloquear SMS:
Ela inclui o rate plan para identificar a oferta e a opção para bloquear todos os SMS de saída:
APIs recomendadas:
- Webhooks
Use esta API para registrar um endpoint e receber eventos de webhook.
Como muitas ações são assíncronas (ex: ativação de SIM pode levar alguns minutos após a chamada da
API), os webhooks permitem acompanhar quando uma operação foi concluída.
Os eventos disponíveis para IoT Connect relacionados à conectividade estão detalhados aqui.
APIs opcionais
- Se você utiliza eSIMs para consumidor, pode integrar também a API de Gerenciamento de SIM.
Nesta API, normalmente você precisará apenas da chamada "Get eSIM details".
Ela permite:
* recuperar o código de ativação, o link para download do QR Code e o status do eSIM,
* consultar o status do eSIM no dispositivo — útil para suporte e troubleshooting.
As APIs para “Reservar” e “Liberar” perfis não se aplicam à oferta IoT Connect, pois os perfis já são
reservados e liberados automaticamente.
- APIs de Diagnóstico
Se você quiser integrar APIs de Network Attach ou Data Session para replicar funcionalidades do
portal, pode utilizar essas APIs.
Observação: essas APIs são apenas para consultas unitárias — não podem ser usadas para extrair dados
de toda a sua frota de forma automatizada.
Para evitar isso, aplicamos limites de taxa (rate limit) mais altos e controlados.
Sobre APIs OCS
Nossas ofertas genéricas IoT Connect não utilizam o Online Charging System (OCS). Portanto, APIs OCS
não são compatíveis e não podem ser utilizadas.
Como encontrar as opções específicas do seu serviço para
as chamadas de API?
Todos os valores das opções podem ser encontrados no menu Catalogue > Options da plataforma de
gerenciamento de SIMs.
Lá você encontrará os nomes técnicos das opções da oferta para incluir nas suas chamadas de API.
Se você tiver vários rate plans (por exemplo, diferentes bundles agrupados) disponíveis no
contrato, eles aparecerão em uma lista suspensa:
Exemplo de opções para uma oferta IoT genérica:
Esses são os mesmos valores usados para criar e modificar Service Profiles na interface.
A chamada de API para ativar uma SIM contém as mesmas informações de um Service Profile:
- o Rate Plan (ligado à oferta),
- o valor de cada opção.
Observação: atualmente os Service Profiles não podem ser usados diretamente via API, mas você
pode recriar qualquer configuração usando as opções na API de Gerenciamento de Conectividade.
Algumas opções possuem múltiplas escolhas — apenas uma pode ser selecionada. Na interface, elas
aparecem como listas suspensas.
Exemplo: para “SMS de Saída”, você pode escolher: “Ativado”, “Desativado” ou “Ativado apenas para
SMS on-net”:
Cada opção possui um valor padrão — se você não informar um valor na chamada, será aplicado o
valor padrão. No exemplo de SMS, o padrão é “Ativado”.
