NFS-e/Repasse: Prestador Médico

Endpoints da WebApiAlcance para o domínio prestador_medico do produto NFS-e/Repasse - o cadastro de prestadores médicos (clínicas e profissionais) e seus dois sub-recursos aninhados: despesas fixas e pró-labores fixos do prestador. Cobrem criação, listagem geral (com filtros), listagem por cliente associado, detalhamento por ID, atualização parcial e exclusão, tanto do prestador quanto de cada sub-recurso.

Este domínio veio da migração single-company do app webapp-nfs-repasse-medico (Supabase) para a WebApi.

Base path

/api/v1/nfse-repasse/prestadores

Escopos necessários

• nfse_repasse:read - listagens (geral, por cliente e sub-recursos) e detalhamento
• nfse_repasse:write - criação, atualização e exclusão (prestador, despesas e pró-labores)

O escopo é derivado do primeiro segmento da rota: /nfse-repasse/... vira o recurso nfse_repasse (hífen → underscore), e o método HTTP define a ação (read para GET, write para POST/PUT/DELETE). Esse recurso é único para todo o produto NFS-e/Repasse.

Endpoints

O prefixo /nfse-repasse/prestadores é mantido por extenso em cada título; todos os paths dos sub-recursos pendem dele.

POST /nfse-repasse/prestadores/

Cria um novo prestador médico vinculado ao usuário autenticado. O id_usuario_created é forçado pelo service a partir do usuário logado - não é aceito no body. Exige perfil administrador.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (PrestadorMedicoCreate): razao_social (obrigatório) e os demais campos opcionais do prestador.

Request

{
  "razao_social": "Clínica Exemplo LTDA",
  "nome_fantasia": "Clínica Exemplo",
  "cpfecnpj": "12345678000199",
  "email": "contato@exemplo.com.br",
  "status": "ativo",
  "id_customer": 1
}

Response 201 Created

{
  "success": true,
  "message": "Prestador criado com sucesso!",
  "data": {
    "id": 1,
    "razao_social": "Clínica Exemplo LTDA",
    "nome_fantasia": "Clínica Exemplo",
    "cpfecnpj": "12345678000199",
    "inscricao_municipal": null,
    "email": "contato@exemplo.com.br",
    "telefone": null,
    "endereco": null,
    "municipio": null,
    "uf": null,
    "status": "ativo",
    "id_customer": 1,
    "uuid_legado": null,
    "id_usuario_created": 42,
    "created_at": "2026-07-03T12:00:00Z",
    "updated_at": "2026-07-03T12:00:00Z"
  }
}

Escopo: nfse_repasse:write

GET /nfse-repasse/prestadores/by-customer/{customer_id}

Lista os prestadores associados a um cliente (customer.id), com filtro opcional por status e paginação. Rota estática declarada antes das rotas dinâmicas /{prestador_id}.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Prestadores recuperados com sucesso!",
  "data": [
    {
      "id": 1,
      "razao_social": "Clínica Exemplo LTDA",
      "nome_fantasia": "Clínica Exemplo",
      "cpfecnpj": "12345678000199",
      "status": "ativo",
      "id_customer": 1,
      "uuid_legado": null,
      "id_usuario_created": 42,
      "created_at": "2026-07-03T12:00:00Z",
      "updated_at": "2026-07-03T12:00:00Z"
    }
  ]
}

Escopo: nfse_repasse:read

GET /nfse-repasse/prestadores/

Lista todos os prestadores, com filtros opcionais por status e por cliente, e paginação. Lista vazia é um estado válido - retorna 200 OK com data: [].

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Prestadores recuperados com sucesso!",
  "data": [
    {
      "id": 1,
      "razao_social": "Clínica Exemplo LTDA",
      "nome_fantasia": "Clínica Exemplo",
      "cpfecnpj": "12345678000199",
      "status": "ativo",
      "id_customer": 1,
      "uuid_legado": null,
      "id_usuario_created": 42,
      "created_at": "2026-07-03T12:00:00Z",
      "updated_at": "2026-07-03T12:00:00Z"
    }
  ]
}

Escopo: nfse_repasse:read

GET /nfse-repasse/prestadores/{prestador_id}/despesas

Lista as despesas fixas de um prestador, com filtro opcional por status.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Despesas fixas recuperadas com sucesso!",
  "data": [
    {
      "id": 1,
      "prestador_id": 1,
      "tipo_despesa": "fixa_rateada",
      "descricao": "Aluguel consultório",
      "valor": "1500.00",
      "rateio": true,
      "uuid_medico_legado": null,
      "status": "ativo",
      "uuid_legado": null,
      "id_usuario_created": 42,
      "created_at": "2026-07-03T12:00:00Z",
      "updated_at": "2026-07-03T12:00:00Z"
    }
  ]
}

