Manual de Integração para Desenvolvedores

1Como funciona

O navegador nunca fala com o scanner nem com a estação: tudo passa pelo seu servidor, autenticado por um token de pedido. São três peças — a sua tela, o seu servidor (dois endpoints) e o TCloud Scanner instalado na estação.

1. A tela pede ao endpoint do navegador (com a sessão do usuário) um pedido de digitalização. O servidor gera um token aleatório de 256 bits e devolve o link tcloudscan://digitalizar/?u=…&t=….
2. No clique do usuário, a tela abre o link com as opções escolhidas (resolução, cor, alimentação, frente e verso).
3. O Windows entrega o link ao TCloud Scanner, que pede ao usuário, na primeira vez, autorização para enviar ao endereço u.
4. A estação chama o endpoint da estação (u) com o token: info, depois inicio.
5. O TCloud Scanner digitaliza pelo driver TWAIN e envia cada página (JPEG ou PNG) com pagina, em segundo plano, enquanto o scanner continua.
6. Ao terminar, envia fim com o estado (concluido, cancelado ou erro).
7. Durante todo o processo, a tela consulta estado a cada segundo, mostra as páginas que chegam e, no fim, monta o PDF (ou usa as imagens) e apaga o pedido com descartar.

2Integração em 5 passos

Com o kit, a integração é um arquivo PHP copiado, dois endpoints de poucas linhas e um botão. Os exemplos abaixo são os da pasta exemplo/ do kit, testados ponta a ponta.

1. Copie o kit para o seu sistema. php/TCloudScanner.php (classe TCloudScannerServidor) e js/tcloudscan.js (cliente TCloudScan). Para montar PDF no navegador, sirva também a pdf-lib.min.js localmente (o Atlas tem em arquivamento/assets/vendor/).

2. Crie o endpoint da estação — público, sem sessão; o token é a credencial. Não inclua nada que abra sessão: cada chamada da estação criaria uma sessão vazia.

   PHPCopiar

   <?php
   // estacao.php
   require_once __DIR__ . '/lib/TCloudScanner.php';
   
   (new TCloudScannerServidor(__DIR__ . '/../dados/digitalizacoes', [
       'sistema' => 'BookC',      // nome mostrado na janela do TCloud Scanner
       'versao'  => '3.2.0',
   ]))->atenderEstacao();

3. Crie o endpoint do navegador — atrás da SUA autenticação e do seu CSRF. Quatro ações: criar, estado, pagina, descartar.

   PHPCopiar

   <?php
   // scanner-api.php — PHP 5.6+
   require_once __DIR__ . '/lib/TCloudScanner.php';
   exige_login();                       // a sua função
   if ($_SERVER['REQUEST_METHOD'] === 'POST') { exige_csrf(); }
   
   $usuario = usuario_logado();         // identificador do dono do pedido
   $tcs  = new TCloudScannerServidor(__DIR__ . '/../dados/digitalizacoes', array('sistema' => 'BookC'));
   $acao = isset($_REQUEST['acao']) ? $_REQUEST['acao'] : '';
   $t    = isset($_REQUEST['t']) ? $_REQUEST['t'] : '';
   
   switch ($acao) {
       case 'criar':
           $registro = isset($_POST['registro']) ? $_POST['registro'] : null;
           $p = $tcs->criarPedido($usuario, array(), array('registro' => $registro));
           session_write_close();
           json(array('ok' => true, 'token' => $p['token'],
                 'link' => 'tcloudscan://digitalizar/?u='
                         . rawurlencode(TCloudScannerServidor::urlVizinha('estacao.php'))
                         . '&t=' . $p['token']));
       case 'estado':
           session_write_close();       // consultado a cada segundo
           $e = $tcs->estado($t, $usuario);
           $e ? json(array('ok' => true) + $e) : json(array('ok' => false, 'erro' => 'Pedido não encontrado.'), 404);
       case 'pagina':
           session_write_close();
           $n = isset($_GET['n']) ? (int) $_GET['n'] : 0;
           $tcs->enviarPagina($t, $usuario, $n);   // serve a imagem e encerra
       case 'descartar':
           $motivo = isset($_POST['motivo']) ? $_POST['motivo'] : 'descartado';
           $tcs->descartar($t, $usuario, $motivo);
           json(array('ok' => true));
   }

