API Sales

Introdução

A API Sales ou API de Vendas é responsável por exibir todas as vendas que houveram em um determinado período, apresentado informações como status da venda, número único do pedido, método de pagamento, valor pago pelo consumidor, quem acolheu o pagamento do pedido, entre outras informações da venda relevantes para o contexto financeiro.

Atualização dos dados

As vendas são disponibilizadas na API no mesmo dia em que são realizadas. Os eventos associados a cada venda são apresentados no array orderEvents à medida que ocorrem.

Parâmetros de busca

A API é chamada utilizando os seguintes parâmetros:

merchantId: Id da loja
beginSalesDate: Data inicial da busca
endSalesDate: Data final da busca
page: Página inicial (1 por default), pois os itens são paginados

O retorno inclui todas as vendas realizadas pela loja no período especificado.

Principais campos e conceitos

Objeto saleGrossValue: O valor bruto da venda (ou GMV total) é composto por itens do pedido, entrega e taxa de serviço.

Fatores que compõem o valor bruto da venda	Definição	GMV	Existente em todo pedido?	Campo na API Sales correspondente
Itens do pedido	São produtos fornecidos pela loja parceira	GMV Loja	Sim.	`saleGrossValue.bag`
Entrega	Serviço de entrega que pode ser realizado tanto pelo iFood quanto pela loja parceira	GMV iFood ou GMV Loja, a depender de quem realizou o serviço	Não. Não há entrega quando o pedido foi retirado na loja pelo cliente.	`saleGrossValue.deliveryFee`
Taxa de serviço	Taxa cobrada do cliente pelo serviço de transação do pedido que foi realizada pelo iFood	GMV iFood	Não. A taxa de serviço iFood só é aplicada para alguns pedidos.	`saleGrossValue.serviceFee`

Podemos afirmar que os cálculos abaixo são corretos:Valor bruto da venda = itens do pedido + entrega + taxa de serviçoGMV total = GMV loja + GMV iFoodGMV loja = itens do pedido + entrega (quando realizada pela loja)GMV iFood = entrega (quando realizada pelo iFood) + taxa de serviçoObjeto benefitsOs benefícios são exibidos separadamente por aplicação (itens do pedido ou entrega) e por incentivador (iFood, loja, rede ou incentivador externo).Objeto deliveryContém detalhes da entrega, incluindo prestador do serviço (loja ou iFood), valor e benefícios aplicados.Objeto billingSumaryFornece um resumo financeiro atualizado do pedido no momento da consulta à API.O campo saleBalance indica o valor líquido a ser repassado à loja pelo pedido, já considerando eventuais cancelamentos, reembolsos ou ajustes de venda.O array billingEntries consolida todos os eventos financeiros relacionados ao pedido, agrupados por tipo de evento financeiro.Exemplo: Se um pedido teve um evento financeiro de comissão no valor de R$ 10,00 debitado da loja na venda e, posteriormente, o mesmo valor de comissão foi creditado à loja devido ao cancelamento do pedido, o resultado da soma de comissão será zero.Objeto paymentsContém informações sobre os métodos de pagamento utilizados no pedido, seus respectivos valores, recebedor do pagamento (loja ou iFood) e detalhes de parcelamento (quantidade e valor de cada parcela) caso tenha sido um pagamento parcelado pelo cliente.Array orderEventsApresenta a lista completa de eventos da venda, abrangendo também os eventos financeiros detalhados.

Todos os campos

