API da Wivo Analytics

A API da Wivo permite acessar programaticamente dados de vendas, itens de pedidos, custos associados (comissões, fretes, promoções, publicidade), margens e métricas de rentabilidade disponíveis nos relatórios da plataforma.

Por onde começar? Se você vai integrar pela primeira vez, leia as seções 1 a 6 em ordem: elas levam você desde habilitar a API até deixar seus dados sincronizados. As seções 7 a 11 são a referência técnica que você vai consultar de vez em quando (parâmetros, campos, limites).

1. Principais casos de uso#

1. Integrar dados da Wivo em data warehouses, ERPs, sistemas contábeis ou ferramentas internas
2. Automatizar relatórios e painéis personalizados sem exportações manuais de arquivos

2. Dados disponíveis#

A API entrega informação em nível de item de pedido, que inclui:

• Detalhe do pedido (ID, data de compra, SKUs, tipo de envio, status de pedido e pagamento, comprador)
• Atributos do produto (marca, categoria, anúncio) e o seu catálogo interno do Mestre de produtos
• Custos do pedido (comissões, frete, logística)
• Custos adicionais (armazenamento fulfillment, publicidade)
• Métricas derivadas: rentabilidade, custos e percentuais. A Wivo calcula a rentabilidade em três escopos, conforme quais custos são descontados — os três chegam pela API, e estão explicados em Os três escopos de rentabilidade

3. Habilitar a API#

1. Acesse sua conta da Wivo com credenciais de administrador
2. Vá para “Integração API” no menu superior direito
3. Clique em “Solicitar habilitação da API”
4. Agende uma reunião com um representante da Wivo para a ativação
5. Receba sua API Key pessoal e confidencial

Vai enviar os pedidos da sua loja própria? A API de pedidos (beta) está incluída no plano Pro e não precisa desta habilitação: sua API Key está na tela Integración con API.

4. Autenticação#

Inclua sua API Key no header HTTP de cada requisição:

Ocp-Apim-Subscription-Key: SUA_API_KEY

Chaves inválidas ou ausentes retornam HTTP 401 Unauthorized. Se a sua conta não tiver o acesso à API de dados habilitado, ou a assinatura tiver sido revogada, retorna HTTP 403 Forbidden.

5. Sua primeira requisição#

Com a sua API Key pronta, faça esta requisição para confirmar que tudo funciona. Ela traz os itens de pedidos de uma faixa de datas:

curl "https://api.wivoanalytics.com/data?date=purchase_date&from=2025-01-01&to=2025-01-31&page=1" \
  -H "Ocp-Apim-Subscription-Key: SUA_API_KEY_AQUI"

A resposta é um JSON com duas partes:

• data — o array de itens de pedido (cada um com suas vendas, custos e rentabilidade). Veja o detalhe dos campos na seção 8.
• meta — informação de paginação. Observe totalPages: indica quantas páginas é preciso percorrer para trazer toda a faixa.

Com isso você já pode explorar os dados. Para uma integração de verdade, continue na seção 6 (como manter seus dados sincronizados) e use as seções 7 a 11 como referência do detalhe de cada parâmetro e campo.

6. Como sincronizar seus dados: fluxo histórico vs. fluxo regular#

Para uma integração real você terá dois fluxos: uma carga histórica (uma única vez, para trazer todo o passado) e um fluxo regular (recorrente, para se manter sincronizado).

Modelo mental — por que apagar e inserir (delete + insert): Um pedido não é imutável. Após a compra, ele pode mudar de status, ajustar custos, receber reembolsos ou ser cancelado. Por isso, cada vez que um pedido aparece na resposta, apague todos os seus itens no seu banco e insira-os completos de novo. Assim sua cópia sempre reflete o último estado da Wivo, sem duplicados nem dados antigos. O campo para agrupar os itens de um mesmo pedido é Orden.

6.1. Carga histórica (backfill inicial)#

