Developers API

Voltar ao App

Referencia da API

API REST do Rally de Vendas. Integre extensoes, CRMs, checkouts e automacoes. Todos os endpoints retornam JSON com charset UTF-8.

https://rallydevendas.com.br/

Formato

JSON (sempre)

Encoding

UTF-8

Versao

Autenticacao

O sistema usa dois tipos de autenticacao, dependendo do grupo de endpoints:

Extension Token (Chrome Extension)

Obtido via POST /api/ext/auth com email + senha. Token de 64 caracteres, validade de 30 dias. Um token por usuario (login novo revoga o anterior).

Authorization: Bearer <extension_token_64_chars>

API Key (Admin / Integracao)

Gerada no painel Admin em /admin/webhooks. Suporta escopos (write, webhook_receive, admin), IP whitelist e rate limit por token.

Authorization: Bearer <api_key_gerada_no_admin>

Sem Auth (Endpoints Publicos)

Os endpoints de leitura publica (/api/v1/planos, /api/v1/professores, /api/v1/meets, /api/v1/contexto, /api/v1/schema) nao requerem autenticacao.

Rate Limit & CORS

Rate Limiting

Limite: 60 requisicoes por janela de 60 segundos
Escopo: Por token (API Key) / Por IP
Storage: Arquivo local (file-based)
Excedido: HTTP 429 Too Many Requests

CORS

Extension: chrome-extension:// origins permitidos
Dominio: rallydevendas.com.br permitido
API v1: * (publico, para LLMs)
Methods: GET, POST, OPTIONS
Headers: Authorization, Content-Type

Codigos de Erro

Codigo	Significado	Quando
200	OK	Sucesso
201	Created	Recurso criado (ex: novo aluno)
401	Unauthorized	Token ausente, invalido ou expirado
404	Not Found	Recurso nao encontrado
409	Conflict	Recurso ja existe (ex: email duplicado)
422	Unprocessable	Validacao falhou (campos obrigatorios)
429	Too Many Requests	Rate limit excedido

POST

/api/ext/auth

EXTENSION

Autentica o usuario da extensao Chrome. Retorna um token Bearer de 64 caracteres com validade de 30 dias. Login novo revoga o token anterior do mesmo usuario.

Body Params (JSON)

email Requerido
E-mail de login do usuario.
senha Requerido
Senha da conta.

Resposta

ok — boolean
token — string (64 chars, usar em Authorization)
tem_acesso — boolean (permissao para extensao)
user — { id, nome, role, foto }
whatsapp_upgrade — string|null (link WA se sem acesso)

Exemplo Request

curl -X POST https://rallydevendas.com.br/api/ext/auth \
-H "Content-Type: application/json" \
-d '{
    "email": "piloto@email.com",
    "senha": "minha_senha_123"
}'

Exemplo Response (200)

{
    "ok": true,
    "token": "a1b2c3d4...64_chars",
    "tem_acesso": true,
    "user": {
        "id": "user_abc123",
        "nome": "Joao Piloto",
        "role": "pro",
        "foto": ""
    },
    "whatsapp_upgrade": null
}

GET

/api/ext/me

EXTENSION

Dashboard completo do usuario. Retorna dados do Rally, contas ML vinculadas, meets proximos, notificacoes e permissoes efetivas da extensao.

Requer: Authorization: Bearer <token>

Campos da Resposta

ok — boolean
tem_acesso — boolean
user — { id, nome, role, foto }
permissoes — Objeto com flags booleanos:
- extensao_chrome, ml_analisar, ml_tendencias,
- ml_raio_x, ml_calculadora, ml_clonar, fotos_ia
rally — { checkin_hoje, streak, lap, ultimo_checkin, dias_sem_check }
ml.contas[] — Array de contas ML (ml_user_id, nickname, token_ok, anuncios, reputacao, vendas_hoje, gmv_30d...)
ml.notificacoes[] — Ultimas 15 notificacoes nao lidas
ml.vendas_hoje — Total de vendas (hoje)
ml.total_reclam — Reclamacoes abertas
meets[] — Meets nas proximas 48h (titulo, data_hora, link, minutos_restantes)

