API pública

A API pública do Fullmetrix devolve as suas métricas de vendas sob a forma de tabela, em formato JSON. Use-a para alimentar uma ferramenta interna, uma folha de cálculo automatizada, um armazém de dados ou um painel à medida. O conector do Looker Studio assenta nela.

Uma API é um endereço web que um programa consulta em vez de um navegador. Envia um pedido que diz o que quer, por exemplo a receita diária do mês passado, e o Fullmetrix responde com os números.

A API é só de leitura. Não pode alterar nada no Fullmetrix nem na sua loja.

Crie uma chave APICopy Anchor Link

Cada pedido tem de levar uma chave API. A chave identifica a organização cujos dados lê. Não há mais nada a configurar.

A lista de chaves mostra, para cada chave, o Nome, o Prefixo, a data de criação em Criada e a Última utilização. Esta última coluna ajuda a detetar uma chave que já ninguém usa. Para cortar o acesso de uma chave, clique em Revogar e confirme. Qualquer integração que a use deixa de funcionar de imediato. Este ecrã é tratado em pormenor em Chaves API.

Crie uma chave por ferramenta. Se tiver de cortar o acesso a uma, as outras continuam a funcionar.

Autentique-seCopy Anchor Link

O endereço base da API é https://app.fullmetrix.com. Cada pedido leva a chave no cabeçalho Authorization, depois da palavra Bearer.

curl https://app.fullmetrix.com/api/reports/catalog \
  -H "Authorization: Bearer fmx_YOUR_KEY"

As chaves funcionam durante o período de teste gratuito e durante a subscrição. Se a subscrição da organização terminar, os pedidos são recusados até ser retomada.

Liste os campos disponíveisCopy Anchor Link

GET /api/reports/catalog devolve as dimensões e as métricas que pode pedir. Uma dimensão é uma forma de repartir os dados, como a data ou o país. Uma métrica é um número calculado, como o número de encomendas.

curl https://app.fullmetrix.com/api/reports/catalog \
  -H "Authorization: Bearer fmx_YOUR_KEY"

{
  "dimensions": [
    { "id": "date", "label": "Date", "type": "date" },
    { "id": "store", "label": "Boutique", "type": "string" },
    { "id": "country", "label": "Pays", "type": "string" },
    { "id": "customer_type", "label": "Type client", "type": "string" },
    { "id": "status", "label": "Statut commande", "type": "string" }
  ],
  "metrics": [
    { "id": "orders", "label": "Commandes", "type": "number" },
    { "id": "items_sold", "label": "Produits vendus", "type": "number" },
    { "id": "gross_sales", "label": "CA brut", "type": "currency" },
    { "id": "net_revenue", "label": "CA net", "type": "currency" },
    { "id": "average_order_value", "label": "Panier moyen", "type": "currency" },
    { "id": "taxes", "label": "Taxes", "type": "currency" },
    { "id": "shipping", "label": "Livraison", "type": "currency" },
    { "id": "unique_customers", "label": "Clients uniques", "type": "number" },
    { "id": "new_customers", "label": "Nouveaux clients", "type": "number" },
    { "id": "returning_customers", "label": "Clients récurrents", "type": "number" }
  ]
}

Os valores de label são devolvidos em francês. Use os valores de id nos seus pedidos.

Esta chamada é também uma forma de verificar se uma chave funciona. Responde com o estado 200 quando a chave é válida.

DimensõesCopy Anchor Link

MétricasCopy Anchor Link

Os montantes estão na moeda das suas lojas e arredondados a duas casas decimais. Os números seguem as suas definições dos relatórios, incluindo os estados excluídos e as deduções das vendas líquidas.

Consulte as suas métricasCopy Anchor Link

GET /api/reports/tabular devolve uma tabela de linhas. Cada linha combina as dimensões pedidas com as métricas calculadas para essa combinação.

ParâmetrosCopy Anchor Link

O período pedido pode abranger até dois anos. Para além disso, a API encurta-o mantendo a data de fim, e a resposta mostra as datas realmente usadas em from e to.

As datas from e to são lidas em tempo universal, da meia-noite à meia-noite UTC. O parâmetro timezone só altera o dia apresentado para cada encomenda. Por volta da meia-noite, algumas encomendas podem por isso ficar um dia desfasadas em relação aos seus relatórios do Fullmetrix.

Exemplo, receita por diaCopy Anchor Link

curl "https://app.fullmetrix.com/api/reports/tabular?dimensions=date&metrics=orders,net_revenue&from=2026-09-01&to=2026-09-30&timezone=Europe/Paris" \
  -H "Authorization: Bearer fmx_YOUR_KEY"

{
  "dimensions": ["date"],
  "metrics": ["orders", "net_revenue"],
  "from": "2026-09-01",
  "to": "2026-09-30",
  "timezone": "Europe/Paris",
  "rows": [
    { "date": "2026-09-01", "orders": 42, "net_revenue": 2318.4 },
    { "date": "2026-09-02", "orders": 37, "net_revenue": 1975.1 }
  ],
  "rowCount": 30
}

As linhas são ordenadas pela ordem das dimensões pedidas. rowCount indica o número de linhas devolvidas.

Exemplo, vendas por país e tipo de clienteCopy Anchor Link

curl "https://app.fullmetrix.com/api/reports/tabular?dimensions=country,customer_type&metrics=orders,net_revenue,average_order_value&from=2026-07-01&to=2026-09-30" \
  -H "Authorization: Bearer fmx_YOUR_KEY"

Exemplo, totais de um períodoCopy Anchor Link

Sem dimensão, a resposta contém uma única linha.

curl "https://app.fullmetrix.com/api/reports/tabular?metrics=orders,gross_sales,net_revenue,new_customers&from=2026-01-01&to=2026-09-30" \
  -H "Authorization: Bearer fmx_YOUR_KEY"

Exemplo, compare as suas lojasCopy Anchor Link

curl "https://app.fullmetrix.com/api/reports/tabular?dimensions=store&metrics=orders,net_revenue&from=2026-09-01&to=2026-09-30" \
  -H "Authorization: Bearer fmx_YOUR_KEY"

Códigos de resposta e errosCopy Anchor Link

Os erros devolvem um objeto JSON com um campo error que descreve o problema.

Exemplo de resposta 400 para uma métrica desconhecida.

{
  "error": "Dimensions ou métriques inconnues",
  "unknownDimensions": [],
  "unknownMetrics": ["revenue"]
}

Com um código 429, a resposta traz também os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Espace as suas chamadas e guarde os resultados que não mudam, como os dias passados.

Uma resposta bem-sucedida pode ser servida a partir de uma cache durante um minuto. Duas chamadas idênticas feitas em sequência devolvem por isso o mesmo resultado.

A API aceita chamadas vindas de um navegador, mas lembre-se de que a chave nunca deve ser exposta numa página pública.

Perguntas frequentesCopy Anchor Link