Smart: Descontos Concedidos

Endpoints da WebApiAlcance para os descontos concedidos exportados do produto Smart. Cada registro representa um desconto aplicado sobre um documento (NFS-e) de um cliente, com os nomes de campo preservando a nomenclatura da planilha de origem. É 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-descontos-concedidos

Escopos necessários

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

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

Endpoints

`GET /smart-descontos-concedidos/`

Lista os descontos concedidos, 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": "Descontos concedidos recuperados com sucesso",
  "data": [
    {
      "id": 301,
      "cnpj": "12345678000199",
      "cfg_emp": "01 - HOSPITAL EXEMPLO",
      "cliente_cod": "C-4521",
      "cliente": "MARIA DA SILVA",
      "mte_nfs_serie": "1",
      "mte_nfs_numero": 8845,
      "mte_nfs_tipo": "NFS",
      "mte_valor": 1200.0,
      "mte_desconto": 150.0,
      "mte_dthr": "2026-05-10T09:00:00",
      "mcc_dt": "2026-05-10T00:00:00",
      "ind": "PART",
      "indicador_2": "AV",
      "gcc_descr": "DESCONTOS COMERCIAIS",
      "data_hora_criacao": "2026-05-11T08:00:00"
    }
  ]
}

Se nenhum registro casar com o filtro, data volta [] com 200 OK e message: "Nenhum desconto concedido encontrado.".

Escopo: smart_descontos_concedidos:read

`GET /smart-descontos-concedidos/{smart_desconto_id}`

Busca um desconto concedido pelo ID.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`smart_desconto_id`	`int`	path	sim	ID do desconto concedido.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Desconto concedido recuperado com sucesso",
  "data": {
    "id": 301,
    "cnpj": "12345678000199",
    "cfg_emp": "01 - HOSPITAL EXEMPLO",
    "cliente_cod": "C-4521",
    "cliente": "MARIA DA SILVA",
    "mte_nfs_serie": "1",
    "mte_nfs_numero": 8845,
    "mte_nfs_tipo": "NFS",
    "mte_valor": 1200.0,
    "mte_desconto": 150.0,
    "mte_dthr": "2026-05-10T09:00:00",
    "mcc_dt": "2026-05-10T00:00:00",
    "ind": "PART",
    "indicador_2": "AV",
    "gcc_descr": "DESCONTOS COMERCIAIS",
    "data_hora_criacao": "2026-05-11T08:00:00"
  }
}

Quando o ID não existe, responde {"message": "Desconto concedido não encontrado."} com 404 Not Found.

Escopo: smart_descontos_concedidos:read

`POST /smart-descontos-concedidos/`

Cria um novo desconto concedido.

Parâmetros

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

Request

{
  "cnpj": "12345678000199",
  "cfg_emp": "01 - HOSPITAL EXEMPLO",
  "cliente_cod": "C-4521",
  "cliente": "MARIA DA SILVA",
  "mte_nfs_serie": "1",
  "mte_nfs_numero": 8845,
  "mte_nfs_tipo": "NFS",
  "mte_valor": 1200.0,
  "mte_desconto": 150.0,
  "mte_dthr": "2026-05-10T09:00:00",
  "mcc_dt": "2026-05-10T00:00:00",
  "ind": "PART",
  "indicador_2": "AV",
  "gcc_descr": "DESCONTOS COMERCIAIS"
}

Response 201 Created

{
  "status": "success",
  "message": "Desconto concedido criado com sucesso",
  "data": {
    "id": 301,
    "cnpj": "12345678000199",
    "cfg_emp": "01 - HOSPITAL EXEMPLO",
    "cliente_cod": "C-4521",
    "cliente": "MARIA DA SILVA",
    "mte_nfs_serie": "1",
    "mte_nfs_numero": 8845,
    "mte_nfs_tipo": "NFS",
    "mte_valor": 1200.0,
    "mte_desconto": 150.0,
    "mte_dthr": "2026-05-10T09:00:00",
    "mcc_dt": "2026-05-10T00:00:00",
    "ind": "PART",
    "indicador_2": "AV",
    "gcc_descr": "DESCONTOS COMERCIAIS",
    "data_hora_criacao": "2026-05-11T08:00:00"
  }
}

