Templates e Campos

Um Template é uma lista salva e reutilizável de Campos que você deseja extrair de um documento — um campo por coluna de saída. Passe o id de um Template para Iniciar o processamento de um lote em vez de listar seus campos novamente a cada chamada. Você também pode criar um Template a partir de um modelo predefinido ou ignorar Templates completamente e passar fields avulsos diretamente para process para uma execução única.

Listar templates

Retorna seus templates salvos, cada um com sua lista completa e ordenada de campos incorporada.

Parâmetros

Erros possíveis

• missing_api_key / invalid_api_key / plan_required — consulte Tratamento de Erros.
• invalid_parameter — limit ou page_token inválidos.

Criar um modelo

Duas formas de criar um modelo em um único endpoint: do zero (opcionalmente clonando os campos de outro modelo via base_template_id) ou a partir de um modelo predefinido via preset_id. As contas têm um limite de 30 modelos — exclua um existente antes de criar outro ao atingir o limite.

Parâmetros

Erros possíveis

• missing_api_key / invalid_api_key / plan_required — consulte Tratamento de Erros.
• missing_parameter (param: "name") — sem name e sem preset_id.
• invalid_parameter (param: "name") — já existe um modelo com este nome (apenas no caminho de criação sem modelo predefinido).
• invalid_parameter (param: "preset_id") — ID de modelo predefinido desconhecido.
• template_limit_reached — limite de 30 modelos já atingido para esta conta.
• internal_error

Atualizar configurações do modelo

Define o requisito global de formato de um modelo (aplicado sobre o de cada campo) e sua configuração de Multi-Page Merge — se várias páginas enviadas que pertencem ao mesmo registro lógico (um contrato de várias páginas, um pacote de recibos grampeados) devem ser unificadas em uma única linha de saída em vez de permanecer uma linha por página. Uma vez ativado aqui, o merge é aplicado automaticamente sempre que este modelo for usado tanto para processamento quanto para resultados — veja ?merge=true em Get batch results e Export a batch (que sempre o aplica, sem necessidade de opt-in lá). Cada campo no corpo da solicitação abaixo é opcional; apenas as chaves que você envia são atualizadas, todo o resto permanece como está (não há estado separado de rascunho/pré-visualização para confirmar — esta chamada entra em vigor imediatamente, igual ao diálogo de Configurações do Modelo no app web).

Parâmetros

Erros possíveis

• missing_api_key / invalid_api_key / plan_required — consulte Tratamento de Erros.
• template_not_found
• invalid_parameter — merge_mode / merge_trigger_type / merge_fixed_count / merge_conflict_policy / merge_conflict_separator inválidos.
• internal_error

Excluir um modelo

Exclui um modelo e todos os seus campos (em cascata — nenhuma chamada de limpeza separada é necessária). Não afeta documentos que já usaram este modelo em uma chamada process anterior; os resultados já extraídos permanecem intactos.

Parâmetros

Erros possíveis

• missing_api_key / invalid_api_key / plan_required — consulte Tratamento de Erros.
• template_not_found
• internal_error

Listar predefinições

Listas de campos integradas para tipos de documentos comuns (faturas, recibos, extratos bancários e mais) — passe o id de uma predefinição como preset_id em Criar um modelo para obter um modelo funcional sem listar campos manualmente. Predefinições são configuração estática, não linhas de banco de dados — não há como criar, editar ou excluir uma pela API.

Parâmetros

Erros possíveis

• missing_api_key / invalid_api_key / plan_required — veja Tratamento de Erros.
• invalid_parameter — limit ou page_token inválidos.

Listar e criar campos

fields é o nome público da v1 para o que a interface do produto chama de "regras de correspondência" — um campo por coluna de saída, na ordem em que a extração os emitirá. GET retorna todos os campos do modelo, já ordenados por sort_order. POST adiciona um novo campo ao final.

Parâmetros

Erros possíveis

• missing_api_key / invalid_api_key / plan_required — consulte Tratamento de Erros.
• template_not_found
• missing_parameter (param: "name") — somente POST.
• duplicate_field_name — um campo com este name já existe neste modelo.
• internal_error

Atualizar e excluir um campo

PUT renomeia um campo (e substitui seu format_requirement) — é uma substituição completa, não um patch parcial, então inclua ambos os valores mesmo que apenas um tenha mudado. DELETE o remove.

Parâmetros

Erros possíveis

• missing_api_key / invalid_api_key / plan_required — consulte Tratamento de Erros.
• template_not_found — o modelo não existe/não é seu, ou (com uma mensagem observando isso) o field_id não está neste modelo.
• missing_parameter (param: "name") — somente PUT.
• duplicate_field_name — somente PUT, renomeando para um nome que outro campo neste modelo já possui.
• internal_error

Reordenar campos

Define explicitamente a ordem dos campos, que determina a ordem das colunas de saída em line_items e nas exportações para Excel/Word. IDs na lista que não pertencem a este modelo são ignorados silenciosamente, em vez de rejeitar a solicitação inteira.

Parâmetros

Erros possíveis

• missing_api_key / invalid_api_key / plan_required — consulte Tratamento de Erros.
• template_not_found
• invalid_parameter (param: "field_ids") — não é uma lista de inteiros.
• internal_error