Exemplo Response (200)

{
    "ok": true,
    "tem_acesso": true,
    "user": { "id": "user_abc", "nome": "Joao", "role": "pro", "foto": "" },
    "permissoes": {
        "extensao_chrome": true,
        "ml_analisar": true,
        "ml_tendencias": true,
        "ml_raio_x": true,
        "ml_calculadora": true,
        "ml_clonar": false,
        "fotos_ia": true
    },
    "rally": {
        "checkin_hoje": true,
        "streak": 12,
        "lap": 1,
        "ultimo_checkin": "2026-03-28",
        "dias_sem_check": 0
    },
    "ml": {
        "contas": [{
            "ml_user_id": "123456789",
            "nickname": "MINHA_LOJA",
            "token_ok": true,
            "anuncios": 47,
            "reputacao": "5_green",
            "vendas_hoje": 3,
            "gmv_30d": 12500.00
        }],
        "notificacoes": [],
        "total_notifs": 0,
        "vendas_hoje": 3,
        "total_reclam": 0
    },
    "meets": [{
        "titulo": "Mentoria ao Vivo",
        "data_hora": "2026-03-28 20:00:00",
        "link": "https://meet.google.com/...",
        "minutos_restantes": 120
    }]
}

POST

/api/ext/logout

EXTENSION

Invalida o token da extensao. Apos esta chamada, o token nao podera mais ser usado.

Requer: Authorization: Bearer <token>

Body

Nenhum body necessario. O token e identificado pelo header Authorization.

Resposta

ok — true (sempre, mesmo se token ja estava expirado)

Exemplo Request

curl -X POST https://rallydevendas.com.br/api/ext/logout \
-H "Authorization: Bearer a1b2c3d4...token"

GET

/api/ext/ml/check

EXTENSION

Verifica se uma conta do Mercado Livre esta vinculada ao usuario logado. Util para a extensao detectar se o vendedor do anuncio e o proprio usuario.

Requer: Authorization: Bearer <token>

Query Params

seller_id Opcional
ID numerico do vendedor ML.
nickname Opcional
Nickname da loja ML (case-insensitive).

Informe ao menos um dos dois parametros.

Resposta

ok — true
vinculada — boolean (conta encontrada no cadastro do user)
conta — Dados da conta (ml_user_id, nickname, token_ok, anuncios, reputacao, reclamacoes, erro) ou null
total_contas — Numero total de contas ML do usuario

Exemplo Request

curl -G "https://rallydevendas.com.br/api/ext/ml/check" \
  --data-urlencode "seller_id=123456789" \
  --data-urlencode "nickname=MINHA_LOJA" \
  -H "Authorization: Bearer a1b2c3...token"

Exemplo Response (200)

{
    "ok": true,
    "vinculada": true,
    "conta": {
        "ml_user_id": "123456789",
        "nickname": "MINHA_LOJA",
        "token_ok": true,
        "sincronizado_em": "2026-03-28 14:30:00",
        "anuncios": 47,
        "reputacao": "5_green",
        "reclamacoes": 0,
        "erro": null
    },
    "total_contas": 2
}

POST

/ml/notificacoes

WEBHOOK

Receptor de notificacoes do Mercado Livre (webhook). Valida a assinatura HMAC SHA256 usando o header X-Signature e o parametro ts do manifesto. Processa vendas, reclamacoes, alteracoes de itens e perguntas.

Seguranca HMAC

A assinatura e validada usando hash_hmac('sha256', manifest, client_secret) onde o manifesto inclui id:{data_id};request-id:{x_request_id};ts:{timestamp};. Requisicoes com assinatura invalida recebem HTTP 401.

Headers Recebidos do ML

X-Signature — ts=...;v1=hash_hex
X-Request-Id — UUID do request ML

Topicos Processados

orders_v2 — Nova venda (registra, notifica, atualiza GMV)
claims — Reclamacao (atualiza total, cria notif)
items — Item alterado (atualiza total anuncios)
questions — Pergunta nova (notifica WhatsApp)

Payload Exemplo (ML envia)

