Produtos

O recurso Produtos (/products) mantém o catálogo de bens e serviços do tenant. Cada produto tem campos universais (nome, preço, unidade de medida) e, opcionalmente, uma extensão fiscal por país (br_data no Brasil, us_data nos Estados Unidos) — o Extension Table Pattern do bitERP.

Permissão exigida: products (ações create, read, update, delete).

Conceitos e campos-chave

Um produto sempre tem um type — goods (bem) ou service (serviço) — definido na criação. O reference_code é o código do produto no seu catálogo (SKU): você pode enviá-lo ou deixar a API gerar um automaticamente com o prefixo PRD-. Ele é único por tenant e serve para sincronizar com sistemas externos.

is_active está depreciado. É apenas um alias invertido de is_blocked (is_active = !is_blocked), mantido por compatibilidade. Prefira is_blocked. Se você enviar os dois com valores contraditórios, a API retorna erro de validação.

Unidade de medida

Use unit_of_measurement_id (UUID) no topo do payload — é a forma canônica. O campo legado br_data.unit_of_measure ainda é aceito por compatibilidade e resolve tanto um UUID quanto um código de unidade (UN, CX, KG…) pelo país do tenant, mas está depreciado. Se você enviar os dois e eles apontarem para unidades diferentes, a API retorna erro de validação; se forem iguais, unit_of_measurement_id prevalece.

Na resposta, a unidade vem resolvida como objeto: "unit_of_measurement": { "id": "…", "code": "UN", "symbol": "un" }.

Extensão fiscal Brasil (br_data)

Enviada apenas para tenants do Brasil. Campos aceitos incluem ncm_code (8 dígitos), cest_code (7 dígitos), origin (1 dígito), extipi, nbs_code, taxation_type, códigos da Reforma Tributária (ibs_cbs_*) e outros. Enviar br_data em um tenant de outro país (ou us_data num tenant BR) é rejeitado.

Criar um produto

curl -X POST https://api.biterp.ai/products \
  -H "Authorization: Bearer sk_abc123_secretXYZ" \
  -H "Content-Type: application/json" \
  -d '{
    "reference_code": "EXT-SKU-1001",
    "name": "Notebook Pro 14",
    "description": "Notebook 14 polegadas, 16GB RAM",
    "type": "goods",
    "sale_price": "3499.990000",
    "unit_of_measurement_id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
    "tags": ["eletronicos", "informatica"],
    "is_blocked": false,
    "br_data": {
      "ncm_code": "84713012",
      "cest_code": "0100100",
      "origin": "0"
    }
  }'

Buscar produtos

Há três formas de localizar produtos, além da listagem paginada padrão (GET /products com filtros e paginação):

O endpoint por reference_code é o ideal para sincronizar por SKU: se o produto existir mas o type informado não bater, a API retorna 404 — o par (reference_code, type) identifica o produto.

# Buscar por texto (apenas ativos)
curl -G https://api.biterp.ai/products/search \
  -H "Authorization: Bearer sk_abc123_secretXYZ" \
  --data-urlencode "q=notebook" \
  --data-urlencode "activeOnly=true"

# Localizar por SKU externo
curl "https://api.biterp.ai/products/reference/EXT-SKU-1001?type=goods" \
  -H "Authorization: Bearer sk_abc123_secretXYZ"

Campos filtráveis em GET /products: name, reference_code, is_blocked, type, created_at, updated_at. Ordenação por id, name, reference_code, created_at, updated_at.

Remover

DELETE /products/{id} faz soft delete (o produto pode ser recuperado) e responde 204 No Content.

Referência dos endpoints