Escopo: nfse_repasse:read

POST /nfse-repasse/prestadores/{prestador_id}/despesas

Cria uma despesa fixa para o prestador. Exige perfil administrador.

Parâmetros

O corpo é um DespesaFixaPrestadorCreate, cujo campo obrigatório é descricao.

Request

{
  "tipo_despesa": "fixa_rateada",
  "descricao": "Aluguel consultório",
  "valor": "1500.00",
  "rateio": true,
  "status": "ativo"
}

Response 201 Created

{
  "success": true,
  "message": "Despesa fixa criada com sucesso!",
  "data": {
    "id": 1,
    "prestador_id": 1,
    "tipo_despesa": "fixa_rateada",
    "descricao": "Aluguel consultório",
    "valor": "1500.00",
    "rateio": true,
    "uuid_medico_legado": null,
    "status": "ativo",
    "uuid_legado": null,
    "id_usuario_created": 42,
    "created_at": "2026-07-03T12:00:00Z",
    "updated_at": "2026-07-03T12:00:00Z"
  }
}

Escopo: nfse_repasse:write

PUT /nfse-repasse/prestadores/{prestador_id}/despesas/{despesa_id}

Atualiza uma despesa fixa do prestador. O body é um DespesaFixaPrestadorUpdate com campos parciais - somente o que vier preenchido é alterado. Exige perfil administrador.

Parâmetros

Request (DespesaFixaPrestadorUpdate - todos os campos opcionais)

{
  "valor": "1800.00",
  "status": "inativo"
}

Response 200 OK

{
  "success": true,
  "message": "Despesa fixa atualizada!",
  "data": {
    "id": 1,
    "prestador_id": 1,
    "tipo_despesa": "fixa_rateada",
    "descricao": "Aluguel consultório",
    "valor": "1800.00",
    "rateio": true,
    "uuid_medico_legado": null,
    "status": "inativo",
    "uuid_legado": null,
    "id_usuario_created": 42,
    "created_at": "2026-07-03T12:00:00Z",
    "updated_at": "2026-07-03T13:20:00Z"
  }
}

Escopo: nfse_repasse:write

DELETE /nfse-repasse/prestadores/{prestador_id}/despesas/{despesa_id}

Remove uma despesa fixa do prestador. Exige perfil administrador.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Despesa fixa removida!",
  "data": null
}

Escopo: nfse_repasse:write

GET /nfse-repasse/prestadores/{prestador_id}/prolabore

Lista os pró-labores fixos de um prestador, com filtro opcional por status.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Pró-labores fixos recuperados com sucesso!",
  "data": [
    {
      "id": 1,
      "prestador_id": 1,
      "valor": "3000.00",
      "descricao": "Pró-labore mensal",
      "uuid_medico_legado": null,
      "status": "ativo",
      "uuid_legado": null,
      "id_usuario_created": 42,
      "created_at": "2026-07-03T12:00:00Z",
      "updated_at": "2026-07-03T12:00:00Z"
    }
  ]
}

Escopo: nfse_repasse:read

POST /nfse-repasse/prestadores/{prestador_id}/prolabore

Cria um pró-labore fixo para o prestador. Exige perfil administrador.

Parâmetros

O corpo é um ProlaboreFixoPrestadorCreate; todos os campos de negócio são opcionais (valor tem default 0).

Request

{
  "valor": "3000.00",
  "descricao": "Pró-labore mensal",
  "status": "ativo"
}

Response 201 Created

{
  "success": true,
  "message": "Pró-labore fixo criado com sucesso!",
  "data": {
    "id": 1,
    "prestador_id": 1,
    "valor": "3000.00",
    "descricao": "Pró-labore mensal",
    "uuid_medico_legado": null,
    "status": "ativo",
    "uuid_legado": null,
    "id_usuario_created": 42,
    "created_at": "2026-07-03T12:00:00Z",
    "updated_at": "2026-07-03T12:00:00Z"
  }
}

Escopo: nfse_repasse:write

PUT /nfse-repasse/prestadores/{prestador_id}/prolabore/{prolabore_id}

Atualiza um pró-labore fixo do prestador. O body é um ProlaboreFixoPrestadorUpdate com campos parciais. Exige perfil administrador.

Parâmetros

Request (ProlaboreFixoPrestadorUpdate - todos os campos opcionais)

{
  "valor": "3500.00",
  "status": "inativo"
}

Response 200 OK

