NFS-e/Repasse: Alertas

Endpoints da WebApiAlcance para os alertas configuráveis do produto NFS-e/Repasse (app de gestão de repasse médico). Um alerta_configuravel descreve uma verificação recorrente (despesa fixa, tributo, repasse ou tarefa operacional) que a equipe precisa acompanhar; cada alerta_conclusao registra que aquele alerta foi tratado em um mês de referência específico. Os endpoints cobrem criação, listagem com filtros, detalhamento por ID, atualização, exclusão e o ciclo de conclusões de cada alerta.

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.

Escopo compartilhado do produto NFS-e/Repasse

O 1º segmento da rota - nfse-repasse - define o recurso de escopo compartilhado por todo o produto NFS-e/Repasse. O escopo é nfse_repasse:read (GET) e nfse_repasse:write (POST/PUT/DELETE), e é o mesmo para todos os subdomínios deste produto (alertas, prestadores, despesas etc.). Ou seja, uma API Key com nfse_repasse:read enxerga a leitura de todo o produto, não apenas dos alertas. Emita chaves com o menor escopo necessário.

Base path

/api/v1/nfse-repasse/alertas

Escopos necessários

nfse_repasse:read - listagem, detalhamento e leitura de conclusões (GET)
nfse_repasse:write - criação, atualização, exclusão e registro/remoção de conclusões (POST/PUT/DELETE)

O escopo é derivado do 1º segmento da rota: /nfse-repasse/... vira o recurso nfse_repasse (hífen → underscore), compartilhado por todo o produto. O método HTTP define a ação (read para GET, write para POST/PUT/DELETE).

Perfil administrador nas escritas

Na WebApi, além do escopo, as operações de escrita (POST, PUT, DELETE) exigem que o usuário autenticado tenha perfil administrador. As leituras (GET) estão liberadas para qualquer staff autenticado.

Endpoints

`POST /nfse-repasse/alertas/`

Cria um novo alerta configurável. O campo de auditoria id_usuario_created é preenchido pelo service a partir do usuário autenticado - não é aceito no body.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (AlertaConfiguravelCreate): titulo (obrigatório); os demais campos têm defaults.

Request

{
  "titulo": "Revisar despesa fixa de aluguel",
  "descricao": "Conferir se o valor do aluguel mudou no mês.",
  "escopo_alerta": "global",
  "categoria": "despesa_fixa",
  "periodicidade": "mensal",
  "ativo": true,
  "acao_sugerida": "revisar_valor"
}

Response 201 Created

{
  "success": true,
  "message": "Alerta criado com sucesso!",
  "data": {
    "id": 1,
    "titulo": "Revisar despesa fixa de aluguel",
    "descricao": "Conferir se o valor do aluguel mudou no mês.",
    "escopo_alerta": "global",
    "categoria": "despesa_fixa",
    "periodicidade": "mensal",
    "mes_referencia": null,
    "ativo": true,
    "acao_sugerida": "revisar_valor",
    "tipo_alerta": "operacional",
    "nivel_alerta": "informativo",
    "prestador_id": null,
    "medico_id": null,
    "despesa_fixa_id": null,
    "id_usuario_created": 42,
    "created_at": "2026-01-10T12:00:00",
    "updated_at": "2026-01-10T12:00:00"
  }
}

Escopo: nfse_repasse:write

`GET /nfse-repasse/alertas/`

Lista os alertas configuráveis, com filtros opcionais e paginação. Lista vazia é um estado válido - sempre retorna 200 OK.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`ativo`	`bool`	query	não	Filtra por alertas ativos/inativos.
`escopo_alerta`	`str`	query	não	Filtra por escopo: `global` ou `prestador`.
`categoria`	`str`	query	não	Filtra por categoria.
`prestador_id`	`int`	query	não	Filtra por prestador (`prestador_medico.id`).
`medico_id`	`int`	query	não	Filtra por médico (`medico.id`).
`page`	`int`	query	não	Página (1-based, `>= 1`).
`per_page`	`int`	query	não	Itens por página (`1..500`).

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Alertas recuperados com sucesso!",
  "data": [
    { "id": 1, "titulo": "Revisar despesa fixa de aluguel", "ativo": true },
    { "id": 2, "titulo": "Conferir DAS do mês", "ativo": true }
  ]
}

