Retorno do Webhook
webhook é informado no envio do documento, a mostValid notifica a URL configurada quando o processo é enviado para revisão e quando atinge um status final, enviando o resultado do processamento. Dessa forma, não é necessário consultar periodicamente a rota Consultar status para saber se o resultado está disponível.Configurando o webhook
| Parâmetro (JSON) | Parâmetro (form-data) | Obrigatório | Descrição |
|---|---|---|---|
webhook.url | webhook.url | Não | URL que receberá o resultado do processamento. |
webhook.fallbackUrl | webhook.fallbackUrl | Não | URL alternativa, utilizada quando não for possível entregar o resultado na webhook.url. |
webhook:{
"fileUrl": "https://exemplo.com.br/documentos/nota-fiscal.pdf",
"webhook": {
"url": "https://seu-dominio.com.br/webhook/mostvalid",
"fallbackUrl": "https://seu-dominio.com.br/webhook/mostvalid-fallback"
}
}Importante: as URLs informadas devem ser públicas, utilizar HTTPS e estar preparadas para receber requisições POSTcom corpoapplication/json.
Quando o webhook é enviado
processStatus | Quando ocorre |
|---|---|
TO_ANALYSIS | O documento precisa de complementação e foi gerada uma tarefa de revisão. |
FINISHED | O processo foi concluído e o resultado está disponível, com ou sem revisão. |
ERROR | Ocorreu um erro no processamento. O motivo é informado em processStatusDescription. |
IN_PROCESS, IN_ANALYSIS e CANCELED não geram notificação via webhook.Atenção: um mesmo processo pode gerar mais de uma notificação. Quando o documento vai para revisão, sua aplicação recebe primeiro um webhook com TO_ANALYSISe, após a conclusão da revisão, um segundo webhook comFINISHED. Utilize o campoprocessStatuspara identificar a etapa de cada notificação.
Estrutura do payload
requestId, elapsedMilliseconds e status) não são enviados, pois o webhook não é a resposta a uma chamada feita pelo cliente.| Campo | Tipo | Descrição |
|---|---|---|
mostQiRequestId | string | Identificador da requisição de extração. |
processId | string (UUID) | Identificador do processo, o mesmo retornado no envio do documento. Utilize-o para relacionar o webhook à requisição original. |
processStatus | string | Status final do processo. Os valores possíveis estão descritos em Status do processo. |
processStatusDescription | string | null | Detalhe sobre o status do processo. É preenchido principalmente em casos de ERROR, com o motivo da falha; nos demais casos, geralmente é enviado como null. |
result | array | null | Resultado da extração, com a mesma estrutura da rota Consultar status (type, stdType, extractions, sections, fields e tables). Em casos de ERROR, é enviado como null. |
REVIEWED, MODIFIED ou UNREADABLE, e o valor a ser utilizado é sempre o do campo finalValue.Exemplos de payload
Processo finalizado (FINISHED)
REVIEWED e finalValue igual a null.{
"mostQiRequestId": "Tn6wQa1ZeX8cVb3MkL9Rp",
"processId": "5e8a1c3f-7b2d-4f6e-9a0c-1d3b5f7e9a2c",
"processStatus": "FINISHED",
"processStatusDescription": null,
"result": [
{
"type": "documento-fiscal",
"stdType": "fiscal-document",
"extractions": [
{
"source": "iocr",
"score": 0.99,
"status": "REVIEWED",
"tags": [
"country=bra",
"id=bra-nlp-danfce-1",
"language=pt-BR",
"std-type=fiscal-document",
"subtype=danfce",
"type=documento-fiscal"
],
"sections": [
{
"name": "documento",
"stdName": "document",
"score": 0.99,
"status": "REVIEWED",
"fields": [
{
"name": "nome_prestador",
"stdName": "supplier_name",
"value": "EMPRESA EXEMPLO SERVIÇOS IMOBILIÁRIOS LTDA.",
"finalValue": "EMPRESA EXEMPLO SERVIÇOS IMOBILIÁRIOS LTDA.",
"score": 0.69,
"status": "MOSTQIIOCR"
},
{
"name": "nome_fantasia_prestador",
"stdName": "supplier_trade_name",
"value": null,
"finalValue": null,
"score": null,
"status": "REVIEWED"
},
{
"name": "cpf_cnpj_prestador",
"stdName": "supplier_cpf_cnpj",
"value": "11222333000181",
"finalValue": "11222333000181",
"score": 0.99,
"status": "MOSTQIIOCR"
},
{
"name": "endereco_prestador",
"stdName": "supplier_address",
"value": "AV EXEMPLO, 100, SALA 101, Centro - Cep: 01234-567 Cidade Fictícia SP",
"finalValue": "AV EXEMPLO, 100, SALA 101, Centro - Cep: 01234-567 Cidade Fictícia SP",
"score": 0.99,
"status": "MOSTQIIOCR"
},
{
"name": "inscricao_estadual_prestador",
"stdName": "supplier_state_registration",
"value": null,
"finalValue": null,
"score": null,
"status": "REVIEWED"
},
{
"name": "valor_total",
"stdName": "total_value",
"value": "2425.00",
"finalValue": "2425.00",
"score": 0.99,
"status": "MOSTQIIOCR"
},
{
"name": "valor_desconto",
"stdName": "discount_value",
"value": "0.00",
"finalValue": "0.00",
"score": 0.99,
"status": "MOSTQIIOCR"
},
{
"name": "valor_total_bruto",
"stdName": "total_gross_value",
"value": "2500.00",
"finalValue": "2500.00",
"score": 0.99,
"status": "MOSTQIIOCR"
},
{
"name": "chave_acesso",
"stdName": "access_key",
"value": null,
"finalValue": null,
"score": null,
"status": "REVIEWED"
},
{
"name": "nome",
"stdName": "name",
"value": "MARIA SILVA SANTOS",
"finalValue": "MARIA SILVA SANTOS",
"score": 0.99,
"status": "MOSTQIIOCR"
},
{
"name": "endereco",
"stdName": "address",
"value": null,
"finalValue": null,
"score": null,
"status": "REVIEWED"
},
{
"name": "cpf_cnpj",
"stdName": "cpf_cnpj",
"value": "12345678909",
"finalValue": "12345678909",
"score": 0.99,
"status": "MOSTQIIOCR"
},
{
"name": "numero_documento",
"stdName": "document_number",
"value": "000123",
"finalValue": "000123",
"score": 0.94,
"status": "MOSTQIIOCR"
},
{
"name": "serie",
"stdName": "serial",
"value": null,
"finalValue": null,
"score": null,
"status": "REVIEWED"
},
{
"name": "data_emissao",
"stdName": "issue_date",
"value": "2025-03-10",
"finalValue": "2025-03-10",
"score": 0.99,
"status": "MOSTQIIOCR"
},
{
"name": "hora_emissao",
"stdName": "issue_time",
"value": "14:30:00",
"finalValue": "14:30:00",
"score": 0.99,
"status": "MOSTQIIOCR"
},
{
"name": "numero_protocolo",
"stdName": "protocol_number",
"value": null,
"finalValue": null,
"score": null,
"status": "REVIEWED"
},
{
"name": "data_protocolo",
"stdName": "protocol_date",
"value": null,
"finalValue": null,
"score": null,
"status": "REVIEWED"
},
{
"name": "hora_protocolo",
"stdName": "protocol_time",
"value": null,
"finalValue": null,
"score": null,
"status": "REVIEWED"
},
{
"name": "valor_tributo",
"stdName": "tax_value",
"value": "75.00",
"finalValue": "75.00",
"score": 0.99,
"status": "MOSTQIIOCR"
}
],
"tables": [
{
"name": "tabela_demonstrativo",
"stdName": "demonstrative_table",
"score": 0.98,
"status": "REVIEWED",
"headers": [
{
"name": "codigo",
"stdName": "code",
"score": 0.99,
"status": "MOSTQIIOCR"
},
{
"name": "descricao",
"stdName": "description",
"score": 0.99,
"status": "MOSTQIIOCR"
},
{
"name": "quantidade",
"stdName": "quantity",
"score": 0.99,
"status": "MOSTQIIOCR"
},
{
"name": "valor_unitario",
"stdName": "unit_value",
"score": 0.99,
"status": "MOSTQIIOCR"
},
{
"name": "valor_desconto",
"stdName": "discount_value",
"score": null,
"status": "REVIEWED"
},
{
"name": "valor",
"stdName": "value",
"score": 0.91,
"status": "MOSTQIIOCR"
}
],
"values": [
[
{
"name": "codigo",
"stdName": "code",
"value": "7890000000017",
"finalValue": "7890000000017",
"score": 0.99,
"status": "MOSTQIIOCR"
},
{
"name": "descricao",
"stdName": "description",
"value": "INTERMEDIAÇÃO NA COMPRA E VENDA DE IMÓVEIS",
"finalValue": "INTERMEDIAÇÃO NA COMPRA E VENDA DE IMÓVEIS",
"score": 0.99,
"status": "MOSTQIIOCR"
},
{
"name": "quantidade",
"stdName": "quantity",
"value": "1",
"finalValue": "1",
"score": 0.99,
"status": "MOSTQIIOCR"
},
{
"name": "valor_unitario",
"stdName": "unit_value",
"value": "2500.00",
"finalValue": "2500.00",
"score": 0.99,
"status": "MOSTQIIOCR"
},
{
"name": "valor_desconto",
"stdName": "discount_value",
"value": null,
"finalValue": null,
"score": null,
"status": "REVIEWED"
},
{
"name": "valor",
"stdName": "value",
"value": "2425.00",
"finalValue": "2425.00",
"score": 0.91,
"status": "MOSTQIIOCR"
}
]
]
},
{
"name": "tabela_forma_pagamento",
"stdName": "payment_method_table",
"score": null,
"status": "MOSTQIIOCR",
"headers": [
{
"name": "forma_pagamento",
"stdName": "payment_method",
"score": null,
"status": "MOSTQIIOCR"
},
{
"name": "valor",
"stdName": "value",
"score": null,
"status": "MOSTQIIOCR"
}
],
"values": []
}
]
}
]
}
]
}
]
}Processo com erro (ERROR)
result é null e o motivo do erro é informado em processStatusDescription.{
"mostQiRequestId": "Lm4nPq7RsT1uVw3XyZ5Ab",
"processId": "9b2e4d6f-1a3c-4e5b-8d7f-0c2a4e6b8d1f",
"processStatus": "ERROR",
"processStatusDescription": "The uploaded file is encrypted by a password",
"result": null
}Processo enviado para revisão (TO_ANALYSIS)
TO_ANALYSIS segue a mesma estrutura do exemplo de FINISHED. O result traz os dados extraídos até o momento, e os itens que aguardam revisão aparecem com status TO_ANALYSIS e finalValue igual a null (ou ainda sem o valor revisado). O resultado definitivo deve ser considerado apenas no webhook de FINISHED.Boas práticas para receber o webhook
2xx assim que receber a requisição e processe o conteúdo de forma assíncrona, evitando que a entrega seja considerada como falha.processId como chave. Relacione o webhook ao documento enviado por meio do processId. Como um mesmo processo pode notificar TO_ANALYSIS e depois FINISHED, use o processStatus para decidir a ação e trate de forma idempotente uma mesma notificação recebida mais de uma vez.ERROR, verifique o processStatusDescription para identificar o motivo, como um arquivo protegido por senha, e, se for o caso, reenvie o documento corrigido (por exemplo, informando o filePassword).finalValue. O campo value contém o valor extraído originalmente; o finalValue contém o valor final, já considerando a revisão, quando houver.processId.Modificado em 2026-10-23 17:25:40