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-fiscais

Escopos 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âmetroTipoLocalObrigatórioDescrição
statusstrquerynãoFiltro por status da nota
id_customerintquerynãoFiltro por cliente associado
id_prestadorintquerynãoFiltro por prestador (prestador_medico.id)
id_tomadorintquerynãoFiltro por tomador (tomador.id)
pageint ≥1querynãoPágina (1-based)
per_pageint 1..500querynãoItens 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=50

Response 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âmetroTipoLocalObrigatórioDescrição
nota_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
nota_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
nota_idintpathsimID 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: ids filtra direto pela chave da nota. status, id_customer, id_prestador e id_tomador são atributos da nota_fiscal e entram por subconsulta, então nenhuma linha sai duplicada. Os filtros se combinam com E.
  • Ordem fixa: id_nota_fiscal crescente, depois created_at e id crescentes. O consumidor agrupa por nota sem reordenar.
  • Paginação: só vale com page e per_page informados. Sem os dois, a resposta traz todas as linhas que casam com os filtros. A resposta é a lista pura, sem total.
  • 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âmetroTipoLocalObrigatórioDescrição
idsstrquerynãoIDs das notas separados por vírgula (1,2,3). Máximo de 500; acima disso, ou com item não inteiro, 422.
statusstrquerynãoStatus da nota (ex.: emitida).
id_customerintquerynãoCliente associado à nota.
id_prestadorintquerynãoPrestador da nota (prestador_medico.id).
id_tomadorintquerynãoTomador da nota (tomador.id).
pageintquerynãoPágina, começando em 1 (>= 1).
per_pageintquerynãoItens 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âmetroTipoLocalObrigatórioDescrição
idsstrquerynãoIDs das notas separados por vírgula (1,2,3). Máximo de 500; acima disso, ou com item não inteiro, 422.
statusstrquerynãoStatus da nota (ex.: emitida).
id_customerintquerynãoCliente associado à nota.
id_prestadorintquerynãoPrestador da nota (prestador_medico.id).
id_tomadorintquerynãoTomador da nota (tomador.id).
status_financeirostrquerynãoStatus financeiro do próprio registro: a_receber, recebida, em_atraso ou abatida_no_repasse. Não confundir com status, que é o da nota.
pageintquerynãoPágina, começando em 1 (>= 1).
per_pageintquerynãoItens 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âmetroTipoLocalObrigatórioDescrição
nota_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
nota_idintpathsimID 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

Remove o vínculo do médico.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
nota_idintpathsimID da nota
medico_link_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
nota_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
nota_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
nota_idintpathsimID da nota
recebimento_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
nota_idintpathsimID da nota
recebimento_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
nota_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
nota_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
nota_idintpathsimID da nota
conta_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
nota_idintpathsimID da nota
fileUploadFileform (multipart)simArquivo 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âmetroTipoLocalObrigatórioDescrição
nota_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
nota_idintpathsimID 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 de rascunho, pronta_emissao, em_processamento, emitida, erro_emissao, cancelada (default rascunho).
  • 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 adiciona id, 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 status da nota e por processamento_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 com Content-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_arquivo reflete 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.