Escopo: nfse_repasse:read

`DELETE /nfse-repasse/alertas/conclusoes/{conclusao_id}`

Remove uma conclusão de alerta pelo seu ID. Declarada antes da rota dinâmica /{alerta_id} para não colidir com ela (ver Notas).

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Conclusão removida!",
  "data": null
}

Escopo: nfse_repasse:write

`GET /nfse-repasse/alertas/{alerta_id}/conclusoes`

Lista as conclusões registradas de um alerta, opcionalmente filtradas por mês de referência.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`alerta_id`	`int`	path	sim	ID do alerta configurável.
`mes_referencia`	`str`	query	não	Filtro por mês de referência (ex.: `2026-01`).

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Conclusões recuperadas com sucesso!",
  "data": [
    {
      "id": 10,
      "alerta_id": 1,
      "mes_referencia": "2026-01",
      "concluido_por": 42,
      "data_conclusao": "2026-01-31T18:00:00"
    }
  ]
}

Escopo: nfse_repasse:read

`POST /nfse-repasse/alertas/{alerta_id}/conclusoes`

Registra a conclusão de um alerta em um período (mês de referência). O alerta_id do path é a fonte da verdade e sobrescreve o do body. O campo concluido_por é preenchido pelo service a partir do usuário autenticado, e data_conclusao é server-side.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`alerta_id`	`int`	path	sim	ID do alerta configurável.

O corpo é um AlertaConclusaoCreate; obrigatório: mes_referencia.

Request

{
  "mes_referencia": "2026-01"
}

Response 201 Created

{
  "success": true,
  "message": "Conclusão registrada com sucesso!",
  "data": {
    "id": 10,
    "alerta_id": 1,
    "mes_referencia": "2026-01",
    "prestador_id": null,
    "medico_id": null,
    "concluido_por": 42,
    "data_conclusao": "2026-01-31T18:00:00",
    "created_at": "2026-01-31T18:00:00",
    "updated_at": "2026-01-31T18:00:00"
  }
}

Escopo: nfse_repasse:write

`GET /nfse-repasse/alertas/{alerta_id}`

Detalha um alerta configurável pelo ID inteiro. Quando não encontrado, retorna 404 Not Found.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`alerta_id`	`int`	path	sim	ID interno do alerta

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Alerta encontrado!",
  "data": {
    "id": 1,
    "titulo": "Revisar despesa fixa de aluguel",
    "escopo_alerta": "global",
    "categoria": "despesa_fixa",
    "ativo": true
  }
}

Escopo: nfse_repasse:read

`PUT /nfse-repasse/alertas/{alerta_id}`

Atualiza um alerta existente. O body é um AlertaConfiguravelUpdate com campos parciais - somente o que vier preenchido é alterado. Os campos id, uuid_legado, id_usuario_created, created_at e updated_at são imutáveis.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`alerta_id`	`int`	path	sim	ID do alerta

Request (AlertaConfiguravelUpdate - todos os campos opcionais)

{
  "titulo": "Revisar despesa fixa de aluguel (revisado)",
  "ativo": false
}

Response 200 OK

{
  "success": true,
  "message": "Alerta atualizado!",
  "data": {
    "id": 1,
    "titulo": "Revisar despesa fixa de aluguel (revisado)",
    "ativo": false
  }
}

Escopo: nfse_repasse:write

`DELETE /nfse-repasse/alertas/{alerta_id}`

Remove um alerta configurável pelo ID.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`alerta_id`	`int`	path	sim	ID do alerta

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Alerta removido!",
  "data": null
}

Escopo: nfse_repasse:write

Schemas

`AlertaConfiguravelCreate`

