Smart: Faturas Glosadas

Endpoints da WebApiAlcance para as faturas glosadas exportadas do produto Smart. Cada registro associa uma NFS de origem (nfs_serie/nfs_tipo/nfs_numero) ao documento de glosa correspondente (mns_serie/mns_num/mns_vlr/mns_dt), 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-faturas-glosadas

Escopos necessários

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

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

Endpoints

`GET /smart-faturas-glosadas/`

Lista as faturas glosadas, 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": "Faturas glosadas recuperadas com sucesso",
  "data": [
    {
      "id": 851,
      "cnpj": "12345678000199",
      "cfg_emp": "01 - HOSPITAL EXEMPLO",
      "nfs_serie": "1",
      "nfs_tipo": "NFS",
      "nfs_numero": 7732,
      "mns_vlr": 420.5,
      "mns_dt": "2026-04-20T00:00:00",
      "mns_serie": "126",
      "mns_num": 55201,
      "nfs_emp_codigo": "07",
      "codigo_nome": "CONVENIO EXEMPLO SAUDE",
      "data_hora_criacao": "2026-04-21T08:00:00"
    }
  ]
}

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

Escopo: smart_faturas_glosadas:read

`GET /smart-faturas-glosadas/{smart_fatura_id}`

Busca uma fatura glosada pelo ID.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`smart_fatura_id`	`int`	path	sim	ID da fatura glosada.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Fatura glosada recuperada com sucesso",
  "data": {
    "id": 851,
    "cnpj": "12345678000199",
    "cfg_emp": "01 - HOSPITAL EXEMPLO",
    "nfs_serie": "1",
    "nfs_tipo": "NFS",
    "nfs_numero": 7732,
    "mns_vlr": 420.5,
    "mns_dt": "2026-04-20T00:00:00",
    "mns_serie": "126",
    "mns_num": 55201,
    "nfs_emp_codigo": "07",
    "codigo_nome": "CONVENIO EXEMPLO SAUDE",
    "data_hora_criacao": "2026-04-21T08:00:00"
  }
}

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

Escopo: smart_faturas_glosadas:read

`POST /smart-faturas-glosadas/`

Cria uma nova fatura glosada.

Parâmetros

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

Request

{
  "cnpj": "12345678000199",
  "cfg_emp": "01 - HOSPITAL EXEMPLO",
  "nfs_serie": "1",
  "nfs_tipo": "NFS",
  "nfs_numero": 7732,
  "mns_vlr": 420.5,
  "mns_dt": "2026-04-20T00:00:00",
  "mns_serie": "126",
  "mns_num": 55201,
  "nfs_emp_codigo": "07",
  "codigo_nome": "CONVENIO EXEMPLO SAUDE"
}

Response 201 Created

{
  "status": "success",
  "message": "Fatura glosada criada com sucesso",
  "data": {
    "id": 851,
    "cnpj": "12345678000199",
    "cfg_emp": "01 - HOSPITAL EXEMPLO",
    "nfs_serie": "1",
    "nfs_tipo": "NFS",
    "nfs_numero": 7732,
    "mns_vlr": 420.5,
    "mns_dt": "2026-04-20T00:00:00",
    "mns_serie": "126",
    "mns_num": 55201,
    "nfs_emp_codigo": "07",
    "codigo_nome": "CONVENIO EXEMPLO SAUDE",
    "data_hora_criacao": "2026-04-21T08:00:00"
  }
}

Escopo: smart_faturas_glosadas:write

`PUT /smart-faturas-glosadas/{smart_fatura_id}`

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

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`smart_fatura_id`	`int`	path	sim	ID da fatura glosada.

O corpo é um SmartFaturasGlosadasUpdate.

Request

{ "mns_vlr": 450.0 }

Response 200 OK

{
  "status": "success",
  "message": "Fatura glosada atualizada com sucesso",
  "data": {
    "id": 851,
    "cnpj": "12345678000199",
    "cfg_emp": "01 - HOSPITAL EXEMPLO",
    "nfs_serie": "1",
    "nfs_tipo": "NFS",
    "nfs_numero": 7732,
    "mns_vlr": 450.0,
    "mns_dt": "2026-04-20T00:00:00",
    "mns_serie": "126",
    "mns_num": 55201,
    "nfs_emp_codigo": "07",
    "codigo_nome": "CONVENIO EXEMPLO SAUDE",
    "data_hora_criacao": "2026-04-21T08:00:00"
  }
}

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

Escopo: smart_faturas_glosadas:write

`DELETE /smart-faturas-glosadas/{smart_fatura_id}`

Remove uma fatura glosada.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`smart_fatura_id`	`int`	path	sim	ID da fatura glosada.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Fatura glosada removida com sucesso",
  "data": null
}

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

Escopo: smart_faturas_glosadas:write

Schemas

`SmartFaturasGlosadasCreate`

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.
`nfs_serie`	`string`	Máx. 20 caracteres. Série da NFS de origem.
`nfs_tipo`	`string`	Máx. 20 caracteres. Tipo do documento de origem.
`nfs_numero`	`int`	Número da NFS de origem.
`mns_vlr`	`float`	Valor da glosa.
`mns_dt`	`datetime`	Data do lançamento da glosa.
`mns_serie`	`string`	Máx. 20 caracteres. Série do documento de glosa.
`mns_num`	`int`	Número do documento de glosa.
`nfs_emp_codigo`	`string`	Máx. 20 caracteres. Código da empresa/convênio na origem (pode ter zeros à esquerda).
`codigo_nome`	`string`	Máx. 300 caracteres. Nome associado ao `nfs_emp_codigo` (ex.: convênio).

`SmartFaturasGlosadasUpdate`

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

`SmartFaturasGlosadasRead`

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

Notas

Sucesso segue o envelope { status: "success", message, data }. Erros levantados como HTTPException (404, 500) respondem { message } com o código HTTP correspondente.
mns_vlr é 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.
nfs_emp_codigo e mns_serie são string (não int) de propósito: a origem traz zeros à esquerda que se perderiam num tipo numérico.
?cnpj= vazio ou sem dígitos é tratado como "sem filtro" (não gera WHERE cnpj = '').
GET /smart-faturas-glosadas/ sempre retorna 200 OK; lista vazia é estado normal.