API do Fluv Hub: pedidos, produtos, fotos e estoque

Visão geral

São três endereços. O mesmo token serve para os três; o de produtos e o de estoque só funcionam depois de ligados no cartão da loja.

Endereço base: https://fluvhub.com/sistema/apps/lojas_virtuais/api

Começar em 3 passos

1. Crie a conexão. No Fluv Hub, vá em Lojas & Marketplaces › Conectar conta › Loja virtual e escolha API própria. Dê um nome (ex.: "Meu site") e clique em Criar.
2. Copie o token. No cartão da loja, o botão </> mostra os três endereços e o token (começa com fh_). O botão "Copiar tudo para o dev" junta tudo num texto só.
3. Ligue o que vai usar. Na engrenagem do cartão, ligue "Receber produtos pela API" e/ou "Receber estoque pela API". Os dois nascem desligados. Ligar o estoque pede um usuário que possa alterar estoque.

Teste a conexão (não grava nada):

curl https://fluvhub.com/sistema/apps/lojas_virtuais/api/produtos.php \
  -H "Authorization: Bearer fh_SEU_TOKEN"

{ "ok": true, "loja": "Meu site", "mensagem": "Conectado. Envie produtos por POST; consulte com ?codigo=<SKU>.", "estoque_pela_api": true }

Token e segurança

• Mande o token no cabeçalho Authorization: Bearer fh_… (ou X-Fluv-Token: fh_…).
• Nunca no endereço. Produtos e estoque recusam ?token= com 401, porque endereço fica gravado em log. (Pedidos ainda aceita, para quem já usava, mas prefira o cabeçalho.)
• Só HTTPS. Chamada sem HTTPS em produtos e estoque volta 403.
• O token diz qual é a loja e a empresa. Nenhum campo do corpo troca isso.
• Guarde o token no servidor, nunca no JavaScript do navegador do cliente.
• Vazou? Cartão da loja › </> › Gerar outro token. O antigo para na hora.
• Toda chamada fica registrada (loja, rota, resultado). Saldo e cadastro mudados aparecem no histórico do produto como "API <nome da loja>".

Regras de toda chamada

• Corpo em JSON UTF-8, com Content-Type: application/json. Máximo de 2 MB por chamada.
• Um item ou um lote. Mande um objeto, ou uma lista: {"pedidos": […]}, {"produtos": […]}, {"itens": […]} — até 100 por chamada.
• Limite: 120 chamadas por minuto por loja. Passou, volta 429: espere e mande em lote.
• Números com ponto: 59.90. "59,90" é recusado (é ambíguo).
• Teste sem gravar: acrescente ?teste=1 no endereço (ou "teste": true no corpo). A resposta diz o que aconteceria.
• Pode repetir. Mandar o mesmo pedido, produto ou saldo de novo não duplica nada.

A resposta

Cada item do lote volta em resultados, na mesma ordem (indice), com ok e o que foi feito (acao) ou o motivo (erro). Um item errado não impede os outros.

{
  "ok": false,
  "teste": false,
  "resultados": [
    { "indice": 0, "ok": true,  "codigo": "CAMISA-P", "acao": "criado" },
    { "indice": 1, "ok": false, "codigo": "CAMISA-M", "erro": "preco tem de ser número (use ponto: 59.90)" }
  ]
}

Pedidos

POST https://fluvhub.com/sistema/apps/lojas_virtuais/api/pedidos.php

Cada venda da loja vira um pedido em Pedidos, pronto para nota fiscal e etiqueta. Com o sku igual ao do Fluv Hub, o estoque baixa sozinho.

{
  "id": "1042",
  "numero": "1042",
  "data": "2026-11-03T10:30:00-03:00",
  "status": "pago",
  "cliente": { "nome": "Maria Silva", "documento": "123.456.789-09",
               "email": "maria@email.com", "telefone": "11999998888" },
  "entrega": { "cep": "01001-000", "logradouro": "Praça da Sé", "numero": "100",
               "complemento": "", "bairro": "Sé", "cidade": "São Paulo", "uf": "SP" },
  "itens": [ { "sku": "CAMISA-P", "nome": "Camisa P", "quantidade": 2, "preco": 59.90, "desconto": 0 } ],
  "frete": 15.00,
  "desconto": 0,
  "total": 134.80,
  "pagamento": "Pix",
  "rastreio": "",
  "observacoes": ""
}

Mudar o status

Mande o mesmo id com o status novo. cancelado cancela no Fluv Hub e devolve o estoque; enviado e entregue andam a situação para frente (nunca para trás).

acao de cada resultado: criado, atualizado, igual (nada mudou) ou ignorado (pedido pendente com a loja configurada para receber só pagos, ou cancelamento de um pedido que nunca entrou).

Consultar

GET https://fluvhub.com/sistema/apps/lojas_virtuais/api/pedidos.php?id=1042

numero_fluvhub é o número do pedido dentro do Fluv Hub (o prefixo da loja + o seu número).

{ "ok": true, "pedido": { "id": "1042", "numero": "1042", "numero_fluvhub": "SITE-1042", "status": "pago", "total": 134.8, "recebido_em": "2026-11-03 10:30:12" } }