Campo	Tipo	Descrição	Nulo
page	number	Número da página da consulta. Valores possíveis 0-pageCount.	Não
size	number	Tamanho de registros por página.	Não
beginSalesDate	string	Data de início do período de vendas, fornecida na query da API e levando em conta o timezone do merchant.	Não
endSalesDate	string	Data de término do período de vendas, informada na query da API, considerando o timezone do merchant.	Não
sales[]	list	Lista de vendas.	Sim
sales.id	string	Identificador do pedido.	Não
sales.shortId	number	Identificador curto do pedido.	Não
sales.createdAt	string	Data e hora em que o pedido foi criado, no fuso horário UTC.	Não
sales.type	string	Tipo da transação.	Não
sales.category	string	Categoria da venda.	Não
sales.salesChannel	string	Canal de vendas.	Não
sales.currentStatus	string	Status atual do pedido.	Não
sales.merchant.id	string	Identificador único do comerciante responsável pelo pedido.	Não
sales.merchant.shortId	number	ID curto do comerciante.	Não
sales.merchant.document[]	list	Lista de documentos associados ao comerciante.	Não
sales.merchant.document.value	string	Número do documento do comerciante.	Não
sales.merchant.document.type	string	Tipo do documento, por exemplo CNPJ, CPF.	Não
sales.merchant.name	string	Nome do estabelecimento.	Não
sales.merchant.type	string	Tipo do estabelecimento.	Não
sales.merchant.timezone	string	Fuso horário em que o estabelecimento opera.	Não
sales.saleGrossValue.bag	number	Valor bruto dos itens (bag) no pedido.	Não
sales.saleGrossValue.deliveryFee	number	Valor da taxa de entrega dentro de order (marketplace).	Não
sales.saleGrossValue.serviceFee	number	Valor da taxa de serviço cobrada do cliente.	Não
sales.benefits.benefits[]	list	Lista de benefícios usadas na order.	Sim
sales.benefits.benefits.target	string	Foco do benefício.	Sim
sales.benefits.benefits.sponsorships[]	list	Lista de sponsorships.	Sim
sales.benefits.benefits.sponsorships.name	string	Quem é o responsável pelo benefício.	Sim
sales.benefits.benefits.sponsorships.value	number	Valor monetário do benefício aplicado.	Sim
sales.benefits.benefits.totalValue	number	Valor total de todos os benefícios aplicados ao pedido.	Sim
sales.delivery.informationProvider.name	string	Nome do provedor que disponibiliza as informações de entrega.	Não
sales.delivery.type	string	Tipo de entrega.	Não
sales.delivery.deliveryParameters.logisticProvider	string	Nome do prestador logístico responsável pelo pedido.	Não
sales.delivery.deliveryParameters.deliveryProduct	string	Tipo de produto/serviço de entrega.	Não
sales.delivery.deliveryParameters.code	string	Código que identifica o tipo de entrega.	Não
sales.delivery.deliveryParameters.schedulingType	string	Tipo de agendamento.	Não
sales.delivery.prices.grossValue	number	Valor bruto.	Não
sales.delivery.prices.discount	number	Valor de descontos.	Não
sales.delivery.prices.netValue	number	Valor líquido.	Não
sales.payments.methods[]	list	Lista de métodos de pagamento.	Não
sales.payments.methods.method.wallet.name	string	Nome da carteira digital utilizada.	Sim
sales.payments.methods.method.method	string	Nome do método de pagamento.	Não
sales.payments.methods.method.currency	string	Moeda na qual o pagamento foi realizado.	Não
sales.payments.methods.method.type	string	Tipo de pagamento.	Não
sales.payments.methods.method.value	number	Valor pago.	Não
sales.payments.methods.method.cash.changeFor	number	Valor informado para troco em pagamentos em dinheiro.	Sim
sales.payments.methods.method.card.brand	string	Bandeira do cartão de crédito.	Sim
sales.payments.methods.method.installment.maxInstallments	number	Quantidade de vezes em que o pagamento foi parcelado.	Sim
sales.payments.methods.method.installment.installmentDetail[]	list	Detalhes do parcelamento.	Sim
sales.payments.methods.method.installment.installmentDetail.reference	string	Número identificador (sequencial) da parcela.	Sim
sales.payments.methods.method.installment.installmentDetail.amount	number	Valor monetário de cada parcela.	Sim
sales.payments.methods.method.liability	string	Entidade responsável pelo método de pagamento.	Não
sales.payments.methods.method.transaction.nsu	string	Número de identificação único atribuído a cada transação realizada com um cartão de crédito ou débito	Sim
sales.payments.methods.method.transaction.acquirerDocument	string	Documento da adquirente	Sim
sales.payments.methods.method.refundType	string	Tipo de estorno realizado	Sim
sales.orderStatusHistory[]	list	Lista de status de order.	Sim
sales.orderStatusHistory.value	string	Valor do status histórico do pedido.	Sim
sales.orderStatusHistory.createdAt	string	Data e hora em que esse status foi atribuído.	Sim
sales.orderStatusHistory.metadata	map<string,object>	Informações adicionais do status da order.	Sim
sales.billingSummary.saleBalance	number	Soma dos valores (amounts) das entradas financeiras do evento FINANCIAL_BILLED_ORDER_ENTRY mais recente, exceto aquelas cujo nome de entrada seja STORE_SUBSIDY.	Não
sales.billingSummary.billingEntries[]	list	Lista de entradas Financeiras.	Sim
sales.billingSummary.billingEntries.name	string	Nome que classifica cada entrada financeira.	Sim
sales.billingSummary.billingEntries.value	number	Quantia correspondente à entrada financeira.	Sim
sales.orderEvents[]	list	Lista de eventos de order.	Sim
sales.orderEvents.id	string	Identificador único do evento no histórico.	Sim
sales.orderEvents.fullCode	string	Código completo do evento.	Sim
sales.orderEvents.code	string	Código derivado do valor do evento (ex.: “FBOE” para FINANCIAL_BILLED_ORDER_ENTRY).	Sim
sales.orderEvents.createdAt	string	Data e hora em que o evento foi registrado.	Sim
sales.orderEvents.metadata	string	Metadata do evento.	Sim
total	number	Quantidade total de vendas localizadas no período consultado.	Não
pageCount	number	Número total de páginas necessárias para exibir todas as vendas (total / size).	Não

