NFS-e/Repasse: Repasse

Endpoints da WebApiAlcance para o cálculo e a gestão de repasses médicos (domínio repasse, financeiro crítico). Este domínio porta o app single-company webapp-nfs-repasse-medico (originalmente Supabase + edge function calcular-repasse) para a API. Cobrem o CRUD do cabeçalho do repasse, o cálculo síncrono (recalcula impostos, rateio e IRRF regravando as tabelas calculadas), os sub-recursos calculados (médicos, notas, créditos - somente leitura) e os sub-recursos manuais que servem de input do cálculo (despesas, antecipações, devolução de aporte, pró-labore).

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 primeiro segmento

O primeiro segmento do path - nfse-repasse - é compartilhado por todos os módulos da família NFS-e/Repasse (tomadores, notas, prestadores, repasses etc.). Por isso o escopo desta página é nfse_repasse:read / nfse_repasse:write, e não um escopo específico de "repasse". Uma API Key com nfse_repasse:write habilita escrita em todo o domínio NFS-e/Repasse, não apenas em repasses. Emita chaves com o menor escopo possível - preferencialmente nfse_repasse:read.

Base path

/api/v1/nfse-repasse/repasses

Escopos necessários

nfse_repasse:read - leitura: listagem, busca por ID e todos os GET de sub-recursos (calculados e manuais).
nfse_repasse:write - escrita: criação, atualização, exclusão, o cálculo (POST /{repasse_id}/calcular) e todo o CRUD dos sub-recursos manuais.

Perfil administrador na WebApi. Além do escopo nfse_repasse:write, todas as operações de escrita (POST/PUT/DELETE) e o cálculo exigem o perfil administrador do usuário autenticado. A leitura (GET) é liberada para qualquer staff autenticado. API Keys emitidas para o gateway MCP devem usar apenas nfse_repasse:read sempre que possível - repasse é um domínio financeiro crítico.

Endpoints

Todos os endpoints devolvem o envelope padrão { success, message, data } (ou { success: false, message, details } em erro). O código HTTP reflete a semântica REST padrão; o service mapeia mensagens canônicas para 404 (não encontrado), 409 (conflito / já fechado / já existe), 403 (acesso negado) e 422 (validação).

Ordem de rotas no FastAPI

As rotas com segmento estático - sub-recursos aninhados e /{repasse_id}/calcular - são declaradas antes da rota dinâmica /{repasse_id}, porque o FastAPI casa na ordem de declaração. Isso não muda a forma de chamar, mas explica por que /{repasse_id}/calcular nunca é interpretado como um repasse_id inválido.

Cabeçalho do repasse

`POST /nfse-repasse/repasses/`

Cria um novo repasse. O usuário informa prestador + período + competência; os 10 totais não entram no body (são derivados pelo cálculo). O id_usuario_created é forçado pelo service a partir do usuário autenticado.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (RepasseCreate): id_prestador, periodo_inicio e periodo_fim (obrigatórios); data_fechamento, mes_referencia, status e uuid_legado (opcionais).

Request

{
  "id_prestador": 1,
  "periodo_inicio": "2026-06-01",
  "periodo_fim": "2026-06-30",
  "mes_referencia": "2026-06",
  "status": "em_calculo"
}

Response 201 Created

{
  "success": true,
  "message": "Repasse criado com sucesso!",
  "data": {
    "id": 1,
    "id_prestador": 1,
    "periodo_inicio": "2026-06-01",
    "periodo_fim": "2026-06-30",
    "mes_referencia": "2026-06",
    "status": "em_calculo",
    "faturamento_total": "0",
    "resultado_final": "0",
    "created_at": "2026-06-30T12:00:00",
    "updated_at": "2026-06-30T12:00:00"
  }
}

Escopo: nfse_repasse:write (perfil administrador)

`GET /nfse-repasse/repasses/`

