Documentação

API da ecommercebase

A mesma base do app dentro dos seus sistemas: busque lojas virtuais com filtros, conte um mercado, abra a ficha completa por domínio e acompanhe mudanças.

Versão v1Base https://ecommercebase.com.br/api/v1OpenAPI 3.1

Visão geral

A API devolve JSON, em português, com os mesmos dados e filtros da busca do app. Todas as rotas são GET sobre https://ecommercebase.com.br/api/v1.

Rota	O que faz	Plano	Cota
`/lojas`	Buscar lojas	Pro e Business	Não consome
`/lojas/contagem`	Contar lojas	Pro e Business	Não consome
`/lojas/{dominio}`	Ficha da loja	Pro e Business	Loja nova: 1
`/filtros`	Opções de filtro	Pro e Business	Não consome
`/eventos`	Mudanças nas lojas	Business	Não consome

Autenticação

Toda chamada leva a chave da organização no cabeçalho Authorization: Bearer eb_live_…. Crie e revogue chaves em Integrações → API, no app (Dono e Admin, plano Pro ou Business). A chave inteira aparece uma vez só, ao criar; guarde como uma senha. Cada chave vê os dados da organização e gasta a mesma cota do app.

Authorization: Bearer eb_live_0123456789abcdef0123456789abcdef

Planos

API básica no Pro: busca, contagem, ficha por domínio e opções de filtro. API completa no Business: tudo do Pro e as mudanças nas lojas (/eventos). O MCP usa a mesma chave, as mesmas regras e a mesma cota. Ver planos e preços.

Cota por loja única

A cota do plano conta lojas, não chamadas: buscar, contar e listar mudanças não consome cota. A ficha completa de uma loja (/lojas/{dominio}) consome 1 na primeira vez que a organização a lê numa janela de 12 meses; depois disso, ler de novo pela API ou pelo MCP, exportar no app ou enviar ao CRM a mesma loja não consome. É a mesma cota da exportação no app, somada para toda a equipe.

Limites

Além da cota de lojas, cada organização tem um limite de chamadas por minuto e por mês, conforme o plano, somando API e MCP. Os números do seu plano aparecem em Integrações → API, no app. Passou do limite, a resposta é 429 com o cabeçalho Retry-After (segundos para tentar de novo). Toda resposta bem-sucedida traz X-RateLimit-Limit e X-RateLimit-Remaining (minuto atual).

Paginação

As listas são paginadas por cursor: peça a primeira página sem cursor, depois repita a mesma chamada com cursor igual ao proximo_cursor da resposta, até ele vir null. limite vai de 1 a 100 (padrão 25). Um cursor só vale para os mesmos filtros e a mesma ordem.

Parâmetro	O que é
`limite`	Lojas por página, de 1 a 100 (padrão 25).
`cursor`	Cursor da próxima página: o `proximo_cursor` da resposta anterior, com os mesmos filtros. Ausente = primeira página.
`ordem`	Ordem: `relevancia` (padrão: ativas e maiores primeiro), `novas` (entraram na base mais recentemente), `porte` (maiores primeiro) ou `nome` (A–Z).

Filtros

Os filtros são parâmetros de query string, os mesmos em /lojas, /lojas/contagem e /eventos. Dentro de um filtro, valores separados por vírgula valem como OU; entre filtros, E. Valor desconhecido devolve 400 com a lista de valores aceitos.

