Análise Financeira

O que é

A API de Análise Financeira fornece uma visão contábil detalhada de cada pedido do marketplace Magalu. Seu objetivo é garantir transparência financeira global, consolidando em um único payload todas as movimentações de receita, despesa e subsídio aplicadas sobre cada item ou pedido.

Disponibilidade de Informações

A API retorna informações financeiras somente de pedidos com status Entregue e Cancelado, realizados a partir de 05/05/2026. Pedidos em outros status ou realizados antes desta data não estarão disponíveis para consulta.

Objetivos da API

A API foi projetada para atender simultaneamente aos seguintes objetivos:

• Fornecer visão detalhada de meios de pagamento utilizados em cada transação.
• Expor informações de impostos aplicados por item (ICMS, IOF, IMPORT_TAX e taxa de câmbio).
• Detalhar comissões e taxas cobradas pelo marketplace.
• Apresentar informações de promoções, cupons e descontos com separação do custo por parte (seller vs. subsídio Magalu).
• Indicar os valores líquidos a receber pelo seller após deduções.
• Possibilitar conciliação e planejamento fiscal — auditoria linha a linha por item, entrega e lote (batch_id).

Disponibilidade e Canal

Disponível para o canal Magalu — Magazine Luiza.

Tipagem das Transações

Toda transação retornada pela API possui um campo type que define seu comportamento contábil. Apenas CREDIT e DEBIT compõem o saldo final do pedido. O tipo INFORMATIVE é neutro e serve exclusivamente para auditoria, rastreabilidade fiscal e exibição ao seller.

Tipo	Sinal	Afeta Saldo?	Uso Típico
CREDIT	+	Sim	Receita de venda, subsídios, reembolso de MDR, co-participação de frete.
DEBIT	−	Sim	Comissões, tarifas, MDR, impostos retidos, frete pago pelo seller, estornos, descontos promocionais absorvidos pelo seller.
INFORMATIVE	(neutro)	Não	Impostos informativos (ICMS, IOF, IMPORT_TAX), flags operacionais. Exclusivo sellers internacionais.

Regra de Cálculo do Saldo

Saldo Líquido = SUM(CREDIT) − SUM(DEBIT)

• Ignore linhas com type = INFORMATIVE ao calcular o repasse.
• Valores monetários vêm como inteiros; divida por normalizer (tipicamente 100) para obter o decimal.

Estrutura do Relatório

A leitura do relatório segue uma hierarquia de três camadas que permite ao seller interpretar o pedido do resumo comercial até o detalhamento contábil de subsídios e promoções.

Camada 1 — Resumo Comercial e Operacional

Fornece a visão macro do pedido: valor de catálogo, descontos aplicados, comissão, tarifa fixa e a dinâmica de frete.

Elemento	Categoria / Campo	Tipo	Descrição
Valor total dos itens	SALE	CREDIT	Valor pago pelo cliente
Total de Descontos	DISCOUNT / PRODUCT	DEBIT	Somatório de descontos aplicados diretamente ao item.
Comissão	COMMISSION (SERVICE, TECHNOLOGY)	DEBIT	Comissão de serviço e de tecnologia do marketplace.
Tarifa Fixa	FEES / PLATFORM	DEBIT	Taxa fixa por item/pedido cobrada pela plataforma.
MDR	FEES / PAYMENT_PROCESSING	DEBIT	Intermediações financeiras sobre o valor do produto e do frete.
Frete (Logística Própria)	SHIPPING_COST / FREIGHT	CREDIT	Seller opera logística própria e recebe repasse do frete.
Frete (Logística Magalu)	SHIPPING_COST / FREIGHT	DEBIT	Magalu executa a logística e cobra o seller pelo serviço.

Camada 2 — Identificação de Campanhas (Promoções)

Detalha todas as promoções aplicadas no pedido. Cada promoção é identificada por campos que permitem conciliação com campanhas de marketing, programas de fidelidade ou integrações via Promo3P.

