Smart: Glosas Acatadas

Endpoints da WebApiAlcance para as glosas acatadas exportadas do produto Smart. Cada registro associa a NFS de origem (nfs_serie/nfs_tipo/nfs_numero) e o convênio (cnv_nome/cnv_cod) ao documento de glosa aceita pelo prestador (mns_serie/mns_num/mns_valor), 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-glosas-acatadas

Escopos necessários

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

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

Endpoints

`GET /smart-glosas-acatadas/`

Lista as glosas acatadas, 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": "Glosas acatadas recuperadas com sucesso",
  "data": [
    {
      "id": 951,
      "cnpj": "12345678000199",
      "cfg_emp": "01 - HOSPITAL EXEMPLO",
      "cnv_nome": "CONVENIO EXEMPLO SAUDE",
      "cnv_cod": "04",
      "nfs_tipo": "NFS",
      "nfs_serie": "1",
      "nfs_numero": 6621,
      "nfs_dt_emis": "2026-03-01T00:00:00",
      "mns_serie": "126",
      "mns_num": 44120,
      "mns_valor": 89.9,
      "sgo_descr": "GLOSA POR DIVERGENCIA DE TABELA",
      "mns_dt": "2026-04-02T00:00:00",
      "nfs_nfl_serie": null,
      "nfs_nfl_num": null,
      "mes": "MARCO",
      "mes_num": 3,
      "hsg": "H1",
      "v_dthr": "2026-04-02T10:15:00",
      "grupo": "AMB",
      "data_hora_criacao": "2026-04-03T08:00:00"
    }
  ]
}

Se nenhum registro casar com o filtro, data volta [] com 200 OK e message: "Nenhuma glosa acatada encontrada.".

Escopo: smart_glosas_acatadas:read

`GET /smart-glosas-acatadas/{smart_glosa_id}`

Busca uma glosa acatada pelo ID.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`smart_glosa_id`	`int`	path	sim	ID da glosa acatada.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Glosa acatada recuperada com sucesso",
  "data": {
    "id": 951,
    "cnpj": "12345678000199",
    "cfg_emp": "01 - HOSPITAL EXEMPLO",
    "cnv_nome": "CONVENIO EXEMPLO SAUDE",
    "cnv_cod": "04",
    "nfs_tipo": "NFS",
    "nfs_serie": "1",
    "nfs_numero": 6621,
    "nfs_dt_emis": "2026-03-01T00:00:00",
    "mns_serie": "126",
    "mns_num": 44120,
    "mns_valor": 89.9,
    "sgo_descr": "GLOSA POR DIVERGENCIA DE TABELA",
    "mns_dt": "2026-04-02T00:00:00",
    "nfs_nfl_serie": null,
    "nfs_nfl_num": null,
    "mes": "MARCO",
    "mes_num": 3,
    "hsg": "H1",
    "v_dthr": "2026-04-02T10:15:00",
    "grupo": "AMB",
    "data_hora_criacao": "2026-04-03T08:00:00"
  }
}

Quando o ID não existe, responde {"message": "Glosa acatada não encontrada."} com 404 Not Found.

Escopo: smart_glosas_acatadas:read

`POST /smart-glosas-acatadas/`

Cria uma nova glosa acatada.

Parâmetros

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

Request

{
  "cnpj": "12345678000199",
  "cfg_emp": "01 - HOSPITAL EXEMPLO",
  "cnv_nome": "CONVENIO EXEMPLO SAUDE",
  "cnv_cod": "04",
  "nfs_tipo": "NFS",
  "nfs_serie": "1",
  "nfs_numero": 6621,
  "nfs_dt_emis": "2026-03-01T00:00:00",
  "mns_serie": "126",
  "mns_num": 44120,
  "mns_valor": 89.9,
  "sgo_descr": "GLOSA POR DIVERGENCIA DE TABELA",
  "mns_dt": "2026-04-02T00:00:00",
  "mes": "MARCO",
  "mes_num": 3,
  "hsg": "H1",
  "v_dthr": "2026-04-02T10:15:00",
  "grupo": "AMB"
}

Response 201 Created

{
  "status": "success",
  "message": "Glosa acatada criada com sucesso",
  "data": {
    "id": 951,
    "cnpj": "12345678000199",
    "cfg_emp": "01 - HOSPITAL EXEMPLO",
    "cnv_nome": "CONVENIO EXEMPLO SAUDE",
    "cnv_cod": "04",
    "nfs_tipo": "NFS",
    "nfs_serie": "1",
    "nfs_numero": 6621,
    "nfs_dt_emis": "2026-03-01T00:00:00",
    "mns_serie": "126",
    "mns_num": 44120,
    "mns_valor": 89.9,
    "sgo_descr": "GLOSA POR DIVERGENCIA DE TABELA",
    "mns_dt": "2026-04-02T00:00:00",
    "nfs_nfl_serie": null,
    "nfs_nfl_num": null,
    "mes": "MARCO",
    "mes_num": 3,
    "hsg": "H1",
    "v_dthr": "2026-04-02T10:15:00",
    "grupo": "AMB",
    "data_hora_criacao": "2026-04-03T08:00:00"
  }
}