Objetivo: trazer todo o histórico que o seu plano inclui, uma única vez.

Use date=purchase_date e pagine até esgotar a faixa. O campo meta.totalPages da resposta (ver seção 8) indica quantas páginas existem.

O ponto de partida é o início da janela que o seu plano inclui (ver seção 7.2). Dali em diante, um único intervalo paginado cobre todo o seu histórico: sem to, a janela vai até hoje.

desde_quando = inicio_da_janela_do_seu_plano()   # ver seção 7.2

page = 1
total_pages = 1                      # é atualizado com a primeira resposta
while page <= total_pages:
    resp = GET("/data", params={
        "date": "purchase_date",
        "from": desde_quando,
        "page": page,
        "limit": 1000,
    })
    salvar_com_delete_insert(resp["data"])   # apagar itens de cada Orden e reinserir
    total_pages = resp["meta"]["totalPages"]
    page += 1

# Guarde o maior "Fecha de actualización" (updated_at) que você tiver visto:
# é o ponto de partida do fluxo regular.

Peça páginas grandes e respeite o rate limit. Com limit=1000 você traz 10 vezes mais linhas por requisição do que com o mínimo, e o teto são 5 req/min (ver seção 10): cerca de 5.000 linhas por minuto. Adicione uma pausa entre páginas e retentativas com backoff exponencial diante de um HTTP 429.

6.2. Fluxo regular (incremental, por hora ou por dia)#

Objetivo: manter sua cópia sincronizada trazendo apenas o que mudou.

Use date=updated_at a partir da última data que você processou. Isso traz pedidos novos e atualizações (mudanças de status, ajustes de custo, cancelamentos, reembolsos):

last_synced = "2025-01-15T09:55:00"   # ← último updated_at processado, MENOS a janela de segurança

page = 1
total_pages = 1
while page <= total_pages:
    resp = GET("/data", params={
        "date": "updated_at",
        "from": last_synced,
        "page": page,
        "limit": 1000,
    })
    salvar_com_delete_insert(resp["data"])
    total_pages = resp["meta"]["totalPages"]
    page += 1

A janela se aplica à data de atualização: a resposta traz os subpedidos atualizados no intervalo, mesmo que tenham sido comprados antes. Um pedido comprado três meses atrás que hoje muda de status aparece na janela de hoje.

O alcance cobre as compras dos últimos 120 dias e vem declarado em cada resposta (ver seção 11).

Janela de segurança (recomendado): subtraia 5–10 min do seu último updated_at antes de pedir de novo. Se o último processado foi 2025-01-15T10:00:00, peça a partir de 2025-01-15T09:55:00. Isso evita perder mudanças por desvios de relógio ou latência. Como você reinsere por pedido completo, trazer um pedido de novo não gera duplicados.

Escolha janelas curtas. Uma janela de vários dias pode retornar várias páginas mesmo com limit=1000. Com o rate limit de 5 req/min (ver seção 10), sincronizar por hora é mais rápido e leve do que por dia.

Limite de 7 dias com updated_at: uma requisição não pode cobrir mais de 7 dias (ver seção 7.2). Se o seu processo ficou parado por mais de uma semana, avance em janelas de ≤7 dias até alcançar o presente.

7. Referência: endpoint e parâmetros#

7.1. Endpoint#

• GET /data — Retorna pedidos e itens de custos com todo o detalhe.

7.2. Parâmetros de GET /data#

