Manual da API do Catalogo

Base da API

Todas as rotas abaixo usam a versão atual da API do catálogo.

https://www.forzon.com.br/api/v1

Autenticação

Inclua o token recebido pela Forzon em todas as chamadas. O formato recomendado é o header Authorization.

Authorization: Bearer SEU_TOKEN

Como alternativa, também é aceito:

X-API-Token: SEU_TOKEN

Endpoints

Método	Endpoint	Uso
`GET`	`https://www.forzon.com.br/api/v1`	Status da API e links disponíveis para consulta.
`GET`	`https://www.forzon.com.br/api/v1/produtos`	Lista produtos ativos e visíveis no catálogo, com preço conforme as condições comerciais da integração.
`GET`	`https://www.forzon.com.br/api/v1/produtos/{sku}`	Consulta detalhada de um produto pelo SKU.
`GET`	`https://www.forzon.com.br/api/v1/categorias`	Lista categorias ativas com contagem de produtos.
`GET`	`https://www.forzon.com.br/api/v1/marcas`	Lista marcas ativas com contagem de produtos.

Filtros de produtos

Parâmetro	Exemplo	Descrição
`pagina` ou `page`	`pagina=1`	Página da paginação. O padrão é 1.
`limite` ou `limit`	`limite=100`	Quantidade por página. Máximo de 200 itens.
`q` ou `busca`	`q=nice`	Busca por nome, SKU, ID externo, marca ou categoria.
`sku`	`sku=RTAG3010`	Filtra um SKU exato na listagem.
`marca` ou `brand`	`marca=nice`	Filtra por slug da marca. Aceita lista separada por vírgula.
`categoria` ou `category`	`categoria=controle-de-acesso`	Filtra pela categoria e suas subcategorias.
`estoque` ou `stock`	`estoque=1`	Retorna apenas produtos com quantidade em estoque maior que zero.
`promocao` ou `promotion`	`promocao=1`	Retorna apenas produtos marcados como promoção.
`atualizados_desde` ou `updated_since`	`atualizados_desde=2026-07-01`	Ajuda na sincronização incremental. Aceita data ISO ou `YYYY-MM-DD HH:MM:SS`.
`ordenar` ou `sort`	`ordenar=atualizado`	Valores: `nome`, `sku`, `estoque` ou `atualizado`.

Exemplos de chamada

Listar produtos

curl -H "Authorization: Bearer SEU_TOKEN" \
  "https://www.forzon.com.br/api/v1/produtos?pagina=1&limite=100"

Consultar produto por SKU

curl -H "Authorization: Bearer SEU_TOKEN" \
  "https://www.forzon.com.br/api/v1/produtos/RTAG3010"

Filtrar por marca e estoque

curl -H "X-API-Token: SEU_TOKEN" \
  "https://www.forzon.com.br/api/v1/produtos?marca=nice&estoque=1&ordenar=atualizado"

Exemplo de resposta da listagem

{
  "ok": true,
  "data": [
    {
      "id": 123,
      "external_id": "5934",
      "sku": "RTAG3010",
      "nome": "Antena TAG UHF RTAG3010 Nice",
      "slug": "antena-tag-uhf-rtag3010-nice",
      "url": "https://www.forzon.com.br/produtos/antena-tag-uhf-rtag3010-nice",
      "marca": {"nome": "Nice", "slug": "nice"},
      "categoria": {"nome": "Controle de acesso", "slug": "controle-de-acesso"},
      "descricao_curta": "Resumo comercial do produto.",
      "estoque": {
        "quantidade": 10,
        "disponivel": true,
        "origem": "tiny",
        "sincronizado_em": "2026-07-07 10:00:00"
      },
      "preco": {
        "moeda": "BRL",
        "valor": 123.45,
        "valor_regular": null,
        "valor_promocional": null,
        "promocao_ativa": false,
        "origem": "base",
        "tabela": {"id": 1, "nome": "Revenda", "codigo": "revenda"}
      },
      "promocao_ativa": false,
      "imagem_principal": "https://cdn.exemplo.com/produto.jpg",
      "imagens": [],
      "atualizado_em": "2026-07-07 10:00:00",
      "criado_em": "2026-07-01 09:00:00"
    }
  ],
  "meta": {
    "pagina": 1,
    "limite": 100,
    "total": 1046,
    "total_paginas": 11,
    "tabela_preco": {"id": 1, "nome": "Revenda", "codigo": "revenda"}
  }
}

Exemplo de detalhe do produto

{
  "ok": true,
  "data": {
    "sku": "RTAG3010",
    "nome": "Antena TAG UHF RTAG3010 Nice",
    "descricao": "Descricao completa sem HTML.",
    "categorias": [
      {"id": 10, "nome": "Controle de acesso", "slug": "controle-de-acesso"}
    ],
    "atributos": [
      {"nome": "Frequencia", "slug": "frequencia", "valor": "UHF", "valor_slug": "uhf"}
    ]
  }
}

Erros comuns

Status	Código	Quando ocorre
`401`	`unauthorized`	Token ausente ou inválido.
`404`	`not_found`	SKU não encontrado na consulta detalhada.
`422`	`invalid_filter`	Filtro `atualizados_desde` em formato inválido.

{
  "ok": false,
  "erro": "unauthorized",
  "mensagem": "Informe o token em Authorization: Bearer TOKEN ou X-API-Token."
}

Boas práticas de integração

Use o sku como chave principal de conciliação no ERP sempre que possível.
Use paginação e mantenha limite em até 200 itens por chamada.
Para rotina recorrente, prefira sincronização incremental com atualizados_desde.
Não armazene token em repositório, front-end, planilha compartilhada ou URL.
Considere preco.valor como o preço vigente retornado para a integração.

Manual da API do catálogo