A camada documental entre o seu ERP e as suas ferramentas

O Arhivix é um sistema de gestão documental com REST API v1, webhooks assinados e um servidor MCP, desenvolvido pela NOTIX DOO em Belgrado. Recebe documentos, lê-os com OCR e IA, pede a uma pessoa que confirme os valores que marcar para revisão e passa os dados ao seu ERP e às suas ferramentas.

Está alojado em AWS na UE (Frankfurt e Dublin). Um novo processo de negócio configura-se na aplicação como tipos de documento, fluxos e livros de registo, pelo que o código que escreve continua pequeno: um recetor ao lado do seu ERP.

Última revisão: . Factos verificados com a versão da aplicação desse dia.

Onde fica o Arhivix quando os dados vêm em documentos

Faturas de fornecedores, guias de remessa, notas de encomenda, certificados e contratos chegam como PDF e digitalizações, enquanto o ERP espera registos limpos. O Arhivix trata da parte documental dessa integração, em seis passos.

  1. Os documentos chegam

    Por carregamento, das caixas de e-mail da empresa através de Gmail, Microsoft 365 ou IMAP, de um scanner de secretária, da câmara do telemóvel ou do seu próprio programa através da API. O Arhivix também recebe documentos do OneDrive, do SharePoint, do Google Drive, de um bucket Amazon S3 ou de um contentor Azure Blob.

  2. O Arhivix lê-os

    O OCR converte as digitalizações em texto. Um modelo de linguagem reconhece o tipo de documento e propõe os campos: fornecedor, comprador, números de identificação fiscal, montantes, IVA, datas e números numa fatura, ou partes, datas, prazo de pré-aviso, valor e condições de pagamento num contrato.

  3. Uma pessoa confirma

    Um valor lido é uma proposta até a sua regra de revisão ser cumprida. Para cada campo de um tipo de documento escolhe a regra: Automática, Requer revisão ou Tem de ser confirmado. Os revisores comparam os valores com o original e confirmam-nos campo a campo.

  4. O caso avança

    Um fluxo verifica condições, envia o documento para aprovação a uma pessoa ou a uma função, arquiva-o, acrescenta-o a um dossier de negócio e acompanha o respetivo prazo.

  5. O seu código é notificado

    Um passo do fluxo envia uma mensagem assinada para o seu recetor, e o recetor lê o registo através da REST API. Carregamentos, novos documentos, faturas e e-mails também chegam como eventos de webhook assinados e no feed de alterações.

  6. O ERP continua a ser o sistema de referência

    O seu recetor escreve no ERP através da importação que o ERP suporta. Quando um fluxo precisa de prova de que o ERP aceitou o registo, pede uma confirmação externa e aguarda o seu callback assinado.

A integração num só esquema
  1. Ferramentas e assistentes

    • Notificações no Microsoft Teams
    • Zapier, Make, n8n e Power Automate através dos seus passos de webhook e HTTP
    • Claude, Claude Code e Codex através de MCP

Ligar um ERP antigo que não tem API

O ERP fica como está. Os documentos continuam a chegar como chegam hoje, e o lado do ERP na integração é o seu recetor e a importação que o seu ERP já suporta.

  • E-mail e digitalizações: os fornecedores continuam a enviar PDF, e o Arhivix lê-os da caixa de correio, do scanner ou do telemóvel.
  • Um pequeno recetor, o seu próprio middleware ao lado do ERP: aceita webhooks assinados ou consulta periodicamente GET /events, lê o registo através da API e escreve-o com a importação que o próprio ERP disponibiliza, como uma pasta de entrada de ficheiros, uma tabela de staging ou o SDK do fornecedor do ERP.
  • SAP Business One: liga-o nas Definições através do SAP Service Layer e, a cada 15 minutos, o Arhivix lê dele os parceiros de negócio, os artigos, os armazéns, as notas de encomenda, as guias de receção e as faturas.
  • Ferramentas com um gatilho de webhook e um passo HTTP, como Zapier, Make, n8n e Power Automate: recebem o evento e leem o registo através da API.
  • Microsoft Teams: um canal recebe uma mensagem quando uma fatura é criada, aprovada ou rejeitada, quando a aprovação de uma fatura é pedida ou concluída e quando é criada uma exceção.
  • No sentido inverso: um fluxo envia uma mensagem assinada para o seu sistema e pode aguardar a respetiva confirmação assinada antes de continuar.
  • Faturas eletrónicas por Peppol: através da conta da sua empresa na Storecove, um ponto de acesso Peppol, o Arhivix envia as faturas que emite (BIS Billing 3.0) e recebe as faturas de fornecedores.