• date (purchase_date ou updated_at): Você deve escolher um destes parâmetros (obrigatório)
• from: obrigatório, ISO 8601. Aceita 2025-01-31 ou 2025-01-31T09:55:00
• to: opcional, ISO 8601. Aceita 2025-02-01 ou 2025-02-01T18:30:00
• item_type: opcional. Filtra por tipo de linha: order, publication ou marketplace. Aceita vários valores separados por vírgula. Os apelidos orders e publications continuam válidos
• payment_status: opcional. Filtra por estado de pagamento: paid, unpaid ou noinformation. Aceita vários valores separados por vírgula
• item_status: opcional. Filtra por estado do pedido: paid, canceled ou returned. Aceita vários valores separados por vírgula
• page: opcional
• limit: opcional, tamanho de página. Padrão 1000, máximo 1000
• categories: opcional, lista separada por vírgulas: income, costs, reimbursement, products, orders, channels, internal-cost. Adiciona colunas a cada linha da resposta — medidas, atributos, ou ambos conforme a categoria — (ver seção 9). Se for omitido, retorna exatamente o conjunto base

Hora em from e to: se você enviar hora, ela é respeitada. Se enviar apenas a data, from é completado às 00:00:00 e to às 23:59:59 desse dia. O fuso em que são interpretados depende do campo que você filtra (ver seção 11).

Janela de datas que o seu plano inclui. O seu plano define desde quando você pode consultar:

Plano	Você pode consultar desde
Free	O dia 1º do mês anterior ao atual
Pro	1º de janeiro de dois anos atrás

Com purchase_date você pode pedir essa janela completa em uma única requisição e percorrê-la paginando com limit (o ritmo é dado pelo rate limit, ver seção 10).

Com date=updated_at uma requisição não pode cobrir mais de 7 dias, qualquer que seja o seu plano.

Um to posterior ao dia de hoje é recortado para hoje, porque além disso ainda não há dados. O valor efetivo vem em meta.to.

Um from anterior à janela do seu plano retorna HTTP 400 Bad Request, com o seu plano e a data a partir da qual você pode consultar na mensagem. A requisição falha por completo: não é devolvido um intervalo recortado, para que você possa distinguir um trecho que não entrou de um que veio vazio.

Um parâmetro inválido — data, intervalo excedido, ou um valor não reconhecido em item_type, payment_status ou item_status — retorna HTTP 400 Bad Request indicando qual valor foi rejeitado e quais são os válidos.

Um nome de parâmetro que não esteja nesta lista também retorna 400, com os nomes válidos na mensagem. É de propósito: se um parâmetro escrito errado fosse ignorado em silêncio, você receberia todas as linhas achando que filtrou.

Exemplos:

Com purchase_date:

curl "https://api.wivoanalytics.com/data?date=purchase_date&from=2025-01-01&to=2025-01-31&page=1" \
  -H "Ocp-Apim-Subscription-Key: SUA_API_KEY_AQUI"

Com updated_at:

curl "https://api.wivoanalytics.com/data?date=updated_at&from=2025-01-01T20:55:00" \
  -H "Ocp-Apim-Subscription-Key: SUA_API_KEY_AQUI"

7.3. Valores dos filtros e o que cada coluna retorna#

Os filtros são enviados com a chave em inglês. As colunas da resposta trazem o rótulo em espanhol.

unpaid é exibido como Informado. Antes essa coluna dizia No Pagado. O que mudou é o rótulo que viaja na resposta, não o contrato: o valor que você envia no filtro continua sendo payment_status=unpaid. Se o seu processo concilia comparando o texto da coluna Estado de Pago, ajuste-o para Informado; se ele filtra pela chave, não precisa mudar nada.

Atenção com item_status=paid: retorna os pedidos no estado Regular, ou seja, os que não foram cancelados nem devolvidos. Não tem relação com o estado de pagamento; para isso existe payment_status.

Os filtros são independentes entre si e se combinam com AND. Os valores dentro de um mesmo filtro se combinam com OR: payment_status=paid,unpaid traz as linhas que estejam em qualquer um dos dois estados.

O que traz uma linha marketplace#

São movimentos que o marketplace registra no nível da conta e não de uma venda específica: tarifas de armazenamento, cobranças de publicidade, encargos de faturamento, e também seus reembolsos e compensações.

O que caracteriza essas linhas:

