Artigo Técnico · REST v1

Documentação da API Foliade

API de iniciação: 5 conversões bem-sucedidas em 30 dias, uma de cada vez; 50 MB e 100 páginas por PDF, 250 MB de pacotes API guardados.

O MCP está incluído desde o plano gratuito. A API completa, as estatísticas, o carregamento em massa e os webhooks estão incluídos a partir do Pro. A exportação HTML autónoma está incluída a partir do Business.

Referência interativa aberta Baixar OpenAPI

Autenticação do portador

Crie uma chave em Foliade → API e envie-a no cabeçalho Authorization. A chave dá acesso aos catálogos de sua conta: guarde-a em um gerenciador de segredos e nunca no código-fonte.

export FOLIADE_API_KEY="fl_live_your_key"
curl https://foliade.gekkode.com/v1/me \
  -H "Authorization: Bearer ${FOLIADE_API_KEY}"

Ciclo de vida principal

crie uma chave dedicada para cada integração;
copie seu valor ao criá-lo;
monitorar sua última ligação;
revogá-lo assim que não for mais usado.

Uma chave ausente, desconhecida ou revogada é respondida 401.

Terminais v1

Método	Caminho	Resultado
`POST`	`/v1/catalogs`	Converte um PDF, rascunho ou publicado.
`POST`	`/v1/catalogs/bulk`	Aceite uma fonte pública e inicie um lote.
`GET`	`/v1/catalogs`	Lista os catálogos da conta.
`GET`	`/v1/catalogs/{id}`	Devolve o catálogo e o estado da última conversão.
`POST`	`/v1/catalogs/{id}/publish`	Publica um rascunho existente sem nova conversão nem alteração do link.
`GET`	`/v1/catalogs/{id}/stats?days=30`	Retorna leituras, leitores, contatos e visualizações de páginas.
`DELETE`	`/v1/catalogs/{id}`	Cancela a publicação do catálogo sem excluir os dados da conta.
`GET`	`/v1/me`	Verifica a chave, a oferta e a quantidade de catálogos.

Publicar um PDF

Envie um corpo multipart/form-data. Sozinho fichier é obrigatório. publier=0 cria um rascunho; publier=1 torna o link público. Com attendre=1, a consulta aguardará a conversão por até 300 segundos antes de renderizar um 202.

curl -X POST https://foliade.gekkode.com/v1/catalogs \
  -H "Authorization: Bearer ${FOLIADE_API_KEY}" \
  -F "[email protected];type=application/pdf" \
  -F "titre=Catalogue été 2026" \
  -F "langue=fr" \
  -F "publier=1" \
  -F "attendre=1"

Campo	Padrão	Descrição
`fichier`	—	API de iniciação: 50 MB e 100 páginas por PDF. API completa: 300 MB por PDF.
`remplace`	—	Identificador de um catálogo da conta a substituir, sem alterar a ligação ou proteção. Uma conversão bem-sucedida consome uma unidade da quota de iniciação.
`titre`	nome do arquivo	Título visível do catálogo.
`langue`	idioma da conta	Código de idioma suportado pelo player.
`publier`	`0`	`1` para abrir imediatamente o link público.
`attendre`	`1`	`0` para receber imediatamente trabalho assíncrono.

{
  "id": "abc123",
  "url": "https://foliade.gekkode.com/c/abc123",
  "etat": "public",
  "pages": 24,
  "duree_s": 8.4,
  "texte_indexe": true
}

Processamento em massa

A API completa está incluída a partir do Pro.

O ponto de entrada em massa recebe uma URL HTTP(S) pública em um corpo JSON. O webhook é opcional. A resposta 202 contém o identificador do lote aceito.

curl -X POST https://foliade.gekkode.com/v1/catalogs/bulk \
  -H "Authorization: Bearer ${FOLIADE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "https://exemple.fr/catalogues.zip",
    "webhook": "https://exemple.fr/webhooks/foliade"
  }'

A fonte é um arquivo ZIP de até 2 GB, com no máximo 500 PDFs de 300 MB cada. As notificações usam uma fila persistente: após uma falha de HTTP, cinco novas tentativas são agendadas após 1 minuto, 5 minutos, 15 minutos, 1 hora e 6 horas.

Cada notificação inclui um identificador estável e uma assinatura HMAC-SHA256. Recupere o segredo de assinatura do seu espaço por meio da API Identity. Verifique a assinatura bruta do corpo HTTP, rejeite carimbos de data/hora com mais de cinco minutos e desduplique eventos já processados. Uma rotação da chave do aplicativo renova os segredos.

GET /v1/me → webhook_signing_secret
X-Foliade-Event-Id: event_id
X-Foliade-Signature: t=timestamp,v1=signature
signature = HMAC-SHA256(webhook_signing_secret, timestamp + "." + raw_body)

Estatísticas

As estatísticas exigem Pro.

O período é transmitido com days. A API REST e o servidor MCP hospedado aceitam um número inteiro de 1 a 3650 dias. Valores fora da faixa são recusados.

curl "https://foliade.gekkode.com/v1/catalogs/abc123/stats?days=30" \
  -H "Authorization: Bearer ${FOLIADE_API_KEY}"

Respostas e erros

Estado	Significado	Acção
`201`	Conversão concluída.	Usar `url` e `id`.
`202`	Conversão ou lote aceito, ainda em andamento.	Guarde o ID devolvido.
`400`	A origem em massa não é um URL público aceito.	Forneça um URL HTTP(S) acessível.
`401`	Chave ausente, desconhecida ou revogada.	Verifique o cabeçalho ou crie uma chave.
`403`	Função reservada a um plano superior ou conta suspensa.	Verifique as permissões da conta.
`404`	Catálogo ausente na conta autenticada.	Verifique o ID e a chave.
`409`	Conversão em curso, vagas ocupadas ou armazenamento cheio.	Aguarde ou liberte uma vaga na sua conta.
`413`	O PDF ultrapassa o limite de tamanho ou páginas do seu plano.	Reduza ou divida o documento.
`422`	PDF protegido, corrompido ou falha na conversão.	Exporte novamente um PDF legível sem senha.
`429`	Quota API ou limite de proteção atingido.	Consulte as quotas antes de tentar novamente.

Proteção contra abusos: 60 chamadas API por minuto e 10 tentativas de carregamento por 24 horas, partilhadas com o site e o MCP. As falhas contam para o limite diário, não para a quota mensal.

Eliminar ou despublicar não devolve uma conversão bem-sucedida. As 5 vagas de publicação são partilhadas com os carregamentos web. Os rascunhos e arquivos API contam nos 5 catálogos API guardados e nos 250 MB de armazenamento.

Após uma resposta 202, consulte o catálogo para acompanhar a conversão. A resposta de identidade da conta indica as quotas de iniciação restantes; o segredo do webhook só é fornecido ao Pro e planos superiores.

Servidor API ou MCP?

A API é adequada para um aplicativo, backend ou canal editorial. O servidor MCP envolve as mesmas operações com ferramentas que Codex e Claude Code podem chamar sob controle do usuário.

Compreendendo a diferença entre MCP e API

Referência executável

A documentação do Swagger e o esquema OpenAPI são gerados a partir das rotas realmente implantadas.

Teste em Swagger UI

Registro de alterações

Versão	Data	Mudanças
v1	28 de agosto de 2026	Documentação pública de conversão, lotes, estatísticas, cancelamento de publicação e identidade da conta.