API de processamento do lado do servidor do FormRead

Processamento de Formulários no Lado do Servidor

A API do lado do servidor do FormRead permite enviar uma imagem de formulário escaneado e receber resultados estruturados (OMR, OCR, BCR) diretamente como JSON. Sem navegador, sem iframe - apenas uma simples solicitação HTTP do seu backend para o nosso.

• Envie uma imagem e receba os resultados como JSON em uma única solicitação
• Suporta OMR (detecção de bolhas), OCR (extração de texto) e BCR (leitura de código de barras/QR)
• A configuração do formulário é carregada automaticamente a partir do formulário que você configurou no painel

Autenticação

Para usos corporativos, a API pode ser usada gerando um token Bearer Auth.

Faça login no FormRead painel e acesse a opção API Token:

Crie os tokens de API para permitir que serviços de terceiros se autentiquem com nosso aplicativo em seu nome:

Processar uma Imagem de Formulário

Envie uma imagem de formulário escaneado para ser processada. O formulário já deve estar configurado com áreas de leitura (OMR, OCR, BCR) via painel ou iframe. A API usa a configuração de formulário salva para processar a imagem.

Cabeçalhos

Com upload de arquivo:

curl --location 'https://formread.org/api/forms/123/process' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --form 'image=@"/path/to/scanned-form.jpg"'

Com URL da imagem:

curl --location 'https://formread.org/api/forms/123/process' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"image_url": "https://example.com/scanned-form.jpg"}'

Resposta

{
  "success": true,
  "results": {
    "OMR-0-0": "A",
    "OMR-0-1": "C",
    "OMR-0-2": "B,D",
    "OCR-1": "John Smith",
    "BCR-2": "1234567890"
  },
  "omr_details": {
    "OMR-0": {
      "questions": [
        [
          {"left": 0.12, "top": 0.22, "width": 0.02, "height": 0.02, "blackPixelsRatio": 0.72},
          {"left": 0.15, "top": 0.22, "width": 0.02, "height": 0.02, "blackPixelsRatio": 0.15}
        ]
      ]
    }
  },
  "anchor_error": false,
  "processing_time_ms": 450
}

Campos da Resposta

Opções de Entrada de Imagem

Você pode fornecer a imagem de três maneiras. Use exatamente uma:

Processamento em lote

Para processar várias imagens do mesmo formulário em uma única solicitação, passe uma lista de URLs separadas por vírgulas no campo image_url. Os resultados são retornados como uma matriz na mesma ordem.

Solicitação

curl --location 'https://formread.org/api/forms/123/process' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"image_url": "https://example.com/a.jpg,https://example.com/b.jpg,https://example.com/c.jpg"}'

Resposta

{
  "results": [
    {
      "id": "0",
      "image_url": "https://example.com/a.jpg",
      "success": true,
      "results": { "OMR-0-0": "A", "OCR-1": "John Smith" },
      "anchor_error": false,
      "processing_time_ms": 430
    },
    {
      "id": "1",
      "image_url": "https://example.com/b.jpg",
      "success": true,
      "results": { "OMR-0-0": "B", "OCR-1": "Jane Doe" }
    },
    {
      "id": "2",
      "image_url": "https://example.com/c.jpg",
      "success": false,
      "error": "Failed to fetch image from URL: 404"
    }
  ],
  "total": 3
}

Parâmetros do lote

Lote com omr_details

curl --location 'https://formread.org/api/forms/123/process' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "image_url": "https://example.com/a.jpg,https://example.com/b.jpg",
    "details": true
  }'

Limites

Uma resposta 429 tem esta aparência:

{
  "message": "Too Many Attempts."
}

Uma solicitação em lote conta como uma chamada, independentemente de quantas URLs contém.

Tipos de Área Suportados

Exemplos de Código

Aqui estão exemplos completos em Python e JavaScript para processar uma imagem de formulário:

Python

import requests

API_URL = "https://formread.org/api/forms/{form_id}/process"
TOKEN = "YOUR_API_TOKEN"

with open("scanned-form.jpg", "rb") as f:
    response = requests.post(
        API_URL.format(form_id=123),
        headers={
            "Accept": "application/json",
            "Authorization": f"Bearer {TOKEN}",
        },
        files={"image": f},
    )

data = response.json()
print(data["results"])
# {"OMR-0-0": "A", "OMR-0-1": "C", "OCR-1": "John Smith"}

Node.js

const FormData = require('form-data');
const fs = require('fs');
const axios = require('axios');

const form = new FormData();
form.append('image', fs.createReadStream('scanned-form.jpg'));

const response = await axios.post(
  'https://formread.org/api/forms/123/process',
  form,
  {
    headers: {
      ...form.getHeaders(),
      'Accept': 'application/json',
      'Authorization': 'Bearer YOUR_API_TOKEN',
    },
  }
);

console.log(response.data.results);
// { 'OMR-0-0': 'A', 'OMR-0-1': 'C', 'OCR-1': 'John Smith' }

Perguntas frequentes