API de revenda

Para servidores e painéis parceiros ativarem, renovarem e gerenciarem TVs com o UTM Play direto do seu sistema.

O que é

A API de revenda deixa o painel do seu servidor IPTV agir sobre as TVs dos seus clientes no UTM Play: renovar a licença de um MAC, enviar a lista (M3U) para a TV, trocar o nome do cliente e consultar aparelhos, vencimentos e créditos usados.

O acesso é por token. Cada token pertence a um servidor parceiro e é entregue pela equipe do UTM Play; ele não é criado pela API.

Endereço base

As rotas ficam em /api/… em qualquer um dos endereços abaixo; os dois respondem igual.

https://api2.utmplay.wtf
https://utmplay.wtf

Use HTTPS. Todas as rotas aceitam CORS (Access-Control-Allow-Origin: *).

Autenticação

Authorization: SEU_TOKEN

Mande o token no cabeçalho Authorization, sem prefixo. As rotas aceitam também "Bearer SEU_TOKEN", menos o get_device, que só aceita o token puro: use sempre o token puro.

O /api/login serve para conferir o token e saber o nome do servidor ligado a ele; não gera um token novo nem é obrigatório antes das outras chamadas.

Formato

Corpo dos POST em JSON (Content-Type: application/json), menos o delete_mac, que recebe o MAC na URL.
O MAC é comparado exatamente como está gravado: hexadecimal em minúsculas com dois-pontos, por exemplo 00:1a:2b:3c:4d:5e.
Respostas de sucesso trazem JSON (algumas com Content-Type text/plain, herdado da API original) ou uma frase curta em texto. Erros vêm em texto puro, uma linha, com o código HTTP do erro.
Datas de vencimento no formato AAAA-MM-DD; 9999-12-31 é vitalício.

Limites

Não há limite geral de pedidos por minuto. Use a API com moderação: lotes grandes em sequência, não em paralelo.
Código do aparelho (device_key) errado no renew: depois de 5 erros no mesmo MAC, ou 20 erros do mesmo servidor, em 1 hora, a renovação fica bloqueada por 1 hora e responde 404 "Device not found", mesmo com o código certo.
Em um token com plataformas definidas, as rotas que alteram recusam aparelhos de outras plataformas (veja abaixo).

Plataformas liberadas por token

A equipe do UTM Play pode limitar um token a algumas plataformas (por exemplo, só Samsung e LG). Sem limite definido, o token vale para todas, que é o padrão.

Com limite, as rotas que alteram o aparelho recusam o MAC cuja plataforma gravada não está na lista, antes de gravar qualquer coisa ou contar crédito: 403 com a mensagem abaixo, onde o final é a plataforma do aparelho (samsung, lg, roku, android, androidtv, firetv, ios…).

Aparelho sem plataforma gravada não é recusado. As consultas (get_device, device_expiration, count_credits, count_macs) e o login não mudam.

403

Platform not allowed for this token: roku

Rotas afetadas: renew, add_playlist, update_client_name e delete_mac.

Erros comuns a todas as rotas com token

Além dos erros de cada rota:

401Sem o cabeçalho Authorization.
```
Authorization token is required
```
403Token desconhecido.
```
Forbidden
```
405Método errado (ex.: GET numa rota POST). Corpo vazio.
500Falha interna; tente de novo mais tarde.
```
Internal Server Error
```

POST/api/loginConsulta

Confere se o token vale e devolve o nome do servidor ligado a ele. Não precisa do cabeçalho Authorization.

Parâmetros

tokenstring · JSON: Obrigatório: simO seu token.

Exemplo

curl -X POST https://api2.utmplay.wtf/api/login \
  -H 'Content-Type: application/json' \
  -d '{"token":"SEU_TOKEN"}'

Sucesso

200Token válido.

{"status":"success", "role":"client", "server":"MeuServidor"}

Erros

400Sem token, ou corpo que não é JSON.
```
Token is required
```
403Token desconhecido.
```
Invalid token or IP not allowed
```

POST/api/renewAltera o aparelho

Ativar ou renovar um MAC

Renova a licença da TV e grava no aparelho o crédito da renovação: semestral = 1, anual = 2, vitalício = 3 (o count_credits soma esse valor dos seus aparelhos). Se a licença ainda está valendo, o novo prazo conta a partir do vencimento atual; se já venceu, a partir de hoje.

Precisa do MAC e do código do aparelho (device_key, 6 dígitos mostrados na TV). O MAC precisa já existir: a TV tem de ter aberto o UTM Play pelo menos uma vez. O aparelho passa a ser do seu servidor.

Parâmetros

mac_addressstring · JSON: Obrigatório: simMAC da TV.
device_keystring · JSON: Obrigatório: simCódigo do aparelho mostrado na TV.
renew_typestring · JSON: Obrigatório: simsemi_annual (6 meses), annual (1 ano) ou lifetime (vitalício).
revenda_idint · JSON: Obrigatório: nãoIdentificador da revenda no seu sistema (número). Usado no count_credits e no get_device.
clientestring · JSON: Obrigatório: nãoNome do cliente, só ecoado na resposta.
reseller_namestring · JSON: Obrigatório: nãoAceito por compatibilidade; não é gravado.