Parâmetro	O que filtra	Valores
`plataforma`	Plataforma da loja virtual.	nuvemshop, woocommerce, loja-integrada, shopify, tray, wix, vtex, magento
`uf`	Estado (sigla da UF) da loja.	AC, AL, AP, AM, BA, CE, DF, ES, GO, MA, MT, MS, MG, PA, PB, PR, PE, PI, RJ, RN, RS, RO, RR, SC, SP, SE, TO
`cidade`	Cidade da loja, pelo nome (sem diferença de maiúsculas e acentos). Combine com `uf` para evitar cidades homônimas.	texto (ex.: Blumenau)
`segmento`	Segmento ou categoria da loja (ex.: Moda, Beleza, Pet). Os valores com lojas estão em `GET /api/v1/filtros`.	texto (ex.: Moda)
`pagamento`	Meio de pagamento ou gateway aceito na loja. Vários valores: a loja aceita pelo menos um deles.	pix, mercado-pago, pagseguro, pagar-me, paypal, cielo, getnet, stone, asaas, stripe, appmax, vindi, moip, efi
`porte`	Porte da loja (micro, pequena, média ou grande).	micro, pequena, media, grande
`status`	Situação da loja: `ativa`, `nova` (entrou na base recentemente), `fora` (saiu do ar) ou `trocou` (trocou de plataforma).	ativa, nova, fora, trocou
`canal`	Canal de venda: `online` (vende online), `checkout` (checkout na própria loja), `externo` (checkout externo), `marketplace`, `whatsapp`, `social` (redes sociais) ou `catalogo` (catálogo sem carrinho).	online, checkout, externo, marketplace, whatsapp, social, catalogo
`marketplace`	Marketplace em que a loja também vende.	mercado-livre, shopee, amazon, magalu, americanas, shein, netshoes
`loja_fisica`	Tem loja física (`sim`) ou é só online (`nao`).	sim, nao
`parcelas`	Parcelamento no cartão: `3` = até 3x; `6`, `10` ou `12` = N vezes ou mais.	3, 6, 10, 12
`frete_gratis`	Frete grátis: `qualquer` (oferece), `sem` (sem pedido mínimo) ou `99`, `199`, `299` (pedido mínimo de até R$ N).	qualquer, sem, 99, 199, 299
`desconto_pix`	Desconto no Pix: `1` = dá algum desconto; `5`, `10` ou `15` = desconto de N% ou mais.	1, 5, 10, 15
`app_frete`	Apps da loja na categoria Frete: nomes dos apps (a loja usa pelo menos um), ou `algum` (usa algum app da categoria) ou `nenhum` (não usa nenhum). Os nomes com lojas estão em `GET /api/v1/filtros`.	texto (ex.: Melhor Envio)
`app_antifraude`	Apps da loja na categoria Antifraude: nomes dos apps (a loja usa pelo menos um), ou `algum` (usa algum app da categoria) ou `nenhum` (não usa nenhum). Os nomes com lojas estão em `GET /api/v1/filtros`.	texto (ex.: algum)
`app_avaliacoes`	Apps da loja na categoria Avaliações: nomes dos apps (a loja usa pelo menos um), ou `algum` (usa algum app da categoria) ou `nenhum` (não usa nenhum). Os nomes com lojas estão em `GET /api/v1/filtros`.	texto (ex.: algum)
`app_crm`	Apps da loja na categoria CRM e e-mail: nomes dos apps (a loja usa pelo menos um), ou `algum` (usa algum app da categoria) ou `nenhum` (não usa nenhum). Os nomes com lojas estão em `GET /api/v1/filtros`.	texto (ex.: algum)
`app_busca`	Apps da loja na categoria Busca e recomendação: nomes dos apps (a loja usa pelo menos um), ou `algum` (usa algum app da categoria) ou `nenhum` (não usa nenhum). Os nomes com lojas estão em `GET /api/v1/filtros`.	texto (ex.: algum)
`app_atendimento`	Apps da loja na categoria Atendimento: nomes dos apps (a loja usa pelo menos um), ou `algum` (usa algum app da categoria) ou `nenhum` (não usa nenhum). Os nomes com lojas estão em `GET /api/v1/filtros`.	texto (ex.: algum)
`app_pixels`	Apps da loja na categoria Pixels e tags: nomes dos apps (a loja usa pelo menos um), ou `algum` (usa algum app da categoria) ou `nenhum` (não usa nenhum). Os nomes com lojas estão em `GET /api/v1/filtros`.	texto (ex.: algum)
`app_checkout`	Apps da loja na categoria Checkout: nomes dos apps (a loja usa pelo menos um), ou `algum` (usa algum app da categoria) ou `nenhum` (não usa nenhum). Os nomes com lojas estão em `GET /api/v1/filtros`.	texto (ex.: algum)
`app_erp`	Apps da loja na categoria ERP e hub: nomes dos apps (a loja usa pelo menos um), ou `algum` (usa algum app da categoria) ou `nenhum` (não usa nenhum). Os nomes com lojas estão em `GET /api/v1/filtros`.	texto (ex.: algum)
`busca`	Texto no nome ou no domínio da loja (até 100 caracteres).	texto (ex.: jeans)
`idade_empresa`	Tempo desde a abertura da empresa (CNPJ da loja), em anos.	0-1, 1-3, 3-5, 5-10, 10+
`capital_social`	Faixa de capital social da empresa.	0-10k, 10k-100k, 100k-1mi, 1mi-10mi, 10mi+
`regime`	Regime tributário da empresa: `mei`, `simples` (Simples Nacional, sem MEI) ou `outro` (fora do Simples).	mei, simples, outro
`marca`	Empresa com (`sim`) ou sem (`nao`) marca registrada.	sim, nao
`governo`	Empresa que vende para o governo.	sim
`divida`	Empresa com (`sim`) ou sem (`nao`) dívida ativa.	sim, nao
`cnae`	CNAE principal da empresa: subclasse com 7 dígitos ou prefixo de 2 a 6 dígitos (divisão, grupo, classe). Até 20.	texto (ex.: 4781400)

