STGuard
API de integração

1Visão geral

A API do STGuard permite que o seu sistema de vendas libere o acesso às suas estratégias e indicadores protegidos no momento em que a venda é aprovada, sem ninguém precisar entrar no portal.

Com ela, o seu sistema pode:

• Ativar e renovar a licença de um cliente, definindo até quando ela vale.
• Conceder a avaliação gratuita de 7 dias, uma única vez por computador.
• Consultar a situação das licenças: por estratégia, por computador ou por CPF.
• Cancelar uma licença, em caso de reembolso ou fim de assinatura.
• Listar as suas estratégias ativas.

Tudo o que a API faz também pode ser feito pela tela do portal, em portal.tradersoftware.com.br → STGuard. Os dois caminhos gravam no mesmo lugar: uma ativação feita pela API aparece na consulta da tela, e vice-versa.

Características

2Conceitos

Parceiro

É você: quem desenvolve ou distribui estratégias e indicadores protegidos pelo STGuard. Cada chave de API pertence a um cadastro de parceiro e só enxerga as estratégias desse cadastro.

Estratégia

Cada indicador ou robô protegido é uma estratégia, identificada por um número de 9 dígitos, por exemplo 700018801. O número aparece no portal, em STGuard → Estratégias → Consultar, e pode ser obtido pela rota GET /estrategias. Nos pedidos à API, a estratégia é sempre informada pelo número, nunca pelo nome.

ID do computador

A licença é presa a um computador. O computador é identificado pelo ID do computador, um código de 10 caracteres (letras e números) que aparece no STGuard instalado na máquina do cliente. Exemplo: A1B2C3D4A7.

• Os 2 últimos caracteres são um dígito verificador. Um ID digitado errado é recusado pela API com 400 id_computador_invalido, antes de gravar qualquer coisa.
• Letras minúsculas são aceitas e convertidas para maiúsculas.
• Cada computador precisa da sua própria licença. O cliente que usa a estratégia em dois computadores precisa de duas ativações, uma para cada ID.

CPF

O CPF do comprador é obrigatório na ativação e na avaliação. A API confere os dígitos verificadores, e pode ser enviado com ou sem pontuação (123.456.789-09 ou 12345678909). Ele permite consultar depois todas as licenças de um mesmo cliente.

Licença

É o direito de um computador usar uma estratégia até uma data. Para cada combinação de estratégia + computador existe uma situação atual:

• ativa — o computador pode usar a estratégia;
• vencida — passou do vencimento, ou foi cancelada.

A licença vale até o fim do dia do vencimento (23:59:59, horário de Brasília). Uma licença com vencimento 2026-12-31 funciona durante todo o dia 31 de dezembro.

Avaliação

Período gratuito de 7 dias que você pode oferecer para o cliente conhecer a estratégia. É concedida uma única vez por computador em cada estratégia (detalhes no capítulo 10).

3Primeiros passos: a chave de API

A chave identifica você na API. Ela é gerada por você mesmo, no portal, e funciona como uma senha.

Gerar a chave

1. Entre em portal.tradersoftware.com.br com o seu login de parceiro.
2. Abra o STGuard. Se você tiver mais de um cadastro de parceiro, escolha qual deles vai integrar, no botão Alterar ao lado do nome.
3. No menu à esquerda, em Integração, clique em API.
4. Clique em Gerar chave.
5. Copie a chave na hora. Ela começa com stg_ e é mostrada uma única vez. Depois disso, a tela mostra só o começo dela (por exemplo stg_6cp9pScD…), a data de criação e o último uso.
6. Guarde a chave no servidor do seu sistema de vendas, em variável de ambiente ou arquivo de configuração.

Uma chave por cadastro

Cada cadastro de parceiro tem uma chave ativa. Ao gerar uma nova, a anterior deixa de funcionar no mesmo instante. Por isso a tela pede confirmação. Gere a nova só quando estiver pronto para atualizar o seu sistema logo em seguida.

Revogar a chave

Em Revogar chave, a chave para de funcionar e nenhuma outra é criada. Use se a chave vazou ou se você vai parar de usar a integração. Para voltar, gere uma nova.

Cadastro inativo

Se o seu cadastro de parceiro for desativado, a chave para de funcionar junto: a API responde 403 parceiro_inativo até o cadastro ser reativado.

4Como fazer um pedido

Endereço

https://portal.tradersoftware.com.br/api/stguard/v1