O ERP continua a ser o sistema de referência. O Arhivix lê, verifica e encaminha os documentos, e o seu código passa os resultados adiante.

O que recebe em vez de construir um pipeline de documentos

Chamar um modelo de linguagem sobre um PDF é a parte pequena. Uma integração com um ERP precisa também de receção, confirmação por uma pessoa (human in the loop), aprovações, um lugar para o original e um histórico de auditoria de cada decisão. Essas partes funcionam hoje no Arhivix.

Partes da integração e onde estão no Arhivix
Parte da integraçãoO que o Arhivix fazOnde o seu código se liga
Receção Carregamento, caixas de e-mail da empresa, scanner, câmara do telemóvel e origens ligadas como OneDrive, SharePoint, Google Drive, Amazon S3 e Azure Blob. POST /nodes/{id}/upload: multipart, até 200 MiB.
Leitura OCR, campos propostos e 22 tipos de documento reconhecidos. GET /nodes/{id}/metadata devolve ocr_status, a classificação com doc_type, um resumo e etiquetas, e os dados extraídos da fatura.
Confirmação O Smart Inbox mostra um caminho sugerido e o grau de confiança da IA, e uma pessoa aprova ou rejeita. Os valores lidos são confirmados campo a campo segundo a regra de revisão que definir. Os valores do livro de registo têm um estado como confirmed ou proposed, e a condição de fluxo «Está confirmado» (Is confirmed) protege os passos do seu ramo afirmativo.
Aprovações Cadeias de até cinco pessoas ou funções, por ordem, com prazo e escalamento para uma função. A pessoa que iniciou o processamento e os aprovadores anteriores ficam excluídos das fases seguintes. Dentro do Arhivix, na fila Aprovações de negócio. O fluxo continua sozinho depois da decisão.
Caso de negócio Dossiers de negócio com uma lista de verificação dos documentos obrigatórios, entidades acompanhadas, documentos esperados e livros de registo. POST /document-pipelines/registers/{id}/query devolve as linhas de um livro de registo. Os documentos das entidades acompanhadas também podem ser lidos através da API.
Armazenamento e histórico de auditoria Versões, permissões por espaço de trabalho e por pasta, e um registo de auditoria que guarda as ações da API com a chave que as executou. GET /nodes/{id}/versions e GET /nodes/{id}/download.

Os seus próprios tipos de documento podem usar 22 tipos de valor, entre eles Tabela, Lista, Registo ligado e Valor calculado.

Como se modela um caso de negócio no Arhivix

Todos os processos de negócio são feitos das mesmas partes: uma entidade com dados, provas, regras, um estado e ações permitidas. No Arhivix, isso é um dossier de negócio, um modelo de gestão de casos cujas partes suportam processos muito diferentes.

Um modelo, dois processos
Parte do casoNo ArhivixQualificação de fornecedoresEntrega de projeto
Entidade Um dossier com um tipo, uma chave de negócio, um período, um responsável e uma data-limite. Um fornecedor. Um projeto.
Provas Documentos aceites face a uma lista de verificação. Cada um fica registado com o hash do conteúdo e a data de validade. Registo comercial da empresa, o certificado exigido e o seguro. Telas finais, manuais de utilização, garantias e certificados, registos de inspeção e de ensaio.
Ligações Campos de registo ligado, livros de registo e entidades acompanhadas: um parceiro, um equipamento, um imóvel ou um tipo que defina. O parceiro e os seus certificados. O imóvel e os seus equipamentos.
Regras Itens obrigatórios com quantidade mínima e verificação de validade, uma regra de revisão por campo e condições de fluxo com 18 operadores. O certificado e o seguro têm de estar válidos. Cada grupo precisa de pelo menos um documento.
Estado A recolher, A aguardar revisão, Pronto para o pacote final, Arquivado. Os mesmos quatro estados. Os mesmos quatro estados.
Ações Pedir documentos em falta através de uma ligação segura de carregamento, aceitar ou rejeitar cada documento, confirmar a recolha, enviar para aprovação, notificar, enviar dados para outro sistema. Pedir ao fornecedor um certificado renovado. Pedir ao empreiteiro os manuais em falta.
Resultado Uma recolha confirmada, um histórico de decisões com a ação, o motivo e a pessoa, e um pacote ZIP final. Um fornecedor qualificado, com prova. Um pacote de entrega.