Buscar lojas

GET /api/v1/lojas · Pro e Business · não consome cota

Lista as lojas de um recorte com os mesmos filtros da busca do app, paginada por cursor. Cada linha traz os dados da lista (domínio, nome, plataforma, pagamentos, cidade/UF, porte, status, segmento). Ler a lista não consome cota; contato, CNPJ e dados de empresa ficam na ficha (/lojas/{dominio}).

Aceita todos os filtros e a paginação.

Pedido

curl "https://ecommercebase.com.br/api/v1/lojas?plataforma=nuvemshop&uf=SC&limite=50" \
  -H "Authorization: Bearer eb_live_sua_chave"

Resposta

{
  "total": 4812,
  "lojas": [
    {
      "dominio": "bossajeans.com.br",
      "nome": "Bossa Jeans",
      "plataforma": "Nuvemshop",
      "plataforma_anterior": null,
      "pagamentos": [
        "Pix",
        "Mercado Pago"
      ],
      "cidade": "Blumenau",
      "uf": "SC",
      "porte": "Média",
      "status": "Ativa",
      "categoria": "Moda",
      "na_base_desde": "2021-03-04"
    }
  ],
  "proximo_cursor": "eyJvIjo1MH0"
}

Campo	Tipo	O que é
`total`	integer	Total de lojas do recorte (todas as páginas).
`lojas`	array	Lojas desta página.
`proximo_cursor`	string (ou null)	Cursor da próxima página, ou null na última.

Cada loja

Campo	Tipo	O que é
`dominio`	string	Domínio da loja, sem www (chave da loja).
`nome`	string	Nome da loja.
`plataforma`	string	Plataforma da loja virtual.
`plataforma_anterior`	string (ou null)	Plataforma anterior, quando a loja trocou.
`pagamentos`	array	Meios de pagamento e gateways aceitos.
`cidade`	string (ou null)	Cidade.
`uf`	string (ou null)	Estado (sigla).
`porte`	string	Porte da loja. Valores: `Micro`, `Pequena`, `Média`, `Grande`.
`status`	string	Situação da loja. Valores: `Ativa`, `Nova`, `Fora do ar`, `Trocou de plataforma`.
`categoria`	string	Segmento principal.
`na_base_desde`	string	Data em que a loja entrou na base (AAAA-MM-DD).

Contar lojas

GET /api/v1/lojas/contagem · Pro e Business · não consome cota

Total de lojas de um recorte e a contagem por opção dos principais filtros (plataforma, UF, pagamento, porte, status, segmento, marketplace). Útil para dimensionar um mercado antes de listar. Não consome cota.

Aceita todos os filtros.

Pedido

curl "https://ecommercebase.com.br/api/v1/lojas/contagem?plataforma=nuvemshop&pagamento=pix" \
  -H "Authorization: Bearer eb_live_sua_chave"

Resposta

{
  "total": 4812,
  "facetas": {
    "uf": {
      "SC": 1210,
      "SP": 980
    },
    "porte": {
      "Micro": 2400,
      "Pequena": 1500,
      "Média": 700,
      "Grande": 212
    }
  }
}

Campo	Tipo	O que é
`total`	integer	Total de lojas do recorte.
`facetas`	object	Contagem por opção.

Ficha da loja

GET /api/v1/lojas/{dominio} · Pro e Business · loja nova consome 1 da cota

Ficha completa da loja: dados da loja, apps, catálogo e preços, contato da loja, CNPJ, contato nominal e dados públicos da empresa. A primeira leitura de uma loja que a organização ainda não liberou consome 1 da cota do plano (loja única: depois disso, reler, exportar ou enviar ao CRM a mesma loja não consome por 12 meses).

Pedido