Todas as rotas deste manual são relativas a esse endereço. A rota /ativacoes, por exemplo, é https://portal.tradersoftware.com.br/api/stguard/v1/ativacoes.

Cabeçalhos

Corpo

Os pedidos POST levam um objeto JSON de até 64 KB. Campos desconhecidos são recusados com 400 pedido_invalido. Um campo com o nome errado, por exemplo id_computer no lugar de id_computador, gera erro em vez de ser ignorado em silêncio.

Respostas

Toda resposta é JSON. O status HTTP diz se deu certo:

Datas

Sempre no formato AAAA-MM-DD (exemplo: 2026-12-31), no horário de Brasília.

5Rotas

5.1 Listar as estratégias

Devolve as suas estratégias ativas, com número e nome. Útil para conferir os números ao configurar o seu sistema.

Exemplo

curl https://portal.tradersoftware.com.br/api/stguard/v1/estrategias \
  -H "Authorization: Bearer stg_SUA_CHAVE"

Resposta — 200

{
  "estrategias": [
    { "estrategia": 700018801, "nome": "MeuIndicador" },
    { "estrategia": 700018802, "nome": "MeuRobo" }
  ]
}

Campos do corpo

Exemplo

curl -X POST https://portal.tradersoftware.com.br/api/stguard/v1/ativacoes \
  -H "Authorization: Bearer stg_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
        "estrategia": 700018801,
        "id_computador": "A1B2C3D4A7",
        "cpf": "123.456.789-09",
        "validade": "2026-12-31"
      }'

Resposta — 201

A licença como ela ficou depois da gravação (o objeto Licença, capítulo 6):

{
  "estrategia": 700018801,
  "nome": "MeuIndicador",
  "id_computador": "A1B2C3D4A7",
  "cpf": "12345678909",
  "inicio": "2026-10-08",
  "vencimento": "2026-12-31",
  "situacao": "ativa"
}

Erros possíveis

Campos do corpo

Exemplo

curl -X POST https://portal.tradersoftware.com.br/api/stguard/v1/avaliacoes \
  -H "Authorization: Bearer stg_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
        "estrategia": 700018801,
        "id_computador": "A1B2C3D4A7",
        "cpf": "12345678909",
        "unica_por_parceiro": false
      }'

Resposta — 201

{
  "estrategia": 700018801,
  "nome": "MeuIndicador",
  "id_computador": "A1B2C3D4A7",
  "cpf": "12345678909",
  "inicio": "2026-10-08",
  "vencimento": "2026-10-15",
  "situacao": "ativa"
}

Erros possíveis

Pedir de novo, no mesmo dia, a avaliação que acabou de ser concedida responde 200 com a mesma avaliação (capítulo 7). Os erros são os mesmos da ativação (exceto validade_invalida), mais:

Parâmetros (na URL)

É obrigatório informar ao menos um de estrategia, id_computador ou cpf. Os filtros se combinam.

Exemplos

# todos os clientes ativos de uma estratégia
curl "https://portal.tradersoftware.com.br/api/stguard/v1/licencas?estrategia=700018801&situacao=ativa" \
  -H "Authorization: Bearer stg_SUA_CHAVE"

# um computador numa estratégia (conferir antes de entregar)
curl "https://portal.tradersoftware.com.br/api/stguard/v1/licencas?estrategia=700018801&id_computador=A1B2C3D4A7" \
  -H "Authorization: Bearer stg_SUA_CHAVE"

# tudo de um cliente, em todas as estratégias
curl "https://portal.tradersoftware.com.br/api/stguard/v1/licencas?cpf=12345678909" \
  -H "Authorization: Bearer stg_SUA_CHAVE"

Resposta — 200

{
  "licencas": [
    {
      "estrategia": 700018801, "nome": "MeuIndicador",
      "id_computador": "A1B2C3D4A7", "cpf": "12345678909",
      "inicio": "2026-10-08", "vencimento": "2026-12-31", "situacao": "ativa"
    },
    { ... }
  ],
  "pagina": 1,
  "proxima_pagina": null
}

Lista vazia ("licencas": []) significa que nada casou com o filtro. Não é erro.

Paginação

Quando há mais de 500 linhas, proxima_pagina traz o número da página seguinte. Repita o pedido com pagina= esse número até proxima_pagina vir null.

Erros possíveis

Exemplo

