{"openapi":"3.0.3","info":{"title":"Jodda API","version":"1.0.0","description":"Os dados da sua conta da Jodda por HTTP: vendas, pedidos, cancelamentos, produtos, ADS e finanças, com os mesmos números do site e do assistente. Só leitura. Documentação: https://joddaia.com.br/api-documentacao"},"servers":[{"url":"https://api.joddaia.com.br/v1"}],"security":[{"chave":[]}],"paths":{"/conta":{"get":{"operationId":"conta","summary":"Conta e chave da chamada","description":"De qual conta é a chave, quais páginas ela lê e quando foi criada. Sem parâmetros: o primeiro teste de quem integra.","tags":["conta"],"responses":{"200":{"description":"A conta pelo `org_uuid` (o \"ID da conta\" do Perfil) e a chave pelo prefixo.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"type":"object","required":["conta","chave","avisos"],"properties":{"conta":{"type":"object","properties":{"org_uuid":{"type":"string","format":"uuid"},"paginas":{"type":"array","items":{"type":"string","enum":["dashboard","pedidos","produtos","dre"]}},"escopos":{"type":"array","items":{"type":"string"}}}},"chave":{"type":"object","properties":{"prefixo":{"type":"string"},"nome":{"type":"string"},"criada_em":{"type":"string"}}},"avisos":{"type":"array","items":{"type":"string"}}}}}}},"400":{"$ref":"#/components/responses/Erro"},"401":{"$ref":"#/components/responses/Erro"},"403":{"$ref":"#/components/responses/Erro"},"404":{"$ref":"#/components/responses/Erro"},"429":{"$ref":"#/components/responses/Erro"},"500":{"$ref":"#/components/responses/Erro"},"502":{"$ref":"#/components/responses/Erro"},"503":{"$ref":"#/components/responses/Erro"}}}},"/filtros":{"get":{"operationId":"filtros_disponiveis","summary":"Filtros disponíveis","description":"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.","tags":["dashboard"],"parameters":[],"responses":{"200":{"description":"O mesmo JSON que o assistente da Jodda recebe, com `avisos`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"type":"object","required":["avisos"],"properties":{"avisos":{"type":"array","items":{"type":"string"},"description":"Quando um número é parcial ou estimado. Guarde junto do dado."}},"additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Erro"},"401":{"$ref":"#/components/responses/Erro"},"403":{"$ref":"#/components/responses/Erro"},"404":{"$ref":"#/components/responses/Erro"},"429":{"$ref":"#/components/responses/Erro"},"500":{"$ref":"#/components/responses/Erro"},"502":{"$ref":"#/components/responses/Erro"},"503":{"$ref":"#/components/responses/Erro"}}}},"/vendas/resumo":{"get":{"operationId":"resumo_vendas","summary":"Resumo de vendas","description":"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.","tags":["dashboard"],"parameters":[{"name":"periodo","in":"query","required":false,"description":"Padrão: mes_atual. Preset calculado no horário de Brasília: \"7d\" e \"30d\" incluem hoje. No lugar de `inicio` + `fim`, nunca junto.","schema":{"type":"string","enum":["hoje","ontem","7d","30d","mes_atual","mes_anterior"]}},{"name":"inicio","in":"query","required":false,"description":"Início do intervalo (inclusive), junto de `fim`.","schema":{"type":"string","format":"date"}},{"name":"fim","in":"query","required":false,"description":"Fim do intervalo (inclusive), junto de `inicio`.","schema":{"type":"string","format":"date"}},{"name":"marketplace","in":"query","required":false,"description":"Rótulo exato do marketplace como aparece no dashboard (ex.: \"Mercado Livre\", \"Shopee\", \"Amazon\", \"Via ERP\"). Use GET /v1/filtros para descobrir os valores válidos.","schema":{"type":"string","minLength":1,"maxLength":80}},{"name":"conta","in":"query","required":false,"description":"Rótulo exato da conta/loja como aparece no dashboard: o nome da conta cadastrada; venda sem conta cadastrada aparece com o nome do marketplace (ex.: \"Via ERP\"). Use GET /v1/filtros para descobrir os valores válidos.","schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"cnpj","in":"query","required":false,"description":"CNPJ formatado (XX.XXX.XXX/XXXX-XX) ou só dígitos.","schema":{"type":"string","minLength":11,"maxLength":18}},{"name":"status","in":"query","required":false,"description":"\"Aprovado\" = tudo que não foi cancelado (padrão). \"Cancelado\" = só cancelados.","schema":{"type":"string","enum":["Aprovado","Cancelado"]}},{"name":"incluir_serie_diaria","in":"query","required":false,"description":"Devolve serie_diaria (um ponto por dia). Padrão: true em períodos curtos (hoje, ontem, 7d ou até 14 dias), false nos longos.","schema":{"type":"boolean"}},{"name":"incluir_top_produtos","in":"query","required":false,"description":"Devolve os N produtos de maior faturamento em top_produtos (0 a 10). Padrão: 5 em períodos curtos, 0 nos longos.","schema":{"type":"integer","minimum":0,"maximum":10}}],"responses":{"200":{"description":"O mesmo JSON que o assistente da Jodda recebe, com `avisos`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"type":"object","required":["avisos"],"properties":{"avisos":{"type":"array","items":{"type":"string"},"description":"Quando um número é parcial ou estimado. Guarde junto do dado."}},"additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Erro"},"401":{"$ref":"#/components/responses/Erro"},"403":{"$ref":"#/components/responses/Erro"},"404":{"$ref":"#/components/responses/Erro"},"429":{"$ref":"#/components/responses/Erro"},"500":{"$ref":"#/components/responses/Erro"},"502":{"$ref":"#/components/responses/Erro"},"503":{"$ref":"#/components/responses/Erro"}}}},"/pedidos":{"get":{"operationId":"listar_pedidos","summary":"Listar pedidos","description":"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.","tags":["pedidos"],"parameters":[{"name":"periodo","in":"query","required":false,"description":"Padrão: 7d. Preset calculado no horário de Brasília: \"7d\" e \"30d\" incluem hoje. No lugar de `inicio` + `fim`, nunca junto.","schema":{"type":"string","enum":["hoje","ontem","7d","30d","mes_atual","mes_anterior"]}},{"name":"inicio","in":"query","required":false,"description":"Início do intervalo (inclusive), junto de `fim`.","schema":{"type":"string","format":"date"}},{"name":"fim","in":"query","required":false,"description":"Fim do intervalo (inclusive), junto de `inicio`.","schema":{"type":"string","format":"date"}},{"name":"status","in":"query","required":false,"description":"\"Todos\" (padrão) lista aprovados e cancelados; os KPIs separam os cancelados.","schema":{"type":"string","enum":["Aprovado","Cancelado","Todos"]}},{"name":"marketplace","in":"query","required":false,"description":"Rótulo exato do marketplace como aparece no dashboard (ex.: \"Mercado Livre\", \"Shopee\", \"Amazon\", \"Via ERP\"). Use GET /v1/filtros para descobrir os valores válidos.","schema":{"type":"string","minLength":1,"maxLength":80}},{"name":"conta","in":"query","required":false,"description":"Rótulo exato da conta/loja como aparece no dashboard: o nome da conta cadastrada; venda sem conta cadastrada aparece com o nome do marketplace (ex.: \"Via ERP\"). Use GET /v1/filtros para descobrir os valores válidos.","schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"busca","in":"query","required":false,"description":"Texto livre: número do pedido, SKU ou parte da descrição do produto.","schema":{"type":"string","minLength":2,"maxLength":80}},{"name":"logistica","in":"query","required":false,"description":"Full = estoque no marketplace; Flex = entrega própria; Padrao = o resto.","schema":{"type":"string","enum":["Full","Flex","Padrao"]}},{"name":"metrica","in":"query","required":false,"description":"Campo numérico para filtrar (use junto com condicao e valor). Ex.: margem_pct lte 10.","schema":{"type":"string","enum":["total","custo","comissao","imposto","lucro","margem_pct"]}},{"name":"condicao","in":"query","required":false,"description":"gte = maior ou igual; lte = menor ou igual; eq = igual.","schema":{"type":"string","enum":["gte","lte","eq"]}},{"name":"valor","in":"query","required":false,"description":"Valor numérico da condição (R$ ou %, conforme a métrica).","schema":{"type":"number"}},{"name":"pagina","in":"query","required":false,"description":"Página, começando em 1.","schema":{"type":"integer","minimum":1}},{"name":"por_pagina","in":"query","required":false,"description":"Itens por página (máximo 100, padrão 50).","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"O mesmo JSON que o assistente da Jodda recebe, com `avisos`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"type":"object","required":["avisos"],"properties":{"avisos":{"type":"array","items":{"type":"string"},"description":"Quando um número é parcial ou estimado. Guarde junto do dado."}},"additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Erro"},"401":{"$ref":"#/components/responses/Erro"},"403":{"$ref":"#/components/responses/Erro"},"404":{"$ref":"#/components/responses/Erro"},"429":{"$ref":"#/components/responses/Erro"},"500":{"$ref":"#/components/responses/Erro"},"502":{"$ref":"#/components/responses/Erro"},"503":{"$ref":"#/components/responses/Erro"}}}},"/pedidos/{numero}":{"get":{"operationId":"pedido","summary":"Detalhar pedido","description":"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`).","tags":["pedidos"],"parameters":[{"name":"numero","in":"path","required":true,"description":"Número do pedido no marketplace (numero_loja) ou número interno do ERP (numero).","schema":{"type":"string","minLength":3,"maxLength":64}},{"name":"periodo","in":"query","required":false,"description":"Opcional. Padrão: últimos 365 dias. Informe se o pedido for mais antigo. Preset calculado no horário de Brasília: \"7d\" e \"30d\" incluem hoje. No lugar de `inicio` + `fim`, nunca junto.","schema":{"type":"string","enum":["hoje","ontem","7d","30d","mes_atual","mes_anterior"]}},{"name":"inicio","in":"query","required":false,"description":"Início do intervalo (inclusive), junto de `fim`.","schema":{"type":"string","format":"date"}},{"name":"fim","in":"query","required":false,"description":"Fim do intervalo (inclusive), junto de `inicio`.","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"O mesmo JSON que o assistente da Jodda recebe, com `avisos`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"type":"object","required":["avisos"],"properties":{"avisos":{"type":"array","items":{"type":"string"},"description":"Quando um número é parcial ou estimado. Guarde junto do dado."}},"additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Erro"},"401":{"$ref":"#/components/responses/Erro"},"403":{"$ref":"#/components/responses/Erro"},"404":{"$ref":"#/components/responses/Erro"},"429":{"$ref":"#/components/responses/Erro"},"500":{"$ref":"#/components/responses/Erro"},"502":{"$ref":"#/components/responses/Erro"},"503":{"$ref":"#/components/responses/Erro"}}}},"/cancelamentos":{"get":{"operationId":"cancelamentos","summary":"Cancelamentos","description":"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.","tags":["pedidos"],"parameters":[{"name":"periodo","in":"query","required":false,"description":"Padrão: mes_atual. Preset calculado no horário de Brasília: \"7d\" e \"30d\" incluem hoje. No lugar de `inicio` + `fim`, nunca junto.","schema":{"type":"string","enum":["hoje","ontem","7d","30d","mes_atual","mes_anterior"]}},{"name":"inicio","in":"query","required":false,"description":"Início do intervalo (inclusive), junto de `fim`.","schema":{"type":"string","format":"date"}},{"name":"fim","in":"query","required":false,"description":"Fim do intervalo (inclusive), junto de `inicio`.","schema":{"type":"string","format":"date"}},{"name":"marketplace","in":"query","required":false,"description":"Rótulo exato do marketplace como aparece no dashboard (ex.: \"Mercado Livre\", \"Shopee\", \"Amazon\", \"Via ERP\"). Use GET /v1/filtros para descobrir os valores válidos.","schema":{"type":"string","minLength":1,"maxLength":80}},{"name":"conta","in":"query","required":false,"description":"Rótulo exato da conta/loja como aparece no dashboard: o nome da conta cadastrada; venda sem conta cadastrada aparece com o nome do marketplace (ex.: \"Via ERP\"). Use GET /v1/filtros para descobrir os valores válidos.","schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"comparar","in":"query","required":false,"description":"true (padrão) inclui `anterior` com os KPIs do período imediatamente anterior de mesma duração.","schema":{"type":"boolean"}},{"name":"incluir_serie_diaria","in":"query","required":false,"description":"Devolve serie_diaria (cancelamentos por dia). Padrão: true em períodos de até 14 dias, false nos longos.","schema":{"type":"boolean"}},{"name":"top_produtos","in":"query","required":false,"description":"Quantos produtos mais cancelados devolver em top_produtos (0 a 20, padrão 10).","schema":{"type":"integer","minimum":0,"maximum":20}}],"responses":{"200":{"description":"O mesmo JSON que o assistente da Jodda recebe, com `avisos`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"type":"object","required":["avisos"],"properties":{"avisos":{"type":"array","items":{"type":"string"},"description":"Quando um número é parcial ou estimado. Guarde junto do dado."}},"additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Erro"},"401":{"$ref":"#/components/responses/Erro"},"403":{"$ref":"#/components/responses/Erro"},"404":{"$ref":"#/components/responses/Erro"},"429":{"$ref":"#/components/responses/Erro"},"500":{"$ref":"#/components/responses/Erro"},"502":{"$ref":"#/components/responses/Erro"},"503":{"$ref":"#/components/responses/Erro"}}}},"/produtos":{"get":{"operationId":"consultar_produtos","summary":"Análise de Produtos","description":"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.","tags":["produtos"],"parameters":[{"name":"visao","in":"query","required":false,"description":"Padrão resumo. lista e abc descobrem SKUs; detalhe, anuncios e kit exigem sku. Catálogo: fornecedores/categorias/marcas/tags.","schema":{"type":"string","enum":["resumo","lista","abc","detalhe","anuncios","kit","sem_custo","fornecedores","categorias","marcas","tags"]}},{"name":"periodo","in":"query","required":false,"description":"Padrão mes_atual; até 366 dias. Não se aplica a kit nem catálogo, que são o cadastro atual. Preset calculado no horário de Brasília: \"7d\" e \"30d\" incluem hoje. No lugar de `inicio` + `fim`, nunca junto.","schema":{"type":"string","enum":["hoje","ontem","7d","30d","mes_atual","mes_anterior"]}},{"name":"inicio","in":"query","required":false,"description":"Início do intervalo (inclusive), junto de `fim`.","schema":{"type":"string","format":"date"}},{"name":"fim","in":"query","required":false,"description":"Fim do intervalo (inclusive), junto de `inicio`.","schema":{"type":"string","format":"date"}},{"name":"sku","in":"query","required":false,"description":"Obrigatório e exclusivo de detalhe, anuncios e kit. Use codigo_produto da lista ou sku da ABC.","schema":{"type":"string","minLength":1,"maxLength":255}},{"name":"marketplace","in":"query","required":false,"description":"Somente resumo, lista e abc; rótulo exato do marketplace.","schema":{"type":"string","minLength":1,"maxLength":80}},{"name":"conta","in":"query","required":false,"description":"Somente resumo, lista e abc; apelido da conta, diferente do ID usado em GET /v1/ads/resumo.","schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"cnpj","in":"query","required":false,"description":"Somente resumo, lista e abc. CNPJ exato do cadastro da integração; não aceita raiz.","schema":{"type":"string","minLength":11,"maxLength":18}},{"name":"deslocamento","in":"query","required":false,"description":"Posição inicial, padrão 0. Use proximo_deslocamento da resposta com os mesmos filtros. Em detalhe pagina os pedidos.","schema":{"type":"integer","minimum":0,"maximum":1000000}},{"name":"limite","in":"query","required":false,"description":"Linhas por resposta, padrão 10, máximo 20. Pode ser reduzido pelo teto de 30 KB.","schema":{"type":"integer","minimum":1,"maximum":20}},{"name":"ordenar_por","in":"query","required":false,"description":"Exclusivo de lista. total_produtos significa faturamento; padrão total_produtos.","schema":{"type":"string","enum":["sku","descricao","total_produtos","quantidade","margem","lucro","cancelados","taxa_cancelamento","var_total_produtos_pct","var_quantidade_pct","var_margem_pp","acao"]}},{"name":"direcao","in":"query","required":false,"description":"Exclusivo de lista; padrão desc.","schema":{"type":"string","enum":["asc","desc"]}},{"name":"acao","in":"query","required":false,"description":"Exclusivo de lista. Filtra o campo acao original, não limiar.acao_ajustada.","schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"categoria","in":"query","required":false,"description":"Exclusivo de lista. Rótulo exato de visao=categorias, campo do_erp[].nome; é a folha da hierarquia, não o caminho.","schema":{"type":"string","minLength":1,"maxLength":255}},{"name":"marca","in":"query","required":false,"description":"Exclusivo de lista. Rótulo exato de visao=marcas, campo do_erp[].nome. Marca só existe no ERP.","schema":{"type":"string","minLength":1,"maxLength":255}},{"name":"fornecedor","in":"query","required":false,"description":"Exclusivo de lista. Nome de visao=fornecedores (do_erp ou data), ou o identificador quando a origem é Tiny, que não guarda nome.","schema":{"type":"string","minLength":1,"maxLength":255}},{"name":"metrica","in":"query","required":false,"description":"Exclusivo de abc; padrão faturamento.","schema":{"type":"string","enum":["faturamento","quantidade"]}},{"name":"comparar","in":"query","required":false,"description":"Exclusivo de anuncios; padrão true. Outras visões com comparativo o retornam conforme o contrato do serviço.","schema":{"type":"boolean"}},{"name":"incluir_serie_diaria","in":"query","required":false,"description":"Somente resumo/detalhe; padrão false. Reduza o período se a série exceder 30 KB.","schema":{"type":"boolean"}},{"name":"incluir_canais","in":"query","required":false,"description":"Somente resumo/detalhe; padrão false.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"O mesmo JSON que o assistente da Jodda recebe, com `avisos`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"type":"object","required":["avisos"],"properties":{"avisos":{"type":"array","items":{"type":"string"},"description":"Quando um número é parcial ou estimado. Guarde junto do dado."}},"additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Erro"},"401":{"$ref":"#/components/responses/Erro"},"403":{"$ref":"#/components/responses/Erro"},"404":{"$ref":"#/components/responses/Erro"},"429":{"$ref":"#/components/responses/Erro"},"500":{"$ref":"#/components/responses/Erro"},"502":{"$ref":"#/components/responses/Erro"},"503":{"$ref":"#/components/responses/Erro"}}}},"/ads/resumo":{"get":{"operationId":"resumo_ads","summary":"Análise de ADS","description":"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.","tags":["produtos"],"parameters":[{"name":"periodo","in":"query","required":false,"description":"Padrão: mes_atual. Preset calculado no horário de Brasília: \"7d\" e \"30d\" incluem hoje. No lugar de `inicio` + `fim`, nunca junto.","schema":{"type":"string","enum":["hoje","ontem","7d","30d","mes_atual","mes_anterior"]}},{"name":"inicio","in":"query","required":false,"description":"Início do intervalo (inclusive), junto de `fim`.","schema":{"type":"string","format":"date"}},{"name":"fim","in":"query","required":false,"description":"Fim do intervalo (inclusive), junto de `inicio`.","schema":{"type":"string","format":"date"}},{"name":"nivel","in":"query","required":false,"description":"Padrão: produto. Use cnpj → conta → produto → anuncio para aprofundar, ou campanha para avaliar campanhas.","schema":{"type":"string","enum":["cnpj","conta","produto","anuncio","campanha"]}},{"name":"cnpj","in":"query","required":false,"description":"Raiz de 8 dígitos ou CNPJ completo; agrupa todas as filiais da mesma raiz. Use a chave retornada em nivel=cnpj.","schema":{"type":"string","minLength":8,"maxLength":18}},{"name":"conta","in":"query","required":false,"description":"ID da loja, retornado em linhas[].chave no nivel=conta. Não é o apelido usado por GET /v1/filtros.","schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"sku","in":"query","required":false,"description":"SKU do produto; use a chave retornada em nivel=produto.","schema":{"type":"string","minLength":1,"maxLength":255}},{"name":"limite","in":"query","required":false,"description":"Máximo de linhas: 1 a 50, padrão 20. Totais não são limitados. Para explorar a cauda, filtre ou altere ordenar_por.","schema":{"type":"integer","minimum":1,"maximum":50}},{"name":"ordenar_por","in":"query","required":false,"description":"Ordem decrescente; padrão gasto. acos usa receita atribuída; participacao usa faturamento total. Em acos e receita_ads, linhas sem a métrica (como as da Amazon) vão para o fim.","schema":{"type":"string","enum":["gasto","acos","faturamento","receita_ads","participacao"]}}],"responses":{"200":{"description":"O mesmo JSON que o assistente da Jodda recebe, com `avisos`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"type":"object","required":["avisos"],"properties":{"avisos":{"type":"array","items":{"type":"string"},"description":"Quando um número é parcial ou estimado. Guarde junto do dado."}},"additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Erro"},"401":{"$ref":"#/components/responses/Erro"},"403":{"$ref":"#/components/responses/Erro"},"404":{"$ref":"#/components/responses/Erro"},"429":{"$ref":"#/components/responses/Erro"},"500":{"$ref":"#/components/responses/Erro"},"502":{"$ref":"#/components/responses/Erro"},"503":{"$ref":"#/components/responses/Erro"}}}},"/financas":{"get":{"operationId":"consultar_financas","summary":"Análise de Finanças","description":"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.","tags":["dre"],"parameters":[{"name":"periodo","in":"query","required":false,"description":"Padrão: mes_atual. Em visao=\"dre\", só o mês de início e o mês de fim do período contam (o dia é ignorado); a DRE é sempre por mês inteiro, desde set/2025. Preset calculado no horário de Brasília: \"7d\" e \"30d\" incluem hoje. No lugar de `inicio` + `fim`, nunca junto.","schema":{"type":"string","enum":["hoje","ontem","7d","30d","mes_atual","mes_anterior"]}},{"name":"inicio","in":"query","required":false,"description":"Início do intervalo (inclusive), junto de `fim`.","schema":{"type":"string","format":"date"}},{"name":"fim","in":"query","required":false,"description":"Fim do intervalo (inclusive), junto de `inicio`.","schema":{"type":"string","format":"date"}},{"name":"visao","in":"query","required":false,"description":"\"dre\" (padrão): a DRE como a tela mostra, com receita líquida, margem de contribuição, lucro líquido e indicadores de equilíbrio. \"movimentacoes\": lançamentos individuais de receita/despesa (descrição, categoria, status), sem os cálculos da DRE.","schema":{"type":"string","enum":["dre","movimentacoes"]}},{"name":"detalhar_categorias","in":"query","required":false,"description":"Só em visao=\"dre\". Detalha despesas e receitas confirmadas/previstas por categoria. Padrão: false.","schema":{"type":"boolean"}},{"name":"limite_categorias","in":"query","required":false,"description":"Só em visao=\"dre\" com detalhar_categorias=true. Máximo de categorias por lista; padrão 15, teto 30.","schema":{"type":"integer","minimum":1,"maximum":30}}],"responses":{"200":{"description":"O mesmo JSON que o assistente da Jodda recebe, com `avisos`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"type":"object","required":["avisos"],"properties":{"avisos":{"type":"array","items":{"type":"string"},"description":"Quando um número é parcial ou estimado. Guarde junto do dado."}},"additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Erro"},"401":{"$ref":"#/components/responses/Erro"},"403":{"$ref":"#/components/responses/Erro"},"404":{"$ref":"#/components/responses/Erro"},"429":{"$ref":"#/components/responses/Erro"},"500":{"$ref":"#/components/responses/Erro"},"502":{"$ref":"#/components/responses/Erro"},"503":{"$ref":"#/components/responses/Erro"}}}}},"components":{"securitySchemes":{"chave":{"type":"http","scheme":"bearer","bearerFormat":"jda_…","description":"Chave de API criada pelo titular da conta em Integrações → Extensão e API → API da Jodda. Vai no cabeçalho Authorization, nunca na URL."}},"headers":{"X-Request-Id":{"description":"Identifica a chamada para o suporte.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"Chamadas por minuto permitidas para a chave.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Quantas ainda restam no minuto.","schema":{"type":"integer"}}},"responses":{"Erro":{"description":"Erro com mensagem em português e um `code` estável. A integração decide pelo `code`, nunca pelo texto.","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","enum":["INVALID_PARAMS","UNAUTHENTICATED","ORG_MUDOU","ORG_AMBIGUA","API_NAO_LIBERADA","ASSINATURA_NECESSARIA","FORBIDDEN_PAGE","NOT_FOUND","RATE_LIMITED","INTERNAL","UPSTREAM_AUTH","UPSTREAM_UNAVAILABLE","TRANSIENT_DB"]}}}}}}}}}