Documentação da API

A API REST da Mktos permite que você integre a plataforma em seus próprios sistemas — automações, CRMs, scripts ou qualquer outra ferramenta que fale HTTP.

Base URL

https://mktos.com.br

✓Todas as requisições e respostas usam Content-Type: application/json
✓Respostas de sucesso seguem o formato { "success": true, "data": {...} }
✓Todos os campos usam snake_case — tanto nas requisições quanto nas respostas

Autenticação

Todas as requisições à API pública precisam de uma API key válida. Gere suas chaves em Configurações → API Keys dentro da plataforma.

Inclua a chave em um dos headers abaixo (ambos são aceitos):

http

Authorization: Bearer mkt_sua_chave_aqui

http

X-API-Key: mkt_sua_chave_aqui

Exemplo com curl:

bash

curl https://mktos.com.br/api/v1/leads \
  -H "Authorization: Bearer mkt_sua_chave_aqui"

Importante: A chave completa é exibida apenas no momento da criação. Guarde-a em um lugar seguro — não é possível recuperá-la depois.

Escopos

Cada API key tem um escopo que define o nível de acesso. Use o menor escopo necessário.

Escopo	Permissões
read	Leitura de leads, execuções e status de jobs (todos os endpoints GET)
write	Tudo do `read` + disparar mineração (POST /miner) + atualizar leads (PATCH)
admin	Acesso total — reservado para integrações avançadas

Erros

Erros retornam um objeto JSON com success: false e um código HTTP adequado.

json

{
  "success": false,
  "error": "API key inválida.",
  "code": "UNAUTHORIZED"
}

HTTP	code	Significado
400	VALIDATION_ERROR	Parâmetros inválidos ou ausentes
401	UNAUTHORIZED	API key ausente, inválida, inativa ou expirada
403	FORBIDDEN	Escopo insuficiente para esta operação
404	NOT_FOUND	Recurso não encontrado
429	RATE_LIMIT_EXCEEDED	Limite de requisições atingido
500	INTERNAL_ERROR	Erro interno do servidor

Rate Limiting

Cada API key tem um limite de 100 requisições por minuto para endpoints de leitura, e 20 requisições por minuto para o endpoint de mineração (POST /miner).

Ao atingir o limite, a API retorna HTTP 429. Aguarde o próximo ciclo de 60 segundos antes de tentar novamente.

Leads

Endpoints para acessar e gerenciar leads minerados.

GET/api/v1/leadsescopo: read

Listar leads

Retorna uma lista paginada de leads do tenant autenticado, ordenados pelo mais recente. Usa cursor-based pagination.

Query parameters

Nome	Tipo	Obrigatório	Descrição
limit	number	—	Quantidade de registros por página. Padrão: 50. Máx: 200.
cursor	string (uuid)	—	ID do último lead da página anterior para paginação.

Exemplo de resposta

json

{
  "success": true,
  "data": {
    "leads": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "tenant_id": "...",
        "name": "Pizzaria do João",
        "phone": "11999999999",
        "address": "Rua das Flores, 123 - SP",
        "website": "https://pizzariadojoao.com.br",
        "crm_stage": "leads",
        "created_at": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "has_more": true,
      "next_cursor": "550e8400-e29b-41d4-a716-446655440001"
    }
  }
}

GET/api/v1/leads/:idescopo: read

Buscar lead

Retorna os dados completos de um lead específico.

Path parameters

Nome	Tipo	Obrigatório	Descrição
id	string (uuid)	sim	ID do lead.

Exemplo de resposta

json

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "...",
    "name": "Pizzaria do João",
    "phone": "11999999999",
    "email": "contato@pizzariadojoao.com.br",
    "address": "Rua das Flores, 123 - SP",
    "website": "https://pizzariadojoao.com.br",
    "ai_note": "Negócio local com alta presença no delivery...",
    "pain_score": 0.75,
    "opportunity_score": 0.82,
    "crm_stage": "first_contact",
    "converted": false,
    "created_at": "2024-01-15T10:30:00Z"
  }
}