curl -X DELETE https://portal.tradersoftware.com.br/api/stguard/v1/licencas/700018801/A1B2C3D4A7 \
  -H "Authorization: Bearer stg_SUA_CHAVE"

Resposta — 200

{
  "estrategia": 700018801, "nome": "MeuIndicador",
  "id_computador": "A1B2C3D4A7", "cpf": "12345678909",
  "inicio": "2026-10-08", "vencimento": "2026-10-08", "situacao": "ativa"
}

Erros possíveis

6O objeto Licença

É o que as rotas de ativação, avaliação e cancelamento devolvem, e o que vem em cada linha da consulta.

Uma linha por computador

Cada renovação grava um registro novo, mas a API sempre mostra só o que vale: o registro de maior vencimento daquele computador na estratégia. Você não precisa juntar o histórico.

7Repetir um pedido

A conexão caiu antes da resposta e você não sabe se o pedido chegou? Repita. Todo pedido é executado, e repetir não duplica nada.

Ou seja: na dúvida, repita o mesmo pedido. A resposta sempre traz a licença como ela ficou, e é ela que vale.

8Erros

Todo erro vem com o status HTTP correspondente e um corpo neste formato:

{
  "erro": {
    "codigo": "avaliacao_ja_usada",
    "mensagem": "Este ID do computador já teve avaliação ou ativação nesta estratégia."
  }
}

O seu sistema deve decidir pelo codigo, que é fixo. A mensagem é para gente ler, pode ser mostrada ao seu cliente e pode mudar de redação.

Em qualquer erro, nada foi gravado.

Tabela completa

Como tratar no seu sistema

• 4xx: não repita o mesmo pedido, porque ele vai falhar de novo. Corrija o dado ou avise o cliente. A exceção é o 429, que pede só uma espera.
• 5xx ou falta de resposta: repita o mesmo pedido, esperando um pouco mais a cada tentativa (2 s, 4 s, 8 s…).

9Limites

O limite de chamadas existe para conter erros de programação, como um laço que dispara pedidos sem parar. Uma loja com vendas normais fica muito abaixo dele. Para tarefas em lote, como renovar centenas de clientes de uma vez, espace os pedidos em pelo menos 1 segundo.

10Regras de negócio

Renovação: sempre a nova validade

Não existe "somar dias". Cada ativação informa a data até quando a licença vale. Para renovar uma assinatura mensal que vence em 31/10, ative com "validade": "2026-11-30".

• Se a nova validade é maior que a atual, a licença passa a valer até a nova data.
• Se é menor ou igual, nada é gravado (resposta 200): a licença continua até a data atual. Para encurtar, cancele e ative de novo.
• Licença vencida é reativada normalmente com a nova validade.

Avaliação: uma única vez

• A avaliação é recusada se o computador já teve qualquer registro naquela estratégia: avaliação anterior ou ativação paga, vigente ou vencida.
• Com "unica_por_parceiro": true, a regra vale para todas as suas estratégias: quem já testou ou comprou qualquer uma não ganha avaliação em outra.
• A avaliação dura 7 dias a partir de hoje. Depois, o cliente segue normalmente com uma ativação paga.
• O controle é pelo computador. Um cliente com dois computadores pode avaliar em cada um deles.

Cancelamento

• Ao cancelar, a estratégia permanece válida até a meia-noite do dia de hoje. O vencimento passa a ser a data de hoje e, a partir de amanhã, o acesso está encerrado. Até a meia-noite a consulta mostra situacao: "ativa" com o vencimento de hoje.
• Cancelar de novo, ou cancelar uma licença já vencida, não é erro: responde 200 com a licença como está. 404 licenca_nao_encontrada só para um computador que nunca teve licença na estratégia.
• Nada é apagado: o histórico continua na consulta, com situacao: "vencida" a partir de amanhã.

Computador bloqueado

Alguns computadores são bloqueados no STGuard (máquinas virtuais clonadas, por exemplo). A ativação e a avaliação desses IDs são recusadas com 403 id_bloqueado.

Quando o cliente percebe a mudança

O STGuard do cliente confere as licenças ao ser aberto e quando o cliente clica em Atualizar. Depois de uma ativação, renovação ou cancelamento, a mudança vale a partir da próxima conferência.

11Fluxos recomendados

Venda aprovada