Campo	Tipo	Obrigatório	Observações
`titulo`	`str`	sim	Título do alerta (máx. 200).
`descricao`	`str`	não	Descrição/detalhe. Default `null`.
`escopo_alerta`	`str`	não	`global` ou `prestador`. Default `global`.
`categoria`	`str`	não	`despesa_fixa`, `tributo`, `repasse` ou `operacional`. Default `operacional`.
`periodicidade`	`str`	não	`mensal` ou `anual`. Default `mensal`.
`mes_referencia`	`int`	não	Mês `1..12` - usado quando `periodicidade='anual'`. Default `null`.
`ativo`	`bool`	não	Default `true`.
`acao_sugerida`	`str`	não	`incluir_despesa`, `revisar_valor`, `remover_despesa` ou `revisar_regra`.
`tipo_alerta`	`str`	não	Texto livre (máx. 30). Default `operacional`.
`nivel_alerta`	`str`	não	Texto livre (máx. 30). Default `informativo`.
`prestador_id`	`int`	não	`prestador_medico.id` associado. Default `null`.
`medico_id`	`int`	não	`medico.id` associado. Default `null`.
`despesa_fixa_id`	`int`	não	`despesa_fixa_prestador.id` associada. Default `null`.
`uuid_legado`	`str`	não	UUID do registro original no Supabase (rastreabilidade da migração; imutável depois).

`AlertaConfiguravelUpdate`

Todos os campos são opcionais; apenas os enviados são atualizados. Aceita os mesmos campos de conteúdo do Create (titulo, descricao, escopo_alerta, categoria, periodicidade, mes_referencia, ativo, acao_sugerida, tipo_alerta, nivel_alerta, prestador_id, medico_id, despesa_fixa_id). id, uuid_legado, id_usuario_created, created_at e updated_at não podem ser alterados.

`AlertaConfiguravelRead`

Estende o AlertaConfiguravelBase (todos os campos de conteúdo acima) com os campos gerenciados:

Campo	Tipo	Notas
`id`	`int`	ID interno do alerta.
`uuid_legado`	`str`	UUID de origem (migração). Pode ser `null`.
`id_usuario_created`	`int`	Usuário que criou (auditoria).
`created_at`	`datetime`	Criação (server-side).
`updated_at`	`datetime`	Última atualização (server-side).

`AlertaConclusaoCreate`

Campo	Tipo	Obrigatório	Observações
`alerta_id`	`int`	sim	`alerta_configuravel.id` concluído. Sobrescrito pelo path no POST.
`mes_referencia`	`str`	sim	Mês de referência (ex.: `2026-01`; máx. 20).
`prestador_id`	`int`	não	`prestador_medico.id`. Default `null`.
`medico_id`	`int`	não	`medico.id`. Default `null`.
`uuid_legado`	`str`	não	UUID do registro original no Supabase (migração).

`AlertaConclusaoRead`

Estende o AlertaConclusaoBase (alerta_id, mes_referencia, prestador_id, medico_id) com os campos gerenciados:

Campo	Tipo	Notas
`id`	`int`	ID interno da conclusão.
`uuid_legado`	`str`	UUID de origem (migração). Pode ser `null`.
`concluido_por`	`int`	Usuário que concluiu (auditoria).
`data_conclusao`	`datetime`	Data da conclusão (server-side).
`created_at`	`datetime`	Criação (server-side).
`updated_at`	`datetime`	Última atualização (server-side).

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: 404 quando não encontrado, 409 em conflito (já existe), 403 em acesso negado, 422 para validação.
Armadilha de roteamento FastAPI. A rota DELETE /conclusoes/{conclusao_id} (estática) é declarada antes da rota dinâmica de 1º nível /{alerta_id}. Se a ordem fosse invertida, /conclusoes/5 casaria com /{alerta_id} e conclusoes seria interpretado como um alerta_id inválido.
mes_referencia tem semânticas diferentes entre os dois recursos: em alerta_configuravel é um inteiro 1..12; em alerta_conclusao é texto (ex.: 2026-01). Ambas preservadas da origem.
Campos de auditoria são forçados pelo service: id_usuario_created (alerta) e concluido_por (conclusão) vêm do usuário autenticado e não são aceitos no body.
Este é um subdomínio do produto NFS-e/Repasse e compartilha o escopo nfse_repasse:* com os demais subdomínios do produto.