Principais pontos
- Restrinja os uploads aos tipos de documento que a rota de conversão escolhida realmente suporta.
- Converta o arquivo de origem aceito em PDF antes de exportá-lo para um caminho do Box específico do caso ou projeto.
- Mantenha o acesso ao Box em Credenciais de Template e mantenha a seleção de pastas sob controle da aplicação confiável.
O recebimento de documentos costuma começar com uma mistura de DOCX, PPTX, ODT e outros formatos de escritório, enquanto os revisores esperam um PDF estável. Enviar o original diretamente para uma pasta de colaboração deixa as regras de conversão e a nomenclatura inconsistentes. Um fluxo de trabalho salvo torna previsíveis o PDF derivado e o destino dele, sem transformar o Box no serviço de processamento de uploads.
O que mais importa
- Deixe create_sharing_link como false, a menos que uma decisão de autorização separada permita um link de compartilhamento.
- Use caminhos de destino exclusivos para que novas tentativas e uploads com o mesmo nome não sobrescrevam registros não relacionados.
- Registre tanto a identidade da origem quanto o resultado em PDF exportado no registro durável do documento na aplicação.
Escolha um contrato restrito para o recebimento de documentos
Nem todo arquivo em pastas cheias de “documentos” tem o mesmo formato técnico. Defina os formatos de entrada, o limite de bytes, as expectativas de páginas e os requisitos de fidelidade antes de aceitar uploads. /document/convert pode criar PDFs a partir de formatos compatíveis de escritório, texto, HTML e apresentação.
Mantenha os PDFs existentes fora deste ramo de conversão, porque /document/convert não é uma ferramenta genérica para converter PDF em qualquer formato. Se o produto aceita tanto PDFs quanto arquivos de escritório conversíveis, encaminhe-os de forma deliberada: preserve os PDFs aceitos e converta apenas os formatos que precisam de normalização.
Crie o Template de PDF para o Box
Este Template recebe um upload como :original, converte-o em PDF e passa esse PDF para /box/store. Ele não impõe uma lista de formatos de escritório permitidos: a aplicação deve validar os formatos aceitos antes de escolher este fluxo de trabalho ou, então, adicionar um Step /file/filter com error_on_decline. PDFs existentes precisam de um fluxo de trabalho separado, selecionado pela aplicação, porque este exemplo não implementa um desvio para PDFs. O caminho de destino inclui um identificador de caso ou projeto aprovado pela aplicação, além de valores exclusivos da Assembly, o que impede que dois usuários que enviem report.docx sobrescrevam os arquivos um do outro.
Defina create_sharing_link como false. Um link de compartilhamento de colaboração é uma decisão de autorização e retenção, não um efeito colateral da conversão. Se o produto precisar de um link depois, crie-o somente depois que a aplicação confirmar o destino no Box, o público pretendido e a política de expiração ou revogação.
{
"allow_steps_override": false,
"auth": {
"max_number_of_files": 1,
"max_size": 104857600
},
"steps": {
":original": {
"robot": "/upload/handle"
},
"review_pdf": {
"use": ":original",
"robot": "/document/convert",
"format": "pdf"
},
"box_export": {
"use": "review_pdf",
"robot": "/box/store",
"credentials": "box-documents",
"path": "cases/${fields.case_id}/${unique_prefix}/${file.url_name}",
"create_sharing_link": false,
"result": true
}
}
}Controle caminhos, credenciais e identidades duráveis
Armazene o acesso ao Box em Credenciais de Template e faça referência ao nome da credencial a partir do Template salvo. Não permita que um cliente não confiável escolha uma credencial, uma pasta arbitrária ou um caminho de substituição. É recomendável que o servidor autorize o usuário com base no registro do caso ou projeto e forneça um identificador delimitado que o Template possa incluir no caminho.
Nomes de pastas são apresentação, não identidade durável. Mantenha juntos o ID do documento na aplicação, a versão de origem, o Assembly ID, a identidade do resultado no Box e a versão do fluxo de trabalho. Esses campos sobrevivem a uma futura movimentação de pasta e permitem que os operadores distingam uma reexecução de uma nova versão do documento.
Identidade mantida pela aplicação
Os identificadores estáveis de documento, caso, locatário e versão.
Identidade do processamento
A versão do fluxo de trabalho e o Assembly ID que produziram o PDF.
Identidade do armazenamento
A identidade e o caminho do arquivo no Box retornados pela exportação bem-sucedida.
Verifique a conversão antes de marcar o documento como pronto
Uma Assembly bem-sucedida é necessária, mas não suficiente para documentos críticos. Faça com que a aplicação inspecione o tipo MIME e a contagem de páginas do PDF exportado e, em seguida, use arquivos de teste representativos para inspecionar fontes, tabelas, quebras de página, cabeçalhos, rodapés, links e texto não latino. Um Job /document/convert bem-sucedido não comprova, por si só, que o resultado corresponde ao aplicativo de origem. Decida se uma divergência bloqueia o fluxo de trabalho ou encaminha o arquivo para revisão manual.
Conclua o registro da aplicação somente depois que a exportação para o Box existir e corresponder à Assembly esperada. Processe webhooks de forma idempotente e reconcilie os registros ativos com o Assembly Status quando uma notificação atrasar ou se perder.
Teste falhas de armazenamento e de recuperação
Teste credenciais revogadas ou inválidas do app de Server Authentication do Box, uma pasta de destino ausente, permissão de gravação insuficiente, uploads com o mesmo nome, formatos de origem não suportados, falha na conversão e uma conversão bem-sucedida seguida de falha na exportação. Sempre que possível, a nova tentativa segura deve reutilizar a origem e o estado da operação existentes, em vez de pedir que o usuário faça o upload novamente.
Defina separadamente a retenção do upload de origem, do PDF derivado e do registro da aplicação. O Box pode ser a cópia durável de colaboração, mas a aplicação ainda precisa de identidade e estado de auditoria suficientes para explicar como essa cópia foi produzida e se ela está atualizada.
Mantenha explícitos os papéis da origem e do PDF
Um PDF normalizado pode ser a cópia de colaboração enquanto o arquivo de escritório editável continua sendo a origem de referência. Como alternativa, um processo de gestão de registros pode designar o PDF revisado como a versão fixa. Documente essa escolha na aplicação em vez de permitir que qualquer arquivo que apareça no Box se torne a referência por acidente.
Quando uma origem for substituída, crie uma nova versão na aplicação e uma nova identidade de destino, ou aplique um contrato deliberado de sobrescrita. Nunca presuma que um upload com o mesmo nome representa o mesmo documento de negócio e não exclua a origem anterior até que os requisitos de retenção e de reversão tenham sido atendidos.
Detalhes técnicos que vale a pena conhecer
- /document/convert pode converter formatos de escritório e de texto compatíveis em PDF. PDF não é uma entrada compatível, então desvie os PDFs existentes do Step de conversão.
- /box/store aceita caminhos que contenham Assembly Variables e, quando nenhum caminho é informado, usa por padrão caminhos com prefixo exclusivo.
- A opção de exportação do Box create_sharing_link tem false como padrão. Ativá-la substitui a propriedade url do arquivo de resultado pela URL de compartilhamento.
- As credenciais de Template do Box usam Server Authentication com JWT. Os administradores da aplicação precisam manter válidos essa autorização do app e o respectivo material de chave.
- As credenciais de Template mantêm o acesso ao Box fora do JSON do Template e do bundle do navegador, mas a aplicação ainda precisa autorizar a pasta de destino.
- O PDF exportado é um novo derivado. Manter ou excluir o upload original é uma decisão separada de produto e de gestão de registros.
Uma abordagem prática
- 1
Defina os formatos de escritório compatíveis, o tamanho máximo, a política de pastas de destino e a retenção.
- 2
Crie Credenciais de Template do Box com escopo restrito e salve o Template bloqueado de três Steps.
- 3
Faça upload de documentos representativos e verifique o layout das páginas, as fontes, os nomes de arquivo e o posicionamento no Box.
- 4
Confirme que as entradas em PDF e outros formatos de origem não compatíveis são rejeitados e, em seguida, teste nomes duplicados, autorização revogada do app do Box e falhas parciais de exportação.
Quando a Transloadit é útil
Use este fluxo de trabalho para o recebimento interativo por usuário em uma pasta de colaboração do Box. Use /upload/handle para o recebimento dos usuários, /document/convert para a conversão compatível de documentos de escritório em PDF e /box/store para a exportação durável. Mantenha o acesso ao Box em Credenciais de Template, use um caminho de pasta aprovado pela aplicação e deixe a criação de links de compartilhamento desativada, a menos que o produto precise explicitamente dela.
Limite da arquitetura
A Transloadit converte e exporta o documento enviado. A aplicação continua responsável pela permissão do usuário, pela identidade do caso ou projeto, pela retenção, pela classificação jurídica, pelas configurações de colaboração do Box e por decidir se um documento resultante pode ser compartilhado.
Perguntas frequentes
Este Template pode aceitar PDFs como entrada?
/document/convert não aceita PDF como entrada. Desvie os PDFs existentes da conversão ou use um fluxo de trabalho separado, adequado à operação de PDF necessária.
/box/store deve criar um link de compartilhamento?
Normalmente não durante o recebimento. Mantenha create_sharing_link como false e torne o compartilhamento uma ação autorizada posterior, com público e política de revogação explícitos.
A conversão preserva todos os recursos de documentos de escritório?
Não. Verifique, com exemplos representativos, fontes, layout, fórmulas, links e recursos complexos específicos de cada aplicativo antes de confiar no PDF como versão de referência.
O navegador pode escolher a pasta do Box?
O navegador pode enviar um identificador delimitado da aplicação, mas é recomendável que um servidor confiável o autorize e que o Template bloqueado controle o caminho de destino real.
O que deve ser armazenado no banco de dados da aplicação?
Guarde a identidade do documento de origem e da versão, a versão do fluxo de trabalho, o Assembly ID, a identidade do arquivo no Box, o caminho de destino e o estado final do fluxo de trabalho.