1. Na compra, peça ao cliente o ID do computador e o CPF. Se possível, já valide o formato do ID no seu formulário: 10 caracteres, letras e números.
2. Quando o pagamento for aprovado, chame POST /ativacoes com a validade do período comprado. Se a resposta não chegar, repita o mesmo pedido.
3. Com 201, avise o cliente que a licença está liberada e que ele deve abrir o STGuard.
4. Com 400 id_computador_invalido, peça ao cliente para conferir o ID. O pagamento já está feito; só falta o dado certo.

Assinatura recorrente

1. A cada cobrança aprovada, chame POST /ativacoes com a validade do novo período.
2. Dê alguns dias de folga na validade, além do dia da próxima cobrança. Assim, um atraso de poucos dias no pagamento não tira o acesso do cliente.

Reembolso ou cancelamento da assinatura

Chame DELETE /licencas/{estrategia}/{id_computador}. A estratégia permanece válida até a meia-noite do dia de hoje. Se a política for manter o acesso até o fim do período pago, não cancele: a licença vence sozinha na data.

Teste grátis

Chame POST /avaliacoes. Com 409 avaliacao_ja_usada, ofereça a compra em vez do teste.

Cliente trocou de computador

1. Cancele a licença do computador antigo (ela permanece válida até a meia-noite de hoje).
2. Ative o computador novo com a mesma validade.

Conferir antes de entregar

Chame GET /licencas?estrategia=…&id_computador=… e entregue somente se situacao for ativa.

Conciliação periódica

Uma vez por dia ou por semana, chame GET /licencas?estrategia=…&situacao=ativa, percorrendo as páginas, e compare com as assinaturas ativas no seu sistema. Diferenças apontam ativações que faltaram ou cancelamentos esquecidos.

12Exemplos de código

Os exemplos leem a chave da variável de ambiente STGUARD_CHAVE. Nunca escreva a chave dentro do código-fonte.

PHP (cURL)

<?php
function stguard(string $metodo, string $rota, ?array $corpo = null): array
{
    $cab = [
        'Authorization: Bearer ' . getenv('STGUARD_CHAVE'),
        'Content-Type: application/json',
    ];
    $ch = curl_init('https://portal.tradersoftware.com.br/api/stguard/v1' . $rota);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST  => $metodo,
        CURLOPT_HTTPHEADER     => $cab,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 20,
    ]);
    if ($corpo !== null) {
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($corpo));
    }
    $resposta = curl_exec($ch);
    $status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    if ($resposta === false) {
        return ['status' => 0, 'dados' => null]; // sem resposta: repetir o mesmo pedido
    }
    return ['status' => $status, 'dados' => json_decode($resposta, true)];
}

// Venda aprovada
$r = stguard('POST', '/ativacoes', [
    'estrategia'    => 700018801,
    'id_computador' => 'A1B2C3D4A7',
    'cpf'           => '12345678909',
    'validade'      => '2026-12-31',
]);

if ($r['status'] === 201) {
    echo 'Liberado até ' . $r['dados']['vencimento'];
} elseif ($r['status'] >= 400 && $r['status'] < 500) {
    echo 'Recusado: ' . $r['dados']['erro']['codigo'];
} else {
    // 5xx ou sem resposta: agendar nova tentativa do mesmo pedido
}

Python (requests)

import os
import requests

BASE = "https://portal.tradersoftware.com.br/api/stguard/v1"
CAB = {"Authorization": f"Bearer {os.environ['STGUARD_CHAVE']}"}

def ativar(estrategia, id_computador, cpf, validade):
    r = requests.post(
        f"{BASE}/ativacoes",
        json={
            "estrategia": estrategia,
            "id_computador": id_computador,
            "cpf": cpf,
            "validade": validade,
        },
        headers=CAB,
        timeout=20,
    )
    if r.status_code == 201:
        return r.json()
    if 400 <= r.status_code < 500:
        raise ValueError(r.json()["erro"]["codigo"])
    r.raise_for_status()  # 5xx: tentar de novo o mesmo pedido

def ativos(estrategia):
    """Todos os clientes ativos de uma estratégia, percorrendo as páginas."""
    pagina, todos = 1, []
    while pagina:
        r = requests.get(
            f"{BASE}/licencas",
            params={"estrategia": estrategia, "situacao": "ativa", "pagina": pagina},
            headers=CAB,
            timeout=20,
        )
        r.raise_for_status()
        dados = r.json()
        todos += dados["licencas"]
        pagina = dados["proxima_pagina"]
    return todos

JavaScript (Node.js 18 ou mais novo)

