Movimentação Estoque

Endpoints da WebApiAlcance para registrar e consultar movimentações de estoque - entradas e saídas de materiais provenientes do Klingo ERP. Cada registro descreve um movimento (tipo, operação, material, valor, série/número do documento e data), vinculado a um cliente pelo CNPJ. Cobrem criação, listagem com filtros e paginação, detalhamento por ID, atualização parcial 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/movimentacao-estoque

Escopos necessários

movimentacao_estoque:read - listagem e detalhamento por ID
movimentacao_estoque:write - criação, atualização e exclusão

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

Endpoints

`POST /movimentacao-estoque/`

Cria uma nova movimentação de estoque. O corpo é um MovimentacaoEstoqueCreate com todos os campos opcionais; o cnpj identifica o cliente ao qual a movimentação pertence.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (MovimentacaoEstoqueCreate).

Request

{
  "cnpj": "12345678000199",
  "cfg_emp": "ACME COMERCIO LTDA",
  "mma_tipo_operacao": "Compra para revenda",
  "mma_tipo_es": "Entrada",
  "valor": 1520.0,
  "grupo_material": "Materiais de escritório",
  "cod_grupo_material": 12,
  "mat_cod": 3345,
  "mat_desc_completa": "Resma de papel A4 75g",
  "mma_usr_login": "operador.klingo",
  "mma_obs": "NF-e 001234",
  "mma_serie": 1,
  "mma_num": 1234,
  "mma_data_mov": "2026-07-01T00:00:00"
}

Response 201 Created

{
  "success": true,
  "message": "Movimentação de estoque criada com sucesso",
  "data": {
    "id": 4821,
    "cnpj": "12345678000199",
    "cfg_emp": "ACME COMERCIO LTDA",
    "mma_tipo_operacao": "Compra para revenda",
    "mma_tipo_es": "Entrada",
    "valor": 1520.0,
    "grupo_material": "Materiais de escritório",
    "cod_grupo_material": 12,
    "mat_cod": 3345,
    "mat_desc_completa": "Resma de papel A4 75g",
    "mma_usr_login": "operador.klingo",
    "mma_obs": "NF-e 001234",
    "mma_serie": 1,
    "mma_num": 1234,
    "mma_data_mov": "2026-07-01T00:00:00",
    "data_hora_criacao": "2026-07-03T09:15:42"
  }
}

Em caso de dados inválidos, retorna 422 Unprocessable Entity com detail descrevendo o erro. Escopo: movimentacao_estoque:write

`GET /movimentacao-estoque/`