Produtos

POST https://fluvhub.com/sistema/apps/lojas_virtuais/api/produtos.php

Cria ou atualiza pelo codigo (o SKU). Existe = muda só os campos que você mandou; o resto fica como está. Não existe = cria (aí nome é obrigatório).

{
  "codigo": "CAMISA-P",
  "nome": "Camisa P",
  "descricao": "<p>Algodão 100%</p>",
  "preco": 59.90,
  "custo": 21.00,
  "marca": "Minha Marca",
  "categoria": "Camisetas",
  "unidade": "UN",
  "peso": 0.25,
  "altura_cm": 3, "largura_cm": 20, "comprimento_cm": 30,
  "ncm": "61091000",
  "gtin": "7891234567895",
  "estoque_minimo": 2,
  "ativo": true,
  "estoque": 10,
  "fotos": ["https://cdn.minhaloja.com/camisa-p-1.jpg", "https://cdn.minhaloja.com/camisa-p-2.jpg"]
}

• Não mande null para "limpar" um campo (é recusado). Para não mudar, simplesmente não mande o campo.
• Campo que não existe volta como aviso em avisos, não como erro.
• acao: criado ou atualizado (com ?teste=1: criaria / atualizaria).
• SKU de produto que vem do ERP integrado (Bling, Tiny…) é recusado: ele é cuidado lá.
• O limite de produtos do seu plano vale igual ao da tela. Cada variação conta como um SKU.
• Com estoque junto e a rota de estoque desligada, o produto salva e estoque.erro diz por que o saldo não mudou.

Consultar

GET https://fluvhub.com/sistema/apps/lojas_virtuais/api/produtos.php?codigo=CAMISA-P

Devolve o produto como está hoje: os mesmos campos, o saldo, as fotos (endereços públicos, a primeira é a capa) e, no produto com grade, as variacoes com saldo e fotos de cada uma.

Variações (cor, tamanho…)

Mande a grade no produto-mãe. Cada variação tem o próprio codigo (SKU) e até 2 atributos.

{
  "codigo": "CAMISETA",
  "nome": "Camiseta Básica",
  "preco": 59.90,
  "fotos": ["https://cdn.minhaloja.com/camiseta.jpg"],
  "variacoes": [
    { "codigo": "CAM-AZ-M", "atributos": { "Cor": "Azul", "Tamanho": "M" }, "estoque": 3,
      "fotos": ["https://cdn.minhaloja.com/camiseta-azul.jpg"] },
    { "codigo": "CAM-AZ-G", "atributos": { "Cor": "Azul", "Tamanho": "G" }, "estoque": 5 },
    { "codigo": "CAM-PR-M", "atributos": { "Cor": "Preta", "Tamanho": "M" }, "preco": 64.90, "estoque": 0 }
  ]
}

• Em cada variação: codigo e atributos (obrigatórios ao criar), e se quiser preco, custo, gtin, peso, medidas, estoque_minimo, ativo, estoque e fotos.
• Nome, descrição, NCM e categoria são do produto-mãe.
• Variação que já existe é encontrada pelo código. As que você não mandar ficam como estão — dá para mandar só a que mudou.
• Produto com variações não tem estoque próprio: mande estoque em cada variação.
• Atalho: mandar o código de uma variação direto no topo ({"codigo": "CAM-AZ-M", "preco": 69.9}) atualiza só ela.
• A resposta traz estoque_variacoes e fotos_variacoes com o resultado de cada uma.

Fotos

Mande fotos como uma lista de endereços https://. O Fluv Hub baixa cada imagem, confere e guarda — a foto aparece no cadastro e vai para os anúncios como qualquer foto subida na tela.

"fotos": [
  "https://cdn.minhaloja.com/camisa-p-frente.jpg",
  "https://cdn.minhaloja.com/camisa-p-costas.jpg"
]

• A galeria fica igual à lista, na ordem: a primeira é a capa. Foto que estava e não veio sai (inclusive a que foi subida à mão na tela).
• Não mandou fotos? As fotos ficam como estão. Lista vazia [] é recusada (tirar todas, só pela tela).
• O mesmo endereço não é baixado de novo. Pode mandar o catálogo inteiro toda hora. Trocou a imagem? Troque o endereço (ex.: …/camisa.jpg?v=2).
• Até 12 fotos por produto e 4 próprias por variação (as do produto-mãe valem para ela).
• Formatos JPG, PNG, WEBP ou GIF, até 15 MB, com pelo menos 300 px no menor lado (o ideal é 1200 px ou mais). A imagem é convertida para JPG de até 2000 px.
• O endereço tem de abrir a imagem direto, sem login, com o nome do site (não IP).
• Foto que falha não muda nada: se um endereço não abre ou a imagem não serve, o produto inteiro não é alterado e o erro diz qual (fotos[1]) e por quê.
• Até 100 fotos novas por chamada. Num lote grande com muita foto nova, os produtos que passarem disso voltam com erro: mande-os na chamada seguinte.
• Com ?teste=1 o endereço é conferido, mas nada é baixado: a resposta diz quantas fotos seriam baixadas (fotos.baixaria).