Lista os repasses, com filtros opcionais e paginação. Sempre retorna 200 OK, inclusive com data: [] quando não há repasses.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`status`	`str`	query	não	Filtro por status (ex.: `em_calculo`, `fechado`)
`id_prestador`	`int`	query	não	Filtro por prestador (`prestador_medico.id`)
`page`	`int >= 1`	query	não	Página 1-based
`per_page`	`int 1..500`	query	não	Itens por página

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Repasses recuperados com sucesso!",
  "data": [
    {
      "id": 1,
      "id_prestador": 1,
      "periodo_inicio": "2026-06-01",
      "periodo_fim": "2026-06-30",
      "mes_referencia": "2026-06",
      "status": "em_calculo",
      "faturamento_total": "100000.00",
      "resultado_final": "83500.00",
      "created_at": "2026-06-30T12:00:00",
      "updated_at": "2026-06-30T12:00:00"
    }
  ]
}

Escopo: nfse_repasse:read

`GET /nfse-repasse/repasses/{repasse_id}`

Detalha um repasse pelo ID inteiro (inclui os 10 totais). Quando não encontrado, retorna 404 Not Found.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Repasse encontrado!",
  "data": {
    "id": 1,
    "id_prestador": 1,
    "periodo_inicio": "2026-06-01",
    "periodo_fim": "2026-06-30",
    "mes_referencia": "2026-06",
    "status": "em_calculo",
    "faturamento_total": "100000.00",
    "total_impostos": "6000.00",
    "total_despesas": "5000.00",
    "total_nao_recebido": "0.00",
    "total_creditos_anteriores": "0.00",
    "total_antecipacoes": "1000.00",
    "total_irrf": "1500.00",
    "total_devolucao_aporte": "0.00",
    "total_prolabore_liquido": "3000.00",
    "resultado_final": "83500.00",
    "id_usuario_created": 42,
    "created_at": "2026-06-30T12:00:00",
    "updated_at": "2026-06-30T12:00:00"
  }
}

Escopo: nfse_repasse:read

`PUT /nfse-repasse/repasses/{repasse_id}`

Atualiza um repasse. O body é um RepasseUpdate com campos parciais - somente o que vier preenchido é alterado. id, uuid_legado, id_usuario_created, timestamps e os 10 totais (derivados pelo cálculo) são imutáveis por este endpoint.

Parâmetros

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

Request (RepasseUpdate - todos os campos opcionais)

{
  "mes_referencia": "2026-06",
  "status": "fechado"
}

Response 200 OK

{
  "success": true,
  "message": "Repasse atualizado!",
  "data": {
    "id": 1,
    "id_prestador": 1,
    "periodo_inicio": "2026-06-01",
    "periodo_fim": "2026-06-30",
    "mes_referencia": "2026-06",
    "status": "fechado",
    "resultado_final": "83500.00",
    "created_at": "2026-06-30T12:00:00",
    "updated_at": "2026-06-30T14:20:00"
  }
}

Escopo: nfse_repasse:write (perfil administrador)

`DELETE /nfse-repasse/repasses/{repasse_id}`

Remove um repasse pelo ID. Operação destrutiva. A cascata dos sub-recursos (médicos, notas, créditos, despesas, antecipações, devoluções, pró-labores) é feita pelo banco via ON DELETE CASCADE.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

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

Escopo: nfse_repasse:write (perfil administrador)

Cálculo

`POST /nfse-repasse/repasses/{repasse_id}/calcular`

Cálculo síncrono. Porta o edge function calcular-repasse: recalcula impostos, rateio de despesas e IRRF, e regrava as tabelas calculadas (notas, médicos, créditos) numa única transação. Não retorna binário - retorna um resumo (RepasseCalculoResult).

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`repasse_id`	`int`	path	sim	ID do repasse a calcular

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Repasse calculado com sucesso!",
  "data": {
    "faturamento_total": "100000.00",
    "total_impostos": "6000.00",
    "total_despesas": "5000.00",
    "total_nao_recebido": "0.00",
    "total_creditos_anteriores": "0.00",
    "total_antecipacoes": "1000.00",
    "total_irrf": "1500.00",
    "total_devolucao_aporte": "0.00",
    "total_prolabore_liquido": "3000.00",
    "resultado_final": "83500.00",
    "notas_count": 42,
    "creditos_count": 3,
    "medicos_count": 8
  }
}

Escopo: nfse_repasse:write (perfil administrador)

Sub-recursos calculados (somente leitura)

Recriados a cada execução do cálculo - não têm CRUD.

`GET /nfse-repasse/repasses/{repasse_id}/medicos`