Escopo: smart_descontos_concedidos:write

`PUT /smart-descontos-concedidos/{smart_desconto_id}`

Atualiza um desconto concedido (update parcial - cnpj não pode ser alterado por esta rota).

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`smart_desconto_id`	`int`	path	sim	ID do desconto concedido.

O corpo é um SmartDescontosConcedidosUpdate.

Request

{ "mte_desconto": 180.0 }

Response 200 OK

{
  "status": "success",
  "message": "Desconto concedido atualizado com sucesso",
  "data": {
    "id": 301,
    "cnpj": "12345678000199",
    "cfg_emp": "01 - HOSPITAL EXEMPLO",
    "cliente_cod": "C-4521",
    "cliente": "MARIA DA SILVA",
    "mte_nfs_serie": "1",
    "mte_nfs_numero": 8845,
    "mte_nfs_tipo": "NFS",
    "mte_valor": 1200.0,
    "mte_desconto": 180.0,
    "mte_dthr": "2026-05-10T09:00:00",
    "mcc_dt": "2026-05-10T00:00:00",
    "ind": "PART",
    "indicador_2": "AV",
    "gcc_descr": "DESCONTOS COMERCIAIS",
    "data_hora_criacao": "2026-05-11T08:00:00"
  }
}

Quando o ID não existe, responde {"message": "Desconto concedido não encontrado."} com 404 Not Found.

Escopo: smart_descontos_concedidos:write

`DELETE /smart-descontos-concedidos/{smart_desconto_id}`

Remove um desconto concedido.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`smart_desconto_id`	`int`	path	sim	ID do desconto concedido.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Desconto concedido removido com sucesso",
  "data": null
}

Quando o ID não existe, responde {"message": "Desconto concedido não encontrado."} com 404 Not Found.

Escopo: smart_descontos_concedidos:write

Schemas

`SmartDescontosConcedidosCreate`

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_emp`	`string`	Máx. 300 caracteres. Identificação da empresa na origem.
`cliente_cod`	`string`	Máx. 50 caracteres. Código do cliente na origem.
`cliente`	`string`	Máx. 300 caracteres. Nome do cliente.
`mte_nfs_serie`	`string`	Máx. 20 caracteres. Série do documento de origem.
`mte_nfs_numero`	`int`	Número do documento de origem.
`mte_nfs_tipo`	`string`	Máx. 20 caracteres. Tipo do documento de origem.
`mte_valor`	`float`	Valor do documento antes do desconto.
`mte_desconto`	`float`	Valor do desconto concedido.
`mte_dthr`	`datetime`	Data/hora do lançamento do desconto.
`mcc_dt`	`datetime`	Data de referência do lançamento contábil associado.
`ind`	`string`	Máx. 100 caracteres. Indicador/classificador de origem.
`indicador_2`	`string`	Máx. 100 caracteres. Indicador adicional de origem.
`gcc_descr`	`string`	Máx. 300 caracteres. Descrição do grupo/conta contábil de origem.

`SmartDescontosConcedidosUpdate`

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

`SmartDescontosConcedidosRead`

Retorno de leitura. Estende SmartDescontosConcedidosCreate 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 `SmartDescontosConcedidosCreate`.

Notas

Sucesso segue o envelope { status: "success", message, data }. Erros levantados como HTTPException (404, 500) respondem { message } com o código HTTP correspondente.
mte_valor e mte_desconto são armazenados como DECIMAL(15,2) no banco, mas o schema os expõe como float; o valor trafega como número JSON de ponto flutuante.
?cnpj= vazio ou sem dígitos é tratado como "sem filtro" (não gera WHERE cnpj = '').
GET /smart-descontos-concedidos/ sempre retorna 200 OK; lista vazia é estado normal.