NFS-e/Repasse: Documentos OCR

Endpoints da WebApiAlcance para o domínio de documentos OCR do produto NFS-e/Repasse (migração single-company do app webapp-nfs-repasse-medico). Cobrem quatro recursos que sustentam o pipeline de extração de dados de documentos médicos/fiscais:

modelos-documento - modelos que identificam automaticamente o tipo de documento recebido.
modelos-descricao - modelos de descrição de nota (texto padrão de emissão).
documentos-entrada - documentos recebidos e seu ciclo de processamento OCR.
documentos-pdf - PDFs (páginas/arquivos) vinculados a um documento de entrada.

Esta fatia entrega CRUD + schema. O pipeline OCR propriamente dito (extração de texto, classificação por IA, tasks Celery) ainda não está exposto nesta API - os campos de resultado (texto_extraido, dados_extraidos_json, resultado_ia, score_confianca) são persistidos como JSON livre e populados por processos que virão depois.

Autenticação e escopo compartilhado do produto

Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key. O escopo usa o primeiro segmento da rota como recurso: aqui o segmento é nfse-repasse, então o escopo nfse_repasse:read / nfse_repasse:write é compartilhado por todo o produto NFS-e/Repasse (documentos OCR, repasses, tomadores, prestadores etc.). Não existe um escopo isolado só para documentos OCR. O Swagger oficial está em api.contabilidadealcance.com.br/docs.

Base path

/api/v1/nfse-repasse/documentos

Cada recurso vive em um sub-prefixo abaixo desse base path:

/api/v1/nfse-repasse/documentos/modelos-documento
/api/v1/nfse-repasse/documentos/modelos-descricao
/api/v1/nfse-repasse/documentos/documentos-entrada
/api/v1/nfse-repasse/documentos/documentos-pdf

Escopos necessários

nfse_repasse:read - todas as listagens e buscas por ID (métodos GET).
nfse_repasse:write - criação, atualização e exclusão (métodos POST, PUT, DELETE).

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). Como o segmento é o mesmo para todo o produto, o escopo é compartilhado.

Perfil administrador nas escritas

Além do escopo, as rotas de escrita (POST/PUT/DELETE) exigem, internamente na WebApi, o perfil administrador (require_perfil("administrador")). As rotas de leitura (GET) aceitam qualquer usuário autenticado.

Endpoints

Todos os retornos seguem o envelope { success, message, data }. Além do escopo, as rotas de escrita (POST/PUT/DELETE) exigem o perfil administrador; as de leitura (GET) aceitam qualquer usuário autenticado.

modelos-documento

`POST /nfse-repasse/documentos/modelos-documento/`

Cria um novo modelo de documento (usado para identificar automaticamente o tipo de documento recebido).

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (ModeloDocumentoCreate): nome_modelo (obrigatório) e tipo_documento, descricao, palavras_chave, regex_identificacao, exemplo_nome_arquivo, ativo e uuid_legado (opcionais).

Request

{
  "nome_modelo": "Demonstrativo DASA",
  "tipo_documento": "solicitacao_nota",
  "descricao": "Modelo para notas da DASA",
  "palavras_chave": ["dasa", "remuneração"],
  "ativo": "S"
}

Response 201 Created

{
  "success": true,
  "message": "Modelo de documento criado com sucesso!",
  "data": {
    "id": 3,
    "nome_modelo": "Demonstrativo DASA",
    "tipo_documento": "solicitacao_nota",
    "descricao": "Modelo para notas da DASA",
    "palavras_chave": ["dasa", "remuneração"],
    "regex_identificacao": null,
    "exemplo_nome_arquivo": null,
    "ativo": "S",
    "uuid_legado": null,
    "id_usuario_created": 7,
    "created_at": "2026-07-03T12:00:00",
    "updated_at": "2026-07-03T12:00:00"
  }
}

Escopo: nfse_repasse:write

`GET /nfse-repasse/documentos/modelos-documento/`

