Documentação da API e do MCP

Autenticação

Envie a chave no cabeçalho Authorization de toda chamada. Chave na URL (na query string) é recusada com 401, mesmo que seja válida.

Authorization: Bearer jda_…

Parâmetros comuns

As rotas com período aceitam os mesmos três parâmetros. Use periodo ou inicio + fim, nunca os dois juntos.

• Um valor por parâmetro: o mesmo parâmetro repetido na URL dá 400.
• Parâmetro desconhecido dá 400, em vez de ser ignorado: um nome digitado errado não passa despercebido.
• Os filtros marketplace e conta usam o rótulo exato que aparece na Jodda: descubra os valores em GET /v1/filtros. Em GET /v1/ads/resumo, conta é o ID da loja, não o rótulo.

Erros

Toda resposta é JSON. O erro vem sempre como {"error": "...", "code": "..."}: a mensagem em português é para pessoas, e a integração decide pelo code, que não muda.

{
  "error": "Mensagem em português explicando o que aconteceu.",
  "code": "INVALID_PARAMS"
}

Cabeçalhos da resposta

Limites

• Até 60 chamadas por minuto por chave de API.
• As respostas trazem X-RateLimit-Limit (o limite da chave) e X-RateLimit-Remaining (quantas chamadas ainda restam no minuto).
• Acima do limite, a resposta é 429 com o code RATE_LIMITED e o cabeçalho Retry-After, com os segundos até poder chamar de novo. Espere esse tempo antes de repetir a chamada.

Servidor MCP

A Jodda expõe um servidor MCP (Model Context Protocol) oficial. Claude, ChatGPT e outros clientes compatíveis passam a consultar a sua operação pedido a pedido — com autorização segura e os mesmos números da plataforma.

O que você precisa

• Uma conta ativa na Jodda (o mesmo login do app).
• Um assistente com suporte a conectores MCP remotos: Claude.ai, Claude Desktop, ChatGPT (modo desenvolvedor), Cursor, VS Code e similares.
• Nenhuma chave de API: a autorização é feita com o seu login da Jodda, via OAuth.
• Para o assistente cadastrar produtos ou atualizar o custo dos pedidos, marque a permissão de escrita na tela de autorização. A atualização de custo pede também acesso às páginas Pedidos e Produtos.

Como conectar

Leva menos de dois minutos. Em todos os casos, a URL é a mesma.

Assistentes de IA

AUTORIZAR CONEXÃO

Conecte seu assistente à Jodda

Claude

Destino de retorno: claude.ai

O que o assistente pode consultar

Leitura

Dashboard

Vendas e desempenho

Pedidos

Listagem e cancelamentos

Produtos

Catálogo, custos e ADS

Finanças

DRE e movimentações

Cadastro de produtos e custo dos pedidos

Leitura e escrita

Primeiro a prévia, depois a gravação — só após a sua confirmação.

Não permitirPermitir conexão

Integrações→Assistentes de IA

Claude

1 conexão

ChatGPT

1 conexão

Outro MCP

Não conectado

Conexões ativas · Claude

ClaudeConectado

Autorizado em 14/09 · último uso hoje, 22:07

Desconectar

ClaudeDesconectado

Autorizado em 07/09 · revogado em 14/09

Ferramentas

Três níveis por ferramenta. O avançado é onde a Jodda rende mais: quando o assistente cruza duas ou três consultas para chegar a uma decisão.

Exemplos de conversa por ferramenta

Gerencie as conexões no app

Em Integrações → Assistentes de IA você vê quais assistentes estão conectados, quando foram autorizados, o último uso e pode desconectar cada um com um clique.

GET/v1/conta

Conta e chave da chamada

De qual conta é a chave, quais páginas ela lê e quando foi criada. Sem parâmetros: o primeiro teste de quem integra.

Página exigida

nenhuma (qualquer chave válida)

Resposta

application/json

Parâmetros

Esta rota não recebe parâmetros.

Exemplo

curl "https://api.joddaia.com.br/v1/conta" \
  -H "Authorization: Bearer $JODDA_API_KEY"

import os
import requests

resposta = requests.get(
    "https://api.joddaia.com.br/v1/conta",
    headers={"Authorization": f"Bearer {os.environ['JODDA_API_KEY']}"},
    timeout=30,
)
resposta.raise_for_status()
dados = resposta.json()

{
  "conta": {
    "org_uuid": "5f0c2a4e-8b1d-4c7e-9a3f-2d6b8e1c4a70",
    "paginas": ["dashboard", "pedidos", "produtos", "dre"],
    "escopos": ["jodda:read"]
  },
  "chave": {
    "prefixo": "jda_Ab12Cd34",
    "nome": "Power BI do financeiro",
    "criada_em": "2026-11-13 12:00:00"
  },
  "avisos": []
}

GET/v1/filtros

Filtros disponíveis

Lista os rótulos exatos de marketplaces, contas (lojas) e CNPJs da conta da Jodda, para usar como filtro em GET /v1/vendas/resumo e GET /v1/pedidos. Chame antes de filtrar por marketplace ou conta: o filtro exige o texto exato e um rótulo errado devolve zero. Não devolve valores de venda.