4. Ponha o botão na tela. O pedido é criado ao abrir a tela (preparar) porque o navegador só abre link de aplicativo dentro do clique do usuário — se o fetch de criação acontecer depois do clique, o gesto pode expirar.

   HTMLCopiar

   <script src="js/tcloudscan.js"></script>
   <script>
   var scan = new TCloudScan({
     api: 'scanner-api.php',
     cabecalhos: { 'X-CSRF-Token': CSRF },
     aoChegar: function (p) { mostrarMiniatura(scan.urlPagina(p.n), p); },
     aoMudar: function (e) { mostrarStatus(e.estado, e.paginas.length, e.mensagem); },
     aoSemResposta: function () { mostrarComoInstalar(); }
   });
   scan.preparar();
   
   botaoDigitalizar.onclick = function () {
     scan.digitalizar({ dpi: 300, cor: 'cinza', alimentacao: 'auto', duplex: false, interface: false });
   };
   </script>

5. Use o resultado e limpe. Monte o PDF no navegador e envie pelo seu upload normal, ou leia as imagens no servidor com caminhosPaginas(). Depois chame descartar — o pedido não deve ficar no disco.

   JavaScriptCopiar

   scan.montarPdf(scan.paginas, window.PDFLib, 'Matrícula 12.345').then(function (bytes) {
     var arquivo = new File([bytes], 'digitalizacao.pdf', { type: 'application/pdf' });
     minhaFilaDeUpload.adicionar(arquivo);
     scan.descartar('anexado');
   });

3O link tcloudscan://

O link carrega o endereço do endpoint da estação, o token e as opções; só u e t são obrigatórios. As opções vêm do link, e não do servidor, para que a tela possa mudá-las sem criar outro pedido.

tcloudscan://digitalizar/?u=http%3A%2F%2F26.10.20.30%2Fbookc%2Festacao.php&t=86df8cfb…a24&dpi=300&cor=cinza&alim=auto&duplex=0&ui=0&fmt=pdf

• O caminho depois de tcloudscan:// (digitalizar/) é fixo; mantenha-o para compatibilidade com versões futuras.
• u deve ser o endereço como a estação o enxerga. Como a estação é o mesmo computador do navegador, o host da própria requisição serve (TCloudScannerServidor::urlVizinha()). Atrás de proxy reverso ou NAT, fixe o endereço em configuração.
• Abra o link criando um <a href> oculto e chamando click() dentro do clique do usuário (TCloudScan.abrirLink). Se a sua página tem aviso de beforeunload, ignore-o enquanto TCloudScan.abrindoLink for true.
• Recursos que o scanner não tem são ignorados e ele digitaliza com o padrão dele. Se o driver recusar operar sem a própria janela, o TCloud Scanner abre a janela do driver.

4Formato de saída: imagens, JPG ou PDF

O sistema que integra decide como a digitalização chega, pelo fmt do link e pelo formato gravado no pedido. O padrão continua imagem, igual às versões anteriores.

// O formato gravado no pedido é o EXIGIDO: estação anterior à 1.2.0 é recusada no inicio.
$p = $tcs->criarPedido($usuario, array('formato' => 'pdf'));

var scan = new TCloudScan({
  api: 'scanner-api.php',
  formato: 'pdf',                               // vai no criar e no link
  aoDocumento: function (doc) {                 // {bytes, paginas, sha256, recebido}
    visualizador.src = scan.urlDocumento();
  }
});