{ "indice": 0, "ok": true, "codigo": "CAMISA-P", "acao": "atualizado",
  "fotos": { "ok": true, "total": 2, "novas": 1, "removidas": 1 } }

Estoque

POST https://fluvhub.com/sistema/apps/lojas_virtuais/api/estoque.php

É o mesmo ajuste da tela de Estoque: o número segue para os anúncios ligados ao produto (Mercado Livre, Shopee, Magalu, TikTok Shop…), kits recalculam e o histórico do produto registra a mudança.

{ "sku": "CAMISA-P", "estoque": 12 }

{ "sku": "CAMISA-P", "somar": -2 }

{ "itens": [
  { "sku": "CAMISA-P", "estoque": 5 },
  { "sku": "CAMISA-M", "somar": 3, "motivo": "contagem" }
] }

• Só funciona com o estoque "Pelo Fluv Hub" ou "Misto" em Integrações › Modo de Operação. Em "Pelo sistema de gestão", quem manda é o ERP: volta 403.
• Saldo que ficaria negativo é recusado e nada muda.
• SKU que divide o saldo com outro (produto vinculado) ajusta o principal — a resposta diz qual em ajustado_em.
• Kit (combo) não recebe número: o saldo dele vem dos componentes.
• Se o produto acabou de receber entrada pelo anúncio, o item volta com pergunta: mande de novo com "entrada_ja_contada": "sim" (já está no saldo) ou "nao" (somar).

{ "indice": 0, "sku": "CAMISA-P", "ok": true, "alterado": true,
  "estoque_antes": 10, "estoque_agora": 12, "resumo": "…" }

Com ?teste=1, cada item traz estoque_antes, estoque_depois, o_que_acontece e mudam_junto (SKUs que dividem o saldo), sem gravar.

Consultar

GET https://fluvhub.com/sistema/apps/lojas_virtuais/api/estoque.php?sku=CAMISA-P

{ "ok": true, "sku": "CAMISA-P", "estoque": 12, "anuncios": [ … ] }

Traz também estoque_compartilhado_com quando o SKU divide o saldo e combo quando é kit.

Erros e o que fazer

Exemplos de código

Atualizar preço, saldo e fotos de um produto. Troque fh_SEU_TOKEN pelo seu token.

curl -X POST https://fluvhub.com/sistema/apps/lojas_virtuais/api/produtos.php \
  -H "Authorization: Bearer fh_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"codigo":"CAMISA-P","preco":59.9,"estoque":12,"fotos":["https://cdn.minhaloja.com/camisa-p-1.jpg"]}'

// Node 18+ (no servidor — nunca exponha o token no navegador)
const resp = await fetch('https://fluvhub.com/sistema/apps/lojas_virtuais/api/produtos.php', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + process.env.FLUVHUB_TOKEN,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    codigo: 'CAMISA-P',
    preco: 59.9,
    estoque: 12,
    fotos: ['https://cdn.minhaloja.com/camisa-p-1.jpg'],
  }),
});
const dados = await resp.json();
for (const r of dados.resultados) {
  if (!r.ok) console.error(r.codigo, r.erro);
}

<?php
$ch = curl_init('https://fluvhub.com/sistema/apps/lojas_virtuais/api/produtos.php');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('FLUVHUB_TOKEN'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        'codigo'  => 'CAMISA-P',
        'preco'   => 59.9,
        'estoque' => 12,
        'fotos'   => ['https://cdn.minhaloja.com/camisa-p-1.jpg'],
    ]),
]);
$dados = json_decode(curl_exec($ch), true);
foreach ($dados['resultados'] as $r) {
    if (!$r['ok']) error_log($r['codigo'] . ': ' . $r['erro']);
}

import os, requests

resp = requests.post(
    'https://fluvhub.com/sistema/apps/lojas_virtuais/api/produtos.php',
    headers={'Authorization': 'Bearer ' + os.environ['FLUVHUB_TOKEN']},
    json={
        'codigo': 'CAMISA-P',
        'preco': 59.9,
        'estoque': 12,
        'fotos': ['https://cdn.minhaloja.com/camisa-p-1.jpg'],
    },
    timeout=120,
)
for r in resp.json()['resultados']:
    if not r['ok']:
        print(r['codigo'], r['erro'])

Mandar um pedido

curl -X POST https://fluvhub.com/sistema/apps/lojas_virtuais/api/pedidos.php \
  -H "Authorization: Bearer fh_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":"1042","status":"pago","cliente":{"nome":"Maria"},"itens":[{"sku":"CAMISA-P","quantidade":1,"preco":59.9}],"total":59.9}'

Cancelar o mesmo pedido

curl -X POST https://fluvhub.com/sistema/apps/lojas_virtuais/api/pedidos.php \
  -H "Authorization: Bearer fh_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":"1042","status":"cancelado"}'

Sincronizar o estoque de vários SKUs

curl -X POST https://fluvhub.com/sistema/apps/lojas_virtuais/api/estoque.php \
  -H "Authorization: Bearer fh_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"itens":[{"sku":"CAMISA-P","estoque":12},{"sku":"CAMISA-M","estoque":4}]}'