Os dois exemplos são modelos prontos na aplicação, ao lado de Documentos mensais do cliente (faturas de venda, faturas de compra e extratos bancários).

Porque é que o próximo processo é configuração e não um novo projeto

Entre o primeiro processo e o segundo, o motor é o mesmo. O que muda são as definições: tipos de documento, fluxos e livros de registo, e o modelo de dossier que o processo segue. A sua equipa define-os na aplicação, em Processamento de documentos, e o seu recetor continua a funcionar.

  1. Escolha a tarefa

    O assistente de configuração pergunta o que o Arhivix deve fazer: faturas recebidas por e-mail, contratos e prazos, registos de assistência técnica ou o seu próprio documento. Nada é ativado até confirmar.

  2. Mostre um exemplo

    Descreva o tipo de documento ou arraste documentos de exemplo, e o assistente de tipos propõe os campos. Revê a proposta antes de qualquer coisa ser guardada.

  3. Teste e depois publique

    Um tipo é testado num documento com valores conhecidos, e só a versão testada é publicada. Todas as versões ficam no histórico.

  4. Desenhe o fluxo

    O editor de fluxos tem 24 tipos de passo: aprovação, condições, encaminhamento por várias regras, arquivamento, etiquetas, dossiers, notificações, prazos e lembretes, consultas a livros de registo, caminhos paralelos, subfluxos, envio de dados para outro sistema e pedido de confirmação externa.

  5. Reutilize a configuração

    Os modelos de negócio guardam as definições de tipos, livros de registo, vistas e widgets num ficheiro JSON que importa onde precisar da mesma configuração. Os tipos importados ficam em rascunho até serem verificados num exemplo.

O que o Arhivix memoriza

  • Para onde vão os documentos de um fornecedor: depois de uma pessoa ter arquivado três vezes documentos com o mesmo número de identificação fiscal do fornecedor no mesmo grupo de arquivamento, os novos documentos desse fornecedor passam a ser arquivados lá automaticamente.
  • Como se lê um tipo de documento: «Lembrar para este tipo de documento» (Remember for this document type) guarda onde se encontra um campo ou o que significa numa nova versão do tipo, usada assim que essa versão é testada e publicada.
  • As palavras que os seus documentos usam: uma nota por campo sobre onde encontrá-lo e o que significa, e expressões memorizadas para as opções de escolha.
  • As regras que a sua equipa define: regras de arquivamento por fornecedor, tipo de documento ou categoria, regras de e-mail e fluxos.
  • Cada decisão: as correções e as decisões ficam no histórico, com a pessoa e o motivo.

Esta memória pertence à sua empresa e é guardada como regras, mapeamentos e versões de tipos. Os dados dos clientes não são usados para treinar modelos de IA, e o acordo de tratamento de dados estabelece-o.

REST API v1: autenticação, limites, carregamentos e erros

