Smart: Estoque Retroativo

Endpoints da WebApiAlcance para as posições de estoque retroativo exportadas do produto Smart (relatório de estoque geral, hierarquizado em grupo/linha/material). Os nomes de campo preservam a nomenclatura da planilha de origem; valor é a única medida que deve ser somada - os campos compute_2, compute_4 e compute_6 são subtotais do próprio relatório, repetidos em cada linha, e não devem ser agregados junto com valor. É um CRUD simples: listagem paginada com filtro opcional por CNPJ, busca por ID, criação, atualização e exclusão.

Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key. O Swagger oficial está em api.contabilidadealcance.com.br/docs.

Base path

/api/v1/smart-estoque-retroativo

Escopos necessários

smart_estoque_retroativo:read - listagem e busca por ID
smart_estoque_retroativo:write - criação, atualização e exclusão

O escopo é derivado do prefixo público da rota: /smart-estoque-retroativo vira o recurso smart_estoque_retroativo (hífen → underscore), e o método HTTP define a ação (read para GET, write para POST/PUT/DELETE).

Endpoints

`GET /smart-estoque-retroativo/`

Lista as posições de estoque retroativo, com filtro opcional por CNPJ e paginação.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`cnpj`	`string`	query	não	Filtra por CNPJ do cliente.
`limit`	`int`	query	não	Itens por página. `1..500`. Default `100`.
`offset`	`int`	query	não	Offset de paginação. `>= 0`. Default `0`.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Posições de estoque recuperadas com sucesso",
  "data": [
    {
      "id": 1201,
      "cnpj": "12345678000199",
      "cfg_cfg_emp": "01 - HOSPITAL EXEMPLO",
      "mat_mat_cod": 44210,
      "mat_mat_desc_resumida": "SORO FISIOLOGICO 500ML",
      "valor": 3245.8,
      "preco_medio": 6.49,
      "compute_5": "UN",
      "estoque_c": 500,
      "consignado": "N",
      "st_mw": "Relatorio Estoque Geral - 2026-05-10 08:00",
      "compute_6": 364142.84,
      "compute_1": "Grupo: 001 - MATERIAIS DE CONSUMO",
      "compute_2": 89210.5,
      "compute_3": "Linha: 001 - SOROS E SOLUCOES",
      "compute_4": 15400.2,
      "data_hora_criacao": "2026-05-11T08:00:00"
    }
  ]
}

Se nenhum registro casar com o filtro, data volta [] com 200 OK e message: "Nenhuma posição de estoque encontrada.".

Escopo: smart_estoque_retroativo:read

`GET /smart-estoque-retroativo/{smart_estoque_id}`

Busca uma posição de estoque pelo ID.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`smart_estoque_id`	`int`	path	sim	ID da posição de estoque.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Posição de estoque recuperada com sucesso",
  "data": {
    "id": 1201,
    "cnpj": "12345678000199",
    "cfg_cfg_emp": "01 - HOSPITAL EXEMPLO",
    "mat_mat_cod": 44210,
    "mat_mat_desc_resumida": "SORO FISIOLOGICO 500ML",
    "valor": 3245.8,
    "preco_medio": 6.49,
    "compute_5": "UN",
    "estoque_c": 500,
    "consignado": "N",
    "st_mw": "Relatorio Estoque Geral - 2026-05-10 08:00",
    "compute_6": 364142.84,
    "compute_1": "Grupo: 001 - MATERIAIS DE CONSUMO",
    "compute_2": 89210.5,
    "compute_3": "Linha: 001 - SOROS E SOLUCOES",
    "compute_4": 15400.2,
    "data_hora_criacao": "2026-05-11T08:00:00"
  }
}

Quando o ID não existe, responde {"message": "Posição de estoque não encontrada."} com 404 Not Found.

Escopo: smart_estoque_retroativo:read

`POST /smart-estoque-retroativo/`

Cria uma nova posição de estoque.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query. O corpo é um SmartEstoqueRetroativoCreate.

Request

{
  "cnpj": "12345678000199",
  "cfg_cfg_emp": "01 - HOSPITAL EXEMPLO",
  "mat_mat_cod": 44210,
  "mat_mat_desc_resumida": "SORO FISIOLOGICO 500ML",
  "valor": 3245.8,
  "preco_medio": 6.49,
  "compute_5": "UN",
  "estoque_c": 500,
  "consignado": "N",
  "st_mw": "Relatorio Estoque Geral - 2026-05-10 08:00",
  "compute_6": 364142.84,
  "compute_1": "Grupo: 001 - MATERIAIS DE CONSUMO",
  "compute_2": 89210.5,
  "compute_3": "Linha: 001 - SOROS E SOLUCOES",
  "compute_4": 15400.2
}

Response 201 Created

{
  "status": "success",
  "message": "Posição de estoque criada com sucesso",
  "data": {
    "id": 1201,
    "cnpj": "12345678000199",
    "cfg_cfg_emp": "01 - HOSPITAL EXEMPLO",
    "mat_mat_cod": 44210,
    "mat_mat_desc_resumida": "SORO FISIOLOGICO 500ML",
    "valor": 3245.8,
    "preco_medio": 6.49,
    "compute_5": "UN",
    "estoque_c": 500,
    "consignado": "N",
    "st_mw": "Relatorio Estoque Geral - 2026-05-10 08:00",
    "compute_6": 364142.84,
    "compute_1": "Grupo: 001 - MATERIAIS DE CONSUMO",
    "compute_2": 89210.5,
    "compute_3": "Linha: 001 - SOROS E SOLUCOES",
    "compute_4": 15400.2,
    "data_hora_criacao": "2026-05-11T08:00:00"
  }
}