Casos de uso

Pedido com pagamento parcelado:

{
  "page": 0,
  "size": 15,
  "beginSalesDate": "2025-02-20",
  "endSalesDate": "2025-02-21",
  "sales": [
    {
      "id": "f1e509a0-030c-458b-b902-282837260321",
      "shortId": "2247",
      "createdAt": "2025-02-20T20:41:25.611Z",
      "type": "ORDER",
      "category": "GROCERY",
      "salesChannel": "IFOOD",
      "currentStatus": "CONCLUDED",
      "merchant": {
        "id": "f07d23bd-74fc-47fa-9abf-2889e8127c00",
        "shortId": 1790358,
        "documents": [
          {
            "value": "999999999999",
            "type": "CPF"
          },
          {
            "value": "9999999999999",
            "type": "CNPJ"
          }
        ],
        "name": "Farmácia do Zé",
        "type": "PHARMACY",
        "timezone": "Etc/GMT+3"
      },
      "saleGrossValue": {
        "bag": 207.86,
        "deliveryFee": 8.99,
        "serviceFee": -0.99
      },
      "benefits": {
        "benefits": [
          {
            "target": "ITEM",
            "value": 3,
            "sponsorships": [
              {
                "name": "IFOOD",
                "value": 3
              }
            ]
          },
          {
            "target": "DELIVERY_FEE",
            "value": 8.99,
            "sponsorships": [
              {
                "name": "CHAIN",
                "value": 5
              },
              {
                "name": "IFOOD",
                "value": 3.99
              }
            ]
          }
        ],
        "totalValue": 11.99
      },
      "delivery": {
        "informationProvider": {
          "name": "DELIVERY_OFFER"
        },
        "type": "DELIVERY",
        "deliveryParameters": {
          "logisticProvider": "IFOOD_LOGISTICS",
          "deliveryProduct": "FULL_SERVICE_COMPLETE_AREA",
          "code": "DEFAULT",
          "schedulingType": "IMMEDIATE"
        },
        "prices": {
          "grossValue": 8.99,
          "discount": 8.99,
          "netValue": 0
        }
      },
      "payments": {
        "methods": [
          {
            "method": "CREDIT",
            "currency": "BRL",
            "type": "ONLINE",
            "value": 205.85,
            "card": {
              "brand": "MASTERCARD"
            },
            "installment": {
              "maxInstallments": 3,
              "installmentDetail": [
                {
                  "reference": "1",
                  "amount": 68.61
                },
                {
                  "reference": "2",
                  "amount": 68.62
                },
                {
                  "reference": "3",
                  "amount": 68.62
                }
              ]
            },
            "liability": "IFOOD"
          }
        ]
      },
      "orderStatusHistory": [
        {
          "value": "CONCLUDED",
          "createdAt": "2025-02-20T21:29:12.396Z"
        },
        {
          "value": "ARRIVED",
          "createdAt": "2025-02-20T21:27:41.627Z"
        },
        {
          "value": "DISPATCHED",
          "createdAt": "2025-02-20T21:10:39.219Z"
        },
        {
          "value": "SEPARATION_ENDED",
          "createdAt": "2025-02-20T21:07:33.055Z"
        },
        {
          "value": "SEPARATION_STARTED",
          "createdAt": "2025-02-20T20:42:50.807Z"
        },
        {
          "value": "CONFIRMED",
          "createdAt": "2025-02-20T20:41:28.539Z"
        },
        {
          "value": "PLACED",
          "createdAt": "2025-02-20T20:41:27.750Z"
        },
        {
          "value": "CREATED",
          "createdAt": "2025-02-20T20:41:26.292Z"
        }
      ],
      "billingSummary": {
        "saleBalance": 191.23,
        "billingEntries": [
          {
            "name": "DELIVERY_FEE_IFOOD",
            "value": -8.99
          },
          {
            "name": "ORDER_PAYMENT",
            "value": 205.85
          },
          {
            "name": "SERVICE_FEE",
            "value": -0.99
          },
          {
            "name": "ORDER_COMMISSION",
            "value": -16.63
          },
          {
            "name": "CHAIN_SUBSIDY",
            "value": 5
          },
          {
            "name": "IFOOD_SUBSIDY",
            "value": 6.99
          }
        ]
      },
      "orderEvents": [
        {
          "id": "23dc558e-dbb5-495b-90c8-0379ce00ae5f",
          "fullCode": "FINANCIAL_BILLED_ORDER_ENTRY",
          "code": "FBOE",
          "createdAt": "2025-02-20T23:30:00.020Z",
          "metadata": {
            "entries": [
              {
                "triggerEventName": "ORDER_CONCLUDED",
                "summaryKey": "deliveryFee",
                "amount": -8.99,
                "financialEntryName": "DELIVERY_FEE_IFOOD",
                "expectedPaymentDate": "2025-03-19",
                "billedDate": "2025-02-20T21:29:12.761727Z"
              },
              {
                "amount": 68.62,
                "financialEntryName": "ORDER_PAYMENT",
                "expectedPaymentDate": "2025-05-21",
                "feeBaseValue": "205.85",
                "triggerEventName": "ORDER_CONCLUDED",
                "summaryKey": "payment",
                "billedDate": "2025-02-20T21:29:12.761727Z"
              },
              {
                "amount": 68.62,
                "financialEntryName": "ORDER_PAYMENT",
                "expectedPaymentDate": "2025-04-16",
                "feeBaseValue": "205.85",
                "triggerEventName": "ORDER_CONCLUDED",
                "summaryKey": "payment",
                "billedDate": "2025-02-20T21:29:12.761727Z"
              },
              {
                "amount": 68.61,
                "financialEntryName": "ORDER_PAYMENT",
                "expectedPaymentDate": "2025-03-19",
                "feeBaseValue": "205.85",
                "triggerEventName": "ORDER_CONCLUDED",
                "summaryKey": "payment",
                "billedDate": "2025-02-20T21:29:12.761727Z"
              },
              {
                "amount": -0.99,
                "financialEntryName": "SERVICE_FEE",
                "expectedPaymentDate": "2025-03-19",
                "feeBaseValue": "-0.99",
                "triggerEventName": "ORDER_CONCLUDED",
                "summaryKey": "serviceFee",
                "billedDate": "2025-02-20T21:29:12.761727Z"
              },
              {
                "amount": -16.63,
                "financialEntryName": "ORDER_COMMISSION",
                "feePercentage": "8",
                "expectedPaymentDate": "2025-03-19",
                "feeBaseValue": "207.86",
                "triggerEventName": "ORDER_CONCLUDED",
                "summaryKey": "commission",
                "billedDate": "2025-02-20T21:29:12.761727Z"
              },
              {
                "amount": 5,
                "financialEntryName": "CHAIN_SUBSIDY",
                "expectedPaymentDate": "2025-03-19",
                "feeBaseValue": "5",
                "triggerEventName": "ORDER_CONCLUDED",
                "summaryKey": "subsidy",
                "billedDate": "2025-02-20T21:29:12.761727Z"
              },
              {
                "amount": 3.99,
                "financialEntryName": "IFOOD_SUBSIDY",
                "expectedPaymentDate": "2025-03-19",
                "feeBaseValue": "3.99",
                "triggerEventName": "ORDER_CONCLUDED",
                "summaryKey": "subsidy",
                "billedDate": "2025-02-20T21:29:12.761727Z"
              },
              {
                "amount": 3,
                "financialEntryName": "IFOOD_SUBSIDY",
                "expectedPaymentDate": "2025-03-19",
                "feeBaseValue": "3",
                "triggerEventName": "ORDER_CONCLUDED",
                "summaryKey": "subsidy",
                "billedDate": "2025-02-20T21:29:12.761727Z"
              }
            ]
          }
        },
        {
          "id": "868c6c84-d23c-4724-928d-14becd1d2c68",
          "fullCode": "DELIVERY_DROP_CODE_VALIDATION_SUCCESS",
          "code": "DDCS",
          "createdAt": "2025-02-20T21:28:53.946Z"
        },
        {
          "id": "2c5ef52e-6d58-42e3-81f1-fedab285db68",
          "fullCode": "DELIVERY_ARRIVED_AT_DESTINATION",
          "code": "DAAD",
          "createdAt": "2025-02-20T21:27:39.469Z"
        },
        {
          "id": "7e0a1b41-4473-4910-bca8-aaf564054102",
          "fullCode": "DELIVERY_COLLECTED",
          "code": "DCLT",
          "createdAt": "2025-02-20T21:10:37.064Z"
        },
        {
          "id": "53aa3bca-43bb-4fd1-8b4b-9577929858df",
          "fullCode": "READY_TO_DELIVER",
          "code": "RTD",
          "createdAt": "2025-02-20T21:07:33.301Z"
        },
        {
          "id": "5d01194c-b572-4d35-a62c-941bcc3c93b4",
          "fullCode": "DELIVERY_ARRIVED_AT_ORIGIN",
          "code": "DAAO",
          "createdAt": "2025-02-20T21:06:29.907Z"
        },
        {
          "id": "80b52f34-c75f-4490-8e50-8c6097672f0d",
          "fullCode": "DELIVERY_DROP_CODE_REQUESTED",
          "code": "DDCR",
          "createdAt": "2025-02-20T20:57:08.120Z"
        },
        {
          "id": "97d0b7c8-2a68-4027-845a-f103fec388cc",
          "fullCode": "DELIVERY_ACCEPTED",
          "code": "DADR",
          "createdAt": "2025-02-20T20:57:06.057Z"
        },
        {
          "id": "39800f0e-b22b-4655-bb80-ee19a4d5a75e",
          "fullCode": "DELIVERY_GOING_TO_ORIGIN",
          "code": "DGTO",
          "createdAt": "2025-02-20T20:57:06.093Z"
        },
        {
          "id": "28438232-0bb4-488f-be74-c23ec7005697",
          "fullCode": "DELIVERY_GROUP_ASSIGNED",
          "code": "DGA",
          "createdAt": "2025-02-20T20:57:06.050Z"
        }
      ]
    }
  ]
}

Esta página foi útil?

Avalie sua experiência no novo Developer portal:

Nesta página