--- title: Análise Financeira --- # 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. :::info Disponibilidade de Informações A partir de 19/08/2026 a API irá disponibilizar informações financeiras para os pedidos à partir do pagamento com status de "Pagamento Aprovado". ::: ### 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|SKU|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) ```json { "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 } ] } ``` :::warning 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. ::: ## Compliance com o BACEN Para atender às exigências regulatórias do **Banco Central do Brasil (BACEN)**, as transações financeiras possuem um campo chamado `res_514_bacen` no objeto `extras`, **sempre retornado como lista**. Se a transação de origem vier como um objeto único, ela é automaticamente envelopada em uma lista de um elemento. Os seguintes campos são expostos dentro de cada objeto da lista `res_514_bacen`: * **id da transação (`external_id`)**: O identificador externo da transação (ex.: ID do pagamento no gateway ou adquirente). * **método de pagamento (`payment_method`)**: O meio eletrônico ou método de pagamento utilizado (ex.: `credit_card`, `debit_card`, `pix`, `boleto`). * **bandeira (`brand`)**: A bandeira/flag do cartão utilizado no pagamento (ex.: `visa`, `mastercard`, `elo`), aplicável quando o método é cartão. * **antecipação automática (`auto_anticipate`)**: Flag indicando se a transação passou por antecipação automática de recebíveis. :::info Sempre uma lista `extras.res_514_bacen` é sempre uma lista de objetos. Se a fonte enviou um objeto único, o sistema o envelopa automaticamente em `[...]`. ::: ### Exemplo — Bloco de Extras com Compliance BACEN ```json { "extras": { "res_514_bacen": [ { "external_id": "txn_credit_001", "payment_method": "credit_card", "brand": "visa", "auto_anticipate": true } ] } } ``` ## Aviso Crítico — Preço Promocional (Absolute Discount) :::warning 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)](#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\ | 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](#tabela-de-categorias-e-subcategorias) para lista completa. | | identifier | String | Identificador técnico da transação (ex.: sale\_amount|ITEM\_ID|DELIVERY\_ID). | | 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 | Metadados adicionais da transação: dados de promoções (origin, list\_price) e campos de compliance com o BACEN envelopados no objeto ou array `res_514_bacen` (external\_id, payment\_method, brand, auto\_anticipate). | ### 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\ | 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. :::info 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. | | res\_514\_bacen | Transação | **Sempre uma lista** de objetos com campos de compliance BACEN (`external_id`, `payment_method`, `brand`, `auto_anticipate`). Objetos únicos recebidos na origem são automaticamente envelopados em lista. | ## 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](/docs/first-steps/environment)