API v1 — incluída em todos os planos pagos

API Reference

A folit.ai expõe uma API REST para sincronizar o catálogo do seu ERP, receber os documentos e recepções processados e, opcionalmente, integrar fichas de colaboradores. Toda a comunicação é iniciada pelo seu sistema, em HTTPS, com um token de integração criado no portal.

1. Introdução

Toda a comunicação é iniciada pelo cliente, em HTTPS, com payloads e respostas em application/json. Não precisamos de aceder à sua rede — o conector vive no seu lado e fala com a folit como qualquer outra API REST.

Base URL

https://api.folit.ai

Os endpoints abaixo já incluem o prefixo /api/v1. api.folit.ai aponta para o mesmo servidor do portal (app.folit.ai) — qualquer um funciona, mas para integrações novas use api.folit.ai.

Seguro

TLS + tokens de integração com permissões por token, revogáveis

REST

JSON em todos os endpoints, idempotente por externalRef

Incremental

Cursores incrementais — só puxa o que mudou

2. Como funciona — Push, IA, Pull, Ack

O fluxo de integração tem quatro passos. O conector do cliente faz tudo por chamadas REST simples — sem ligação inversa, sem agentes residentes, sem permissões na rede do cliente.

Passo 1

Push catálogo

O conector envia fornecedores e artigos do ERP para a folit, identificados por externalRef. Idempotente: re-envios não duplicam.

Passo 2

IA processa

Faturas que chegam à folit (PDF, foto, ou email per-tenant) são extraídas pela IA. Linhas, fornecedores e identificadores são correspondidos ao catálogo enviado.

Passo 3

Pull documentos

O conector chama /purchases/changes com cursor incremental. Recebe novos documentos com cabeçalho, linhas, séries e lotes prontos a integrar no ERP.

Passo 4

Ack

Após escrever no ERP, o conector confirma com /ack — opcionalmente devolvendo o externalRef criado no ERP para correlação futura.

3. Autenticação

Autentique cada pedido com um token de integração no header Authorization. Os tokens têm o prefixo flx_:

http
Authorization: Bearer flx_…

Os tokens são criados por um administrador em Sincronização ERP → Configuração, cada um com nome e permissões próprias. O segredo só é mostrado uma vez, na criação, e não pode ser consultado depois. Revogar um token bloqueia-o de imediato.

Trate o token como uma password. Quem o tiver pode fazer tudo o que as permissões desse token permitem. Guarde-o numa secret store ou variável de ambiente — nunca em ficheiros versionados nem por email.

Guia de integração

Tokens de integração

Cada empresa pode ter vários tokens de integração, um por sistema, cada um com as suas permissões. O segredo só é mostrado uma vez, na criação. Se perder um segredo, revogue o token e crie outro.

Menor privilégio

Um token novo não tem permissões. Dê a cada sistema só o que precisa — por exemplo purchases:read + purchases:ack para um conector que só puxa compras. GET /api/v1/health aceita qualquer token válido; sem a permissão exigida a resposta é 403. A permissão de cada endpoint está indicada no catálogo abaixo.

Colaboradores (RH) — opt-in

/api/v1/employees gere fichas administrativas de colaboradores: listar, ler por id e criar/actualizar por referência externa (PUT /api/v1/employees/by-reference/{externalRef}). Não são contas de acesso ao portal — não existe API pública para gerir utilizadores ou logins. Só tokens com employees:read / employees:write explícitos lhes acedem; o preset ERP não as inclui.

HTTP 200 com falhas parciais

Os upserts em lote validam o payload e gravam registo a registo. Um 200 pode trazer ok: false e itens rejeitados: inspeccione sempre failed e items e reenvie só depois de corrigir a causa. Não há atomicidade do lote; reenviar com as mesmas referências é seguro.

Paginação — cada recurso tem o seu cursor

  • Compras, recepções e artigos pendentes: guarde nextCursorMs e nextCursorId e envie-os juntos como since + afterId.
  • Colaboradores: envie o nextCursor opaco em cursor; continue mesmo que a página venha vazia.
  • Referências de fornecedor: repita com afterId=nextAfterId até receber null.

Artigos criados ou editados na folit

GET /api/v1/articles/pending-sync lista artigos criados ou alterados na folit que aguardam confirmação do ERP — incluindo artigos que já têm referência ERP mas foram editados. Depois de os gravar no ERP, confirme com POST /api/v1/articles/sync-back.

Kit de conector — opcional

O ERP Kit (Node.js, perfis PHC, ICG, Primavera, Sage, Eticadata e custom) é um ponto de partida facultativo. Qualquer cliente HTTP que siga esta documentação integra da mesma forma. O kit e o seu link partilhável não contêm credenciais.

4. Endpoints

Lista gerada a partir da especificação OpenAPI publicada. Abra cada endpoint para ver a permissão exigida, parâmetros, exemplo e schemas de pedido e resposta.

5. Dados extraídos por linha

Cada documento devolvido em /purchases/changes traz um cabeçalho (fornecedor, número, data, totais) e um array items. Cada linha tem os campos estruturados prontos a escrever no ERP — incluindo o trabalho normalmente manual de captar números de série, lotes e datas de validade:

O campo reference é preenchido com o externalRef do artigo correspondido no catálogo (vazio se não houver correspondência). O array serials aceita números de série (NS/SN), lotes e datas de validade — cada entrada com serialNumber, lotNumber, expiryDate e quantity.

6. Recepções de mercadoria (Folit Check)

Quando um cliente usa o Folit Check para registar entradas de mercadoria, cada recepção fica disponível na API. O endpoint /api/v1/receptions/changes unifica dois cenários:

  • linked — recepção contra uma fatura existente.
  • standalone — recepção sem fatura.

Confirme cada recepção com POST /api/v1/receptions/:id/ack. Para recepções linked, o id contém o caracter # — faça URL-encode antes de o colocar no path.

7. Health & versionamento

Toda a API vive sob /api/v1 e as respostas incluem o header X-Folit-Api-Version: 1. Endpoints a descontinuar passam a devolver X-Folit-Deprecated: true. Use /api/v1/health para validar o token no arranque do conector.

curl
curl -i "https://api.folit.ai/api/v1/health" \
  -H "Authorization: Bearer $FOLIT_TOKEN"

8. Webhooks

A API não envia webhooks. A integração faz polling incremental dos endpoints de alterações, guardando o cursor entre execuções.

9. Limites e planos

Pricing actual: a API está incluída em todos os planos pagos (Starter, Growth, Business, Enterprise) e durante o trial de 15 dias. Os limites técnicos são iguais — o que diferencia é a quota de documentos/mês do plano.

Os tamanhos máximos de lote e de página variam por endpoint e estão nos schemas do catálogo. Códigos frequentes: 400 payload inválido, 401 token inválido ou revogado, 403 permissão em falta, 404 recurso desconhecido, 409 conflito, 413 lote demasiado grande, 423 empresa inactiva, 503 indisponível (reenviar com as mesmas referências).

Importante — integração com o ERP

A folit fornece a API REST e o ERP Kit (perfis prontos para PHC, ICG, Primavera, Sage, Eticadata + perfil custom) para puxar facturas e empurrar artigos/lotes. A integração do lado do ERP é da responsabilidade do parceiro implementador ou do cliente. A nossa equipa apoia tecnicamente, mas não acede ao ERP do cliente.

© 2026 folit.ai · Crazy Particle, Lda.

Voltar ao site