Lista modelos de documento com filtros opcionais.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`ativo`	`str`	query	não	Filtro por ativo (`'S'` \| `'N'`).
`tipo_documento`	`str`	query	não	Filtro por tipo de documento.
`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": "Modelos recuperados com sucesso!",
  "data": [
    {
      "id": 3,
      "nome_modelo": "Demonstrativo DASA",
      "tipo_documento": "solicitacao_nota",
      "descricao": "Modelo para notas da DASA",
      "palavras_chave": ["dasa", "remuneração"],
      "regex_identificacao": null,
      "exemplo_nome_arquivo": null,
      "ativo": "S",
      "uuid_legado": null,
      "id_usuario_created": 7,
      "created_at": "2026-07-03T12:00:00",
      "updated_at": "2026-07-03T12:00:00"
    }
  ]
}

Escopo: nfse_repasse:read

`GET /nfse-repasse/documentos/modelos-documento/{modelo_id}`

Busca um modelo de documento pelo ID. Quando não encontrado, retorna 404 Not Found.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Modelo de documento encontrado!",
  "data": {
    "id": 3,
    "nome_modelo": "Demonstrativo DASA",
    "tipo_documento": "solicitacao_nota",
    "descricao": "Modelo para notas da DASA",
    "palavras_chave": ["dasa", "remuneração"],
    "regex_identificacao": null,
    "exemplo_nome_arquivo": null,
    "ativo": "S",
    "uuid_legado": null,
    "id_usuario_created": 7,
    "created_at": "2026-07-03T12:00:00",
    "updated_at": "2026-07-03T12:00:00"
  }
}

Escopo: nfse_repasse:read

`PUT /nfse-repasse/documentos/modelos-documento/{modelo_id}`

Atualiza um modelo existente. O body é um ModeloDocumentoUpdate com campos parciais - somente o que vier preenchido é alterado (uuid_legado é imutável e não aparece no Update).

Parâmetros

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

Request (ModeloDocumentoUpdate - todos os campos opcionais)

{
  "descricao": "Modelo atualizado para notas da DASA",
  "ativo": "N"
}

Response 200 OK

{
  "success": true,
  "message": "Modelo de documento atualizado!",
  "data": {
    "id": 3,
    "nome_modelo": "Demonstrativo DASA",
    "tipo_documento": "solicitacao_nota",
    "descricao": "Modelo atualizado para notas da DASA",
    "palavras_chave": ["dasa", "remuneração"],
    "regex_identificacao": null,
    "exemplo_nome_arquivo": null,
    "ativo": "N",
    "uuid_legado": null,
    "id_usuario_created": 7,
    "created_at": "2026-07-03T12:00:00",
    "updated_at": "2026-07-03T13:20:00"
  }
}

Escopo: nfse_repasse:write

`DELETE /nfse-repasse/documentos/modelos-documento/{modelo_id}`

Remove um modelo de documento pelo ID.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Modelo de documento removido!",
  "data": null
}

Escopo: nfse_repasse:write

modelos-descricao

`POST /nfse-repasse/documentos/modelos-descricao/`

Cria um novo modelo de descrição de nota (texto padrão de emissão).

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (ModeloDescricaoNotaCreate): nome_modelo (obrigatório) e descricao_texto, status e uuid_legado (opcionais).

Request

{
  "nome_modelo": "Descrição padrão consultas",
  "descricao_texto": "Prestação de serviços médicos...",
  "status": "ativo"
}

Response 201 Created

{
  "success": true,
  "message": "Modelo de descrição criado com sucesso!",
  "data": {
    "id": 5,
    "nome_modelo": "Descrição padrão consultas",
    "descricao_texto": "Prestação de serviços médicos...",
    "status": "ativo",
    "uuid_legado": null,
    "id_usuario_created": 7,
    "created_at": "2026-07-03T12:00:00",
    "updated_at": "2026-07-03T12:00:00"
  }
}

Escopo: nfse_repasse:write

`GET /nfse-repasse/documentos/modelos-descricao/`

Lista modelos de descrição com filtros opcionais.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`status`	`str`	query	não	Filtro por status (`'ativo'` \| `'inativo'`).
`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": "Modelos recuperados com sucesso!",
  "data": [
    {
      "id": 5,
      "nome_modelo": "Descrição padrão consultas",
      "descricao_texto": "Prestação de serviços médicos...",
      "status": "ativo",
      "uuid_legado": null,
      "id_usuario_created": 7,
      "created_at": "2026-07-03T12:00:00",
      "updated_at": "2026-07-03T12:00:00"
    }
  ]
}

Escopo: nfse_repasse:read

`GET /nfse-repasse/documentos/modelos-descricao/{modelo_id}`