Lista movimentações de estoque com filtros opcionais e paginação. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com data: [] e a mensagem "Nenhuma movimentação de estoque encontrada.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`cnpj`	`str`	query	não	Filtrar por CNPJ do cliente.
`cfg_emp`	`str`	query	não	Filtrar por empresa.
`mma_tipo_es`	`str`	query	não	Filtrar por tipo (`Entrada` / `Saída`).
`limit`	`int`	query	não	Itens por página. Faixa `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

{
  "success": true,
  "message": "Movimentações de estoque recuperadas com sucesso",
  "data": [
    {
      "id": 4821,
      "cnpj": "12345678000199",
      "cfg_emp": "ACME COMERCIO LTDA",
      "mma_tipo_operacao": "Compra para revenda",
      "mma_tipo_es": "Entrada",
      "valor": 1520.0,
      "grupo_material": "Materiais de escritório",
      "cod_grupo_material": 12,
      "mat_cod": 3345,
      "mat_desc_completa": "Resma de papel A4 75g",
      "mma_usr_login": "operador.klingo",
      "mma_obs": "NF-e 001234",
      "mma_serie": 1,
      "mma_num": 1234,
      "mma_data_mov": "2026-07-01T00:00:00",
      "data_hora_criacao": "2026-07-03T09:15:42"
    }
  ]
}

Escopo: movimentacao_estoque:read

`GET /movimentacao-estoque/{movimentacao_id}`

Detalha uma movimentação de estoque pelo ID inteiro. Quando não encontrada, retorna 404 Not Found.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`movimentacao_id`	`int`	path	sim	ID interno da movimentação

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Movimentação de estoque recuperada com sucesso",
  "data": {
    "id": 4821,
    "cnpj": "12345678000199",
    "cfg_emp": "ACME COMERCIO LTDA",
    "mma_tipo_operacao": "Compra para revenda",
    "mma_tipo_es": "Entrada",
    "valor": 1520.0,
    "grupo_material": "Materiais de escritório",
    "cod_grupo_material": 12,
    "mat_cod": 3345,
    "mat_desc_completa": "Resma de papel A4 75g",
    "mma_usr_login": "operador.klingo",
    "mma_obs": "NF-e 001234",
    "mma_serie": 1,
    "mma_num": 1234,
    "mma_data_mov": "2026-07-01T00:00:00",
    "data_hora_criacao": "2026-07-03T09:15:42"
  }
}

Escopo: movimentacao_estoque:read

`PUT /movimentacao-estoque/{movimentacao_id}`

Atualiza uma movimentação existente. O body é um MovimentacaoEstoqueUpdate com campos parciais - somente o que vier preenchido é alterado. O campo cnpj é imutável via PUT (omitido do schema como proteção contra reatribuição / mass-assignment).

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`movimentacao_id`	`int`	path	sim	ID da movimentação

Request (MovimentacaoEstoqueUpdate - todos os campos opcionais)

{
  "mma_tipo_operacao": "Ajuste de inventário",
  "valor": 1480.5,
  "mma_obs": "Correção de quantidade"
}

Response 200 OK

{
  "success": true,
  "message": "Movimentação de estoque atualizada com sucesso",
  "data": {
    "id": 4821,
    "cnpj": "12345678000199",
    "cfg_emp": "ACME COMERCIO LTDA",
    "mma_tipo_operacao": "Ajuste de inventário",
    "mma_tipo_es": "Entrada",
    "valor": 1480.5,
    "grupo_material": "Materiais de escritório",
    "cod_grupo_material": 12,
    "mat_cod": 3345,
    "mat_desc_completa": "Resma de papel A4 75g",
    "mma_usr_login": "operador.klingo",
    "mma_obs": "Correção de quantidade",
    "mma_serie": 1,
    "mma_num": 1234,
    "mma_data_mov": "2026-07-01T00:00:00",
    "data_hora_criacao": "2026-07-03T09:15:42"
  }
}

Quando não encontrada, retorna 404 Not Found; para outros erros de validação, 422 Unprocessable Entity. Escopo: movimentacao_estoque:write

`DELETE /movimentacao-estoque/{movimentacao_id}`

Remove uma movimentação de estoque pelo ID. Quando não encontrada, retorna 404 Not Found.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`movimentacao_id`	`int`	path	sim	ID da movimentação

Request

Sem corpo de requisição.

Response 200 OK

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

Escopo: movimentacao_estoque:write

Schemas

`MovimentacaoEstoqueCreate`

Herda de MovimentacaoEstoqueBase. Todos os campos são opcionais.

Campo	Tipo	Máx.	Observações
`cnpj`	`str`	30	CNPJ do cliente ao qual a movimentação pertence.
`cfg_emp`	`str`	300	Empresa (configuração Klingo).
`mma_tipo_operacao`	`str`	200	Tipo de operação (ex.: compra, venda, ajuste).
`mma_tipo_es`	`str`	20	Tipo do movimento: `Entrada` ou `Saída`.
`valor`	`float`	-	Valor da movimentação.
`grupo_material`	`str`	200	Descrição do grupo de material.
`cod_grupo_material`	`int`	-	Código do grupo de material.
`mat_cod`	`int`	-	Código do material.
`mat_desc_completa`	`str`	500	Descrição completa do material.
`mma_usr_login`	`str`	100	Login do usuário que registrou a movimentação.
`mma_obs`	`str`	500	Observações.
`mma_serie`	`int`	-	Série do documento.
`mma_num`	`int`	-	Número do documento.
`mma_data_mov`	`datetime`	-	Data/hora do movimento.

`MovimentacaoEstoqueUpdate`

Todos os campos são opcionais; apenas os enviados são atualizados. Não inclui cnpj (imutável via PUT).

Campo	Tipo	Máx.	Observações
`cfg_emp`	`str`	300	Empresa.
`mma_tipo_operacao`	`str`	200	Tipo de operação.
`mma_tipo_es`	`str`	20	Tipo do movimento (`Entrada` / `Saída`).
`valor`	`float`	-	Valor da movimentação.
`grupo_material`	`str`	200	Descrição do grupo de material.
`cod_grupo_material`	`int`	-	Código do grupo de material.
`mat_cod`	`int`	-	Código do material.
`mat_desc_completa`	`str`	500	Descrição completa do material.
`mma_usr_login`	`str`	100	Login do usuário.
`mma_obs`	`str`	500	Observações.
`mma_serie`	`int`	-	Série do documento.
`mma_num`	`int`	-	Número do documento.
`mma_data_mov`	`datetime`	-	Data/hora do movimento.

`MovimentacaoEstoqueRead`

Herda todos os campos de MovimentacaoEstoqueBase e adiciona os campos gerados pelo sistema.

Campo	Tipo	Notas
`id`	`int`	Identificador da movimentação.
`cnpj`	`str`	CNPJ do cliente.
`cfg_emp`	`str`	Empresa.
`mma_tipo_operacao`	`str`	Tipo de operação.
`mma_tipo_es`	`str`	Tipo do movimento (`Entrada` / `Saída`).
`valor`	`float`	Valor da movimentação.
`grupo_material`	`str`	Descrição do grupo de material.
`cod_grupo_material`	`int`	Código do grupo de material.
`mat_cod`	`int`	Código do material.
`mat_desc_completa`	`str`	Descrição completa do material.
`mma_usr_login`	`str`	Login do usuário que registrou.
`mma_obs`	`str`	Observações.
`mma_serie`	`int`	Série do documento.
`mma_num`	`int`	Número do documento.
`mma_data_mov`	`datetime`	Data/hora do movimento.
`data_hora_criacao`	`datetime`	Data/hora de criação do registro na WebApi.

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro). Códigos HTTP refletem semântica REST padrão.
Os campos com prefixo mma_ refletem a nomenclatura de origem do Klingo ERP para movimentações de material.
O par mma_serie + mma_num identifica o documento fiscal/interno que originou a movimentação.
Na listagem GET /movimentacao-estoque/, prefira filtrar por cnpj e mma_tipo_es e paginar com limit/offset - o limit máximo é 500.