Exemplo

curl -X POST https://api2.utmplay.wtf/api/renew \
  -H 'Authorization: SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"mac_address":"00:1a:2b:3c:4d:5e","device_key":"123456","renew_type":"annual","revenda_id":42,"cliente":"joao"}'

Sucesso

200Renovado. Aparelho atualizado.

{"id":"66f1c2a9e4b0a1b2c3d4e5f6","is_trial":1,"credit_count":2,"mac_address":"00:1a:2b:3c:4d:5e","app_type":"samsung","device_key":"123456","expire_date":"2027-10-12","revenda_id":42,"server":"MeuServidor","cliente":"joao","updated_at":"2026-10-06T00:27:49.952547665+02:00"}

Erros

400Corpo inválido: a mensagem é a do decodificador JSON, por exemplo com revenda_id em texto.
```
json: cannot unmarshal string into Go struct field .revenda_id of type int
```
400renew_type desconhecido.
```
Invalid renew_type
```

400O aparelho já é vitalício.

Renewal not allowed. Device has lifetime license.

403Plataforma do aparelho fora da lista do token.
```
Platform not allowed for this token: roku
```
404MAC inexistente, código errado ou bloqueio por códigos errados (veja Limites).
```
Device not found
```

POST/api/add_playlistAltera o aparelho

Enviar a lista para a TV

Grava a URL da lista (M3U) na TV: troca a primeira lista do aparelho ou cria uma, se não houver. O aparelho passa a ser do seu servidor; o nome do cliente é tirado do username= da URL, quando houver.

A resposta diz se a lista foi criada (InsertedID) ou trocada (MatchedCount).

Parâmetros

device_idstring · JSON: Obrigatório: simMAC da TV.
urlstring · JSON: Obrigatório: simURL da lista M3U.
revenda_idint · JSON: Obrigatório: nãoIdentificador da revenda no seu sistema (número).
reseller_namestring · JSON: Obrigatório: nãoNome da revenda, gravado junto da lista criada.

Exemplo

curl -X POST https://api2.utmplay.wtf/api/add_playlist \
  -H 'Authorization: SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"device_id":"00:1a:2b:3c:4d:5e","url":"http://exemplo.com:8080/get.php?username=joao&password=1234&type=m3u_plus&output=ts","revenda_id":42,"reseller_name":"Revenda X"}'

Sucesso

200Lista criada.

{"InsertedID":"6ac42465ca34be2c60e18662"}

200Lista existente trocada.

{"MatchedCount":1,"ModifiedCount":1,"UpsertedCount":0,"UpsertedID":null}

Erros

400Corpo inválido (mensagem do decodificador JSON, como no renew).
```
json: cannot unmarshal …
```
403Plataforma do aparelho fora da lista do token.
```
Platform not allowed for this token: roku
```
404MAC inexistente.
```
Device not found
```

GET/api/get_deviceConsulta

Listar e buscar aparelhos

Lista os aparelhos do SEU servidor, com filtros e paginação. Cada item traz o total de aparelhos que casam com o filtro (campo total). Sem nenhum resultado, a resposta é null.

Esta rota exige o token puro no Authorization (sem "Bearer").

Parâmetros

macstring · URL: Obrigatório: nãoComeço do MAC (sem diferenciar maiúsculas).
device_keystring · URL: Obrigatório: nãoComeço do código do aparelho.
clientestring · URL: Obrigatório: nãoComeço do nome do cliente.
revenda_idint · URL: Obrigatório: nãoRevenda exata.
app_typestring · URL: Obrigatório: nãoPlataforma exata (samsung, lg, roku…).
statusstring · URL: Obrigatório: nãoactive (vence depois de hoje) ou expired (vencido).
pageint · URL: Obrigatório: nãoPágina, a partir de 1 (padrão 1).
limitint · URL: Obrigatório: nãoItens por página (padrão 10).

Exemplo

curl 'https://api2.utmplay.wtf/api/get_device?mac=00:1a&status=active&page=1&limit=10' \
  -H 'Authorization: SEU_TOKEN'

Sucesso

200Aparelhos encontrados (application/json).

[{"__v":0,"_id":"66f1c2a9e4b0a1b2c3d4e5f6","app_type":"samsung","cliente":"joao","credit_count":2,"device_key":"123456","expire_date":"2027-10-12","is_trial":1,"mac_address":"00:1a:2b:3c:4d:5e","revenda_id":42,"server":"MeuServidor","total":1,"updated_at":"2026-10-06T00:27:49.952+02:00"}]

200Nenhum aparelho.
```
null
```

Erros

401Sem o cabeçalho Authorization.
```
Authorization token is required
```
401Token desconhecido ou enviado com "Bearer ".
```
Invalid token
```
404Filtro de texto inválido (caracteres especiais de expressão regular).
```
Failed to find devices
```

GET/api/device_expirationConsulta

Vencimento de um MAC

Devolve a data de vencimento da licença do aparelho.

Parâmetros