Lista as linhas calculadas por médico do repasse (RepasseMedicoRead).

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Médicos do repasse recuperados com sucesso!",
  "data": [
    {
      "id": 1,
      "id_repasse": 1,
      "id_medico": 1,
      "faturamento_medico": "20000.00",
      "impostos_medico": "1200.00",
      "despesas_rateadas": "625.00",
      "despesas_especificas": "0.00",
      "valor_nao_recebido": "0.00",
      "creditos_anteriores": "0.00",
      "total_antecipacoes": "1000.00",
      "irrf": "300.00",
      "base_irrf": "17175.00",
      "total_devolucao_aporte": "0.00",
      "prolabore_liquido": "3000.00",
      "valor_final": "13875.00",
      "created_at": "2026-06-30T12:05:00"
    }
  ]
}

Escopo: nfse_repasse:read

`GET /nfse-repasse/repasses/{repasse_id}/notas`

Lista as notas do período vinculadas ao repasse (RepasseNotaRead, calculadas).

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Notas do repasse recuperadas com sucesso!",
  "data": [
    {
      "id": 1,
      "id_repasse": 1,
      "id_nota_fiscal": 1,
      "valor_bruto": "2500.00",
      "recebida": "S",
      "created_at": "2026-06-30T12:05:00"
    }
  ]
}

Escopo: nfse_repasse:read

`GET /nfse-repasse/repasses/{repasse_id}/creditos`

Lista os créditos de períodos anteriores considerados no repasse (RepasseCreditoRead, calculados).

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Créditos do repasse recuperados com sucesso!",
  "data": [
    {
      "id": 1,
      "id_repasse": 1,
      "id_nota_fiscal": 5,
      "id_medico": 1,
      "valor_credito": "800.00",
      "created_at": "2026-06-30T12:05:00"
    }
  ]
}

Escopo: nfse_repasse:read

Sub-recurso manual: Despesas

CRUD completo. São input do cálculo. id_repasse vem sempre da rota aninhada (não entra no body).

`GET /nfse-repasse/repasses/{repasse_id}/despesas`

Lista as despesas do repasse (RepasseDespesaRead).

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Despesas recuperadas com sucesso!",
  "data": [
    {
      "id": 1,
      "id_repasse": 1,
      "id_medico": null,
      "tipo_despesa": "fixa_rateada",
      "descricao": "Aluguel da clínica",
      "valor_total": "500.00",
      "rateio": "S",
      "created_at": "2026-06-30T12:00:00"
    }
  ]
}

Escopo: nfse_repasse:read

`POST /nfse-repasse/repasses/{repasse_id}/despesas`

Cria uma despesa no repasse. Body RepasseDespesaCreate.

Parâmetros

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

Request

{
  "id_medico": null,
  "tipo_despesa": "fixa_rateada",
  "descricao": "Aluguel da clínica",
  "valor_total": "500.00",
  "rateio": "S"
}

Response 201 Created

{
  "success": true,
  "message": "Despesa criada com sucesso!",
  "data": {
    "id": 1,
    "id_repasse": 1,
    "id_medico": null,
    "tipo_despesa": "fixa_rateada",
    "descricao": "Aluguel da clínica",
    "valor_total": "500.00",
    "rateio": "S",
    "created_at": "2026-06-30T12:00:00"
  }
}

Escopo: nfse_repasse:write (perfil administrador)

`PUT /nfse-repasse/repasses/{repasse_id}/despesas/{despesa_id}`

Atualiza uma despesa (campos parciais, RepasseDespesaUpdate).

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`repasse_id`	`int`	path	sim	ID do repasse
`despesa_id`	`int`	path	sim	ID da despesa

Request (RepasseDespesaUpdate - todos os campos opcionais)

{
  "valor_total": "600.00"
}

Response 200 OK

{
  "success": true,
  "message": "Despesa atualizada!",
  "data": {
    "id": 1,
    "id_repasse": 1,
    "id_medico": null,
    "tipo_despesa": "fixa_rateada",
    "descricao": "Aluguel da clínica",
    "valor_total": "600.00",
    "rateio": "S",
    "created_at": "2026-06-30T12:00:00"
  }
}

Escopo: nfse_repasse:write (perfil administrador)

`DELETE /nfse-repasse/repasses/{repasse_id}/despesas/{despesa_id}`

