NFS-e/Repasse: Nota Fiscal
Endpoints da WebApiAlcance para a gestão de notas fiscais de serviço (NFS-e) no fluxo de repasse médico. Cobrem o CRUD da nota fiscal e seus sub-recursos aninhados - médicos vinculados, recebimentos, status financeiro (contas a receber) - além do anexo de arquivo da nota (upload manual em base64 e download binário de PDF/XML/imagem).
A EMISSÃO da NFS-e não acontece aqui
Este domínio não expõe endpoints de emissão/baixa de NFS-e. A emissão é uma fase assíncrona posterior, fora deste conjunto de rotas. Aqui a API apenas persiste o estado do ciclo: o campo status da nota (rascunho → pronta_emissao → em_processamento → emitida/erro_emissao/cancelada) e o timestamp processamento_iniciado_em. O binário emitido chega depois via upload/vínculo de automação e é servido por GET /{nota_id}/arquivo.
Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key.
Escopo compartilhado: nfse-repasse
O primeiro segmento do escopo - nfse-repasse - é compartilhado por todos os recursos do módulo NFS-e/Repasse (notas fiscais, prestadores médicos, tomadores etc.). Uma API Key com nfse_repasse:read enxerga todos esses recursos em leitura, e nfse_repasse:write habilita escrita em todo o módulo. Emita chaves com o menor escopo possível - prefira nfse_repasse:read para integrações que só consultam.
Base path
/api/v1/nfse-repasse/notas-fiscaisEscopos necessários
nfse_repasse:read- leitura: listagens, busca por ID, sub-recursos (médicos, recebimentos, contas a receber) e download do arquivo.nfse_repasse:write- escrita: criar, atualizar e excluir a nota e seus sub-recursos, além de anexar/remover o arquivo.
Escrita exige permissão adicional
Toda escrita (POST/PUT/DELETE) exige, além do escopo nfse_repasse:write, permissão adicional; sem ela, a resposta é 403 Forbidden. O download GET /{nota_id}/arquivo também é restrito a usuários com permissão adicional.
Envelope de resposta
Salvo o download binário (GET /{nota_id}/arquivo), toda resposta segue o envelope padrão:
{
"status": "success",
"message": "Nota fiscal criada com sucesso!",
"data": {}
}Erros de negócio são mapeados do service para HTTP: "não encontrado" → 404, "já existe" → 409, "acesso negado" → 403, demais violações → 422.
Endpoints
Armadilha de ordem de rotas (FastAPI)
As rotas de path estático (POST /, GET /, GET /contas-receber, GET /recebimentos) e os sub-recursos aninhados (/{nota_id}/medicos, /{nota_id}/arquivo etc.) são declarados antes das rotas dinâmicas GET|PUT|DELETE /{nota_id}. O FastAPI casa na ordem de declaração; inverter faria contas-receber ser interpretado como um {nota_id} inválido. Os segmentos estáticos extras após /{nota_id} (ex.: /medicos) não conflitam com /{nota_id}.
Nota fiscal (recurso principal)
POST /nfse-repasse/notas-fiscais/
Cria uma nota fiscal. O id_usuario_created é definido a partir do usuário autenticado (não entra no body). uuid_legado é aceito apenas para correlação com um registro de origem.
Parâmetros
Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (NotaFiscalCreate): obrigatórios id_prestador e id_tomador; os demais campos (referências fiscais, valores monetários, status, descricao_final, competencia_referencia etc.) são opcionais. Ver Schema NotaFiscal.
Request
{
"id_prestador": 1,
"id_tomador": 1,
"id_customer": 1,
"competencia_referencia": "2026-06",
"valor_bruto": "1500.00",
"valor_liquido": "1350.00",
"status": "rascunho"
}Response 201 Created
{
"status": "success",
"message": "Nota fiscal criada com sucesso!",
"data": {
"id": 1,
"id_prestador": 1,
"id_tomador": 1,
"id_customer": 1,
"competencia_referencia": "2026-06",
"valor_bruto": "1500.00",
"valor_liquido": "1350.00",
"status": "rascunho",
"tem_arquivo": false,
"id_nfe_salvador": null,
"id_usuario_created": 42,
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-01T12:00:00Z"
}
}Escopo: nfse_repasse:write
GET /nfse-repasse/notas-fiscais/
Lista notas fiscais com filtros combináveis e paginação.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
status | str | query | não | Filtro por status da nota |
id_customer | int | query | não | Filtro por cliente associado |
id_prestador | int | query | não | Filtro por prestador (prestador_medico.id) |
id_tomador | int | query | não | Filtro por tomador (tomador.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.
GET /api/v1/nfse-repasse/notas-fiscais/?status=emitida&id_prestador=1&page=1&per_page=50Response 200 OK
{
"status": "success",
"message": "Notas fiscais recuperadas com sucesso!",
"data": [
{
"id": 1,
"id_prestador": 1,
"id_tomador": 1,
"status": "emitida",
"tem_arquivo": true,
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z"
}
]
}Escopo: nfse_repasse:read
GET /nfse-repasse/notas-fiscais/{nota_id}
Detalha uma nota fiscal pelo ID. A resposta não inclui o base64 do arquivo - apenas metadados do anexo (arquivo_nome, arquivo_mime, tem_arquivo) e o vínculo opcional id_nfe_salvador.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
nota_id | int | path | sim | ID interno da nota |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Nota fiscal encontrada!",
"data": {
"id": 1,
"id_prestador": 1,
"id_tomador": 1,
"id_customer": 1,
"status": "emitida",
"arquivo_nome": "nfse-1234.pdf",
"arquivo_mime": "application/pdf",
"tem_arquivo": true,
"id_nfe_salvador": null,
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z"
}
}Escopo: nfse_repasse:read
PUT /nfse-repasse/notas-fiscais/{nota_id}
Atualiza uma nota. Body NotaFiscalUpdate com campos parciais - somente o que vier preenchido é alterado. id, uuid_legado, id_usuario_created, created_at e updated_at são imutáveis (bloqueio de mass-assignment). Permite setar id_nfe_salvador (vínculo à automação NFS-e) e evoluir o status.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
nota_id | int | path | sim | ID da nota |
Request (NotaFiscalUpdate - todos os campos opcionais)
{
"status": "pronta_emissao",
"id_nfe_salvador": 55
}Response 200 OK
{
"status": "success",
"message": "Nota fiscal atualizada!",
"data": {
"id": 1,
"id_prestador": 1,
"id_tomador": 1,
"status": "pronta_emissao",
"id_nfe_salvador": 55,
"tem_arquivo": false,
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-03T14:10:00Z"
}
}Escopo: nfse_repasse:write
DELETE /nfse-repasse/notas-fiscais/{nota_id}
Remove a nota fiscal. Operação destrutiva - os sub-recursos (médicos, recebimentos, contas a receber) são removidos em cascata pelo banco.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
nota_id | int | path | sim | ID da nota |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Nota fiscal removida!",
"data": null
}Escopo: nfse_repasse:write
Listagens agregadas (várias notas)
Duas rotas devolvem os sub-recursos financeiros de várias notas numa única chamada. Elas substituem o laço que o front fazia chamando /{nota_id}/recebimentos e /{nota_id}/contas-receber nota a nota.
- Filtros da nota-mãe:
idsfiltra direto pela chave da nota.status,id_customer,id_prestadoreid_tomadorsão atributos danota_fiscale entram por subconsulta, então nenhuma linha sai duplicada. Os filtros se combinam com E. - Ordem fixa:
id_nota_fiscalcrescente, depoiscreated_ateidcrescentes. O consumidor agrupa por nota sem reordenar. - Paginação: só vale com
pageeper_pageinformados. Sem os dois, a resposta traz todas as linhas que casam com os filtros. A resposta é a lista pura, semtotal. - Nota inexistente não é erro: id que não existe só não devolve linha (não há
404).
Para que serve
Telas que mostram a situação financeira de uma página de notas (ex.: um painel de notas): uma chamada com ids= da página inteira em vez de N chamadas.
GET /nfse-repasse/notas-fiscais/recebimentos
Lista os recebimentos de várias notas. Cada item tem o mesmo formato de GET /{nota_id}/recebimentos.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
ids | str | query | não | IDs das notas separados por vírgula (1,2,3). Máximo de 500; acima disso, ou com item não inteiro, 422. |
status | str | query | não | Status da nota (ex.: emitida). |
id_customer | int | query | não | Cliente associado à nota. |
id_prestador | int | query | não | Prestador da nota (prestador_medico.id). |
id_tomador | int | query | não | Tomador da nota (tomador.id). |
page | int | query | não | Página, começando em 1 (>= 1). |
per_page | int | query | não | Itens por página (1..500). |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Recebimentos recuperados com sucesso!",
"data": [
{
"id": 1,
"id_nota_fiscal": 1,
"valor_recebido": "1500.00",
"data_recebimento": "2026-06-15",
"recebido": "S",
"observacao": "PIX",
"id_usuario_registrou": 42,
"created_at": "2026-06-15T10:00:00Z",
"updated_at": "2026-06-15T10:00:00Z"
},
{
"id": 7,
"id_nota_fiscal": 2,
"valor_recebido": "800.00",
"data_recebimento": "2026-06-20",
"recebido": "N",
"observacao": null,
"id_usuario_registrou": 42,
"created_at": "2026-06-20T09:30:00Z",
"updated_at": "2026-06-20T09:30:00Z"
}
]
}Escopo: nfse_repasse:read
GET /nfse-repasse/notas-fiscais/contas-receber
Lista o status financeiro de várias notas. Cada item tem o mesmo formato de GET /{nota_id}/contas-receber. Aceita os mesmos filtros de /recebimentos e mais o status_financeiro.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
ids | str | query | não | IDs das notas separados por vírgula (1,2,3). Máximo de 500; acima disso, ou com item não inteiro, 422. |
status | str | query | não | Status da nota (ex.: emitida). |
id_customer | int | query | não | Cliente associado à nota. |
id_prestador | int | query | não | Prestador da nota (prestador_medico.id). |
id_tomador | int | query | não | Tomador da nota (tomador.id). |
status_financeiro | str | query | não | Status financeiro do próprio registro: a_receber, recebida, em_atraso ou abatida_no_repasse. Não confundir com status, que é o da nota. |
page | int | query | não | Página, começando em 1 (>= 1). |
per_page | int | query | não | Itens por página (1..500). |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Status financeiro recuperado com sucesso!",
"data": [
{
"id": 1,
"id_nota_fiscal": 1,
"status_financeiro": "a_receber",
"referencia_data": "2026-06-01",
"observacao": "Vencimento em 30 dias",
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-01T12:00:00Z"
}
]
}Response 422 Unprocessable Entity (ids inválido)
{
"detail": "ids deve ser uma lista de inteiros separados por vírgula."
}Escopo: nfse_repasse:read
Médicos da nota (/{nota_id}/medicos)
Vínculo entre a nota e os médicos, com o valor bruto atribuído a cada um.
GET /nfse-repasse/notas-fiscais/{nota_id}/medicos
Lista os médicos vinculados à nota.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
nota_id | int | path | sim | ID da nota |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Médicos recuperados com sucesso!",
"data": [
{
"id": 1,
"id_nota_fiscal": 1,
"id_medico": 1,
"valor_bruto_medico": "1500.00",
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-01T12:00:00Z"
}
]
}Escopo: nfse_repasse:read
POST /nfse-repasse/notas-fiscais/{nota_id}/medicos
Vincula um médico à nota. Body NotaFiscalMedicoCreate (id_nota_fiscal vem da rota).
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
nota_id | int | path | sim | ID da nota |
Request
{
"id_medico": 1,
"valor_bruto_medico": "1500.00"
}Response 201 Created
{
"status": "success",
"message": "Médico vinculado com sucesso!",
"data": {
"id": 1,
"id_nota_fiscal": 1,
"id_medico": 1,
"valor_bruto_medico": "1500.00",
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-01T12:00:00Z"
}
}Escopo: nfse_repasse:write
DELETE /nfse-repasse/notas-fiscais/{nota_id}/medicos/{medico_link_id}
Remove o vínculo do médico.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
nota_id | int | path | sim | ID da nota |
medico_link_id | int | path | sim | ID interno do vínculo |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Médico removido!",
"data": null
}Escopo: nfse_repasse:write
Recebimentos (/{nota_id}/recebimentos)
Registro dos recebimentos financeiros da nota.
GET /nfse-repasse/notas-fiscais/{nota_id}/recebimentos
Lista os recebimentos da nota.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
nota_id | int | path | sim | ID da nota |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Recebimentos recuperados com sucesso!",
"data": [
{
"id": 1,
"id_nota_fiscal": 1,
"valor_recebido": "1500.00",
"data_recebimento": "2026-06-15",
"recebido": "S",
"observacao": "PIX",
"id_usuario_registrou": 42,
"created_at": "2026-06-15T10:00:00Z",
"updated_at": "2026-06-15T10:00:00Z"
}
]
}Escopo: nfse_repasse:read
POST /nfse-repasse/notas-fiscais/{nota_id}/recebimentos
Registra um recebimento. Body RecebimentoNotaCreate. O campo recebido aceita boolean no input e é normalizado para 'S'/'N'.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
nota_id | int | path | sim | ID da nota |
Request
{
"valor_recebido": "1500.00",
"data_recebimento": "2026-06-15",
"recebido": "S",
"observacao": "PIX"
}Response 201 Created
{
"status": "success",
"message": "Recebimento registrado com sucesso!",
"data": {
"id": 1,
"id_nota_fiscal": 1,
"valor_recebido": "1500.00",
"data_recebimento": "2026-06-15",
"recebido": "S",
"observacao": "PIX",
"id_usuario_registrou": 42,
"created_at": "2026-06-15T10:00:00Z",
"updated_at": "2026-06-15T10:00:00Z"
}
}Escopo: nfse_repasse:write
PUT /nfse-repasse/notas-fiscais/{nota_id}/recebimentos/{recebimento_id}
Atualiza um recebimento (campos parciais).
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
nota_id | int | path | sim | ID da nota |
recebimento_id | int | path | sim | ID interno do recebimento |
Request (RecebimentoNotaUpdate - campos parciais)
{
"recebido": "S",
"observacao": "Compensado"
}Response 200 OK
{
"status": "success",
"message": "Recebimento atualizado!",
"data": {
"id": 1,
"id_nota_fiscal": 1,
"valor_recebido": "1500.00",
"data_recebimento": "2026-06-15",
"recebido": "S",
"observacao": "Compensado",
"created_at": "2026-06-15T10:00:00Z",
"updated_at": "2026-06-16T08:00:00Z"
}
}Escopo: nfse_repasse:write
DELETE /nfse-repasse/notas-fiscais/{nota_id}/recebimentos/{recebimento_id}
Remove um recebimento.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
nota_id | int | path | sim | ID da nota |
recebimento_id | int | path | sim | ID interno do recebimento |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Recebimento removido!",
"data": null
}Escopo: nfse_repasse:write
Contas a receber / status financeiro (/{nota_id}/contas-receber)
Histórico do status financeiro da nota (a_receber, recebida, em_atraso, abatida_no_repasse).
GET /nfse-repasse/notas-fiscais/{nota_id}/contas-receber
Lista o status financeiro da nota.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
nota_id | int | path | sim | ID da nota |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Status financeiro recuperado com sucesso!",
"data": [
{
"id": 1,
"id_nota_fiscal": 1,
"status_financeiro": "a_receber",
"referencia_data": "2026-06-01",
"observacao": "Vencimento em 30 dias",
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-01T12:00:00Z"
}
]
}Escopo: nfse_repasse:read
POST /nfse-repasse/notas-fiscais/{nota_id}/contas-receber
Cria um registro de status financeiro. Body ContaReceberStatusCreate.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
nota_id | int | path | sim | ID da nota |
Request
{
"status_financeiro": "a_receber",
"referencia_data": "2026-06-01",
"observacao": "Vencimento em 30 dias"
}Response 201 Created
{
"status": "success",
"message": "Status financeiro criado com sucesso!",
"data": {
"id": 1,
"id_nota_fiscal": 1,
"status_financeiro": "a_receber",
"referencia_data": "2026-06-01",
"observacao": "Vencimento em 30 dias",
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-01T12:00:00Z"
}
}Escopo: nfse_repasse:write
PUT /nfse-repasse/notas-fiscais/{nota_id}/contas-receber/{conta_id}
Atualiza um status financeiro (campos parciais).
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
nota_id | int | path | sim | ID da nota |
conta_id | int | path | sim | ID interno do registro |
Request (ContaReceberStatusUpdate - campos parciais)
{
"status_financeiro": "recebida"
}Response 200 OK
{
"status": "success",
"message": "Status financeiro atualizado!",
"data": {
"id": 1,
"id_nota_fiscal": 1,
"status_financeiro": "recebida",
"referencia_data": "2026-06-01",
"observacao": "Vencimento em 30 dias",
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-16T08:00:00Z"
}
}Escopo: nfse_repasse:write
Arquivo da nota (/{nota_id}/arquivo)
Anexo binário (PDF/XML/imagem) da nota, armazenado como base64 (data URL). Sem OCR.
POST /nfse-repasse/notas-fiscais/{nota_id}/arquivo
Upload manual do arquivo (multipart file). O service valida o tamanho (máx. 15 MB → 413 se exceder), codifica em base64 no formato data:<mime>;base64,... e persiste em nota.arquivo + metadados. Retorna só os metadados (sem o base64).
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
nota_id | int | path | sim | ID da nota |
file | UploadFile | form (multipart) | sim | Arquivo da nota |
Request
Envio multipart/form-data com o campo file (binário do arquivo). Não usa corpo JSON.
Response 200 OK
{
"status": "success",
"message": "Arquivo anexado com sucesso!",
"data": {
"id_nota_fiscal": 1,
"arquivo_nome": "nfse-1234.pdf",
"arquivo_mime": "application/pdf",
"tem_arquivo": true,
"id_nfe_salvador": null
}
}Escopo: nfse_repasse:write
GET /nfse-repasse/notas-fiscais/{nota_id}/arquivo
Download binário do arquivo da nota. Não usa o envelope JSON - retorna o conteúdo bruto com Content-Type do arquivo (application/pdf, image/png, image/jpeg etc.) e header Content-Disposition: attachment; filename="...".
Resolve primeiro o arquivo próprio da nota; se não houver e a nota estiver vinculada a um registro da automação NFS-e (id_nfe_salvador), faz fallback para o arquivo desse registro. Sem nenhum dos dois → 404.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
nota_id | int | path | sim | ID da nota |
Request
Sem corpo de requisição.
Response 200 OK (corpo binário do arquivo, fora do envelope JSON)
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="nfse-1234.pdf"
%PDF-1.7 ...(bytes)...Escopo: nfse_repasse:read
Restrita a usuários com permissão adicional; sem ela, a resposta é 403.
DELETE /nfse-repasse/notas-fiscais/{nota_id}/arquivo
Remove apenas o arquivo próprio da nota (não afeta o vínculo id_nfe_salvador com a automação). Retorna os metadados atualizados (ArquivoNotaMetaRead).
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
nota_id | int | path | sim | ID da nota |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Arquivo removido com sucesso!",
"data": {
"id_nota_fiscal": 1,
"arquivo_nome": null,
"arquivo_mime": null,
"tem_arquivo": false,
"id_nfe_salvador": null
}
}Escopo: nfse_repasse:write
Schemas
Schema NotaFiscal
Campos do modelo (via NotaFiscalCreate / NotaFiscalUpdate / NotaFiscalRead).
Identificação / relacionamentos:
id: int- ID interno (só na leitura).id_prestador: int- prestador médico (prestador_medico.id) - obrigatório no Create.id_tomador: int- tomador (tomador.id) - obrigatório no Create.id_customer: int?- cliente associado, associação de negócio (portal do cliente).id_nfe_salvador: int?- vínculo ao registro da automação NFS-e; habilita o fallback de download.
Referências fiscais (opcionais): id_cnae, id_sub_cnae, id_ctiss, id_nbs, id_indicador_operacao, id_classificacao_tributaria, id_modelo_descricao.
Negócio / emissão:
descricao_final: str?competencia_referencia: str?(≤20, ex.:"2026-06")data_emissao: date?numero_nf: str?(≤50, preenchido após emissão)codigo_verificacao: str?(≤100, após emissão)status: str- um derascunho,pronta_emissao,em_processamento,emitida,erro_emissao,cancelada(defaultrascunho).processamento_iniciado_em: datetime?- quando o processamento de emissão iniciou.observacoes: str?
Valores monetários (Decimal, default 0): aliquota_iss, valor_bruto, iss_retido, pis_retido, cofins_retido, csll_retido, irpj_retido, inss_retido, valor_liquido.
Somente na leitura (NotaFiscalRead): arquivo_nome, arquivo_mime, tem_arquivo (bool - true se há arquivo próprio ou vínculo de automação), id_usuario_created, uuid_legado, created_at, updated_at.
uuid_legado
uuid_legado correlaciona a nota com um registro de origem. É aceito no Create, mas imutável depois (não aparece no Update).
Schemas dos sub-recursos
NotaFiscalMedicoCreate/Read-id_medico: int(obrigatório no Create),valor_bruto_medico: Decimal. Leitura adicionaid,id_nota_fiscal, auditoria e timestamps.RecebimentoNotaCreate/Update/Read-valor_recebido: Decimal,data_recebimento: date?,recebido: 'S'|'N'(aceita boolean no input),observacao: str?,id_usuario_registrou: int?.ContaReceberStatusCreate/Update/Read-status_financeiro: 'a_receber'|'recebida'|'em_atraso'|'abatida_no_repasse',referencia_data: date?,observacao: str?.ArquivoNotaMetaRead-id_nota_fiscal,arquivo_nome?,arquivo_mime?,tem_arquivo: bool,id_nfe_salvador?.
Em todos os Create de sub-recurso, id_nota_fiscal vem da rota aninhada (não entra no body) e id_usuario_created é definido a partir do usuário autenticado. uuid_legado é aceito apenas para correlação com um registro de origem.
Notas
- Emissão é assíncrona. Estas rotas só persistem estado - a emissão real da NFS-e acontece em uma fase posterior. Acompanhe o ciclo pelo
statusda nota e porprocessamento_iniciado_em. - Download binário quebra o envelope.
GET /{nota_id}/arquivoé a única rota que não retorna{ status, message, data }- devolve os bytes comContent-Type/Content-Disposition. Todas as demais usam o envelope padrão. - Fallback de arquivo. Sem arquivo próprio, o download cai para o registro da automação (
id_nfe_salvador).tem_arquivoreflete qualquer uma das fontes. - Limite de upload: 15 MB por arquivo; acima disso,
413 Request Entity Too Large. - Exclusão em cascata. O
DELETE /{nota_id}é o único delete que precisa ser chamado para limpar a nota - os sub-recursos são removidos junto.
Escopo mínimo para integrações
Chaves emitidas para clientes IA / gateway MCP devem, por padrão, receber somente nfse_repasse:read.