mac_addressstring · URL: Obrigatório: simMAC da TV.

Exemplo

curl 'https://api2.utmplay.wtf/api/device_expiration?mac_address=00%3A1a%3A2b%3A3c%3A4d%3A5e' \
  -H 'Authorization: SEU_TOKEN'

Sucesso

200Aparelho encontrado.
```
{"expire_date":"2027-10-12"}
```

Erros

400Sem mac_address.
```
mac_address is required
```
404MAC inexistente.
```
Device not found
```

GET/api/count_creditsConsulta

Créditos usados

Soma o crédito da última renovação de cada aparelho do seu servidor (semestral = 1, anual = 2, vitalício = 3). Sem revenda_id, um total do servidor; com revenda_id=all, um total por revenda; com um número, só aquela revenda. Sem nada para somar, a resposta é null.

Parâmetros

daysint · URL: Obrigatório: nãoSó aparelhos alterados nos últimos N dias.
revenda_idint ou "all" · URL: Obrigatório: nãoall = agrupa por revenda; número = só essa revenda.

Exemplo

curl 'https://api2.utmplay.wtf/api/count_credits?days=30&revenda_id=all' \
  -H 'Authorization: SEU_TOKEN'

Sucesso

200Sem revenda_id.

[{"_id":"MeuServidor","total_credits":2}]

200Com revenda_id=all ou um número.
```
[{"_id":42,"total_credits":2}]
```
200Nada para somar.
```
null
```

Erros

400days não é número.
```
Invalid days parameter
```
400revenda_id não é número nem all.
```
Invalid revenda_id parameter
```

GET/api/count_macsConsulta

Quantidade de aparelhos

Quantos aparelhos estão ligados ao seu servidor.

Parâmetros

Sem parâmetros.

Exemplo

curl https://api2.utmplay.wtf/api/count_macs \
  -H 'Authorization: SEU_TOKEN'

Sucesso

200Total do servidor.
```
{"mac_count":1}
```

Erros

—

POST/api/update_client_nameAltera o aparelho

Trocar o nome do cliente ou o código

Troca o nome do cliente e/ou o código do aparelho (device_key). Mande pelo menos um dos dois. Trocar o código muda o que a TV usa para ser renovada.

A resposta é a mesma quando o MAC não existe (nada é alterado).

Parâmetros

mac_addressstring · JSON: Obrigatório: simMAC da TV.
new_client_namestring · JSON: Obrigatório: nãoNovo nome do cliente.
device_keystring · JSON: Obrigatório: nãoNovo código do aparelho, só números.

Exemplo

curl -X POST https://api2.utmplay.wtf/api/update_client_name \
  -H 'Authorization: SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"mac_address":"00:1a:2b:3c:4d:5e","new_client_name":"maria"}'

Sucesso

200Pedido aceito.
```
Client details updated successfully
```

Erros

400Corpo que não é JSON.
```
Failed to parse request body
```
400device_key com algo além de números.
```
Device key must be numeric
```
400Nem new_client_name nem device_key.
```
No fields provided for update
```
403Plataforma do aparelho fora da lista do token.
```
Platform not allowed for this token: roku
```

POST/api/delete_macAltera o aparelho

Remover um MAC

Remove o aparelho do seu servidor. O MAC vai na URL (?mac=), sem corpo. Só remove aparelhos ligados ao seu servidor.

Atenção: Remover não tem volta pela API: o aparelho sai com a licença e as listas. Se a TV abrir o app de novo, ela entra como aparelho novo, sem a licença anterior, e precisa ser ativada de novo. Confira o MAC antes.

Parâmetros

macstring · URL: Obrigatório: simMAC da TV.

Exemplo

curl -X POST 'https://api2.utmplay.wtf/api/delete_mac?mac=00%3A1a%3A2b%3A3c%3A4d%3A5e' \
  -H 'Authorization: SEU_TOKEN'

Sucesso

200Removido.

Device deleted successfully, but no associated playlist found.

Erros

400Sem o parâmetro mac.
```
MAC address is required
```
403Plataforma do aparelho fora da lista do token.
```
Platform not allowed for this token: roku
```
404MAC inexistente ou de outro servidor.
```
No device or playlist found to delete
```

API de revenda

O que é

Endereço base

Autenticação

Formato

Limites

Plataformas liberadas por token

Erros comuns a todas as rotas com token

Conferir o token

Parâmetros

Exemplo

Sucesso

Erros

Ativar ou renovar um MAC

Parâmetros

Exemplo

Sucesso

Erros

Enviar a lista para a TV

Parâmetros

Exemplo

Sucesso

Erros

Listar e buscar aparelhos

Parâmetros

Exemplo

Sucesso

Erros

Vencimento de um MAC

Parâmetros

Exemplo

Sucesso

Erros

Créditos usados

Parâmetros

Exemplo

Sucesso

Erros

Quantidade de aparelhos

Parâmetros

Exemplo

Sucesso

Erros

Trocar o nome do cliente ou o código

Parâmetros

Exemplo

Sucesso

Erros

Remover um MAC

Parâmetros

Exemplo

Sucesso

Erros