Caminho base
/v1/api/v1, em que as duas partes v1 pertencem ao caminho. Uma só API para todas as regiões: a empresa é determinada pela chave.
Autenticação
Authorization: Bearer <key> ou X-API-Key: <key>. As chaves começam por ak_live_.
Chaves
Um Administrador ou a função integrada Programador cria-as em Definições, Developer API. Uma chave tem um nome, permissões por área, um limite de pedidos, uma data de expiração opcional e uma lista opcional de IP permitidos, e é mostrada uma única vez.
Modelo de acesso
Uma chave é uma identidade de serviço própria. As permissões limitam as operações, as funções da empresa decidem a que recursos a chave chega, e uma chave nova começa sem acesso a nenhum recurso até uma pessoa a rever.
Limite de pedidos
Por chave, de 10 a 10 000 pedidos por minuto, 1000 por predefinição. As respostas incluem X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset.
Escritas
Cada escrita leva um cabeçalho Idempotency-Key. Um resultado concluído é devolvido de novo durante sete dias, pelo que repetir um pedido é seguro.
Carregamentos
multipart/form-data, até 200 MiB, com o cabeçalho X-Arhivix-Request-SHA256: o SHA-256 do corpo exato do pedido. Um carregamento coloca o OCR em fila automaticamente.
Resultados
GET /nodes/{id}/metadata devolve ocr_status, a classificação com doc_type, a categoria, um resumo e etiquetas, e os dados extraídos da fatura. GET /nodes/{id}/text devolve o texto do OCR página a página.
Livros de registo
POST /document-pipelines/registers/{id}/query devolve os valores lidos para os seus próprios tipos de documento. Cada valor tem um estado, como confirmed ou proposed, e um filtro pode pedir um só estado.
Listas
Paginação por keyset: limit de 1 a 100 e o cursor de meta.pagination.next_cursor.
Feed de alterações
GET /events devolve os eventos do mais antigo para o mais recente, a partir do mesmo log que alimenta os webhooks.
Pesquisa
GET /search, com filtros por tipo de documento, categoria e espaço de trabalho.
Erros
Um só formato para todos os erros: error, message e meta.request_id. Envie X-Request-ID para fazer corresponder os seus logs aos nossos.
Referência
Uma descrição OpenAPI 3.1, JSON Schemas para os eventos de webhook e exemplos de cliente em Go e JavaScript. Enviamo-los mediante pedido.
# Upload a document into a folder. The digest covers the exact multipart body.
boundary="bridge-example-boundary"
body="$(mktemp)"
{
  printf -- '--%s\r\nContent-Disposition: form-data; name="file"; filename="invoice.pdf"\r\nContent-Type: application/octet-stream\r\n\r\n' "$boundary"
  cat invoice.pdf
  printf '\r\n--%s--\r\n' "$boundary"
} > "$body"

curl --fail-with-body -sS \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: invoice-4471-upload" \
  -H "X-Arhivix-Request-SHA256: $(sha256sum "$body" | awk '{print $1}')" \
  -H "Content-Type: multipart/form-data; boundary=$boundary" \
  --data-binary "@$body" \
  "$BASE_URL/nodes/$FOLDER_ID/upload"

# OCR and reading start by themselves. Read the result with the id from the response:
curl --fail-with-body -sS \
  -H "Authorization: Bearer $API_KEY" \
  "$BASE_URL/nodes/$NODE_ID/metadata"
Carregue uma digitalização e leia o que o Arhivix propôs. BASE_URL termina em /v1/api/v1.

Webhooks assinados

Adiciona um endereço de webhook na aplicação, em Definições, Developer API, Webhooks: um endereço HTTPS público, com todos os eventos ou com os que selecionar. O segredo de assinatura é mostrado uma única vez. Para notificar o seu sistema apenas sobre dados confirmados, coloque num fluxo o passo «Enviar dados para outro sistema» (Send data to another system) depois da condição «Está confirmado».