{
    "resource": "/orders/1234567890",
    "user_id": 123456789,
    "topic": "orders_v2",
    "application_id": 99999999,
    "attempts": 1,
    "sent": "2026-03-28T14:30:00.000-03:00",
    "received": "2026-03-28T14:30:00.000-03:00"
}

Response (200 — imediato)

{
    "success": true,
    "message": "Notificacao recebida e processada",
    "data": { "status": "received" }
}

GET

/api/v1/cron

CRON

Trigger HTTP para o cron do sistema. Substitui crontab CLI. Executa notificacoes de meets, alertas de inatividade, processamento de fila WhatsApp, sync ML e archival de logs.

Requer: ?token=CRON_SECRET ou Authorization: Bearer CRON_SECRET

Query Params

token Requerido
Token secreto configurado em config/app.php → cron_secret.

Tarefas Executadas

1. Lembretes de Meet (5min e 24h antes)
2. Alertas de inatividade (+3 dias)
3. Rally: lembrete 20h + dia furado
4. Fila WhatsApp (processa pendentes)
5. Sync vendas ML (alunos + agencia)
6. Sync snapshot agencia (lote de 5)
7. Checkup contas ML agencia (cada 6h)
8. Archival de logs (+90 dias, 1x/dia)

Exemplo Request

curl "https://rallydevendas.com.br/api/v1/cron?token=SEU_CRON_SECRET"

Exemplo Response (200)

{
    "ok": true,
    "ts": "2026-03-28 14:30:00",
    "meets_notif": 2,
    "inativos": 0,
    "alertas_20h": 3,
    "furados": 0,
    "wa_enviados": 5,
    "wa_erros": 0,
    "wa_ignorados": 1,
    "ml_sync": { "contas": 12, "vendas_novas": 4, "erros": 0 },
    "agencia_sync": { "sincronizados": 5, "erros": 0 },
    "checkup_agencia": { "verificados": 3, "prontos": 2, "pendentes": 1 },
    "log_archival": { "skipped": true },
    "ms": 2340
}

POST

/api/v1/alunos/criar

API KEY: write

Cria um novo aluno (piloto) na base. Se o e-mail ja existir, retorna 409 Conflict. Uma senha aleatoria e gerada automaticamente. Se WhatsApp for informado, enfileira mensagem de boas-vindas.

Requer: API Key com escopo write

Body Params (JSON)

nome Requerido
Nome completo do comprador.
email Requerido
E-mail unico de acesso.
plano Opcional
Role de permissao: free, pro, vip, piloto_pro, podio. Padrao: free.
whatsapp Opcional
Numero com DDI+DDD (apenas numeros). Ex: 5511999999999.

Exemplo Request

curl -X POST https://rallydevendas.com.br/api/v1/alunos/criar \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{
    "nome": "Joao Piloto",
    "email": "joao@email.com",
    "whatsapp": "5511999999999",
    "plano": "pro"
}'

Response (201 Created)

{
    "success": true,
    "message": "Aluno criado com sucesso.",
    "data": {
        "id": "user_abc123",
        "email": "joao@email.com",
        "plano": "pro"
    }
}

POST

/api/v1/alunos/suspender

API KEY: write

Revoga o acesso do aluno ao sistema. Ideal para automacoes de inadimplencia, chargeback ou cancelamento de assinatura.

Requer: API Key com escopo write

Body Params (JSON)

email Requerido
E-mail do aluno a ser suspenso.

Exemplo Request

curl -X POST https://rallydevendas.com.br/api/v1/alunos/suspender \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{
    "email": "joao@email.com"
}'

Response (200)

{
    "success": true,
    "message": "Aluno suspenso.",
    "data": {
        "id": "user_abc123",
        "email": "joao@email.com"
    }
}

POST

/api/v1/webhook/hotmart

WEBHOOK

Recebe disparos diretos da Hotmart (Aprovado, Cancelado, Atrasado) e gerencia o aluno automaticamente com base no payload padrao da plataforma.

Dica de Configuracao

No painel da Hotmart, cadastre a URL https://rallydevendas.com.br/api/v1/webhook/hotmart e configure o Hottok para seguranca extra.