• Ventas e Unidades vêm em 0
• SKU Producto vem em Sin SKU
• Producto traz a descrição que o marketplace dá ao movimento, exatamente como ele a escreve e no idioma dele: a Wivo não traduz nem normaliza esse texto. Um mesmo tipo de cobrança pode chegar como Tarifa pelo serviço de armazenamento Full de uma conta brasileira e como Cobro por Productos patrocinados de uma conta em espanhol. Não convém classificar por esse texto: para isso existe a medida de custo que acompanha a linha
• Costo de Marketplace traz o valor, junto com a medida da seção de custo correspondente
• Estado de Orden vem em Regular

Elas importam no cálculo de custos: trazem custo e não trazem vendas. Se você as excluir com item_type=order ou item_type=order,publication, esse custo não aparece na resposta. Quanto isso pesa depende da conta e do marketplace.

Pedir o mesmo recorte do painel de Rentabilidade#

A Wivo Analytics tem uma visão de Rentabilidade que mostra esses mesmos dados. Se você usa a plataforma e quer que seus números coincidam com os dessa visão, ou se simplesmente quer o recorte com o qual a Wivo calcula rentabilidade, é este: pedidos e publicações, no estado Regular, deixando de fora as linhas sem informação de pagamento.

Ele é pedido assim:

curl "https://api.wivoanalytics.com/data?date=purchase_date&from=2025-01-01&item_type=order,publication&payment_status=paid,unpaid&item_status=paid" \
  -H "Ocp-Apim-Subscription-Key: SUA_API_KEY_AQUI"

Esse recorte define quais linhas entram. Qual escopo de rentabilidade você quer ler define quais colunas você pede, e é adicionado com categories. Os três escopos — Marketplace, Comercial e Total — diferem pelos custos que descontam, e estão explicados em Os três escopos de rentabilidade:

Comercial e Total são pedidos com as mesmas categorias, então uma única requisição traz as colunas dos dois escopos de uma vez. Não é preciso pedi-los separadamente: você escolhe qual ler conforme a pergunta que estiver respondendo.

Se você comparar com a plataforma e os totais não baterem, revise também a janela de datas e o seu fuso horário (ver seção 11): é a causa mais frequente.

8. Estrutura de resposta de GET /data#

Exemplo simplificado:

{
  "data": [
    {
      "Canal": "Marketplace A",
      "Cuenta": "Cuenta Demo 1",
      "Orden": "1000000000000001",
      "Nro. suborden": "1000000000000001",
      "Nro. Paquete": "1000000000000001",
      "N° de Liquidación": "1000000000000001",
      "SKU Producto": "SKU-DEMO-001",
      "SKU Marketplace": "9000000000001",
      "Producto": "Producto Demostración 1 - Talla: L",
      "Variante": "Talla: L",
      "SKU Variante": "SKU-DEMO-001",
      "Fecha de actualización": "2024-01-11T06:26:29.000Z",
      "Estado de Orden": "Regular",
      "Estado de Pago": "Pagado",
      "Estado de Despacho": "Entregado",
      "Tipo de Despacho": "No Fulfillment",
      "Fecha de compra": "2024-01-09T23:56:56.000",
      "Tipo de Dato": "Orden",
      "Ventas": "7500",
      "Unidades": "1",
      "Costo de Marketplace": "1500.00",
      "Rentabilidad Marketplace": "6000.00",
      "% Rentabilidad Marketplace": "80.00",
      "Costo Envío": "1000",
      "Costo de Comisiones": "500"
    },
    {
      "Canal": "Marketplace A",
      "Cuenta": "Cuenta Demo 1",
      "Orden": "1000000000000002",
      "Nro. suborden": "1000000000000003",
      "Nro. Paquete": "1000000000000002",
      "N° de Liquidación": "1000000000000002",
      "SKU Producto": "SKU-DEMO-002",
      "SKU Marketplace": "9000000000002",
      "Producto": "Producto Demostración 2 - Talla: L Tamaño: 10.2",
      "Variante": "Color: Azul, Tamaño: 10.2",
      "SKU Variante": "SKU-DEMO-002",
      "Fecha de actualización": "2024-01-11T06:29:13.000Z",
      "Estado de Orden": "Regular",
      "Estado de Pago": "Pagado",
      "Estado de Despacho": "Entregado",
      "Tipo de Despacho": "Fulfillment",
      "Fecha de compra": "2024-01-09T23:56:43.000",
      "Tipo de Dato": "Orden",
      "Ventas": "12000",
      "Unidades": "1",
      "Costo de Marketplace": "4000.00",
      "Rentabilidad Marketplace": "8000.00",
      "% Rentabilidad Marketplace": "66.67",
      "Costo Envío": "2000",
      "Costo de Comisiones": "2000"
    }
    // ... aqui você pode continuar adicionando mais itens com os mesmos campos
  ],
  "meta": {
    "page": 1,
    "pageSize": 100,
    "count": 100,
    "from": "2024-01-09T00:00:00",
    "to": "2024-01-09T23:59:59",
    "date": "purchase_date",
    "totalRows": 3282,
    "totalPages": 33
  },
  "correlation_id": "00000000-0000-4000-8000-000000000001"
}

