mostValid Content Extraction - CE

Rotas para extração e complementação de dados de documentos. Quando a extração automática não atende às regras definidas pelo cliente, o documento é encaminhado para revisão no Portal mostValid antes de o resultado ser devolvido.

Fluxo de integração

A integração segue sempre a mesma sequência: o backend do cliente obtém um token na rota de autenticação e o utiliza para chamar a rota de serviço desejada.

Authenticate (Get JWT)

Rota para obter um token de autenticação a partir da client key.

AVISO
Para elevar a segurança, utilizamos o padrão JWT, com tokens únicos e temporários: cada token pode ser utilizado uma única vez e expira em 10 minutos. Dessa forma, é necessário obter um novo token de autenticação para cada requisição.

O token obtido nesta rota é utilizado para autenticar as rotas Enviar documento e Consultar status.

Enviar documento (Content Extraction)

Rota assíncrona para extração e complementação de dados de documentos.

Diferentemente da extração síncrona, a extração assíncrona do mostValid permite que o cliente receba os dados extraídos do arquivo em uma URL de sua escolha (webhook), sem precisar aguardar a resposta na própria requisição.

Como funciona

O arquivo enviado é processado pelo mostQI Content Extraction, que analisa o documento, identifica a sua estrutura e extrai o conteúdo.

Se algum documento do arquivo não for identificado, é criada uma tarefa de revisão para ele no Portal mostValid.

Para os documentos identificados, o mostValid avalia as regras definidas pelo cliente, com base nas tags dos documentos, nos filtros e nos scores de referência.

Se o documento corresponder a alguma regra, são geradas tarefas de revisão para os documentos, campos, tabelas e/ou células de tabela que necessitam de revisão humana. As tarefas ficam disponíveis no Portal mostValid por até 30 dias; após esse prazo, o processo é cancelado.

Se não houver tarefas a realizar, ou após a conclusão da revisão, o resultado é gerado e enviado ao webhook do cliente, quando informado.

Notificações via webhook

Quando o parâmetro webhook é informado, o mostValid envia notificações para a URL configurada:

Notificação intermediária: enviada ao término da extração automática, quando o documento precisa de revisão. Ela apresenta a situação parcial do processo, indicando quais itens (documentos, campos, tabelas e células) estão pendentes de revisão humana (status TO_ANALYSIS) e quais não precisam de revisão (status MOSTQIIOCR).

Notificação de extração: indica que o processo foi concluído e apresenta todos os dados extraídos do arquivo enviado.

Notificação de alerta: indica que o processo foi concluído, mas houve alguma falha durante a sua execução.

Fluxos de extração

Esta rota permite dois tipos de fluxo de extração.

1. Fluxo de requisição única

O arquivo é enviado em uma única requisição. É feita a extração dos dados do(s) documento(s) presente(s) no arquivo e, caso o melhor documento se enquadre em alguma regra de validação do cliente, é aberta uma tarefa de revisão humana.

2. Fluxo de múltiplas requisições

Projetado para processos de integração (onboarding) em que o responsável pela captura das imagens precisa ter a flexibilidade de fazer várias tentativas. Cada tentativa é tratada como um processo (identificado pelo processId) dentro de uma mesma operação (parâmetro operation), antes da abertura de uma tarefa de revisão humana no mostValid.

Finalizadas as tentativas de captura da operação, o processo com a extração da melhor captura (maior score) segue normalmente e, caso o documento se enquadre em alguma regra de validação do cliente, é aberta a tarefa de revisão humana.

Retorno da rota

O retorno da rota é um código de processo (processId), único por requisição enviada, e um código de operação (operationId), no caso do fluxo de múltiplas requisições.

Para acompanhar o andamento, o cliente pode receber as notificações no webhook informado na requisição ou consultar a situação do processo na rota Consultar status até obter o resultado da extração.

Consultar status (Process Status)