Eventos
document.created, file.uploaded, email.received, invoice.created, invoice.updated, invoice.deleted, invoice.approved, invoice.rejected, invoice.storno, approval.requested, approval.completed, exception.created, exception.resolved, despatch_advice.created, despatch_advice.received.
A partir de um fluxo
O passo «Enviar dados para outro sistema» envia uma mensagem assinada com a ligação para o documento ao destino que configurou. «Pedir confirmação externa» (Request external confirmation) aguarda um callback assinado do seu sistema.
Payload
Pequeno de propósito: o id do evento, o nome do evento, a hora, a empresa e o id, o tipo e o nome do registo. O recetor lê o registo através da API.
Assinatura
X-Arhivix-Signature contém sha256= e o HMAC-SHA256 de X-Arhivix-Timestamp, um ponto e o corpo bruto do pedido, com o seu segredo como chave. Rejeite um timestamp com um desvio superior a 300 segundos.
Entrega
Qualquer resposta 2xx confirma a receção. Uma entrega falhada é repetida após 1 minuto, 5 minutos, 30 minutos, 2 horas, 8 horas, 24 horas e 36 horas: oito tentativas ao longo de cerca de 70 horas.
Duplicados
A entrega é feita pelo menos uma vez. Elimine duplicados pelo id do evento ou por X-Arhivix-Delivery.
Log de entregas
Cada entrega mostra as tentativas, o código HTTP, o payload e a última resposta do seu endpoint, com Repetir e Reenviar. Pode enviar um evento de teste com um clique.
{
  "id": "evt_653a9632df26297d6d685aebb8e553fc779785cb260ed6002c4bd0d2d2e1556d",
  "event": "file.uploaded",
  "schema_version": 1,
  "schema": "https://arhivix.com/schemas/webhooks/v1/file.uploaded.schema.json",
  "occurred_at": "2026-08-10T09:00:00Z",
  "timestamp": "2026-08-10T09:00:00Z",
  "company_id": "company_example",
  "data": {
    "id": "node_example",
    "event_id": "workflow_occurrence_example",
    "target_type": "node",
    "name": "receipt.pdf",
    "triggered_by": "user_example"
  }
}
O corpo de um evento file.uploaded.
import { createHmac, timingSafeEqual } from 'node:crypto';

// rawBody:   the request body as a Buffer, captured before JSON parsing
// timestamp: header X-Arhivix-Timestamp
// signature: header X-Arhivix-Signature
export function verifyWebhook({ rawBody, timestamp, signature, secret }) {
  const now = Math.floor(Date.now() / 1000);
  const match = /^sha256=([a-f0-9]{64})$/.exec(signature ?? '');
  if (!/^[0-9]+$/.test(timestamp ?? '') || Math.abs(now - Number(timestamp)) > 300 || !match) {
    return false;
  }
  const expected = createHmac('sha256', secret)
    .update(timestamp, 'utf8')
    .update('.', 'utf8')
    .update(rawBody)
    .digest();
  const supplied = Buffer.from(match[1], 'hex');
  return supplied.length === expected.length && timingSafeEqual(supplied, expected);
}
Verificação da assinatura em Node.js. Verifique primeiro os bytes brutos e só depois faça o parse do JSON.

MCP: assistentes e agentes sobre os documentos da sua empresa

O Arhivix disponibiliza um servidor MCP alojado em https://mcp.arhivix.com/mcp. Adiciona o endereço ao seu cliente, inicia sessão no Arhivix no browser e aprova o acesso para uma empresa. Não há nenhuma chave de API para copiar.

Clientes
Claude como conector personalizado, Claude Code e Codex, com comandos prontos na aplicação.
Início de sessão
OAuth com PKCE e registo dinâmico de clientes.
Quem aprova
Um Administrador ou uma pessoa com a função Programador, para uma empresa.
Leitura
A pesquisa e a leitura estão sempre incluídas: documentos, metadados, faturas, artigos, parceiros, automações e utilizadores que a função de quem aprovou permite.
Alterações
«Permitir alterações» (Allow changes) é opcional e abrange drives, pastas, carregamentos, artigos, parceiros, automações e rascunhos. A emissão e o envio ficam com as pessoas.
Controlo
A ligação recebe a sua própria chave, com acesso limitado, um limite de pedidos próprio e uma data de expiração. Aparece em Definições, Developer API, Chaves de API, onde a pode revogar de imediato.
# Claude Code
claude mcp add --transport http --scope user arhivix "https://mcp.arhivix.com/mcp"

# Codex
codex mcp add arhivix --url "https://mcp.arhivix.com/mcp"
codex mcp login arhivix
O mesmo endereço funciona em todos os clientes.

Alojamento, armazenamento e utilização dos seus dados