const BASE = 'https://portal.tradersoftware.com.br/api/stguard/v1';

async function stguard(metodo, rota, corpo) {
  const cabecalhos = {
    Authorization: `Bearer ${process.env.STGUARD_CHAVE}`,
    'Content-Type': 'application/json',
  };
  const r = await fetch(BASE + rota, {
    method: metodo,
    headers: cabecalhos,
    body: corpo ? JSON.stringify(corpo) : undefined,
  });
  return { status: r.status, dados: await r.json() };
}

// Teste grátis
const r = await stguard('POST', '/avaliacoes', {
  estrategia: 700018801,
  id_computador: 'A1B2C3D4A7',
  cpf: '12345678909',
});

if (r.status === 201) console.log('Avaliação até', r.dados.vencimento);
else if (r.dados.erro?.codigo === 'avaliacao_ja_usada') console.log('Ofereça a compra');

// Cancelamento
await stguard('DELETE', '/licencas/700018801/A1B2C3D4A7');

13O que o seu cliente precisa fazer

Do lado do comprador, o processo é sempre o mesmo, seja indicador ou robô. Você pode copiar estes passos para a sua página de vendas.

1. Instalar o STGuard: https://www.tradersoftware.com.br/downloads/STGuardSetup.exe
2. Abrir o STGuard e copiar o ID do computador que aparece na tela.
3. Informar esse ID na compra, junto com o CPF.
4. Depois da liberação, abrir o STGuard (ou clicar em Atualizar, se ele já estiver aberto). A estratégia é baixada e instalada automaticamente na Plataforma.

Bom saber

• O cliente não recebe arquivo nenhum de você: a estratégia chega pelo STGuard.
• O STGuard se atualiza sozinho. O cliente não precisa reinstalar a cada versão.
• Quando você publica uma versão nova da estratégia no portal, os clientes recebem na próxima vez que abrirem o STGuard.
• Para usar em outro computador, o cliente precisa de outra ativação, com o ID daquele computador.

14Testes, segurança e suporte

Como testar a integração

Não há ambiente separado de testes: a API é sempre a de produção. Para testar sem afetar clientes:

1. Instale o STGuard no seu computador e use o seu próprio ID.
2. Ative com uma validade curta, como a de hoje.
3. Confira com GET /licencas e abrindo o STGuard.
4. Cancele com DELETE ao terminar.

Para testar a avaliação, lembre que ela só é concedida uma vez por computador em cada estratégia. Teste numa estratégia que o seu computador ainda não usou.

Segurança

• Chame a API somente do seu servidor. Nunca coloque a chave em página web, aplicativo, JavaScript do navegador ou planilha compartilhada: quem tiver a chave pode ativar e cancelar licenças em seu nome.
• Guarde a chave em variável de ambiente ou em arquivo de configuração fora do controle de versão.
• Se suspeitar de vazamento, gere uma nova chave no portal. A anterior para de funcionar na hora.
• A tela do portal mostra quando a chave foi usada pela última vez. Uso inesperado é sinal de vazamento.
• Todas as operações de gravação feitas pela API ficam registradas com a chave que as fez.

Suporte

Em caso de dúvida ou problema na integração, fale com a Trader Software pelos canais em www.tradersoftware.com.br/contato. Para agilizar, informe:

• o seu número de parceiro;
• a rota, o horário e o status HTTP da resposta;
• o codigo do erro;
• o começo da chave (os caracteres que a tela mostra), nunca a chave inteira.

AReferência rápida

Base:          https://portal.tradersoftware.com.br/api/stguard/v1
Autenticação:  Authorization: Bearer stg_SUA_CHAVE
Repetição:     segura — todo pedido é executado e não duplica nada

GET     /estrategias
POST    /ativacoes        {estrategia, id_computador, cpf, validade}          → 201
POST    /avaliacoes       {estrategia, id_computador, cpf, unica_por_parceiro} → 201
GET     /licencas?estrategia=&id_computador=&cpf=&situacao=&pagina=
DELETE  /licencas/{estrategia}/{id_computador}

Licença:  {estrategia, nome, id_computador, cpf, inicio, vencimento, situacao}
Erro:     {"erro": {"codigo": "...", "mensagem": "..."}}
Datas:    AAAA-MM-DD, horário de Brasília; vale até o fim do dia do vencimento
Limite:   60 chamadas por minuto por chave (429 + Retry-After)

Códigos de erro