Página exigida

Dashboard

Resposta

application/json

Parâmetros

Esta rota não recebe parâmetros.

Exemplo

curl "https://api.joddaia.com.br/v1/filtros" \
  -H "Authorization: Bearer $JODDA_API_KEY"

import os
import requests

resposta = requests.get(
    "https://api.joddaia.com.br/v1/filtros",
    headers={"Authorization": f"Bearer {os.environ['JODDA_API_KEY']}"},
    timeout=30,
)
resposta.raise_for_status()
dados = resposta.json()

GET/v1/vendas/resumo

Resumo de vendas

Resumo de vendas de um período com os mesmos números do Dashboard da Jodda: faturamento, pedidos, ticket médio, unidades, lucro, margem, imposto, previsão do mês, gasto de ADS, comparação com o período anterior e quebras por marketplace, conta, CNPJ, UF e logística. Filtros opcionais por marketplace, conta e CNPJ exigem o rótulo exato (veja GET /v1/filtros). NÃO lista pedidos individuais (use GET /v1/pedidos) e NÃO detalha um pedido (use GET /v1/pedidos/{numero}). Toda resposta traz avisos que devem ser considerados ao interpretar os números.

Página exigida

Dashboard

Resposta

application/json

Parâmetros

Exemplo

curl "https://api.joddaia.com.br/v1/vendas/resumo?periodo=30d&marketplace=Shopee" \
  -H "Authorization: Bearer $JODDA_API_KEY"

import os
import requests

resposta = requests.get(
    "https://api.joddaia.com.br/v1/vendas/resumo",
    params={"periodo": "30d", "marketplace": "Shopee"},
    headers={"Authorization": f"Bearer {os.environ['JODDA_API_KEY']}"},
    timeout=30,
)
resposta.raise_for_status()
dados = resposta.json()

GET/v1/pedidos

Listar pedidos

Lista pedidos (uma linha por item/SKU) de um período com os mesmos valores da aba Pedidos: número, data, marketplace, conta, status, SKU, quantidade, total, comissão, frete, desconto, custo, imposto, lucro, margem, repasse, logística e UF. Traz KPIs do filtro inteiro (total de linhas, faturamento, lucro, margem, cancelados) e paginação. Filtros: status, marketplace, conta, busca textual, logística e uma condição numérica (ex.: margem_pct lte 10). NÃO agrega por marketplace/período (use GET /v1/vendas/resumo). Considere avisos ao interpretar.

Página exigida

Pedidos

Resposta

application/json

Parâmetros

Exemplo

curl "https://api.joddaia.com.br/v1/pedidos?periodo=7d&metrica=margem_pct&condicao=lte&valor=10" \
  -H "Authorization: Bearer $JODDA_API_KEY"

import os
import requests

resposta = requests.get(
    "https://api.joddaia.com.br/v1/pedidos",
    params={"periodo": "7d", "metrica": "margem_pct", "condicao": "lte", "valor": "10"},
    headers={"Authorization": f"Bearer {os.environ['JODDA_API_KEY']}"},
    timeout=30,
)
resposta.raise_for_status()
dados = resposta.json()

GET/v1/pedidos/{numero}

Detalhar pedido

Detalha um pedido pelo número (do marketplace ou interno do ERP): cabeçalho com data, marketplace, conta, status, logística, UF e totais somados, mais a lista de itens com SKU, quantidade, total, comissão, frete, desconto, custo, imposto, lucro, margem e repasse. Procura nos últimos 365 dias por padrão; passe periodo para pedidos mais antigos. NÃO faz busca por texto (use GET /v1/pedidos com busca).

Página exigida

Pedidos

Resposta

application/json

Parâmetros

Exemplo

curl "https://api.joddaia.com.br/v1/pedidos/2000012345678901" \
  -H "Authorization: Bearer $JODDA_API_KEY"

import os
import requests

resposta = requests.get(
    "https://api.joddaia.com.br/v1/pedidos/2000012345678901",
    headers={"Authorization": f"Bearer {os.environ['JODDA_API_KEY']}"},
    timeout=30,
)
resposta.raise_for_status()
dados = resposta.json()

GET/v1/cancelamentos

Cancelamentos

Análise de cancelamentos de um período com os mesmos números da aba Pedidos > Cancelamentos: quantidade, faturamento e lucro perdidos, unidades, taxa de cancelamento, quebra por marketplace, produtos mais cancelados (com taxa por SKU), logística e UF, e comparação com o período anterior. Filtros opcionais por marketplace e conta (rótulo exato; veja GET /v1/filtros). NÃO lista pedidos cancelados individualmente (use GET /v1/pedidos com status="Cancelado"). Considere avisos ao interpretar.

Página exigida

Pedidos

Resposta

application/json

Parâmetros

Exemplo

curl "https://api.joddaia.com.br/v1/cancelamentos?periodo=mes_anterior" \
  -H "Authorization: Bearer $JODDA_API_KEY"