Rota para consultar o status do processamento do arquivo enviado na rota de extração do mostValid. O cliente pode realizar consultas periódicas nesta rota até obter o resultado da extração. No fluxo de múltiplas requisições, a resposta também traz o operationId e indica, pelo processStatus, se a operação ainda aguarda novas capturas (WAITING_OPERATION_FINISH).

NOTA
O resultado do processo fica disponível para consulta por até uma hora após a sua conclusão. Esse período é contado a partir do momento em que o processo atinge um dos status finais: FINISHED, CANCELED ou ERROR.
Uma tarefa de revisão permanece na fila do mostValid por até 30 dias corridos, contados a partir da data de sua abertura. Caso não seja realizada nesse prazo, o status da tarefa e o processStatus são atualizados automaticamente para CANCELED.
Caso o processStatus retornado seja ERROR, entre em contato com o suporte pelo e-mail suporte@most.com.br, informando o processId da requisição.

Status do processo

Possíveis status retornados no campo processStatus:

Status	Descrição
`IN_PROCESS`	O arquivo enviado está sendo tipificado e processado para verificar se necessita de complementação.
`WAITING_OPERATION_FINISH`	Há uma operação (`operation`) em andamento, e é necessário o envio de outro arquivo para que o processo continue ou seja finalizado.
`CANCELED`	O processo foi cancelado em um fluxo de múltiplas requisições (`operation`). Isso ocorre quando outro arquivo da mesma operação foi processado sem necessidade de gerar tarefa, ou quando foi aberta uma tarefa para outro processo da mesma operação. Também ocorre quando a tarefa de revisão não é realizada no prazo de 30 dias.
`ERROR`	Ocorreu um erro durante uma ou mais etapas do processo.
`TO_ANALYSIS`	O arquivo necessita de complementação e está aguardando para ser analisado.
`IN_ANALYSIS`	O arquivo necessita de complementação e está sendo analisado por um revisor.
`FINISHED`	O arquivo foi analisado com sucesso e o resultado foi retornado, com ou sem complementação.

Status dos atributos

Possíveis status retornados no campo status dos atributos, em que o contexto pode se referir ao documento, ao campo, à célula da tabela ou ao cabeçalho da tabela:

Status	Descrição
`TO_ANALYSIS`	O item necessita de revisão e está aguardando análise.
`MOSTQIIOCR`	O item não foi enviado para revisão, pois, conforme as regras do cliente, a extração feita já é considerada válida.
`MODIFIED`	O item foi enviado para revisão, conforme as regras definidas pelo cliente, e o seu conteúdo original foi modificado pelo revisor.
`UNREADABLE`	O item foi enviado para revisão, conforme as regras definidas pelo cliente, e foi marcado como ilegível pelo revisor.
`REVIEWED`	O item foi enviado para revisão, conforme as regras definidas pelo cliente, e o seu conteúdo original não foi modificado pelo revisor.
`DEPRECATED`	O item corresponde a um campo depreciado, que não é exibido no Portal mostValid durante a tarefa de revisão. Recomenda-se utilizar os nomes de campos correspondentes atualizados. Confira a listagem atualizada de documentos e campos aqui.

Exemplo prático

Quando o revisor marca um campo como ilegível, o JSON de retorno reflete isso no atributo status:

{
  "name": "nome_empregador",
  "value": "EXEMPLO",
  "score": 1,
  "status": "UNREADABLE"
}

Status da operação

No fluxo de múltiplas requisições, a operação pode assumir os seguintes status:

Status	Descrição
`WAITING_NEW_ENTRY`	A operação está aguardando uma nova entrada para continuar o processo.
`IN_PROCESS`	A operação está sendo processada.
`FINISHED`	A operação foi finalizada.

mostValid Content Extraction - CE

Fluxo de integração#

Authenticate (Get JWT)#

Enviar documento (Content Extraction)#

Como funciona#

Notificações via webhook#

Fluxos de extração#

Retorno da rota#

Consultar status (Process Status)#

Status do processo#

Status dos atributos#

Exemplo prático#

Status da operação#