O objeto meta dá tudo o que você precisa para paginar: page (página atual), totalPages (total de páginas do intervalo) e totalRows (total de itens). Percorra de page=1 até totalPages para trazer o intervalo completo.

Este exemplo é a resposta padrão, a que você recebe se não enviar categories. Com esse parâmetro cada item chega com colunas adicionais — atributos do produto e do pedido, o detalhamento de custos, os escopos de rentabilidade — e o conjunto base não muda (ver seção 9).

Ele também traz window e fields, que declaram o fuso horário da janela e de cada campo de data (ver seção 11):

"meta": {
  "page": 1,
  "pageSize": 100,
  "count": 100,
  "from": "2024-01-09T00:00:00",
  "to": "2024-01-09T23:59:59",
  "date": "purchase_date",
  "totalRows": 3282,
  "totalPages": 33,
  "window": { "field": "purchase_date", "timezone": "local" },
  "fields": {
    "Fecha de compra": { "type": "datetime", "timezone": "local" },
    "Fecha de actualización": { "type": "datetime", "timezone": "UTC" }
  }
}

9. Colunas adicionais (categories)#

Por padrão, cada item de data traz um conjunto base: os atributos do pedido e do produto que você vê no exemplo da seção 8, mais 7 medidas.

Ventas, Unidades, Costo de Marketplace, Rentabilidad Marketplace, % Rentabilidad Marketplace, Costo Envío, Costo de Comisiones.

O parâmetro categories adiciona colunas a cada item de data: o detalhamento por trás desses totais, atributos adicionais do produto e do pedido, e os escopos de rentabilidade. Você pede uma ou mais categorias separadas por vírgula.

Uma categoria não significa “tudo o que é de X”. Significa “o que é de X e ainda não vem no conjunto base”. categories=channels adiciona Tipo de Canal, enquanto Canal e Cuenta continuam chegando sempre, você a peça ou não. Com as medidas acontece o mesmo: Ventas pertence a income e chega igual sem pedir nada.

O conjunto base sempre chega. Quaisquer que sejam as categorias pedidas, essas colunas aparecem com as mesmas chaves e os mesmos valores: categories apenas acrescenta, nunca remove nem renomeia.

Um mesmo pedido pode ocupar várias linhas, e duas delas podem coincidir em todas as colunas que você recebe e diferir apenas nos valores. Não use as colunas da resposta como chave única para deduplicar: você perderia registros.

Os percentuais são da linha, não da janela. % Costo Total ou % Rentabilidad Total são a taxa daquela linha sozinha. Para a taxa de um conjunto — um dia, uma marca, um canal — some os valores e faça a divisão você mesmo: a média dos percentuais das linhas dá outro número.

