Extração de OCR — OCR Extract

A funcionalidade Extração de OCR (ocr_extract) usa OCR com suporte de IA para extrair texto visível de imagens (nomes, números e demais conteúdos legíveis), conforme o prompt configurado para a unidade.

Sem interface no portal: não há botão, modal, painel de configuração visível ao usuário nem qualquer fluxo de UI no portal legado (mm-pacs-portal-frontend) ou no new viewer. O uso operacional ocorre somente via backend — serviços ou integrações que chamam diretamente a AI-API.

---

Para quem é

Persona	Quem é	O que faz aqui
Backend / integração	serviço consumidor da AI-API	envia imagens e recebe o texto extraído
Operações / DevOps	equipe que mantém a AI-API	garante configuração ocr_extract ativa por unidade

Este documento não descreve fluxo de tela — apenas contrato e comportamento da API.

---

Pré-requisitos

• Funcionalidade OCR Extract (ocr_extract) ativa e configurada para a unidade (companyId) — provider, modelo, token e prompts válidos no backend da AI-API.
• Consumidor com permissão de chamar POST /ocr/extract/{companyId}.
• Entre 1 e 12 imagens por requisição (JPEG, PNG ou GIF; até 25 MB cada).
• Idioma de saída (language: pt-BR, es-ES, en-US).

---

Diagrama de sequência

Fluxo de execução via backend:

---

Fluxo de execução (backend)

1. Validar configuração da unidade

Antes de chamar o endpoint, confirme que a unidade possui ocr_extract habilitado e configurado na AI-API (provider, modelo, token e prompts). Sem configuração válida, a API retorna erro de configuração ausente.

2. Enviar imagens

Monte uma requisição multipart/form-data com:

• images — de 1 a 12 arquivos de imagem;
• language — idioma da saída (pt-BR, es-ES, en-US; padrão pt-BR).

Path: POST /ocr/extract/{companyId}.

Para processamento assíncrono, inclua o header request-type: job — a resposta inicial traz jobId e status (queued).

3. Consumir o resultado

• Síncrono: corpo { "result": "<texto extraído>" }.
• Assíncrono: consultar o job conforme o fluxo de jobs da AI-API até obter o texto final.

---

Campos / entradas

Campo / origem	Descrição
companyId	ID da unidade (path)
images	Array de arquivos binários (JPEG, PNG ou GIF); mín. 1, máx. 12; até 25 MB cada
language	Idioma da resposta (pt-BR, es-ES, en-US)
request-type (header)	Opcional: job para resposta assíncrona

---

Saída esperada

Modo	Campo	Descrição
Síncrono	result	Texto extraído das imagens (nomes, números e demais conteúdos legíveis)
Assíncrono	jobId, status	Identificador e status inicial do job (queued, etc.)

Exemplo (síncrono):

json
{
  "result": "NOMES:\nJoão Silva\n\nNÚMEROS:\n123456789"
}

---

Endpoints utilizados

Endpoint	Descrição
AI_API POST /ocr/extract/{companyId}	Envia imagens; retorna texto extraído (result) ou job assíncrono (jobId).

→ Detalhe técnico: OCR Extract — OpenAPI

---

Regras de negócio

ID	Regra	Comportamento esperado
RN-01	Sem interface	Nenhum fluxo de UI no portal legado — nem execução nem configuração exposta ao usuário final.
RN-02	Escopo de configuração	ocr_extract — somente empresa (configurationScope: "company").
RN-03	Limite de imagens	Entre 1 e 12 imagens por requisição.
RN-04	Tamanho por arquivo	Até 25 MB por imagem.
RN-05	Formatos aceitos	JPEG, PNG ou GIF.
RN-06	Modo assíncrono	Header request-type: job retorna jobId; resultado final via fluxo de jobs.
RN-07	Consumidor	Qualquer serviço backend autorizado — não o frontend do portal.

---

Mapeamento de erros

Situação	Resposta da API	Comportamento
Nenhuma imagem enviada	400 — IMAGES_REQUIRED	Mensagem: at least one image is required.
Mais de 12 imagens ou arquivo inválido	400	Erro de validação do payload multipart.
Configuração ausente / inválida para a unidade	4xx (conforme AI-API)	Tratado pelo consumidor backend.
Provider / token / modelo inválido	4xx / 5xx	Erro de integração com o provider — ver OpenAPI e logs da AI-API.
Falha interna	500 — UNEXPECTED_ERROR	Erro genérico do servidor.
Execução via portal legado		Não aplicável — não há fluxo de UI.

---

Relacionado

• 📄 API: OCR Extract