Escopo: smart_estoque_retroativo:write

`PUT /smart-estoque-retroativo/{smart_estoque_id}`

Atualiza uma posição de estoque (update parcial - cnpj não pode ser alterado por esta rota).

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`smart_estoque_id`	`int`	path	sim	ID da posição de estoque.

O corpo é um SmartEstoqueRetroativoUpdate.

Request

{ "valor": 3300.0, "estoque_c": 510 }

Response 200 OK

{
  "status": "success",
  "message": "Posição de estoque atualizada com sucesso",
  "data": {
    "id": 1201,
    "cnpj": "12345678000199",
    "cfg_cfg_emp": "01 - HOSPITAL EXEMPLO",
    "mat_mat_cod": 44210,
    "mat_mat_desc_resumida": "SORO FISIOLOGICO 500ML",
    "valor": 3300.0,
    "preco_medio": 6.49,
    "compute_5": "UN",
    "estoque_c": 510,
    "consignado": "N",
    "st_mw": "Relatorio Estoque Geral - 2026-05-10 08:00",
    "compute_6": 364142.84,
    "compute_1": "Grupo: 001 - MATERIAIS DE CONSUMO",
    "compute_2": 89210.5,
    "compute_3": "Linha: 001 - SOROS E SOLUCOES",
    "compute_4": 15400.2,
    "data_hora_criacao": "2026-05-11T08:00:00"
  }
}

Quando o ID não existe, responde {"message": "Posição de estoque não encontrada."} com 404 Not Found.

Escopo: smart_estoque_retroativo:write

`DELETE /smart-estoque-retroativo/{smart_estoque_id}`

Remove uma posição de estoque.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`smart_estoque_id`	`int`	path	sim	ID da posição de estoque.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Posição de estoque removida com sucesso",
  "data": null
}

Quando o ID não existe, responde {"message": "Posição de estoque não encontrada."} com 404 Not Found.

Escopo: smart_estoque_retroativo:write

Schemas

`SmartEstoqueRetroativoCreate`

Corpo do POST. Todos os campos são opcionais no envio (schema não exige nenhum obrigatório).

Campo	Tipo	Observações
`cnpj`	`string`	Máx. 30 caracteres. CNPJ/CPF do cliente.
`cfg_cfg_emp`	`string`	Máx. 300 caracteres. Identificação da empresa na origem.
`mat_mat_cod`	`int`	Código do material.
`mat_mat_desc_resumida`	`string`	Máx. 300 caracteres. Descrição resumida do material.
`valor`	`Decimal`	Valor do estoque - única medida aditiva deste domínio.
`preco_medio`	`Decimal`	Preço médio unitário do material.
`compute_5`	`string`	Máx. 20 caracteres. Unidade de medida (sigla).
`estoque_c`	`int`	Quantidade em estoque, em unidades discretas.
`consignado`	`string`	Máx. 20 caracteres. Indicador de material consignado.
`st_mw`	`string`	Máx. 300 caracteres. Carimbo da ferramenta de relatório (não é dado de negócio).
`compute_6`	`Decimal`	Subtotal geral do relatório, repetido em toda linha. Não somar junto com `valor`.
`compute_1`	`string`	Máx. 300 caracteres. Identificação do grupo do material ("Grupo: ...").
`compute_2`	`Decimal`	Subtotal do grupo (`compute_1`). Não somar junto com `valor`.
`compute_3`	`string`	Máx. 300 caracteres. Identificação da linha do material ("Linha: ...").
`compute_4`	`Decimal`	Subtotal de nível mais fino associado a `compute_3`. Não somar junto com `valor`.

`SmartEstoqueRetroativoUpdate`

Corpo do PUT. Mesmos campos de SmartEstoqueRetroativoCreate, exceto cnpj (o dono do registro não pode ser trocado por update).

`SmartEstoqueRetroativoRead`

Retorno de leitura. Estende SmartEstoqueRetroativoCreate com id e data_hora_criacao.

Campo	Tipo	Observações
`id`	`int`	Identificador do registro.
`data_hora_criacao`	`datetime`	Data/hora de criação do registro.
(demais campos)	-	Todos os campos de `SmartEstoqueRetroativoCreate`.

Notas

Sucesso segue o envelope { status: "success", message, data }. Erros levantados como HTTPException (404, 500) respondem { message } com o código HTTP correspondente.
Os campos monetários (valor, preco_medio, compute_2, compute_4, compute_6) são Decimal no schema e DECIMAL(15,2) no banco; trafegam como número JSON (a API não usa Float de propósito, para não corromper a precisão antes de persistir).
compute_2, compute_4 e compute_6 são subtotais do relatório de origem repetidos em cada linha - somar valor de várias linhas é válido, somar esses três campos infla o resultado.
?cnpj= vazio ou sem dígitos é tratado como "sem filtro" (não gera WHERE cnpj = '').
GET /smart-estoque-retroativo/ sempre retorna 200 OK; lista vazia é estado normal.