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.

Principais casos de uso

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

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)
Custos do pedido (comissões, frete, logística)
Custos adicionais (armazenamento fulfillment, publicidade)
Métricas derivadas (rentabilidade, percentual de rentabilidade)

Processo de habilitação

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

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.

Limites de uso (Rate limits)

5 requisições por minuto por conta
5.000 requisições por dia (recomendado)
Exceder os limites retorna HTTP 429 Too Many Requests

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

5. Os dados que a API entrega

5.1. Endpoints principais

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

5.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, ex: 2025-01-31
to: opcional, ISO 8601, ex: 2025-02-01
page: opcional

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"

5.3. Estrutura de resposta de `GET /data`

Exemplo simplificado:

{
  "data": [
    {
      "Canal": "Marketplace A",
      "Cuenta": "Cuenta Demo 1",
      "Orden": "1000000000000001",
      "Nro. suborden": "1000000000000001",
      "SKU Producto": "SKU-DEMO-001",
      "Producto": "Producto Demostración 1 - Talla: L",
      "Variante": "Talla: L",
      "Fecha de actualización": "2024-01-11T06:26:29.000",
      "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",
      "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",
      "SKU Producto": "SKU-DEMO-002",
      "Producto": "Producto Demostración 2 - Talla: L Tamaño: 10.2",
      "Variante": "Color: Azul, Tamaño: 10.2",
      "Fecha de actualización": "2024-01-11T06:29:13.000",
      "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",
      "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"
  }
}

6. Como usar a API - Fluxo histórico vs fluxo regular

Normalmente você terá dois fluxos de uso de dados: (1) fluxo histórico para a carga inicial de dados e (2) fluxo regular para manter os dados sincronizados.

6.1. Fluxo histórico (backfill inicial)

Objetivo: carregar todo o histórico disponível da Wivo para o seu sistema.

Recomendações:

Definir faixa de datas ampla: Por exemplo, de 2020-01-01 até a data atual.
Usar paginação: Iterar por page até cobrir toda a faixa.
Salvar com lógica de delete+insert: No seu banco de dados, apague os pedidos e insira-os novamente.
Registrar o último purchase_date e updated_at processados: Isso servirá depois para o fluxo incremental.

6.2. Fluxo regular (incremental diário / horário)

Objetivo: manter seus dados sincronizados com a Wivo.