Busca um modelo de descrição pelo ID. Quando não encontrado, retorna 404 Not Found.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Modelo de descrição encontrado!",
  "data": {
    "id": 5,
    "nome_modelo": "Descrição padrão consultas",
    "descricao_texto": "Prestação de serviços médicos...",
    "status": "ativo",
    "uuid_legado": null,
    "id_usuario_created": 7,
    "created_at": "2026-07-03T12:00:00",
    "updated_at": "2026-07-03T12:00:00"
  }
}

Escopo: nfse_repasse:read

`PUT /nfse-repasse/documentos/modelos-descricao/{modelo_id}`

Atualiza um modelo de descrição existente (campos parciais via ModeloDescricaoNotaUpdate).

Parâmetros

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

Request (ModeloDescricaoNotaUpdate - todos os campos opcionais)

{
  "descricao_texto": "Prestação de serviços médicos - consultas eletivas.",
  "status": "inativo"
}

Response 200 OK

{
  "success": true,
  "message": "Modelo de descrição atualizado!",
  "data": {
    "id": 5,
    "nome_modelo": "Descrição padrão consultas",
    "descricao_texto": "Prestação de serviços médicos - consultas eletivas.",
    "status": "inativo",
    "uuid_legado": null,
    "id_usuario_created": 7,
    "created_at": "2026-07-03T12:00:00",
    "updated_at": "2026-07-03T13:20:00"
  }
}

Escopo: nfse_repasse:write

`DELETE /nfse-repasse/documentos/modelos-descricao/{modelo_id}`

Remove um modelo de descrição pelo ID.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Modelo de descrição removido!",
  "data": null
}

Escopo: nfse_repasse:write

documentos-entrada

`POST /nfse-repasse/documentos/documentos-entrada/`

Cria um documento de entrada (o documento recebido que entra no pipeline OCR).

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (DocumentoEntradaCreate). Único campo obrigatório é nome_arquivo; o arquivo é referenciado por arquivo_url (string) - não há upload multipart nesta rota.

Request

{
  "nome_arquivo": "demonstrativo.pdf",
  "arquivo_url": "https://storage/.../demonstrativo.pdf"
}

Response 201 Created

{
  "success": true,
  "message": "Documento de entrada criado com sucesso!",
  "data": {
    "id": 42,
    "nome_arquivo": "demonstrativo.pdf",
    "arquivo_url": "https://storage/.../demonstrativo.pdf",
    "tipo_documento": "pendente_classificacao",
    "status_processamento": "enviado",
    "status_documento": "enviado",
    "modelo_documento_sugerido_id": null,
    "modelo_documento_confirmado_id": null,
    "texto_extraido": null,
    "dados_extraidos_json": null,
    "resultado_ia": null,
    "score_confianca": null,
    "id_usuario_created": 7,
    "created_at": "2026-07-03T12:00:00",
    "updated_at": "2026-07-03T12:00:00"
  }
}

Escopo: nfse_repasse:write

`GET /nfse-repasse/documentos/documentos-entrada/`

