Parceiros técnicos e de ERP

«Dá para automatizar as faturas de fornecedores?» Digam que sim.

Lemos e validamos as faturas de fornecedores dos vossos clientes, e entregamos pela porta que o ERP expõe. Vocês mantêm o cliente, o servidor e a rotina.

Falar connosco Ver como se integra

Porque agora podem dizer que sim

Instalaram o ERP e o cliente continua a pedir-vos o que o ERP não resolve. Três razões para dizer que não, e o que muda em cada uma.

Sem escrever na base de dados

Entregamos pela porta que o ERP expõe: o vosso endpoint, um script SQL para a tabela de importação, ou um ficheiro. Numerar, calcular e lançar continua a ser do ERP.

Ver como encaixa

Com o âmbito escrito numa página

Cinco perguntas ao cliente antes de aceitar, o pedido exacto mostrado antes de haver código, e uma chave de testes no próprio dia.

Ver as cinco perguntas

O que não fecha não entra

NIF com dígito de controlo, soma das linhas contra o total, duplicados, o QR da fatura. O que falha pára para revisão em vez de entrar errado.

Ver as garantias

Como trabalhamos com parceiros

Quatro coisas que não mudam, seja qual for o ERP.

O cliente é vosso. Quem fala com ele, quem escreve a rotina e quem cobra a implementação são vocês. Nós ficamos com a leitura, as regras e o suporte técnico à integração.
Os fluxos configuram-se connosco. Digam que campos querem, onde, e com que regras. Pedidos de alteração são normalmente aplicados no próprio dia. Não é auto-serviço, e é de propósito.
Começa-se num ambiente de testes. Chave própria e uma caixa de email dedicada, no próprio dia. O contrato é o mesmo do de produção; quando passar, mudam os URL e a chave.
Paga-se por documento. Setup à medida do processo e depois por documento processado, sem licenças por utilizador. Os escalões estão na página de preços.

Para quem integra

A parte técnica

O que quem vai ligar o sistema do cliente precisa de saber, por ordem. Os exemplos de pedido e resposta abrem ao clicar.

Como encaixa

Entramos antes do ERP e entregamos pela porta que ele expõe, em vez de escrever na base de dados por baixo. Um INSERT directo salta a numeração, o stock, a contabilidade e os impostos, e é a primeira objecção que qualquer consultor levanta.

Submetem

Um POST com o ficheiro, da vossa aplicação ou do processo que já correm. PDF ou imagem, até 25 MB. Se o utilizador final preferir reencaminhar um email, há uma caixa dedicada que faz o mesmo caminho.

Lemos e verificamos

Cabeçalho e linhas. Depois as regras: o NIF passa o dígito de controlo, a soma das linhas bate com o total, o duplicado é apanhado. O que não fecha pára para revisão humana em vez de entrar errado.

Entregamos

No vosso endpoint, com assinatura. E em paralelo onde mais fizer falta: folha de cálculo, arquivo em SharePoint, script SQL. Não é preciso escolher um só.

Do botão ao número

O caso de quem já tem aplicação própria: o utilizador carrega num botão que vocês já têm, e o documento aparece no sistema do cliente com número atribuído. Não há ecrã nosso pelo meio.

Ver o pedido e a resposta

1. O botão submete

POST /ingest/<INBOX_ID>

{ "data": { "document_id": "a3f1…", "status": "queued",
    "tracking_url": "https://app.docflow.pt/documents/a3f1…",
    "routing": { "flow_id": "…", "strategy": "default_flow" } },
  "error": null }

2. E pergunta como correu

GET /ingest/<INBOX_ID>/documents/a3f1…

{ "data": { "status": "delivered",
    "client_metadata": { "encomenda": "ENC-2026-8842" },
    "deliveries": [
      { "name": "Pedido API para o PHC", "status": "delivered",
        "document_ref": "FT 2026/1187",
        "document_url": "https://erp.cliente.pt/documentos/1187" } ] },
  "error": null }

O document_ref e o document_url são o que o vosso sistema devolveu ao receber o documento. Voltam aqui para o botão poder mostrar o número com que ficou, em vez de apenas «enviado». Aceitamos as chaves mais comuns (id, numero, obrano, stamp), na raiz da resposta ou dentro de data.

Se preferirem não perguntar, chamamos um endereço vosso a cada mudança de estado, incluindo quando o documento pára para revisão. Liga-se na vossa ligação de envio, do nosso lado e no próprio dia: os avisos vão para o mesmo endereço que recebe os documentos, ou para outro que nos indiquem, com a mesma assinatura.

Estados do documento: received, extracting, extracted, pending_approval, approved, delivering, delivered. E ainda failed, rejected e needs_routing. O fim feliz é delivered com todas as entregas entregues.

Ver a referência a ir e a voltar