Como o modo PDF funciona. A estação guarda cada página em qualidade total no próprio disco e envia ao sistema só uma prévia reduzida (até ~1400 px), para a tela acompanhar. Ao terminar, gera o PDF — JPEG embutido sem recompressão, P&B em 1 bit — e o envia em partes com a ação documento. O servidor confere o SHA-256 antes de aceitar. "Digitalizar mais páginas" gera o PDF de novo com todas as páginas do pedido e substitui o anterior. O estado só vira concluido depois de o PDF chegar.

• Use pdf quando o sistema só precisa guardar o documento: o PDF sai pronto da estação, sem pdf-lib no navegador nem TCPDF no servidor.
• Use imagem ou jpg quando o usuário for girar, excluir ou reordenar páginas na tela antes de anexar: no modo pdf, essas ações nas prévias não mudam o PDF da estação.
• As páginas em qualidade total ficam na estação em %LOCALAPPDATA%\TCloud\Scanner\pedidos\<token> e são apagadas quando o pedido vence.

5Endpoint da estação

Um único URL (o u do link) atende cinco ações pelo parâmetro acao. A estação chama sempre nesta ordem: info → inicio → pagina (N vezes) → (só no formato pdf: documento, em partes) → fim. Clicar em "Digitalizar mais páginas" repete inicio → pagina → fim com o mesmo token, e as páginas continuam a numeração.

Regras comuns a todas as chamadas

• Autenticação: cabeçalho X-TCloud-Token: <token> (aceite também ?t= como reserva). Sem sessão, sem cookie.
• User-Agent: TCloudScanner/<versão>. Não use para autorizar — serve só para log.
• Resposta sempre JSON UTF-8: {"ok": true, …} ou {"ok": false, "erro": "mensagem para o usuário"}. A estação mostra erro na tela, então escreva em português claro.
• Erro com corpo JSON (4xx) não é repetido pela estação. Falha de rede sem resposta é repetida até 4 vezes, com espera crescente.

Exemplos

GET /bookc/estacao.php?acao=info
X-TCloud-Token: 86df8cfb491d71c7c6af88362d30f220e68ea113dfe4a8b3467c2ca00bc85a24

200 {"ok":true,"sistema":"BookC","versao":"3.2.0","estado":"aguardando",
     "opcoes":{"dpi":300,"cor":"cinza","duplex":false,"alimentacao":"auto","interface":false},
     "paginas":0,"limite":400,"expira":1791233406}

POST /bookc/estacao.php?acao=inicio
X-TCloud-Token: 86df8c…
Content-Type: application/json

{"estacao":"RECEPCAO-02","versao":"1.2.0","scanner":"fi-7160","formato":"pdf"}

200 {"ok":true,"paginas":0}

POST /bookc/estacao.php?acao=pagina
X-TCloud-Token: 86df8c…
Content-Type: image/jpeg
X-Dpi: 300
Content-Length: 1482211

<bytes do JPEG>

200 {"ok":true,"n":3}
422 {"ok":false,"erro":"A página precisa ser JPEG ou PNG."}

POST /bookc/estacao.php?acao=documento          (formato pdf: um POST por pedaço)
X-TCloud-Token: 86df8c…
Content-Type: application/pdf
X-Offset: 8323072
X-Total: 9841520
X-Paginas: 12
X-Sha256: 5b25cd66a903680b4039893d3e8fcd548fa53ed922f68b4d9923e0716d9698e8
X-Final: 1

<bytes 8323072 a 9841519 do PDF>

200 {"ok":true,"recebido":9841520,"documento":{"bytes":9841520,"paginas":12,"sha256":"5b25cd…","recebido":1791227250}}
409 {"ok":false,"erro":"Parte fora de ordem.","esperado":8323072}
422 {"ok":false,"erro":"O PDF chegou corrompido (SHA-256 não confere). Digitalize de novo."}

POST /bookc/estacao.php?acao=fim
X-TCloud-Token: 86df8c…
Content-Type: application/json

{"estado":"erro","mensagem":"papel enroscado no alimentador."}

200 {"ok":true,"paginas":5}