Lista documentos de entrada com filtros opcionais.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`status_processamento`	`str`	query	não	Filtro por status (`enviado` \| `processando` \| `processado` \| `erro`).
`tipo_documento`	`str`	query	não	Filtro por tipo de documento.
`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": "Documentos recuperados com sucesso!",
  "data": [
    {
      "id": 42,
      "nome_arquivo": "demonstrativo.pdf",
      "arquivo_url": "https://storage/.../demonstrativo.pdf",
      "tipo_documento": "pendente_classificacao",
      "status_processamento": "enviado",
      "status_documento": "enviado",
      "modelo_documento_sugerido_id": null,
      "modelo_documento_confirmado_id": null,
      "texto_extraido": null,
      "dados_extraidos_json": null,
      "resultado_ia": null,
      "score_confianca": null,
      "id_usuario_created": 7,
      "created_at": "2026-07-03T12:00:00",
      "updated_at": "2026-07-03T12:00:00"
    }
  ]
}

Escopo: nfse_repasse:read

`GET /nfse-repasse/documentos/documentos-entrada/{documento_id}`

Busca um documento de entrada pelo ID. Quando não encontrado, retorna 404 Not Found.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Documento de entrada encontrado!",
  "data": {
    "id": 42,
    "nome_arquivo": "demonstrativo.pdf",
    "arquivo_url": "https://storage/.../demonstrativo.pdf",
    "tipo_documento": "pendente_classificacao",
    "status_processamento": "enviado",
    "status_documento": "enviado",
    "modelo_documento_sugerido_id": null,
    "modelo_documento_confirmado_id": null,
    "texto_extraido": null,
    "dados_extraidos_json": null,
    "resultado_ia": null,
    "score_confianca": null,
    "id_usuario_created": 7,
    "created_at": "2026-07-03T12:00:00",
    "updated_at": "2026-07-03T12:00:00"
  }
}

Escopo: nfse_repasse:read

`PUT /nfse-repasse/documentos/documentos-entrada/{documento_id}`

Atualiza um documento de entrada (campos parciais via DocumentoEntradaUpdate). É por aqui que resultados de OCR/IA seriam persistidos (ex.: texto_extraido, dados_extraidos_json, status_processamento).

Parâmetros

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

Request (DocumentoEntradaUpdate - todos os campos opcionais)

{
  "status_processamento": "processado",
  "texto_extraido": "Demonstrativo de remuneração...",
  "score_confianca": 0.97
}

Response 200 OK

{
  "success": true,
  "message": "Documento de entrada atualizado!",
  "data": {
    "id": 42,
    "nome_arquivo": "demonstrativo.pdf",
    "arquivo_url": "https://storage/.../demonstrativo.pdf",
    "tipo_documento": "pendente_classificacao",
    "status_processamento": "processado",
    "status_documento": "enviado",
    "modelo_documento_sugerido_id": null,
    "modelo_documento_confirmado_id": null,
    "texto_extraido": "Demonstrativo de remuneração...",
    "dados_extraidos_json": null,
    "resultado_ia": null,
    "score_confianca": 0.97,
    "id_usuario_created": 7,
    "created_at": "2026-07-03T12:00:00",
    "updated_at": "2026-07-03T13:20:00"
  }
}

Escopo: nfse_repasse:write

`DELETE /nfse-repasse/documentos/documentos-entrada/{documento_id}`

Remove um documento de entrada pelo ID.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Documento de entrada removido!",
  "data": null
}

Escopo: nfse_repasse:write

documentos-pdf

`POST /nfse-repasse/documentos/documentos-pdf/`

Cria um registro de PDF vinculado a um documento de entrada.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (DocumentoPdfCreate). Campos obrigatórios: documento_entrada_id e nome_arquivo; o arquivo é referenciado por arquivo_url (string) - não há upload multipart.

Request

{
  "documento_entrada_id": 42,
  "nome_arquivo": "pagina1.pdf",
  "arquivo_url": "https://storage/.../pagina1.pdf",
  "total_paginas": 1
}

Response 201 Created

{
  "success": true,
  "message": "PDF do documento criado com sucesso!",
  "data": {
    "id": 9,
    "documento_entrada_id": 42,
    "nome_arquivo": "pagina1.pdf",
    "arquivo_url": "https://storage/.../pagina1.pdf",
    "mime_type": "application/pdf",
    "tamanho_bytes": 20480,
    "total_paginas": 1,
    "texto_extraido": null,
    "uuid_legado": null,
    "id_usuario_created": 7,
    "created_at": "2026-07-03T12:00:00",
    "updated_at": "2026-07-03T12:00:00"
  }
}

Escopo: nfse_repasse:write

`GET /nfse-repasse/documentos/documentos-pdf/by-documento/{documento_entrada_id}`

Lista os PDFs de um documento de entrada específico. Rota estática, declarada antes de /{pdf_id} para não colidir com a rota dinâmica.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`documento_entrada_id`	`int`	path	sim	ID do documento de entrada dono dos PDFs
`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": "PDFs recuperados com sucesso!",
  "data": [
    {
      "id": 9,
      "documento_entrada_id": 42,
      "nome_arquivo": "pagina1.pdf",
      "arquivo_url": "https://storage/.../pagina1.pdf",
      "mime_type": "application/pdf",
      "tamanho_bytes": 20480,
      "total_paginas": 1,
      "texto_extraido": null,
      "uuid_legado": null,
      "id_usuario_created": 7,
      "created_at": "2026-07-03T12:00:00",
      "updated_at": "2026-07-03T12:00:00"
    }
  ]
}