Escopo: smart_glosas_acatadas:write

`PUT /smart-glosas-acatadas/{smart_glosa_id}`

Atualiza uma glosa acatada (update parcial - cnpj não pode ser alterado por esta rota).

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`smart_glosa_id`	`int`	path	sim	ID da glosa acatada.

O corpo é um SmartGlosasAcatadasUpdate.

Request

{ "mns_valor": 95.0 }

Response 200 OK

{
  "status": "success",
  "message": "Glosa acatada atualizada com sucesso",
  "data": {
    "id": 951,
    "cnpj": "12345678000199",
    "cfg_emp": "01 - HOSPITAL EXEMPLO",
    "cnv_nome": "CONVENIO EXEMPLO SAUDE",
    "cnv_cod": "04",
    "nfs_tipo": "NFS",
    "nfs_serie": "1",
    "nfs_numero": 6621,
    "nfs_dt_emis": "2026-03-01T00:00:00",
    "mns_serie": "126",
    "mns_num": 44120,
    "mns_valor": 95.0,
    "sgo_descr": "GLOSA POR DIVERGENCIA DE TABELA",
    "mns_dt": "2026-04-02T00:00:00",
    "nfs_nfl_serie": null,
    "nfs_nfl_num": null,
    "mes": "MARCO",
    "mes_num": 3,
    "hsg": "H1",
    "v_dthr": "2026-04-02T10:15:00",
    "grupo": "AMB",
    "data_hora_criacao": "2026-04-03T08:00:00"
  }
}

Quando o ID não existe, responde {"message": "Glosa acatada não encontrada."} com 404 Not Found.

Escopo: smart_glosas_acatadas:write

`DELETE /smart-glosas-acatadas/{smart_glosa_id}`

Remove uma glosa acatada.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`smart_glosa_id`	`int`	path	sim	ID da glosa acatada.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Glosa acatada removida com sucesso",
  "data": null
}

Quando o ID não existe, responde {"message": "Glosa acatada não encontrada."} com 404 Not Found.

Escopo: smart_glosas_acatadas:write

Schemas

`SmartGlosasAcatadasCreate`

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.
`cnv_nome`	`string`	Máx. 300 caracteres. Nome do convênio.
`cnv_cod`	`string`	Máx. 20 caracteres. Código do convênio (pode ter zeros à esquerda).
`nfs_tipo`	`string`	Máx. 20 caracteres. Tipo do documento de origem.
`nfs_serie`	`string`	Máx. 20 caracteres. Série da NFS de origem.
`nfs_numero`	`int`	Número da NFS de origem.
`nfs_dt_emis`	`datetime`	Data de emissão da NFS.
`mns_serie`	`string`	Máx. 20 caracteres. Série do documento de glosa.
`mns_num`	`int`	Número do documento de glosa.
`mns_valor`	`float`	Valor da glosa acatada.
`sgo_descr`	`string`	Máx. 300 caracteres. Descrição do motivo/grupo da glosa.
`mns_dt`	`datetime`	Data do lançamento da glosa.
`nfs_nfl_serie`	`string`	Máx. 20 caracteres. Série de documento relacionado (raramente preenchido na origem).
`nfs_nfl_num`	`int`	Número de documento relacionado (raramente preenchido na origem).
`mes`	`string`	Máx. 20 caracteres. Mês de referência, por extenso.
`mes_num`	`int`	Mês de referência, numérico.
`hsg`	`string`	Máx. 20 caracteres. Indicador/classificador de origem.
`v_dthr`	`datetime`	Data/hora do lançamento de origem.
`grupo`	`string`	Máx. 20 caracteres. Grupo de classificação (ex.: setor de atendimento).

`SmartGlosasAcatadasUpdate`

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

`SmartGlosasAcatadasRead`

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

Notas

Sucesso segue o envelope { status: "success", message, data }. Erros levantados como HTTPException (404, 500) respondem { message } com o código HTTP correspondente.
mns_valor é armazenado como DECIMAL(15,2) no banco, mas o schema o expõe como float; o valor trafega como número JSON de ponto flutuante.
cnv_cod e mns_serie são string (não int) de propósito: a origem traz zeros à esquerda que se perderiam num tipo numérico.
nfs_nfl_serie/nfs_nfl_num vieram vazios em praticamente toda a amostra de origem medida - a API aceita valor quando enviado, mas não espere preenchimento na maioria dos registros.
?cnpj= vazio ou sem dígitos é tratado como "sem filtro" (não gera WHERE cnpj = '').
GET /smart-glosas-acatadas/ sempre retorna 200 OK; lista vazia é estado normal.