Remove uma despesa do repasse.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`repasse_id`	`int`	path	sim	ID do repasse
`despesa_id`	`int`	path	sim	ID da despesa

Request

Sem corpo de requisição.

Response 200 OK

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

Escopo: nfse_repasse:write (perfil administrador)

Sub-recurso manual: Antecipações

CRUD completo. Forma "médico + valor + data + observação" (data_antecipacao).

`GET /nfse-repasse/repasses/{repasse_id}/antecipacoes`

Lista as antecipações do repasse (RepasseAntecipacaoRead).

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Antecipações recuperadas com sucesso!",
  "data": [
    {
      "id": 1,
      "id_repasse": 1,
      "id_medico": 1,
      "valor": "1000.00",
      "data_antecipacao": "2026-06-15",
      "observacao": "Adiantamento quinzenal",
      "created_at": "2026-06-15T10:00:00"
    }
  ]
}

Escopo: nfse_repasse:read

`POST /nfse-repasse/repasses/{repasse_id}/antecipacoes`

Cria uma antecipação. Body RepasseAntecipacaoCreate.

Parâmetros

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

Request

{
  "id_medico": 1,
  "valor": "1000.00",
  "data_antecipacao": "2026-06-15",
  "observacao": "Adiantamento quinzenal"
}

Response 201 Created

{
  "success": true,
  "message": "Antecipação criada com sucesso!",
  "data": {
    "id": 1,
    "id_repasse": 1,
    "id_medico": 1,
    "valor": "1000.00",
    "data_antecipacao": "2026-06-15",
    "observacao": "Adiantamento quinzenal",
    "created_at": "2026-06-15T10:00:00"
  }
}

Escopo: nfse_repasse:write (perfil administrador)

`PUT /nfse-repasse/repasses/{repasse_id}/antecipacoes/{antecipacao_id}`

Atualiza uma antecipação (campos parciais, RepasseAntecipacaoUpdate).

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`repasse_id`	`int`	path	sim	ID do repasse
`antecipacao_id`	`int`	path	sim	ID da antecipação

Request (RepasseAntecipacaoUpdate - todos os campos opcionais)

{
  "valor": "1200.00"
}

Response 200 OK

{
  "success": true,
  "message": "Antecipação atualizada!",
  "data": {
    "id": 1,
    "id_repasse": 1,
    "id_medico": 1,
    "valor": "1200.00",
    "data_antecipacao": "2026-06-15",
    "observacao": "Adiantamento quinzenal",
    "created_at": "2026-06-15T10:00:00"
  }
}

Escopo: nfse_repasse:write (perfil administrador)

`DELETE /nfse-repasse/repasses/{repasse_id}/antecipacoes/{antecipacao_id}`

Remove uma antecipação do repasse.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`repasse_id`	`int`	path	sim	ID do repasse
`antecipacao_id`	`int`	path	sim	ID da antecipação

Request

Sem corpo de requisição.

Response 200 OK

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

Escopo: nfse_repasse:write (perfil administrador)

Sub-recurso manual: Devolução de aporte

CRUD completo. Mesma forma das antecipações, com coluna de data data_devolucao.

`GET /nfse-repasse/repasses/{repasse_id}/devolucao-aporte`

Lista as devoluções de aporte do repasse (RepasseDevolucaoAporteRead).

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Devoluções de aporte recuperadas com sucesso!",
  "data": [
    {
      "id": 1,
      "id_repasse": 1,
      "id_medico": 1,
      "valor": "2000.00",
      "data_devolucao": "2026-06-20",
      "observacao": "Devolução de aporte inicial",
      "created_at": "2026-06-20T09:00:00"
    }
  ]
}

Escopo: nfse_repasse:read

`POST /nfse-repasse/repasses/{repasse_id}/devolucao-aporte`

Cria uma devolução de aporte. Body RepasseDevolucaoAporteCreate.

Parâmetros

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

Request

{
  "id_medico": 1,
  "valor": "2000.00",
  "data_devolucao": "2026-06-20",
  "observacao": "Devolução de aporte inicial"
}

Response 201 Created

{
  "success": true,
  "message": "Devolução de aporte criada com sucesso!",
  "data": {
    "id": 1,
    "id_repasse": 1,
    "id_medico": 1,
    "valor": "2000.00",
    "data_devolucao": "2026-06-20",
    "observacao": "Devolução de aporte inicial",
    "created_at": "2026-06-20T09:00:00"
  }
}

