API e webhooks

Onde encontrar

Se os documentos no seu escritório começam noutro sistema que não o DocuTract, esse sistema pode comunicar connosco diretamente. Abra o menu com o seu endereço no canto superior direito e escolha Integrações: é aí que é emitido o token com que o seu sistema nos contacta, e onde acrescenta o endereço para o qual lhe comunicamos os documentos concluídos.

O ecrã começa com as ligações prontas a CRM (Integrações com CRM); os tokens e webhooks descritos aqui ficam por baixo, na secção API e webhooks.

O token

Prima Criar um token, dê-lhe um nome que reconheça mais tarde (para saber que sistema o está a usar) e assinale o que pode fazer: ler modelos, criar documentos, trabalhar com processos.

O próprio token é mostrado uma vez, logo depois de ser criado: guardamos apenas um hash dele, por isso mostrá-lo uma segunda vez é algo que nem nós conseguimos fazer. Copie-o diretamente para as definições do seu sistema.

A lista mostra os primeiros caracteres de cada token, o que pode fazer e quando foi usado pela última vez. Revogar desativa um token de imediato; o registo dele mantém-se, para que fique visível que existiu e quando deixou de funcionar.

O que a API permite fazer

O seu sistema pode:

• abrir um processo e carregar digitalizações para ele;
• criar um documento a partir de um modelo com os valores já preenchidos;
• perguntar em que fase está um documento;
• obter todos os valores juntamente com a digitalização de onde cada um foi lido;
• obter uma ligação de curta duração para o ficheiro final.

A descrição completa de cada endereço e campo é gerada a partir do próprio código e publicada abertamente: a descrição da API.

Webhooks

Em vez de nos perguntar se um documento está pronto, dê-nos um endereço e nós escrevemos-lhe. Acrescente-o em Webhooks e assinale os eventos: documento pronto, documento falhado, processo pronto, divergência encontrada, um cliente enviou um ficheiro.

Cada pedido é assinado com o cabeçalho X-DocuTract-Signature, e o segredo que verifica a assinatura é mostrado uma vez, tal como o token. O seu sistema tem de verificar a assinatura e responder com um código 2xx. Se responder outra coisa, ou não responder de todo, tentamos de novo: passado um minuto, passados cinco, passada meia hora, passadas duas horas e passadas dez, e depois paramos.

Quando algo não chegou

O botão Entregas mostra o registo: que evento enviámos, quando, quantas vezes, que código de resposta foi devolvido e o início do corpo da resposta. É a resposta a «o nosso sistema não recebeu nada»: fica por escrito que respondeu 500 quatro vezes às 14:12.

Enviar teste envia um ping para o endereço imediatamente, sem esperar por um evento real, para que um recetor possa ser configurado antes de passar por ele qualquer trabalho. Tentar novamente, junto a uma entrega falhada, faz mais uma tentativa de imediato.

Zapier, Make e n8n

As plataformas no-code (serviços onde uma integração se monta sem programar) subscrevem os nossos eventos sozinhas, através da parte de REST hooks da API, por isso ninguém tem de copiar os endereços delas para o DocuTract. Dê à plataforma um token com as permissões webhooks:read e webhooks:write, mais as que as ações dela precisarem (por exemplo, templates:read e documents:write).

• POST /api/v1/hooks com {"event": "document.ready", "target_url": "https://…"} subscreve um endereço a um evento. A resposta traz o id da subscrição e, uma única vez, o seu secret de assinatura.
• GET /api/v1/hooks lista as subscrições criadas assim; DELETE /api/v1/hooks/{id} remove uma.
• GET /api/v1/hooks/events lista os eventos: document.ready, document.failed, case.ready, finding.raised, intake.uploaded.
• GET /api/v1/hooks/samples/{event} devolve um exemplo do conteúdo, que a plataforma mostra no seu «acionador de teste» antes de acontecer qualquer evento real.

Uma subscrição é um endereço de webhook normal: assinado, repetido e registado da mesma maneira, e visível na lista de Webhooks. Deixa de funcionar quando o token que a criou é revogado ou expira, ou quando a plataforma responde a uma entrega com 410 Gone.

Assim é document.ready:

{
  "document_id": "00000000-0000-4000-8000-000000000001",
  "reference": "DOC-26-0001",
  "template_id": "00000000-0000-4000-8000-000000000002",
  "template_version": 1,
  "event": "document.ready",
  "occurred_at": "2026-01-15T10:30:00+00:00"
}

e assim case.ready:

{
  "case_id": "00000000-0000-4000-8000-000000000003",
  "title": "Sample case",
  "documents": [
    { "id": "00000000-0000-4000-8000-000000000001", "reference": "DOC-26-0001" }
  ],
  "event": "case.ready",
  "occurred_at": "2026-01-15T10:30:00+00:00"
}

Os campos de um modelo

GET /api/v1/templates/{id}/fields (permissão templates:read) lista o que um modelo precisa: a key de cada campo (a que serve de chave aos values de POST /api/v1/documents), o seu label, de onde é preenchido e fillable, que é false para um campo que o DocuTract preenche sozinho, como uma data. Um formulário no Zapier ou no Make é construído a partir desta lista, por isso corresponde sempre ao modelo tal como está agora.

Pesquisas

Algumas chamadas existem para que um sistema, ou uma plataforma no-code, encontre o que precisa sem adivinhar:

• GET /api/v1/me (sem permissão) devolve o espaço de trabalho a que o token pertence, o seu plano e o nome e as permissões do próprio token. É a forma mais simples de verificar que um token funciona.
• GET /api/v1/documents (permissão documents:read) lista os documentos, os mais recentes primeiro. Restrinja com reference (a referência DOC-… exata), status ou template_id; limit aceita até 100, 25 por omissão.
• GET /api/v1/cases (permissão cases:read) lista os processos mais recentes, se quiser só os de um status, com o mesmo limit. Cada processo traz agora também o seu created_at.
• GET /api/v1/case-types (permissão cases:read) lista os tipos de processo a partir dos quais se pode abrir um processo.
• GET /api/v1/templates?name=… mantém só os modelos cujo nome contém o texto, sem distinguir maiúsculas.

Não há paginação de propósito: estas listas servem para encontrar o mais recente, não para exportar todo um espaço de trabalho.

Que plano

A API e os webhooks fazem parte do plano Team. Em qualquer outro plano, os tokens e os endereços que já criou continuam visíveis e podem ser revogados, mas não são emitidos novos, e os pedidos feitos com um token deixam de ser atendidos. Compare os planos na página de preços.