{
  "success": true,
  "message": "Pró-labore fixo atualizado!",
  "data": {
    "id": 1,
    "prestador_id": 1,
    "valor": "3500.00",
    "descricao": "Pró-labore mensal",
    "uuid_medico_legado": null,
    "status": "inativo",
    "uuid_legado": null,
    "id_usuario_created": 42,
    "created_at": "2026-07-03T12:00:00Z",
    "updated_at": "2026-07-03T13:20:00Z"
  }
}

Escopo: nfse_repasse:write

DELETE /nfse-repasse/prestadores/{prestador_id}/prolabore/{prolabore_id}

Remove um pró-labore fixo do prestador. Exige perfil administrador.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Pró-labore fixo removido!",
  "data": null
}

Escopo: nfse_repasse:write

GET /nfse-repasse/prestadores/{prestador_id}

Detalha um prestador pelo ID inteiro. Quando não encontrado, retorna 404 Not Found.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Prestador encontrado!",
  "data": {
    "id": 1,
    "razao_social": "Clínica Exemplo LTDA",
    "nome_fantasia": "Clínica Exemplo",
    "cpfecnpj": "12345678000199",
    "inscricao_municipal": null,
    "email": "contato@exemplo.com.br",
    "telefone": null,
    "endereco": null,
    "municipio": null,
    "uf": null,
    "status": "ativo",
    "id_customer": 1,
    "uuid_legado": null,
    "id_usuario_created": 42,
    "created_at": "2026-07-03T12:00:00Z",
    "updated_at": "2026-07-03T12:00:00Z"
  }
}

Escopo: nfse_repasse:read

PUT /nfse-repasse/prestadores/{prestador_id}

Atualiza um prestador existente. O body é um PrestadorMedicoUpdate com campos parciais - somente o que vier preenchido é alterado. Campos como id, uuid_legado, id_usuario_created, created_at e updated_at são imutáveis e não aparecem no body. Exige perfil administrador.

Parâmetros

Request (PrestadorMedicoUpdate - todos os campos opcionais)

{
  "razao_social": "Clínica Exemplo S.A.",
  "status": "inativo"
}

Response 200 OK

{
  "success": true,
  "message": "Prestador atualizado!",
  "data": {
    "id": 1,
    "razao_social": "Clínica Exemplo S.A.",
    "nome_fantasia": "Clínica Exemplo",
    "cpfecnpj": "12345678000199",
    "inscricao_municipal": null,
    "email": "contato@exemplo.com.br",
    "telefone": null,
    "endereco": null,
    "municipio": null,
    "uf": null,
    "status": "inativo",
    "id_customer": 1,
    "uuid_legado": null,
    "id_usuario_created": 42,
    "created_at": "2026-07-03T12:00:00Z",
    "updated_at": "2026-07-03T13:20:00Z"
  }
}

Escopo: nfse_repasse:write

DELETE /nfse-repasse/prestadores/{prestador_id}

Remove um prestador pelo ID. Exige perfil administrador.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

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

Escopo: nfse_repasse:write

Schemas

PrestadorMedicoCreate

PrestadorMedicoUpdate

Todos os campos são opcionais; apenas os enviados são atualizados. Não inclui uuid_legado nem os campos gerenciados (imutáveis).

PrestadorMedicoRead

Estende os campos do Create com os campos gerenciados.

(mais todos os campos de PrestadorMedicoBase: razao_social, nome_fantasia, cpfecnpj, inscricao_municipal, email, telefone, endereco, municipio, uf, status, id_customer.)

DespesaFixaPrestadorCreate

DespesaFixaPrestadorUpdate tem os mesmos campos de negócio (todos opcionais, sem uuid_legado); DespesaFixaPrestadorRead adiciona id, prestador_id, uuid_legado, id_usuario_created, created_at, updated_at.

ProlaboreFixoPrestadorCreate

ProlaboreFixoPrestadorUpdate tem os mesmos campos de negócio (todos opcionais, sem uuid_legado); ProlaboreFixoPrestadorRead adiciona id, prestador_id, uuid_legado, id_usuario_created, created_at, updated_at.

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.
• Escopos são compartilhados por todo o produto NFS-e/Repasse (nfse_repasse:read / nfse_repasse:write), derivados do 1º segmento nfse-repasse - não são específicos de prestadores.
• O campo cpfecnpj é normalizado para apenas dígitos antes da persistência (aceita CPF de 11 ou CNPJ de 14 dígitos; o comprimento não é validado - cadastro tolerante).
• id_usuario_created nunca vem no body de criação - é forçado pelo service a partir do usuário autenticado. uuid_legado é aceito no Create (correlação com o registro Supabase de origem) mas é imutável depois.
• O domínio medico ainda não foi migrado nesta API; por isso despesas específicas e pró-labores referenciam o médico via uuid_medico_legado.