Desenhando seu esquema

O que é um esquema?

Um esquema no Ztract é o formato dos dados que você quer de volta. É uma lista de campos com nomes, tipos e estrutura opcional (por exemplo, “itens” é um array de objetos, cada um com descrição, quantidade e preço unitário). O motor lê cada documento enviado contra o esquema e devolve os valores correspondentes, ancorados ao lugar onde apareceram na página original.

Esquemas vivem dentro de projetos. Um projeto = um esquema = um formato de saída consistente em todo documento daquele projeto. Se você tem vários tipos de documento, normalmente vai criar um projeto por tipo.

Tipos de campo e estrutura

Cada campo tem um de seis tipos:

• string — texto livre. Nomes, endereços, descrições em formato livre.
• number — valores decimais. Valores monetários, percentuais, dimensões.
• integer — números inteiros. Quantidades, contagens.
• enum — uma string que precisa vir de uma lista fixa que você define. Use isso para valores que são restritos por categoria — status do pedido, forma de pagamento, código de moeda.
• object — um grupo de campos aninhados. Use quando uma coisa naturalmente tem subpropriedades (um address com street / city / zip).
• array — uma lista que se repete. Os itens podem ser primitivos (“skills” em um currículo) ou objetos (“itens” em uma nota fiscal).

Estruturas de object e array podem aninhar, até três níveis de profundidade. Para a maioria dos documentos reais, dois níveis já são suficientes — os itens de uma nota fiscal, os signatários de um contrato — e três é o teto para os casos raros em que você realmente precisa.

Método 1 — Comece a partir de um template

O Ztract traz templates prontos para tipos comuns de documento como notas fiscais, recibos, contratos e identidades. Cada template é um esquema funcional com nomes de campos, tipos e (quando faz sentido) estruturas aninhadas. Eles são construídos a partir de exemplos reais, não de ideais de livro-texto. O catálogo exato é localizado — quando o idioma do seu dashboard está em inglês, você vê templates com nomes em inglês; troque para chinês, japonês etc. e a lista é atualizada de acordo.

Quando isso funciona melhor. Quando o seu tipo de documento se encaixa numa categoria bem definida e a sua ferramenta de destino espera o formato padrão — por exemplo, “notas fiscais para o NetSuite” ou “recibos de despesas para o Concur”. Você sai com um esquema funcional em dois cliques.

Como personalizar. Abra o template, renomeie qualquer campo para combinar com o vocabulário do seu time, remova os campos que você não precisa e adicione quaisquer campos personalizados específicos do seu fluxo. Salve o esquema e ele está pronto para envio.

Método 2 — Descreva em linguagem natural

Se nenhum template combina, escreva o que você quer. Digite uma frase ou duas descrevendo os campos. O Ztract redige um esquema completo a partir da sua descrição. Você confirma ou ajusta antes de salvar.

Prompt de exemplo. “Para cada pedido de compra, extraia o número do PO, o nome e o endereço do fornecedor, a data de emissão, a data de entrega, os itens com SKU, descrição, quantidade e preço unitário, e o total do pedido. Também sinalize se o PO está marcado como pedido urgente.”

O motor produz algo como:

• po_number — string
• vendor — { name, address }
• issue_date — date
• delivery_date — date
• line_items — array de { sku, description, quantity, unit_price }
• order_total — number
• rush_order — boolean

Quando isso funciona melhor. Quando você tem um modelo mental claro do que precisa, mas nenhum exemplo canônico para enviar. Ou quando seu tipo de documento é de nicho o suficiente para que nenhum template caiba.

Método 3 — Inferir a partir de um documento de exemplo

Envie um documento de exemplo; o motor lê e propõe um esquema com os nomes de campos, tipos e aninhamentos que encontrou. Aí você ajusta: remova campos que não te interessam, adicione os que o exemplo não trouxe, refine os tipos.

Quando isso funciona melhor. Quando você não sabe quais campos existem até ver um — comum para laudos médicos (cada laboratório imprime seus painéis de um jeito diferente), contratos redigidos sob medida e formulários avulsos de fornecedores. Também é útil quando o nome de um campo no documento é incomum e você quer que o motor sugira um nome normalizado.

Ajustando um esquema depois de criado

Você pode editar um esquema a qualquer momento — renomear campos, adicionar novos, mudar tipos, reestruturar aninhamentos. As edições não afetam documentos já processados; você precisaria rodá-los de novo sob o novo esquema para ter o formato atualizado. Reexecuções são cobradas (veja Cobrança, pacotes e reembolsos), então a maioria dos times finaliza o esquema em um lote pequeno primeiro, antes de processar volume.

Dicas para campos complicados

• Datas. Não importa o que o documento imprima — DD/MM/AAAA, 5 jun 2026, “Q2 2026” — o Ztract converte para o formato de data que você definir no seu esquema. Se nenhum formato for especificado, a data é devolvida como aparece impressa.
• Valores e moedas. A moeda fica na forma original (€, $, ¥, ₩ etc.); a gente não converte silenciosamente. Alíquotas de imposto por linha continuam vinculadas à linha à qual pertencem.
• Estruturas aninhadas. Se o documento naturalmente tem subobjetos (partes em um contrato, condições de pagamento dentro de um acordo com fornecedor), use aninhamento no esquema. O JSON de saída vai espelhar o aninhamento; CSV / Excel vão achatar com caminhos separados por ponto.
• Arrays de strings puras. Campos como “skills” num currículo ou “endosso” num passaporte voltam como arrays de strings. O dashboard renderiza o array como uma tabela no visualizador lado a lado — uma linha por item, ligada à sua região de origem.
• Campos enum. Campos com vocabulário restrito (status, código de moeda, classe do documento) funcionam melhor como enum — você informa os valores permitidos uma vez e o motor se atém a eles em vez de inventar variantes como “Paid”, “paid”, “PAID” ou “Settled”.