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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
O seu ERP
- ERP antigo, contabilidade ou sistema de gestão do negócio
- Continua a ser o sistema de referência
A importação que o seu ERP suporta
O seu recetor
- Verifica a assinatura
- Lê o registo através da API
- Escreve através da importação que o seu ERP suporta
Webhooks assinados e REST API
Arhivix
- Receção
- Leitura com OCR e IA
- Confirmação por uma pessoa
- Fluxos e aprovações
- Dossiers de negócio
- Armazenamento, versões e registo de auditoria
Webhooks, REST API e MCP
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.
| Parte da integração | O que o Arhivix faz | Onde 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.
| Parte do caso | No Arhivix | Qualificação de fornecedores | Entrega 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.
-
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.
-
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.
-
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.
-
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.
-
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 partesv1pertencem ao caminho. Uma só API para todas as regiões: a empresa é determinada pela chave.- Autenticação
Authorization: Bearer <key>ouX-API-Key: <key>. As chaves começam porak_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-RemainingeX-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çalhoX-Arhivix-Request-SHA256: o SHA-256 do corpo exato do pedido. Um carregamento coloca o OCR em fila automaticamente.- Resultados
GET /nodes/{id}/metadatadevolveocr_status, a classificação comdoc_type, a categoria, um resumo e etiquetas, e os dados extraídos da fatura.GET /nodes/{id}/textdevolve o texto do OCR página a página.- Livros de registo
POST /document-pipelines/registers/{id}/querydevolve os valores lidos para os seus próprios tipos de documento. Cada valor tem um estado, comoconfirmedouproposed, e um filtro pode pedir um só estado.- Listas
- Paginação por keyset:
limitde 1 a 100 e o cursor demeta.pagination.next_cursor. - Feed de alterações
GET /eventsdevolve 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,messageemeta.request_id. EnvieX-Request-IDpara 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"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-Signaturecontémsha256=e o HMAC-SHA256 deX-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
iddo evento ou porX-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"
}
}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);
}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 arhivixAlojamento, 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