Códigos HTTP usados pelo kit

Detalhes das páginas. No formato imagem, colorido e cinza chegam em JPEG qualidade 85 e preto e branco em PNG de 1 bit; no formato jpg, tudo em JPEG; no formato pdf, as páginas são prévias reduzidas (JPEG qualidade 70, até ~1400 px; P&B pode vir no PNG original, que já é menor). X-Dpi traz a resolução real informada pelo driver (que pode diferir da pedida); guarde-a com a página, pois é ela que dá o tamanho físico no PDF. O kit também aceita X-Giro (0, 90, 180, 270), reservado para versões futuras da estação.

6Endpoint do navegador e referência do kit

O endpoint do navegador é seu: o protocolo não o fixa. O formato abaixo é o que o cliente TCloudScan espera; se mudar, adapte o cliente.

Cada item de paginas[]: {n, tipo, dpi, giro, largura, altura, bytes} — tipo é jpg ou png; largura e altura em pixels. estacao: {nome, versao, scanner}. contato: horário Unix da última chamada da estação (0 = nunca), compare com agora.

Desde a 1.2.0: cada página traz também previa (true no formato pdf); documento é {bytes, paginas, sha256, recebido} ou null; formato_estacao é o que a estação disse que entrega (vazio antes do inicio).

Classe PHP TCloudScannerServidor

new TCloudScannerServidor(string $pastaDados, array $cfg) — $cfg: sistema (nome na janela da estação), versao, validade_min (180), max_paginas (400), max_bytes_pagina (40 MB), max_bytes_documento (1 GB), auditoria (callable($evento, $pedido, $extra)).

Eventos de auditoria (além de documento, quando o PDF chega): pedido, inicio, concluido, cancelado, erro, e o motivo passado a descartar (anexado, descartado…).

Cliente JavaScript TCloudScan

new TCloudScan({api, cabecalhos, intervalo, esperaEstacaoMs, aoMudar, aoChegar, aoSemResposta, aoErro}) — intervalo padrão 1000 ms (3000 com a aba em segundo plano); esperaEstacaoMs padrão 12000.

Para uma tela completa (miniaturas, girar, excluir, arrastar para reordenar, PDF ou imagens), use como referência arquivamento/assets/js/digitalizador.js do Atlas 2.1.0.

7Estados do pedido

O pedido nasce aguardando, vai para digitalizando no inicio e termina num dos três estados finais enviados pelo fim. Um novo inicio com o mesmo token ("Digitalizar mais páginas") volta para digitalizando sem perder as páginas.

Como saber se a estação respondeu. Guarde contato no momento em que abrir o link; qualquer valor maior depois disso significa que o TCloud Scanner chamou info. Na primeira vez, info só acontece depois de o usuário autorizar o servidor na janela da estação — não trate essa demora como erro definitivo, só mostre a ajuda e continue consultando.

No formato pdf, a estação só envia fim depois de o PDF chegar inteiro: quando estado for concluido, documento já está preenchido. Se o envio do PDF falhar, o estado vem erro com a mensagem da estação.

8Montar o PDF no tamanho físico

Cada página do PDF deve medir o tamanho real da folha: largura e altura em pontos vêm dos pixels divididos pelo DPI real (X-Dpi), vezes 72. Uma folha A4 a 300 dpi tem 2480 × 3508 px e vira 595 × 842 pt.

• No navegador (recomendado): TCloudScan.montarPdf() com a pdf-lib, que embute JPEG e PNG sem recompressão e não consome CPU do servidor. Gire com page.setRotation() em vez de reprocessar a imagem.
• No servidor: caminhosPaginas() devolve os arquivos na ordem; com TCPDF, AddPage no formato [w, h] em pontos e Image() ocupando a página inteira.
• Imagens separadas: se o usuário girou a página, gire os pixels de verdade (canvas no navegador, GD no servidor) — imagem solta não tem "rotação de página".