Escopo: nfse_repasse:write (perfil administrador)

`PUT /nfse-repasse/repasses/{repasse_id}/devolucao-aporte/{devolucao_id}`

Atualiza uma devolução de aporte (campos parciais, RepasseDevolucaoAporteUpdate).

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`repasse_id`	`int`	path	sim	ID do repasse
`devolucao_id`	`int`	path	sim	ID da devolução

Request (RepasseDevolucaoAporteUpdate - todos os campos opcionais)

{
  "valor": "2500.00"
}

Response 200 OK

{
  "success": true,
  "message": "Devolução de aporte atualizada!",
  "data": {
    "id": 1,
    "id_repasse": 1,
    "id_medico": 1,
    "valor": "2500.00",
    "data_devolucao": "2026-06-20",
    "observacao": "Devolução de aporte inicial",
    "created_at": "2026-06-20T09:00:00"
  }
}

Escopo: nfse_repasse:write (perfil administrador)

`DELETE /nfse-repasse/repasses/{repasse_id}/devolucao-aporte/{devolucao_id}`

Remove uma devolução de aporte do repasse.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`repasse_id`	`int`	path	sim	ID do repasse
`devolucao_id`	`int`	path	sim	ID da devolução

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Devolução de aporte removida!",
  "data": null
}

Escopo: nfse_repasse:write (perfil administrador)

Sub-recurso manual: Pró-labore

CRUD completo. Mesma forma, com coluna de data data_prolabore. É o único sub-recurso manual com updated_at no schema de leitura.

`GET /nfse-repasse/repasses/{repasse_id}/prolabore`

Lista os pró-labores do repasse (RepasseProlaboreRead).

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Pró-labores recuperados com sucesso!",
  "data": [
    {
      "id": 1,
      "id_repasse": 1,
      "id_medico": 1,
      "valor": "3000.00",
      "data_prolabore": "2026-06-30",
      "observacao": "Pró-labore mensal",
      "created_at": "2026-06-30T11:00:00",
      "updated_at": "2026-06-30T11:00:00"
    }
  ]
}

Escopo: nfse_repasse:read

`POST /nfse-repasse/repasses/{repasse_id}/prolabore`

Cria um pró-labore. Body RepasseProlaboreCreate.

Parâmetros

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

Request

{
  "id_medico": 1,
  "valor": "3000.00",
  "data_prolabore": "2026-06-30",
  "observacao": "Pró-labore mensal"
}

Response 201 Created

{
  "success": true,
  "message": "Pró-labore criado com sucesso!",
  "data": {
    "id": 1,
    "id_repasse": 1,
    "id_medico": 1,
    "valor": "3000.00",
    "data_prolabore": "2026-06-30",
    "observacao": "Pró-labore mensal",
    "created_at": "2026-06-30T11:00:00",
    "updated_at": "2026-06-30T11:00:00"
  }
}

Escopo: nfse_repasse:write (perfil administrador)

`PUT /nfse-repasse/repasses/{repasse_id}/prolabore/{prolabore_id}`

Atualiza um pró-labore (campos parciais, RepasseProlaboreUpdate).

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`repasse_id`	`int`	path	sim	ID do repasse
`prolabore_id`	`int`	path	sim	ID do pró-labore

Request (RepasseProlaboreUpdate - todos os campos opcionais)

{
  "valor": "3200.00"
}

Response 200 OK

{
  "success": true,
  "message": "Pró-labore atualizado!",
  "data": {
    "id": 1,
    "id_repasse": 1,
    "id_medico": 1,
    "valor": "3200.00",
    "data_prolabore": "2026-06-30",
    "observacao": "Pró-labore mensal",
    "created_at": "2026-06-30T11:00:00",
    "updated_at": "2026-06-30T14:30:00"
  }
}

Escopo: nfse_repasse:write (perfil administrador)

`DELETE /nfse-repasse/repasses/{repasse_id}/prolabore/{prolabore_id}`

Remove um pró-labore do repasse.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`repasse_id`	`int`	path	sim	ID do repasse
`prolabore_id`	`int`	path	sim	ID do pró-labore

Request

Sem corpo de requisição.