As colunas são identificadas pelo seu nome exato (o mesmo que aparece como chave no JSON). As chaves são em espanhol, independentemente do idioma. Se você pedir várias categorias e elas compartilharem alguma coluna, ela aparece uma única vez (não se duplica). Os totais Ventas e Costo de Marketplace já vêm no conjunto base; as categorias adicionam o detalhamento.

income — Receitas do pedido#

costs — Custos do marketplace#

Reflete a análise de custos da plataforma, agrupada por seção. O total de cada seção está em negrito.

Atenção ao total geral. Costo de Marketplace é o custo total do canal e as oito seções abaixo são o seu detalhamento. Se você precisa do total exato, use Costo de Marketplace diretamente em vez de somar as seções.

O detalhamento de comissões descreve a cobrança, não a substitui. Cobro de Comisiones e Reembolso de Comisiones são os totais que o marketplace informa; Comisión Variable, Comisión Fija e Comisión por Cuotas — com os seus três reembolsos — dizem do que eles se compõem. Para conciliar valores, use os totais.

Comissões: Cobro de Comisiones, Comisión Variable, Comisión Fija, Comisión por Cuotas, Reembolso de Comisiones, Reembolso de Comisión Variable, Reembolso de Comisión Fija, Reembolso de Comisión por Cuotas, Costo de Comisiones

Frete: Despacho pagado por comprador, Cobro Envío Flex, Ingreso por Envío Flex, Reembolso de envío, Cobro de Envío, Costo Envío

Publicidade: Cobro por publicidad, Reembolso por publicidad, Costos por publicidad

Armazenamento Fulfillment: Cobro por Costo Logístico, Reembolso de Costo Logístico, Cobro por Servicio Almacenamiento, Cobro por Almacenamiento Prolongado, Cobro por Descarte de Stock, Reembolso por servicio almacenamiento, Reembolso por descarte de stock, Reembolso por almacenamiento prolongado, Costos de Almacenamiento Fulfillment

Outros custos: Cobro de Ajuste sobre la Comisión, Reembolso de Ajuste sobre la Comisión, Cobro de Penalizacion por Cancelación, Devolución de Penalización por Cancelación, Cobro Logística Inversa, Reembolso Logística Inversa, Cobro de Penalización por Daños, Ingreso de Compensación por Daños, Reembolso de Ajuste sobre Venta, Ingreso por promoción, Cobros sin categorizar, Ingresos sin categorizar, Reembolsos sin categorizar, Cobro de Impuestos, Reembolso de Impuestos, Otros costos

Descontos e Promoções: Cobro por Cupones de Descuento, Reembolso por Cupones de Descuento, Costos de Descuentos y Promociones

Gestão de Conta: Cobro por Asesoría Comercial (KAM), Cobro por Uso de Mercado Pago, Cobro por Mantenimiento eShop, Cobro por Reputación, Cobro por Publicar, Reembolso por Asesoría Comercial (KAM), Reembolso por Uso de Mercado Pago, Reembolso por Mantenimiento eShop, Costos de Gestión de Cuenta

Financiamento: Cobro por Financiación y Cuotas Mercado Pago, Cobro por Adelanto de Dinero, Reembolso por Financiación y Cuotas Mercado Pago, Costos de Financiamiento

Total geral: Costo de Marketplace

Além do detalhamento por seção, costs traz os totais e as taxas da visão de Rentabilidade:

Totais da venda: Venta Cancelada, Cobro Total, Cobros Comercial

Custo por escopo: Costo de Marketplace (Marketplace), Costo Comercial (Comercial), Costo Total (Total)

Taxas: % Costo de Marketplace, % Costo Comercial, % Costo Total, % Cobro de Comisiones, % Costo de Comisiones, % Costo de Publicidad, % Costo Envío, % Costo Producto