Tamanho aproximado por página A4: P&B ~50–150 KB, cinza 300 dpi ~300–800 KB, colorido 300 dpi ~1–3 MB, colorido 600 dpi acima de 10 MB. Confira o limite de upload do seu sistema e o post_max_size do PHP antes de liberar 600 dpi colorido.

9Segurança

O endpoint da estação é público por natureza; tudo depende do token e de tratar as páginas como entrada não confiável. Confira cada item antes de publicar uma integração — o kit já cumpre os marcados com kit.

• Token de 256 bits de fonte criptográfica (random_bytes(32), ou OpenSSL no PHP 5), com validade (padrão 180 min) kit
• Token aceito só no formato [a-f0-9]{64}; nunca usado em caminho sem essa validação kit
• Endpoint do navegador atrás do login do sistema e com CSRF nas ações POST
• estado, pagina e descartar conferem que o pedido é do usuário logado, em tempo constante kit
• Página aceita só se getimagesizefromstring disser JPEG ou PNG, independente do Content-Type kit
• Limites de tamanho por página e de páginas por pedido kit
• Pasta de dados fora da raiz pública, ou com .htaccess negando acesso e desligando o PHP; páginas servidas só pelo endpoint do navegador, com nosniff e CSP sandbox kit cria o .htaccess
• Endpoint da estação sem sessão (não inclua o bootstrap que chama session_start)
• descartar chamado assim que as páginas viram anexo, e limpeza de vencidos ativa kit limpa a cada criarPedido
• Gravação do pedido sob flock, porque estação e navegador escrevem ao mesmo tempo kit
• Auditoria dos eventos (pedido, início com nome da estação e do scanner, fim, anexado/descartado)

10Estação, limites e solução de problemas

A estação precisa de Windows 10 ou 11 (o .NET Framework 4.x já vem no sistema), do driver TWAIN do fabricante e do TCloud Scanner, instalado por usuário, sem administrador:

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://tcloudsoft.app/download/scanner/instalar.ps1 | iex"

Na primeira vez, o navegador pergunta se pode abrir o TCloud Scanner (marque Sempre permitir) e o TCloud Scanner pede para autorizar o endereço do sistema. Depois de escolhido, o scanner fica lembrado e a digitalização começa sozinha. Mostre o comando de instalação na sua tela quando aoSemResposta disparar.

• Manual: link Procurar atualização na janela, ou TCloudScanner.exe --atualizar (sem janela; sai 0 se atualizou ou já está em dia).
• Desligar numa estação: atualizacao_automatica=0 em %APPDATA%\TCloud\Scanner\config.ini; outro endereço: atualizacao_url=.
• Estações 1.0/1.1 não têm atualização: rode o comando de instalação uma vez. O kit avisa isso sozinho (426) quando o sistema pede jpg ou pdf.

Limites. Uma digitalização por vez por usuário do Windows. Padrões do kit: 400 páginas por pedido, 40 MB por página, 180 min de validade — todos configuráveis. A estação espera até 15 min para esvaziar a fila de envio antes de reportar falha. Scanners sem driver TWAIN (só WIA ou ScanSnap Home, como o SV600) não são atendidos.

11Versões e arquivos

A 1.2.0 acrescenta o formato de saída (fmt: imagem, jpg, pdf), a ação documento e a atualização automática. Tudo o que existia continua igual: sem fmt, a estação 1.2.0 entrega exatamente o que a 1.1.0 entregava, e o Atlas 2.1.0 funciona sem alteração.

A 1.1.0 do TCloud Scanner tirou os textos fixos do Atlas: a janela mostra o nome que o sistema devolve em info.sistema. O protocolo (link, ações, cabeçalhos, formatos) é o mesmo da 1.0.0 — sistemas integrados com uma funcionam com a outra.

Compatibilidade futura. Ignore campos desconhecidos nos JSON da estação e aceite cabeçalhos extras: versões novas do TCloud Scanner podem acrescentar dados sem quebrar integrações existentes.