Escopo: nfse_repasse:read

`GET /nfse-repasse/documentos/documentos-pdf/`

Lista PDFs de documento com filtro opcional.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`documento_entrada_id`	`int`	query	não	Filtro por documento de entrada.
`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": "PDFs recuperados com sucesso!",
  "data": [
    {
      "id": 9,
      "documento_entrada_id": 42,
      "nome_arquivo": "pagina1.pdf",
      "arquivo_url": "https://storage/.../pagina1.pdf",
      "mime_type": "application/pdf",
      "tamanho_bytes": 20480,
      "total_paginas": 1,
      "texto_extraido": null,
      "uuid_legado": null,
      "id_usuario_created": 7,
      "created_at": "2026-07-03T12:00:00",
      "updated_at": "2026-07-03T12:00:00"
    }
  ]
}

Escopo: nfse_repasse:read

`GET /nfse-repasse/documentos/documentos-pdf/{pdf_id}`

Busca um PDF de documento pelo ID. Quando não encontrado, retorna 404 Not Found.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "PDF do documento encontrado!",
  "data": {
    "id": 9,
    "documento_entrada_id": 42,
    "nome_arquivo": "pagina1.pdf",
    "arquivo_url": "https://storage/.../pagina1.pdf",
    "mime_type": "application/pdf",
    "tamanho_bytes": 20480,
    "total_paginas": 1,
    "texto_extraido": null,
    "uuid_legado": null,
    "id_usuario_created": 7,
    "created_at": "2026-07-03T12:00:00",
    "updated_at": "2026-07-03T12:00:00"
  }
}

Escopo: nfse_repasse:read

`PUT /nfse-repasse/documentos/documentos-pdf/{pdf_id}`

Atualiza um PDF de documento (campos parciais via DocumentoPdfUpdate). documento_entrada_id é imutável - não pode ser reatribuído a outro documento.

Parâmetros

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

Request (DocumentoPdfUpdate - todos os campos opcionais)

{
  "total_paginas": 2,
  "tamanho_bytes": 40960,
  "texto_extraido": "Conteúdo extraído do PDF..."
}

Response 200 OK

{
  "success": true,
  "message": "PDF do documento atualizado!",
  "data": {
    "id": 9,
    "documento_entrada_id": 42,
    "nome_arquivo": "pagina1.pdf",
    "arquivo_url": "https://storage/.../pagina1.pdf",
    "mime_type": "application/pdf",
    "tamanho_bytes": 40960,
    "total_paginas": 2,
    "texto_extraido": "Conteúdo extraído do PDF...",
    "uuid_legado": null,
    "id_usuario_created": 7,
    "created_at": "2026-07-03T12:00:00",
    "updated_at": "2026-07-03T13:20:00"
  }
}

Escopo: nfse_repasse:write

`DELETE /nfse-repasse/documentos/documentos-pdf/{pdf_id}`

Remove um PDF de documento pelo ID.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "PDF do documento removido!",
  "data": null
}

Escopo: nfse_repasse:write

Schemas

`ModeloDocumentoCreate`

Campo	Tipo	Obrigatório	Observações
`nome_modelo`	`str`	sim	Máx. 200 caracteres.
`tipo_documento`	`str`	não	Máx. 50. Default `"solicitacao_nota"`.
`descricao`	`str`	não	Descrição livre.
`palavras_chave`	`list[str]`	não	Palavras-chave para identificação automática.
`regex_identificacao`	`str`	não	Regex para casar o documento.
`exemplo_nome_arquivo`	`str`	não	Máx. 255.
`ativo`	`str`	não	`'S'` ou `'N'`. Default `'S'`.
`uuid_legado`	`str`	não	Máx. 36. UUID de origem no Supabase (rastreabilidade da migração).

ModeloDocumentoUpdate tem os mesmos campos, todos opcionais, exceto uuid_legado (imutável - não aparece no Update). ModeloDocumentoRead acrescenta id, id_usuario_created, created_at e updated_at.

`ModeloDescricaoNotaCreate`

Campo	Tipo	Obrigatório	Observações
`nome_modelo`	`str`	sim	Máx. 200 caracteres.
`descricao_texto`	`str`	não	Texto de descrição da nota.
`status`	`str`	não	`'ativo'` ou `'inativo'`. Default `'ativo'`.
`uuid_legado`	`str`	não	Máx. 36. UUID de origem no Supabase.

ModeloDescricaoNotaUpdate traz nome_modelo, descricao_texto e status - todos opcionais. ModeloDescricaoNotaRead acrescenta id, uuid_legado, id_usuario_created, created_at, updated_at.

`DocumentoEntradaCreate`

Campo	Tipo	Obrigatório	Observações
`nome_arquivo`	`str`	sim	Máx. 255.
`arquivo_url`	`str`	não	URL do arquivo armazenado (não é upload multipart).
`tipo_documento`	`str`	não	Máx. 50. Default `"pendente_classificacao"`. Domínio fechado (ver Notas).
`status_processamento`	`str`	não	`enviado` \| `processando` \| `processado` \| `erro`. Default `enviado`.
`status_documento`	`str`	não	Máx. 30. Default `"enviado"`.
`uuid_prestador_legado`	`str`	não	Máx. 36. UUID do prestador (domínio `prestador_medico`).
`modelo_documento_sugerido_id`	`int`	não	Modelo sugerido pela classificação automática.
`modelo_documento_confirmado_id`	`int`	não	Modelo confirmado por humano.
`texto_extraido`	`str`	não	Texto extraído pelo OCR (populado depois).
`dados_preliminares`	`Any`	não	JSON livre.
`dados_extraidos_json`	`Any`	não	JSON livre - resultado estruturado.
`resultado_ia`	`Any`	não	JSON livre - saída do modelo de IA.
`score_confianca`	`float`	não	Confiança da extração.
`classificacao_confianca`	`float`	não	Confiança da classificação de tipo.
`observacoes`	`str`	não	Observações livres.
`uuid_legado`	`str`	não	Máx. 36. UUID de origem no Supabase.

DocumentoEntradaUpdate traz os mesmos campos, todos opcionais, exceto uuid_legado (imutável). DocumentoEntradaRead acrescenta id, uuid_legado, id_usuario_created, created_at, updated_at.

`DocumentoPdfCreate`

Campo	Tipo	Obrigatório	Observações
`documento_entrada_id`	`int`	sim	Documento de entrada dono do PDF.
`nome_arquivo`	`str`	sim	Máx. 255.
`arquivo_url`	`str`	não	URL do arquivo (não é upload multipart).
`mime_type`	`str`	não	Máx. 100. Default `"application/pdf"`.
`tamanho_bytes`	`int`	não	≥ 0.
`total_paginas`	`int`	não	≥ 0.
`texto_extraido`	`str`	não	Texto extraído do PDF (populado depois).
`uuid_legado`	`str`	não	Máx. 36. UUID de origem no Supabase.

DocumentoPdfUpdate traz nome_arquivo, arquivo_url, mime_type, tamanho_bytes, total_paginas, texto_extraido - todos opcionais. documento_entrada_id não aparece no Update (imutável, bloqueia transferência entre documentos). DocumentoPdfRead acrescenta 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).
Sem upload multipart e sem task Celery nesta fatia. Os arquivos são referenciados por arquivo_url (string). O pipeline OCR - extração de texto, classificação por IA e as tasks Celery que populam texto_extraido, dados_extraidos_json, resultado_ia e os scores - virá em uma etapa posterior e não está exposto aqui.
Domínios fechados (validados na API via Pydantic, não no banco):
- modelo_documento.ativo: S | N.
- modelo_descricao_nota.status: ativo | inativo.
- documento_entrada.status_processamento: enviado | processando | processado | erro.
- documento_entrada.tipo_documento: pendente_classificacao, email_pdf, demonstrativo_remuneracao_individual, demonstrativo_remuneracao_individual_dasa, demonstrativo_operadora, nota_fiscal, relatorio_tomador, outro.
id_usuario_created não entra no Create - é forçado pelo service a partir do usuário autenticado.
uuid_legado é metadado de migração: aceito no Create (correlação com o registro de origem no Supabase), imutável depois.
Ordem de rotas: em documentos-pdf, a rota estática GET /by-documento/{documento_entrada_id} é declarada antes de GET /{pdf_id} - o FastAPI faz match na ordem de declaração, então by-documento não é interpretado como um pdf_id.
Escritas exigem escopo nfse_repasse:write e perfil administrador; leituras exigem nfse_repasse:read e qualquer usuário autenticado.