Response 200 OK

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

Escopo: nfse_repasse:write (perfil administrador)

Schemas

Schema RepasseCreate

Payload de criação do cabeçalho. Os 10 totais não entram (são derivados pelo cálculo).

Campo	Tipo	Obrigatório	Descrição
`id_prestador`	`int`	sim	ID do prestador (`prestador_medico.id`)
`periodo_inicio`	`date`	sim	Início do período do repasse
`periodo_fim`	`date`	sim	Fim do período do repasse
`data_fechamento`	`date`	não	Data de fechamento (preenchida ao fechar)
`mes_referencia`	`str` (≤ 20)	não	Mês de referência/competência (ex.: `2026-06`)
`status`	`str` (≤ 30)	não	`em_calculo` (default) ou `fechado`
`uuid_legado`	`str` (≤ 36)	não	UUID do registro original no Supabase (rastreabilidade)

RepasseUpdate tem os mesmos campos mutáveis (id_prestador, periodo_inicio, periodo_fim, data_fechamento, mes_referencia, status), todos opcionais.

Schema RepasseRead

Além dos campos do RepasseBase, o Read expõe id, uuid_legado, id_usuario_created, os timestamps created_at/updated_at e os 10 totais (todos Decimal, derivados pelo cálculo):

faturamento_total, total_impostos, total_despesas, total_nao_recebido, total_creditos_anteriores, total_antecipacoes, total_irrf, total_devolucao_aporte, total_prolabore_liquido, resultado_final.

Schema RepasseCalculoResult

Resumo retornado por POST /{repasse_id}/calcular - espelha o JSON do edge function calcular-repasse. Contém os 10 totais acima (todos Decimal) mais três contadores int: notas_count, creditos_count, medicos_count.

Schema dos sub-recursos manuais

RepasseDespesa (Create/Update/Read):

Campo	Tipo	Obrigatório	Descrição
`id_medico`	`int`	não	`null` quando `rateio='S'` (despesa rateada não tem médico específico)
`tipo_despesa`	`str` (≤ 50)	não	Ex.: `fixa_rateada` (default), `especifica`, `ajuste`
`descricao`	`str`	sim	Descrição da despesa
`valor_total`	`Decimal`	não	Valor total (default `0`)
`rateio`	`str` (1)	não	`S` (rateada, default) ou `N` (específica/ajuste); aceita boolean
`uuid_legado`	`str` (≤ 36)	não	Só no Create

RepasseAntecipacao, RepasseDevolucaoAporte, RepasseProlabore compartilham a base _ValorMedicoBase (id_medico obrigatório, valor: Decimal, observacao opcional) e diferem apenas no nome da coluna de data:

Sub-recurso	Coluna de data	Observações
`RepasseAntecipacao`	`data_antecipacao`	-
`RepasseDevolucaoAporte`	`data_devolucao`	-
`RepasseProlabore`	`data_prolabore`	Único Read com `updated_at`

Notas

Envelope. Toda resposta segue { success, message, data } (ou { success: false, message, details } em erro). Não há endpoints binários neste domínio - o cálculo (/calcular) é síncrono e retorna JSON (RepasseCalculoResult), não um arquivo.
Duas categorias de sub-recurso. Os calculados (medicos, notas, creditos) são somente leitura e recriados a cada POST /{repasse_id}/calcular; os manuais (despesas, antecipacoes, devolucao-aporte, prolabore) têm CRUD e são o input do cálculo.
Valores monetários. Todos os campos de valor são Decimal (string no JSON), nunca float, por se tratar de domínio financeiro crítico.
Cascata. O DELETE do repasse é único; a remoção dos sub-recursos é feita pelo banco via ON DELETE CASCADE.
id_repasse nunca vai no body dos sub-recursos - ele é sempre inferido da rota aninhada. id_usuario_created é forçado pelo service a partir do usuário autenticado, e uuid_legado é metadado de migração (aceito no Create, imutável depois).

Domínio financeiro crítico

Repasse recalcula impostos, rateio e IRRF e regrava tabelas em transação. Escrita (POST/PUT/DELETE) e o cálculo exigem nfse_repasse:write + perfil administrador. Nunca exponha escrita a clientes IA sem confirmação humana explícita - prefira emitir API Keys apenas com nfse_repasse:read.