Campo	Descrição
identifier	Chave técnica que identifica univocamente a promoção no sistema (ex.: coupon_hash
description	Nome legível da campanha (ex.: ELETRO TEC E MÓVEIS — MENSAL JANEIRO — 4% + 6% PIX).
subcategory	Tipo da promoção: COUPON, PERCENTAGE_DISCOUNT, ABSOLUTE_DISCOUNT, FIDELITY_DISCOUNT, etc.

Camada 3 — Detalhamento Contábil (Par Débito/Crédito)

Camada de maior granularidade. Cada promoção e/ou subsídio é quebrado em um par de transações: um DEBIT identificando o custo absorvido pelo seller e um CREDIT identificando o subsídio coberto pelo Magalu. Isso permite a conciliação exata do quanto saiu do bolso de cada parte.

Papel	Tipo	Significado
Custo Seller	DEBIT	Parte da promoção/frete/subsídio absorvida pelo vendedor.
Subsídio Magalu	CREDIT	Parte da promoção/frete/subsídio custeada pelo marketplace e creditada ao seller.

Pedidos Internacionais (Cross Border)

Para sellers internacionais, a API expõe campos e subcategorias adicionais que não são retornados em pedidos nacionais. Isso garante o suporte tanto de operações domésticas quanto de operações transfronteiriças (Cross Border).

Elemento	Nacional	Internacional (Cross Border)
Categoria TAXES	Retorna ICMS e IOF (quando aplicável).	Adiciona IMPORT_TAX — imposto específico de importação (INFORMATIVE).
exchange_rate	Não retornado.	Retorna value, currency e normalizer com a cotação usada (ex.: USD → BRL).
Descrição de impostos	ICMS retido na fonte por UF.	IMPORT_TAX aplicado por item no desembaraço.

Exemplo — Bloco Cross Border (TAXES + exchange_rate)

{
  "exchange_rate": {
    "value": 576,
    "currency": "USD",
    "normalizer": 100
  },
  "transactions": [
    {
      "description": "ICMS",
      "type": "INFORMATIVE",
      "category": "TAXES",
      "subcategory": "ICMS",
      "value": 3785,
      "currency": "BRL",
      "normalizer": 100
    },
    {
      "description": "Importacao",
      "type": "INFORMATIVE",
      "category": "TAXES",
      "subcategory": "IMPORT_TAX",
      "value": 3779,
      "currency": "BRL",
      "normalizer": 100
    }
  ]
}

aviso

Transações INFORMATIVE da categoria TAXES são puramente informativas e não afetam o saldo líquido. Não as inclua no cálculo de repasse.

Aviso Crítico — Preço Promocional (Absolute Discount)

Risco de Bitributação

O desconto de ABSOLUTE_DISCOUNT (Preço Promocional) é aplicado antes da venda — o seller já ofertou o item com o valor descontado. Sellers devem desconsiderar os débitos desta promoção no cálculo de repasse para evitar bitributação, pois o valor já foi deduzido diretamente do preço do item antes da venda ser registrada. Este cuidado não se aplica aos demais tipos de promoção (COUPON, PERCENTAGE_DISCOUNT, FIDELITY_DISCOUNT), que seguem a lógica padrão de par Débito/Crédito da Camada 3.

Tabela de Categorias e Subcategorias

Lista completa dos valores suportados nos campos category e subcategory. As marcadas com ⭐ são exclusivas de sellers internacionais (Cross Border).

Categoria	Subcategoria	Contexto / Uso
SALE	PRODUCT	Receita total da venda do produto (CREDIT).
SHIPPING_COST	FREIGHT	Custo total do frete. Sinal varia por modelo logístico (CREDIT = logística própria / DEBIT = Magalu executa).
DISCOUNT	PRODUCT	Descontos aplicados diretamente ao item do pedido (DEBIT).
COMMISSION	SERVICE	Comissão referente ao serviço prestado.
	TECHNOLOGY	Comissão referente ao uso de tecnologia/plataforma.
	FREIGHT	Comissão sobre o frete.
FEES	PLATFORM	Tarifas da plataforma (taxa fixa por item/pedido).
	PAYMENT_PROCESSING	Tarifas de processamento de pagamento (MDR) sobre o produto.
	FREIGHT	MDR sobre o frete.
TAXES	ICMS	Impostos estaduais — INFORMATIVE. ⭐ Exclusivo Cross Border.
	IOF	Imposto sobre Operações Financeiras — INFORMATIVE. ⭐ Exclusivo Cross Border.
	IMPORT_TAX	Imposto de importação — INFORMATIVE. ⭐ Exclusivo Cross Border.
REFUND	ORDER	Valor principal do reembolso do pedido (DEBIT).
	PAYMENT	Reembolso de taxas de processamento (MDR).
	PENALTY	Retenção de comissão (multa operacional).
PROMOTION	COUPON	Promoções aplicadas via cupom. Par Débito/Crédito padrão.
	PERCENTAGE_DISCOUNT	Descontos percentuais via Promo3P. Par Débito/Crédito padrão.
	ABSOLUTE_DISCOUNT	Desconto de valor fixo absoluto. Ver Aviso Crítico — Preço Promocional (Absolute Discount) — cuidado com bitributação.
	FIDELITY_DISCOUNT	Descontos de programas de fidelidade. Par Débito/Crédito padrão.
MARKETPLACE	SHIPPING_SUBSIDY	Subsídio/co-participação de frete coberta pelo Marketplace (CREDIT).

Domínios da Solução

Domínio	Descrição
OrderResponse	Detalhamento completo do pedido, incluindo metadados e lista de transações.
Transaction	Detalhamento de uma transação financeira de um pedido.
TransactionEntity	Entidade (item ou ticket) relacionada à transação.
Seller	Informações do vendedor relacionadas ao pedido.
Channel	Informações do canal de venda.
PaginatedResponse	Retorno de buscas paginadas com metadados e lista de resultados.
PageMetadata	Informações da página atual (limit, offset, count) e links de navegação.

Detalhamento dos Campos

OrderResponse

Campo	Tipo	Descrição
id	String	Identificador único do registro de análise financeira.
external_id	String	Identificador externo do pedido (Order ID).
type	String	Tipo de análise financeira. Atualmente fixo como ORDER.
resource	String	URL de origem da informação no Marketplace.
exchange_rate	ExchangeRate	⭐ Cross Border. Taxa de câmbio aplicada (ex.: USD → BRL). Não retornado para sellers nacionais.
extras	Object	Metadados adicionais: order_code e order_date.
seller	Seller	Informações do vendedor (id e nome).
channel	Channel	Informações do canal de venda (id).
transactions	List<Transaction>	Lista detalhada das transações financeiras vinculadas ao pedido.

Transaction

Campo	Tipo	Descrição
batch_id	String	Identificador do lote de processamento. Agrupe por este campo para consolidar atualizações.
transaction_at	String (ISO 8601)	Data e hora em que a transação ocorreu.
created_at	String (ISO 8601)	Data e hora em que o registro da transação foi criado.
description	String	Descrição legível da operação financeira.
type	String	Tipo da transação: DEBIT, CREDIT, INFORMATIVE.
category	String	Categoria: SALE, DISCOUNT, COMMISSION, FEES, TAXES, SHIPPING_COST, PROMOTION, REFUND, MARKETPLACE.
subcategory	String	Subcategoria da transação. Ver Tabela de Categorias e Subcategorias para lista completa.
identifier	String	Identificador técnico da transação (ex.: sale_amount
value	Integer	Valor monetário em centavos. Divida por normalizer para obter o decimal.
currency	String	Moeda da transação (ex.: BRL).
normalizer	Integer	Divisor para conversão do inteiro para decimal. Tipicamente 100.
status	String	Status: ready, payment_requested, concluded.
entity	TransactionEntity	Entidade (item ou ticket) relacionada à transação.
extras	Object	Dados adicionais de promoções: origin (ex.: backoffice), list_price (preço de tabela).

TransactionEntity

Campo	Tipo	Descrição
id	String	Identificador da entidade.
type	String	Tipo: ITEM ou TICKET.
extras	Object	Detalhes: sku, name, quantity, delivery_id, protocol.

Seller

Campo	Tipo	Descrição
id	String	Identificador único do seller.
name	String	Nome do seller.

Channel

Campo	Tipo	Descrição
id	String	Identificador único do canal de venda.

PaginatedResponse

Campo	Tipo	Descrição
meta	PageMetadata	Metadados do resultado paginado.
results	List<OrderResponse>	Lista dos pedidos encontrados na busca.

PageMetadata

Campo	Tipo	Descrição
page	Object	Informações: limit, offset, count, max_limit.
links	Object	Links: previous, self, next.

Retenção de Comissão

A retenção de comissão (também denominada multa operacional) é exposta como flag informativa no objeto extras da transação ou do pedido. Ela não é materializada como DEBIT financeiro direto no payload e não afeta o saldo líquido do pedido no cálculo automático.

Comportamento esperado

Use a flag commission_retention_rate do extras para exibir ao seller que houve retenção de comissão, mas não a some no repasse. O valor financeiro correspondente já estará refletido em transações REFUND/PENALTY ou em ajustes posteriores de comissão.

Flag (extras)	Nível	Descrição
commission_retention_rate	Transação / Item	Percentual de comissão retido (retenção/multa operacional). Informativo — não debitar novamente.
order_code	Pedido	Código de referência comercial do pedido.
order_date	Pedido	Data da compra pelo consumidor final.
sku / name / quantity	Item	Identificação do item na transação.
delivery_id	Item	Identificador da entrega — usado para agrupar item + frete + impostos.
protocol	Ticket / Reembolso	Protocolo operacional de reembolso ou estorno.
origin	Promoção	Origem da promoção (ex.: backoffice).
list_price	Promoção	Preço de tabela do item antes da aplicação da promoção.

Resumo Operacional para Times Financeiros

• Consulte apenas pedidos com status Entregue — pedidos em outros status não retornam dados financeiros.
• Considere apenas transações com type = CREDIT ou type = DEBIT no cálculo de saldo.
• Divida value por normalizer para obter o decimal (ex.: 166440 / 100 = R$ 1.664,40).
• Agrupe transações por batch_id para consolidar lotes de atualização.
• Use entity.extras.delivery_id para reconciliar item + frete + impostos.
• Verifique o type da linha SHIPPING_COST antes de somar (varia por modelo logístico: CREDIT = logística própria, DEBIT = Magalu executa).
• Desconsidere DEBITs de ABSOLUTE_DISCOUNT no cálculo de repasse para evitar bitributação.
• Promoções dos tipos PERCENTAGE_DISCOUNT, COUPON e FIDELITY_DISCOUNT seguem o par Débito/Crédito padrão e devem ser incluídas normalmente no cálculo.
• Retenção de comissão em extras.commission_retention_rate é informativa — não debitar novamente.
• Para sellers internacionais: transações INFORMATIVE da categoria TAXES (ICMS, IOF, IMPORT_TAX) são apenas informativas — não afetam o saldo.

Escopos necessários

Para a utilização das APIs os seguintes escopos poderão ser necessários:

Valor	Descrição
open:order-financial-report-seller:read	Permite a consulta do relatório financeiro do seller.

Ambientes

Ambientes disponíveis: Ambientes