curl "https://ecommercebase.com.br/api/v1/lojas/bossajeans.com.br" \
  -H "Authorization: Bearer eb_live_sua_chave"

Resposta

{
  "dominio": "bossajeans.com.br",
  "nome": "Bossa Jeans",
  "plataforma": "Nuvemshop",
  "plataforma_anterior": null,
  "pagamentos": [
    "Pix",
    "Mercado Pago"
  ],
  "cidade": "Blumenau",
  "uf": "SC",
  "porte": "Média",
  "status": "Ativa",
  "categoria": "Moda",
  "na_base_desde": "2021-03-04",
  "titulo": "Bossa Jeans | Jeans feito em Blumenau",
  "segmentos": [
    "Moda"
  ],
  "bandeiras": [
    "Visa",
    "Mastercard"
  ],
  "parcelas_max": 6,
  "desconto_pix": 5,
  "frete_gratis": {
    "oferece": true,
    "pedido_minimo": 199
  },
  "canais": [
    "checkout",
    "whatsapp"
  ],
  "marketplaces": [],
  "loja_fisica": false,
  "apps": [
    {
      "categoria": "Frete",
      "app": "Melhor Envio",
      "desde": "2025-02-01"
    }
  ],
  "catalogo": {
    "produtos": 412,
    "preco_min": 39.9,
    "preco_medio": 149.9,
    "preco_max": 399
  },
  "contato_loja": {
    "email": "[email protected]",
    "telefone": "(47) 3333-0000",
    "whatsapp": "(47) 99999-0000"
  },
  "redes": {
    "instagram": "https://instagram.com/bossajeans"
  },
  "cnpj": "12345678000190",
  "razao_social": "Bossa Jeans Ltda",
  "contato_nominal": {
    "nome": "Camila Souza",
    "cargo": "Sócia-fundadora",
    "email": "[email protected]",
    "whatsapp": null
  },
  "empresa": null,
  "liberada": {
    "consumiu_cota": true,
    "ate": "2027-10-12T12:00:00.000Z"
  }
}

Campo	Tipo	O que é
`dominio`	string	Domínio da loja.
`nome`	string	Nome da loja.
`titulo`	string (ou null)	Título da página inicial da loja.
`plataforma`	string	Plataforma.
`plataforma_anterior`	string (ou null)	Plataforma anterior, quando trocou.
`status`	string	Situação. Valores: `Ativa`, `Nova`, `Fora do ar`, `Trocou de plataforma`.
`porte`	string	Porte. Valores: `Micro`, `Pequena`, `Média`, `Grande`.
`categoria`	string	Segmento principal.
`segmentos`	array	Segmentos.
`cidade`	string (ou null)	Cidade.
`uf`	string (ou null)	UF.
`na_base_desde`	string	Entrou na base em (AAAA-MM-DD).
`pagamentos`	array	Meios de pagamento e gateways.
`bandeiras`	array	Bandeiras de cartão.
`parcelas_max`	integer (ou null)	Máximo de parcelas no cartão.
`desconto_pix`	number (ou null)	Desconto no Pix, em %.
`frete_gratis`	object	Frete grátis.
`canais`	array	Canais de venda.
`marketplaces`	array	Marketplaces em que também vende.
`loja_fisica`	boolean	Tem loja física.
`apps`	array	Apps da loja por categoria.
`catalogo`	object	Catálogo.
`contato_loja`	object	Contato público da loja.
`redes`	object (ou null)	Redes sociais (rede → endereço).
`cnpj`	string (ou null)	CNPJ (14 dígitos).
`razao_social`	string (ou null)	Razão social.
`contato_nominal`	object (ou null)	Pessoa de contato (contato nominal).
`empresa`	object (ou null)	Dados públicos da empresa pelo CNPJ: cadastro (natureza, capital, situação, CNAE, matriz/filial, MEI/Simples), marcas, governo, registro sanitário, município, sócios e administradores, contato do cadastro e risco (dívida ativa e sanções). null = loja sem CNPJ ou sem dado.
`liberada`	object	Situação da loja na cota da organização.

Opções de filtro

GET /api/v1/filtros · Pro e Business · não consome cota

Valores aceitos em cada filtro da busca. Segmentos e apps vêm com a contagem de lojas de cada valor. Use antes de montar uma busca para não errar um valor.

Pedido

curl "https://ecommercebase.com.br/api/v1/filtros" \
  -H "Authorization: Bearer eb_live_sua_chave"

Resposta