O que cada escopo mede está explicado em Os três escopos de rentabilidade.

reimbursement — Reembolsos de cobranças#

products — Atributos do produto#

Producto, SKU Producto, SKU Marketplace, Variante e SKU Variante já vêm no conjunto base.

orders — Atributos do pedido#

Tipo de Despacho e Tipo de Despacho del Marketplace são duas colunas distintas, não dois nomes do mesmo dado. A primeira vem no conjunto base e distingue fulfillment de não fulfillment. A segunda chega com categories=orders e traz a modalidade que o marketplace declara.

Orden, Nro. suborden, Nro. Paquete, N° de Liquidación, Fecha de compra e os status já vêm no conjunto base.

channels — Atributos do canal#

Canal e Cuenta já vêm no conjunto base.

internal-cost — Catálogo interno e rentabilidade#

Traz o seu catálogo interno — o que você carrega no Mestre de produtos — e o custo de produto com as rentabilidades que dependem dele.

Os custos de cada escopo — Costo Comercial, Costo Total e as suas taxas — chegam com categories=costs.

Os três escopos de rentabilidade#

A Wivo calcula três rentabilidades sobre a mesma venda, e as três estão corretas ao mesmo tempo: o que muda é quais custos cada uma desconta. As três podem ser pedidas pela API.

Comercial é Total sem as quatro cobranças que não são consequência de ter vendido aquela unidade: publicidade, armazenamento fulfillment, gestão de conta e financiamento. Muitos vendedores as pagam de outro orçamento e precisam da rentabilidade do produto sem elas; no escopo Total elas continuam somando. As quatro chegam do mesmo jeito na resposta com categories=costs, cada uma na sua seção.

O que cada escopo significa para o seu negócio e quando convém usar cada um está em Tipos de rentabilidade na Wivo.

Como a rentabilidade se compõe#

Com categories=income,costs,reimbursement,internal-cost você recebe as quatro colunas que a formam, e pode reproduzir o cálculo linha por linha:

Rentabilidad Total     = Ingreso Total - Cobro Total      + Reembolso Total - Costo de Producto
Rentabilidad Comercial = Ingreso Total - Cobros Comercial + Reembolso Total - Costo de Producto

A única diferença entre as duas é a cobrança que subtraem: Cobros Comercial é Cobro Total sem essas quatro cobranças. A subtração entre as duas rentabilidades diz quanto elas pesam na linha.

Quando o custo de produto ainda não está carregado#

O custo de produto é você quem carrega na Wivo: o marketplace não o informa. Quando uma linha ainda não o tem carregado no Mestre de produtos, Costo de Producto chega em 0, não vazio. Esse 0 entra do mesmo jeito no cálculo, então Rentabilidad Comercial e Rentabilidad Total ficam mais altas do que serão depois que você carregar o custo.

Leve isso em conta antes de consolidar rentabilidade sobre um conjunto de linhas. A prática recomendada é cruzar o SKU Producto Interno de cada linha contra o seu próprio mestre de custos e decidir o que fazer com as que não encontrar — excluí-las, atribuir um custo ou revisá-las — em vez de somar tudo direto. Rentabilidad Marketplace não desconta o custo de produto, então não é afetada.

Exemplos#

curl "https://api.wivoanalytics.com/data?date=purchase_date&from=2025-01-01&to=2025-01-31&categories=income,costs" \
  -H "Ocp-Apim-Subscription-Key: SUA_API_KEY_AQUI"

Cada item de data chega com o conjunto base mais as colunas das categorias pedidas (em negrito as que aparecem apenas por causa de categories=income,costs):

{
  "Orden": "1000000000000001",
  "Ventas": "7500",
  "Unidades": "1",
  "Costo de Marketplace": "1500.00",
  "Rentabilidad Marketplace": "6000.00",
  "Ingreso Total": "7500.00",
  "Cobro de Comisiones": "500",
  "Costo de Comisiones": "500",
  "Cobro de Envío": "1000",
  "Costo Envío": "1000"
}