É este detalhe que separa uma integração de um depósito de ficheiros. Na submissão enviam o que vos identifica o processo:

curl -X POST "https://api.docflow.pt/ingest/<INBOX_ID>" \
  -H "Authorization: Bearer dfl_live_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@fatura.pdf;type=application/pdf" \
  -F 'metadata={"encomenda":"ENC-2026-8842","operador":"amaral"}'

Esse campo fica alcançável no mapeamento do destino por _meta.encomenda, e sai no que entregamos:

{ "adoc": "FT 2026/1187", "ncont": "501234567",
  "etotaldeb": 475.89, "encomenda": "ENC-2026-8842" }

E volta na consulta de estado, tal e qual, para não terem de manter uma tabela de correspondência do vosso lado. Não há lista de nomes reconhecidos: _meta. seguido da chave que enviarem.

Sem isto, a fatura chega ao vosso sistema sem ligação ao processo que a originou, e alguém tem de a casar à mão do outro lado. Que é exactamente o trabalho que isto existe para tirar.

Garantias

O que a integração cumpre, com os números escritos.

Não duplica em retentativas

Um cabeçalho de idempotência vosso por submissão. Repetir o pedido devolve a resposta original em vez de criar documento novo. Como segunda linha, o mesmo ficheiro submetido duas vezes pára para revisão.

O vosso processo pergunta se já está

Um GET devolve o estado e cada entrega. Pedindo o payload, devolve também os dados mapeados que seguiram para cada destino. Ninguém precisa de abrir um ecrã para saber o resultado.

Ou não pergunta, e nós avisamos

Em alternativa à consulta, chamamos um endpoint vosso a cada mudança de estado, com assinatura HMAC-SHA256 e retentativas automáticas.

A entrega vai assinada

O pedido leva o identificador do documento e o da entrega, para desduplicarem do vosso lado, e assinatura opcional para verificarem que veio de nós.

Os erros dizem de quem é a culpa

Todas as respostas trazem o mesmo envelope, incluindo as de erro, com código próprio. Se receberem HTML em vez dele, veio da camada de rede à frente da API e não de nós.

Os limites estão escritos

60 pedidos por minuto e 1000 por dia na submissão; 240 e 20 000 na consulta, contados à parte. O 429 traz o tempo de espera e a janela.

As cinco perguntas ao cliente

Fazem-se antes de aceitar, e decidem se o projecto é de duas semanas ou de dois meses. Valem para qualquer ferramenta.

O ERP expõe um web service de entrada de documentos, ou qual é o caminho suportado? Nunca a tabela final.
Que campos são obrigatórios para o lançamento passar, e quais não vêm no papel?
Há tabela de correspondência entre as referências do fornecedor e as do cliente?
Onde vive o documento digitalizado?
Quem revê o que for duvidoso, e em quanto tempo?

Com as cinco respondidas, o resto é connosco: o mapeamento, as regras, o ambiente de testes. O artigo com as perguntas por extenso.

Perguntas de quem integra

Em que ERP é que isto entra?

Em qualquer um: o conector faz-se à medida do ERP do cliente, convosco. A entrega é por pedido HTTP ao vosso endpoint, por script SQL, ou por ficheiro, e quando o ERP tem uma API própria escrevemos e mantemos a ligação a essa API. É por isso que esta página fala de endpoint e não de uma lista de ERP: quem conhece o sistema do cliente são vocês, e nós entregamos no formato que ele aceita.

O que é que se consegue mapear sem escrever código?

Qualquer campo do documento para qualquer nome que o vosso sistema espere, consulta a tabelas de referência do cliente (artigos, fornecedores, contas) com recuperação de gralhas confirmada por um segundo campo, e numeração das linhas com a convenção do ERP. Cálculos e condições não: essas ficam do vosso lado ou do nosso, na configuração.

Conseguimos provar o encaixe antes de haver endpoint?

Sim, e é o caminho que recomendamos. Há um destino que constrói o pedido e o mostra sem o enviar, e outro que gera o script SQL. Vê-se o corpo exacto que sairia, com os campos já mapeados, antes de existir código do vosso lado.

O que é que não fazemos?

Não é auto-serviço A chave é emitida por nós e entregue uma vez. Não há um portal onde a giram, nem onde criem ambientes sozinhos.
Não há SDK Há um guia de integração, entregue com a chave. É multipart/form-data à entrada e JSON à saída, portanto qualquer linguagem lá chega com o que já tem.
A vossa conta é operacional Os documentos da vossa organização, aprovação e reprocessamento, contagens e tempos, e a vista dos fluxos configurados.

Da próxima vez que um cliente pedir, digam que sim.

Digam-nos que sistema é que já instalaram. Uma conversa de vinte minutos chega para saber se encaixa, e saem de lá com um ambiente de testes e uma chave.

Falar connosco