Body

Payload padrao Hotmart. O sistema le o campo event ou data.purchase.status para determinar a acao.

Response (200)

{
    "success": true,
    "message": "Webhook recebido.",
    "data": { "event": "PURCHASE_APPROVED" }
}

POST

/api/v1/webhook/llm

API KEY: webhook_receive

Endpoint bidirecional para LLMs externas (GPT, Claude, Gemini). Recebe um action no body e despacha para o handler correspondente.

Requer: API Key com escopo webhook_receive

Body Params (JSON)

action Requerido
Acao a executar.

Acoes Disponiveis

get_planos — Retorna planos ativos
get_meets — Retorna proximas mentorias
get_contexto — Retorna contexto completo

Exemplo Request

curl -X POST https://rallydevendas.com.br/api/v1/webhook/llm \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "action": "get_planos" }'

GET

/api/v1/contexto

PUBLICO

Contexto completo da plataforma otimizado para injecao em system prompts de LLMs. Inclui dados da plataforma, estatisticas, planos, professores, proximas mentorias e instrucoes de uso para IA.

Exemplo Request

curl https://rallydevendas.com.br/api/v1/contexto

GET

/api/v1/planos

PUBLICO

Retorna todos os planos ativos com titulo, identificador, preco, beneficios e link de checkout.

Exemplo Request

curl https://rallydevendas.com.br/api/v1/planos

GET

/api/v1/professores

PUBLICO

Retorna a lista de professores com nome, total de aulas, foto e redes sociais.

Exemplo Request

curl https://rallydevendas.com.br/api/v1/professores

GET

/api/v1/meets

PUBLICO

Retorna as proximas 10 mentorias ao vivo agendadas, ordenadas por data.

Exemplo Request

curl https://rallydevendas.com.br/api/v1/meets

GET

/api/v1/schema

PUBLICO

Estrutura do banco de dados JSON para contexto de LLMs. Lista todas as tabelas com seus campos, tipos e roles disponiveis.

Exemplo Request

curl https://rallydevendas.com.br/api/v1/schema

Rotas Internas

Endpoints autenticados por sessao (cookie). Usados pelo front-end da plataforma. Documentados aqui para referencia de desenvolvedores.

Estes endpoints requerem login ativo na plataforma (sessao PHP). Nao sao acessiveis via API Key ou Extension Token.

ADMIN