Com categories=products,orders,channels,internal-cost a mesma linha chega com os atributos do catálogo e os outros dois escopos de rentabilidade:

{
  "Orden": "1000000000000001",
  "Marca": "Marca Demostración",
  "Categoría": "Categoría Demostración",
  "Id publicación": "9000000000001",
  "Comprador": "Comprador Demostración",
  "Tipo de Despacho del Marketplace": "Envío a domicilio",
  "Tipo de Canal": "Marketplace",
  "Marca Interna": "Marca Interna Demostración",
  "Categoría Interna": "Categoría Interna Demostración",
  "Producto Interno": "Producto Interno Demostración",
  "SKU Producto Interno": "SKU-INT-001",
  "Ventas": "7500",
  "Costo de Producto": "3000",
  "Rentabilidad Comercial": "3300.00",
  "% Rentabilidad Comercial": "44.0",
  "Rentabilidad Total": "3000.00",
  "% Rentabilidad Total": "40.0"
}

Uma categoria inválida retorna HTTP 400 Bad Request.

10. Limites de uso (Rate limits)#

• 5 requisições por minuto por API Key
• 7.200 requisições por dia por API Key
• Exceder qualquer um dos dois retorna HTTP 429 Too Many Requests

Os dois limites são aplicados, não são uma recomendação. Com limit=1000 (ver seção 7.2), 5 requisições por minuto equivalem a cerca de 5.000 linhas por minuto, então o teto real da sua sincronização é dado pelo tamanho de página que você pedir: quanto maior, menos requisições você precisa para o mesmo dado.

Como boa prática, implemente retentativas com backoff exponencial e agrupe a lógica para aproveitar ao máximo cada requisição.

11. Datas e fusos horários#

A resposta traz dois campos de data, e cada um vem em um fuso diferente. Isso é importante para qualquer cálculo ou cruzamento com suas próprias fontes.

Com categories=orders soma-se uma terceira coluna de data, Fecha de Pago, no mesmo formato de Fecha de compra: sem designador de fuso. Trate-a com o mesmo critério.

Fecha de actualización#

Vem sempre em UTC, com o Z e com milissegundos. É o mesmo valor independentemente do campo pelo qual você filtra, então você pode interpretá-la diretamente como um instante.

Marca quando a Wivo atualizou esse registro por último, e é o campo usado como cursor do fluxo incremental da seção 6.2.

Fecha de compra#

Vem na hora local do canal de venda, sem designador de fuso. Não a interprete como UTC: a maioria dos parsers assume UTC quando falta o Z, e isso desloca a data em várias horas.

Como o fuso depende do canal, dois pedidos comprados no mesmo instante em canais de países diferentes trazem relógios diferentes neste campo. Se você precisa comparar instantes ou cruzar com fontes em UTC, use Fecha de actualización.

Fuso de from e to#

Eles são interpretados no mesmo fuso do campo que você está filtrando, e meta.window informa isso em cada resposta:

Com date=updated_at, o valor de Fecha de actualización que você recebe pode ser reenviado como from na requisição seguinte, sem conversão.

Alcance da busca por data de atualização#

Com date=updated_at, a resposta inclui os subpedidos cuja data de compra esteja dentro dos 120 dias anteriores ao início do intervalo consultado.

Cada resposta declara esse limite em meta.window.purchaseDateFrom:

"window": {
  "field": "updated_at",
  "timezone": "UTC",
  "purchaseDateFrom": "2026-04-16T00:00:00"
}

Para consultar compras anteriores a esse limite, use date=purchase_date com o intervalo que precisar.

Declaração na resposta#

O meta.fields declara o fuso de Fecha de compra e Fecha de actualización em cada resposta, com as mesmas chaves que você vê em data. Se a sua integração precisa verificar o formato antes de interpretar, leia dali em vez de assumir.