PATCH/api/v1/leads/:idescopo: write

Atualizar lead

Atualiza campos de um lead. Todos os campos são opcionais.

Path parameters

Nome	Tipo	Obrigatório	Descrição
id	string (uuid)	sim	ID do lead.

Body (JSON)

Nome	Tipo	Obrigatório	Descrição
name	string	—	Nome do negócio.
phone	string \| null	—	Telefone de contato.
email	string \| null	—	E-mail de contato.
address	string \| null	—	Endereço.
website	string \| null	—	Website.
crm_stage	string	—	Estágio no CRM: leads \| first_contact \| followup_1 \| followup_2 \| followup_3 \| conversing \| meeting_scheduled \| converted \| lost
converted	boolean	—	Marca o lead como convertido.
personalized_message	string \| null	—	Mensagem personalizada gerada para o lead.

Exemplo de requisição

json

{
  "crm_stage": "first_contact",
  "phone": "11988887777"
}

Exemplo de resposta

json

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Pizzaria do João",
    "crm_stage": "first_contact",
    "updated_at": "2024-01-16T09:00:00Z"
  }
}

GET/api/v1/usageescopo: read

Consultar uso

Retorna o consumo atual de leads do tenant autenticado, incluindo quantidade utilizada e limite disponível.

Exemplo de resposta

json

{
  "success": true,
  "data": {
    "leads": {
      "used": 142,
      "limit": 500
    }
  }
}

Mineração

Disparar e acompanhar jobs de prospecção automática.

POST/api/v1/minerescopo: write

Iniciar mineração

Dispara um job de mineração de leads nas plataformas selecionadas. O processamento é assíncrono — use o endpoint de status para acompanhar. Sujeito ao limite de leads e validade do trial.

Body (JSON)

Nome	Tipo	Obrigatório	Descrição
query	string	sim	Termo de busca. Ex: "restaurante italiano".
location	string	sim	Localização. Ex: "São Paulo, SP".
platforms.google	boolean	sim	Minerar no Google Maps.
platforms.instagram	boolean	sim	Minerar no Instagram.

Exemplo de requisição

json

{
  "query": "salão de beleza",
  "location": "Campinas, SP",
  "platforms": {
    "google": true,
    "instagram": false
  }
}

Exemplo de resposta

json

{
  "success": true,
  "data": {
    "job_run_id": "550e8400-e29b-41d4-a716-446655440099",
    "trigger_run_id": "run_abc123xyz",
    "status": "RUNNING",
    "message": "Mineração iniciada. Os resultados serão processados em breve."
  }
}

GET/api/v1/miner/statusescopo: read

Status do job

Consulta o status de um run Apify em execução.

Query parameters

Nome	Tipo	Obrigatório	Descrição
runId	string	sim	ID do run retornado pelo endpoint de mineração (triggerRunId).

Exemplo de resposta

json

{
  "success": true,
  "data": {
    "status": "SUCCEEDED",
    "started_at": "2024-01-15T10:30:00Z",
    "finished_at": "2024-01-15T10:35:22Z"
  }
}

Execuções

Histórico de jobs de mineração.

GET/api/v1/job-runsescopo: read

Listar execuções

Retorna o histórico de jobs de mineração do tenant, paginado do mais recente.

Query parameters

Nome	Tipo	Obrigatório	Descrição
limit	number	—	Quantidade por página. Padrão: 50. Máx: 100.
cursor	string (uuid)	—	Cursor de paginação.
job_type	string	—	Filtrar por tipo: leads:google-maps \| leads:instagram

Exemplo de resposta

json

{
  "success": true,
  "data": {
    "job_runs": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440099",
        "job_type": "leads:google-maps",
        "status": "SUCCESS",
        "origins": ["Google Maps"],
        "payload": { "query": "salão de beleza", "location": "Campinas, SP" },
        "created_at": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": { "has_more": false, "next_cursor": null }
  }
}