admin/gamificacao/*

12 ENDPOINTS

Painel administrativo de gamificacao. Gerencia milestones (M1-M20), tabelas de XP, desafios sazonais e recalculo de rankings. Controller: AdminGamificacaoController.

GET Endpoints

admin/gamificacao
Painel principal — visao geral de milestones, XP, desafios e rankings.
admin/gamificacao/migrar
Inicializa estrutura de gamificacao para todos os alunos que ainda nao possuem.
admin/gamificacao/status
JSON com status de migracao (total users, migrados, pendentes).
admin/gamificacao/desafios-json
Lista todos os desafios sazonais ativos e expirados em JSON.

POST Endpoints

admin/gamificacao/editar-xp
Altera tabela de XP por acao (checkin, venda, aula, etc.).
admin/gamificacao/editar-milestone
Edita milestone (titulo, XP necessario, badge, recompensa).
admin/gamificacao/recalcular
Recalcula XP e nivel de todos os alunos com base no historico.
admin/gamificacao/desafio/salvar
Cria ou atualiza desafio sazonal (titulo, meta, periodo, recompensa).
admin/gamificacao/desafio/excluir
Remove desafio sazonal por ID.
admin/gamificacao/config/salvar
Salva configuracao geral da gamificacao (multiplicadores, limites).

ALUNO

painel/competicao/*

2 ENDPOINTS

Tela de competicao do aluno com ranking geral, milestones atingidos, desafios sazonais ativos e progresso de XP. Controller: RankingController.

GET Endpoints

painel/competicao
View principal — ranking, milestones M1-M20, nivel do aluno, desafios sazonais ativos.
painel/competicao/ranking-json
JSON com ranking paginado (posicao, nome, nivel, XP, badge). Suporta filtro por tipo de ranking.

GET

painel/ml/calculadora/taxas-json

ALUNO

Retorna as taxas reais do Mercado Livre para calculo de margem. Inclui comissao por categoria, taxa fixa por tipo de anuncio, custo de frete, reputacao e aliquota de imposto. Controller: MlCalculadoraController.

Query Params

conta — ID da conta ML para buscar reputacao e taxas personalizadas.
categoria — ID da categoria ML para comissao especifica (opcional).

Campos da Resposta

comissao_classico, comissao_premium — % por tipo de anuncio
taxa_fixa — Valor fixo por venda (BRL)
reputacao — Nivel de reputacao e desconto aplicavel
imposto — Aliquota estimada (MEI, Simples, etc.)

GET

painel/ml/etiqueta

ALUNO

Proxy para download de etiqueta de postagem (PDF) direto do Mercado Livre. Evita exposicao do access token ao front-end. Tambem disponivel em admin/agencia/etiqueta para contas da agencia. Controller: MercadoLivreController.

Query Params

shipment_id Requerido
ID do envio no Mercado Livre.
conta Requerido
ID da conta ML (ml_user_id) proprietaria do envio.

Resposta

Retorna diretamente o PDF da etiqueta com Content-Type: application/pdf. Em caso de erro, retorna texto plano com a mensagem.

AGENCIA

admin/agencia/central-perguntas/*

3 ENDPOINTS

Central unificada de perguntas de compradores para todos os clientes da agencia. Permite visualizar, filtrar e responder perguntas sem sair do painel. Controller: AgenciaPerguntasController.

GET Endpoints

admin/agencia/central-perguntas
View principal — fila de perguntas de todos os clientes, filtros por cliente e status.
admin/agencia/central-perguntas/json
JSON paginado com todas as perguntas pendentes e respondidas.

POST Endpoints

admin/agencia/central-perguntas/responder
Envia resposta a uma pergunta via API ML. Body: question_id, answer, conta.

POST

admin/agencia/ml/sincronizar-todos

ADMIN

Dispara sincronizacao completa de todas as contas ML da agencia. Atualiza anuncios, vendas, reputacao e snapshot de cada cliente. Usa processamento escalonado (5 clientes por ciclo) para evitar rate limit do ML. Controller: AgenciaController.

Body

Nenhum body necessario. A sessao identifica o admin autenticado.

Resposta

ok — boolean
sincronizados — Numero de clientes processados neste ciclo
erros — Numero de erros encontrados
pendentes — Clientes que serao processados no proximo ciclo

Developers API

Visao Geral

Extensao Chrome

Webhooks & Cron

API v1 — Gestao

Rotas Internas (Session Auth)

API v1 — Publicos

Referencia da API

Autenticacao

Extension Token (Chrome Extension)

API Key (Admin / Integracao)

Sem Auth (Endpoints Publicos)

Rate Limit & CORS

Rate Limiting

CORS

Codigos de Erro

/api/ext/auth

Body Params (JSON)

Resposta

/api/ext/me

Campos da Resposta

/api/ext/logout

Body

Resposta

/api/ext/ml/check

Query Params

Resposta

/ml/notificacoes

Headers Recebidos do ML

Topicos Processados

/api/v1/cron

Query Params

Tarefas Executadas

/api/v1/alunos/criar

Body Params (JSON)

/api/v1/alunos/suspender

Body Params (JSON)

/api/v1/webhook/hotmart

Body

/api/v1/webhook/llm

Body Params (JSON)

Acoes Disponiveis

/api/v1/contexto

/api/v1/planos

/api/v1/professores

/api/v1/meets

/api/v1/schema

Rotas Internas

admin/gamificacao/*

GET Endpoints

POST Endpoints

painel/competicao/*

GET Endpoints

painel/ml/calculadora/taxas-json

Query Params

Campos da Resposta

painel/ml/etiqueta

Query Params

Resposta

admin/agencia/central-perguntas/*

GET Endpoints

POST Endpoints

admin/agencia/ml/sincronizar-todos

Body

Resposta