Alojamento
AWS na UE (Frankfurt e Dublin).
Cifragem
AES-256 em repouso e TLS em trânsito.
IA e os seus dados
Os dados dos clientes não são usados para treinar modelos de IA. O acordo de tratamento de dados estabelece-o.
O seu bucket como origem
O Arhivix lê novos documentos do seu bucket Amazon S3, através de uma função só de leitura na sua conta AWS, ou do seu contentor Azure Blob.
O seu próprio armazenamento
O Enterprise suporta bring your own storage: o bucket fica na sua conta, sob as suas chaves e a sua jurisdição, enquanto o Arhivix continua a processar, indexar e servir os documentos através da mesma API.
Isolamento
A empresa é determinada pela chave, por isso uma chave chega aos dados de uma só empresa.
Histórico de auditoria
As ações da API ficam escritas no registo de auditoria com a identidade de serviço e a chave, e o registo pode ser exportado.

O quadro completo está na página Segurança.

Perguntas dos programadores

Posso enviar eu próprio os PDF a um modelo de linguagem em vez de usar uma camada documental?

Pode, e a chamada ao modelo é a parte pequena. Antes de um valor poder chegar a um ERP, alguém tem de receber o documento, confirmar o que foi lido, aprová-lo, guardar o original com as suas versões e registar quem decidiu o quê. O Arhivix trata dessas partes, e ao seu código fica o lado do ERP.

Como impeço que um valor não confirmado chegue ao ERP?

Defina a regra de revisão do campo como Tem de ser confirmado e coloque a condição «Está confirmado» antes do passo que envia dados para outro sistema, para que só o ramo confirmado notifique o seu recetor. O recetor lê depois os valores de um livro de registo, onde cada valor tem o seu estado, como confirmed.

Que documentos o Arhivix lê?

Reconhece 22 tipos de documento, entre eles faturas, contratos, guias de remessa, notas de crédito, extratos bancários, certificados, garantias e propostas. Para qualquer outro documento, como uma nota de encomenda ou um registo de assistência técnica, define o seu próprio tipo e escolhe os campos.

O Arhivix aprende com as correções, e algum modelo é treinado com os meus documentos?

Memoriza o que a sua equipa confirma: para onde vão os documentos de um fornecedor, onde se encontra um campo num tipo de documento, que palavras correspondem a que opção. Essa memória é guardada como regras e versões de tipos da sua empresa. Os dados dos clientes não são usados para treinar modelos de IA, e o acordo de tratamento de dados estabelece-o.

O que acontece se o meu recetor estiver em baixo?

O Arhivix repete uma entrega falhada após 1 minuto, 5 minutos, 30 minutos, 2 horas, 8 horas, 24 horas e 36 horas: oito tentativas ao longo de cerca de 70 horas. O log de entregas guarda cada tentativa, com Repetir e Reenviar, e o feed de alterações GET /events permite ao seu código recuperar o atraso.

Como evito processar o mesmo evento duas vezes?

A entrega é feita pelo menos uma vez, por isso elimine duplicados pelo id do evento ou por X-Arhivix-Delivery. As escritas na API levam um Idempotency-Key, e um resultado concluído é devolvido de novo durante sete dias.

Os agentes de IA podem trabalhar com os nossos documentos?

Sim. O servidor MCP alojado em https://mcp.arhivix.com/mcp liga o Claude, o Claude Code e o Codex depois de um início de sessão no browser. A leitura segue a função da pessoa que aprovou a ligação. As alterações são opcionais e param antes da emissão e do envio, que ficam com as pessoas.

Onde ficam guardados os dados?

Em AWS na UE (Frankfurt e Dublin), cifrados em repouso com AES-256. Os clientes Enterprise podem guardar os documentos no seu próprio bucket compatível com S3, sob as suas próprias chaves.

Como começo?

Crie uma conta no plano gratuito e adicione alguns documentos reais para ver como o Arhivix os lê. A REST API v1 e os webhooks assinados estão incluídos em cada plano pago, e as chaves criam-se em Definições, Developer API. Peça-nos a referência OpenAPI quando criar a sua primeira chave.

Comece com um fluxo de documentos

Peça a referência da API, crie uma chave nas Definições e envie o seu primeiro documento.

Para agentes de programação: esta página em Markdown llms.txt