import os
import requests

resposta = requests.get(
    "https://api.joddaia.com.br/v1/cancelamentos",
    params={"periodo": "mes_anterior"},
    headers={"Authorization": f"Bearer {os.environ['JODDA_API_KEY']}"},
    timeout=30,
)
resposta.raise_for_status()
dados = resposta.json()

GET/v1/produtos

Análise de Produtos

Consulta Produtos: resumo de vendas, lista com cadastro e piso de margem, curva ABC, detalhe de SKU com custos e pedidos, anúncios do produto, composição de kit, produtos sem custo e catálogo Jodda. Comece por resumo/lista/abc e use o SKU retornado em detalhe/anuncios/kit. Detalhe resolve vínculos entre SKUs e vitrines. Não oferece estoque ao vivo. Lucro não desconta ADS; use GET /v1/ads/resumo separadamente. Catálogo atual não é histórico. Totais e margens vêm do serviço; considere avisos. Continue listas usando paginacao.proximo_deslocamento com a mesma visão, período, filtros e ordem. Filtros de marketplace/conta/CNPJ só valem para resumo/lista/abc. Para recortar por categoria, marca ou fornecedor, descubra os rótulos em visao=categorias/marcas/fornecedores (campo do_erp) e passe o nome exato em visao=lista.

Página exigida

Produtos

Resposta

application/json

Parâmetros

Exemplo

curl "https://api.joddaia.com.br/v1/produtos?visao=abc&periodo=30d" \
  -H "Authorization: Bearer $JODDA_API_KEY"

import os
import requests

resposta = requests.get(
    "https://api.joddaia.com.br/v1/produtos",
    params={"visao": "abc", "periodo": "30d"},
    headers={"Authorization": f"Bearer {os.environ['JODDA_API_KEY']}"},
    timeout=30,
)
resposta.raise_for_status()
dados = resposta.json()

GET/v1/ads/resumo

Análise de ADS

Analisa ADS de Mercado Livre, Shopee e Amazon por CNPJ, conta, produto, anúncio ou campanha: gasto, receita atribuída, ACOS, ROAS, cliques, conversões e gasto sem venda. ACOS usa receita atribuída pelo marketplace; participacao_ads_pct usa faturamento total. null ou metricas_disponiveis=false não significa desempenho zero. A Amazon tem só gasto, sem receita atribuída, ACOS, ROAS nem campanha: receita_ads, acos_pct e roas vêm null e, nela, participacao_ads_pct é o TACoS. Em nivel=campanha o gasto da Amazon fica só em totais.gasto_amazon. totais.fontes.amazon=indisponivel não é gasto zero; não há dado da Amazon antes de 28/04/2026. Campanhas identificadas são do Mercado Livre; Shopee pode aparecer em (sem campanha). Para relacionar vendas Shopee use nivel=produto. Totais e cobertura são globais no período; filtros afetam apenas linhas. Preserve avisos e truncado ao interpretar.

Página exigida

Produtos

Resposta

application/json

Parâmetros

Exemplo

curl "https://api.joddaia.com.br/v1/ads/resumo?periodo=30d&nivel=campanha" \
  -H "Authorization: Bearer $JODDA_API_KEY"

import os
import requests

resposta = requests.get(
    "https://api.joddaia.com.br/v1/ads/resumo",
    params={"periodo": "30d", "nivel": "campanha"},
    headers={"Authorization": f"Bearer {os.environ['JODDA_API_KEY']}"},
    timeout=30,
)
resposta.raise_for_status()
dados = resposta.json()

GET/v1/financas

Análise de Finanças

Consulta a DRE (Demonstrativo de Resultados) e as Movimentações financeiras da conta. visao="dre" traz receita líquida, margem de contribuição, lucro operacional, lucro líquido, ponto de equilíbrio, índice de cobertura e margem de segurança — os mesmos números da aba Finanças, não os do GET /v1/vendas/resumo/GET /v1/produtos. O lucro líquido da DRE desconta ADS, o custo de Full do Mercado Livre e as despesas cadastradas; não é o mesmo lucro de Produtos (sem ADS) nem o do Dashboard. imposto_origem diz se o imposto do mês é estimado pela alíquota cadastrada ou já foi ajustado pela DAS paga. visao="movimentacoes" lista os lançamentos individuais (descrição, categoria, status previsto/confirmado) por trás da DRE. A DRE cobre só a partir de setembro/2025. Sempre preserve os avisos e fontes ao explicar um número.

Página exigida

Finanças

Resposta

application/json

Parâmetros

Exemplo

curl "https://api.joddaia.com.br/v1/financas?visao=dre&periodo=mes_anterior" \
  -H "Authorization: Bearer $JODDA_API_KEY"

import os
import requests

resposta = requests.get(
    "https://api.joddaia.com.br/v1/financas",
    params={"visao": "dre", "periodo": "mes_anterior"},
    headers={"Authorization": f"Bearer {os.environ['JODDA_API_KEY']}"},
    timeout=30,
)
resposta.raise_for_status()
dados = resposta.json()