{
  "filtros": [
    {
      "parametro": "plataforma",
      "descricao": "Plataforma da loja virtual.",
      "tipo": "lista",
      "valores": [
        "nuvemshop",
        "woocommerce"
      ]
    }
  ],
  "ordens": [
    "relevancia",
    "novas",
    "porte",
    "nome"
  ],
  "eventos": [
    {
      "evento": "stack.app_added",
      "rotulo": "Passou a usar app"
    }
  ]
}

Campo	Tipo	O que é
`filtros`	array	Um item por parâmetro de filtro.
`ordens`	array	Valores de `ordem`.
`eventos`	array	Tipos de mudança (`evento` em /eventos).

Mudanças nas lojas

GET /api/v1/eventos · Business · não consome cota

Mudanças registradas nas lojas de um recorte num período: app que entrou ou saiu, troca de gateway, lançamento e retirada de produtos, variação do catálogo e da faixa de preço, loja nova, loja fora do ar e troca de plataforma. Os mesmos filtros da busca valem para as lojas. Plano Business (API completa). Não consome cota.

Parâmetro	O que é
`desde`	Data inicial (AAAA-MM-DD), inclusive. Padrão: 30 dias atrás.
`ate`	Data final (AAAA-MM-DD), inclusive. Padrão: hoje. Janela máxima de 366 dias.
`evento`	Tipos de mudança, separados por vírgula. Ausente = todos.

Aceita todos os filtros e a paginação.

Pedido

curl "https://ecommercebase.com.br/api/v1/eventos?evento=stack.app_added&uf=SC&desde=2026-09-01" \
  -H "Authorization: Bearer eb_live_sua_chave"

Resposta

{
  "eventos": [
    {
      "id": 81234,
      "evento": "stack.app_added",
      "rotulo": "Passou a usar Melhor Envio",
      "em": "2026-09-14T10:42:00.000Z",
      "loja": {
        "dominio": "bossajeans.com.br",
        "nome": "Bossa Jeans",
        "plataforma": "Nuvemshop",
        "cidade": "Blumenau",
        "uf": "SC"
      },
      "mudanca": {
        "app": "Melhor Envio",
        "categoria": "frete",
        "de": null,
        "para": null,
        "quantidade": null,
        "variacao_pct": null
      }
    }
  ],
  "proximo_cursor": null
}

Campo	Tipo	O que é
`eventos`	array	Mudanças, mais novas primeiro.
`proximo_cursor`	string (ou null)	Cursor da próxima página, ou null na última.

Cada mudança

Campo	Tipo	O que é
`id`	integer	Identificador da mudança.
`evento`	string	Tipo da mudança. Valores: `stack.app_added`, `stack.app_removed`, `stack.gateway_changed`, `products.launched`, `products.removed`, `products.catalog_changed`, `products.price_range_changed`, `store.new`, `store.offline`, `stack.platform_changed`, `store.size_changed`.
`rotulo`	string	O que mudou, em português.
`em`	string	Quando a mudança foi registrada.
`loja`	object	A loja.
`mudanca`	object	Detalhes, conforme o tipo.

Erros

Erro sempre volta como {"erro": {"codigo": "…", "mensagem": "…"}}, com o status HTTP abaixo.

Status	Código	Quando
400	`parametro_invalido`	Parâmetro desconhecido ou valor fora da lista (a resposta traz `valores_validos`).
401	`nao_autenticado`	Sem `Authorization: Bearer …`, chave inválida, revogada ou de organização encerrada.
402	`cota_esgotada`	A ficha de uma loja nova precisa de cota e a organização não tem saldo no mês (ou chegou ao teto anual).
402	`fatura_em_atraso`	Pagamento em atraso: lojas já liberadas continuam acessíveis, lojas novas não.
403	`sem_plano`	O plano da organização não inclui a API (Pro+) ou o recurso (`/eventos`: Business).
404	`nao_encontrada`	Loja fora da base.
429	`limite_minuto`	Passou do limite de chamadas por minuto. Espere os segundos do cabeçalho `Retry-After`.
429	`limite_mes`	Passou do limite de chamadas do mês. `Retry-After` diz quando zera (dia 1º).

OpenAPI e MCP

A especificação completa está em https://ecommercebase.com.br/api/v1/openapi.json (também em YAML), pronta para gerar clientes ou dar a um assistente de IA. Para usar a base direto no Claude, no ChatGPT ou no Cursor, veja o servidor MCP.