SDK Ruby et exemples REST — TemplateFox

Deux façons d’utiliser l’API TemplateFox depuis Ruby :

• SDK (gem templatefox) — client typé, généré automatiquement depuis notre spécification OpenAPI.
• REST — net/http, de la bibliothèque standard. Pratique pour limiter les dépendances.

Les exemples de cette page montrent les deux côte à côte.

Dépôt GitHub

Installation

Ajoutez la gem à votre Gemfile :

gem 'templatefox'

Puis lancez bundle install, ou installez-la directement avec gem install templatefox.

La variante REST n’a besoin que de net/http (bibliothèque standard).

Configuration

Définissez votre clé API une fois, puis réutilisez le client.

SDK REST

Copier

require 'templatefox'

TemplateFox.configure do |config|
config.api_key['ApiKeyAuth'] = ENV['TEMPLATEFOX_API_KEY']
end

api = TemplateFox::PDFApi.new

require 'net/http'
require 'json'

BASE_URL = 'https://api.templatefox.com'
HEADERS  = {
'x-api-key'    => ENV['TEMPLATEFOX_API_KEY'],
'Content-Type' => 'application/json'
}

def tf_post(path, body)
uri  = URI(BASE_URL + path)
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
req  = Net::HTTP::Post.new(uri, HEADERS)
req.body = body.to_json
JSON.parse(http.request(req).body)
end

Générer un PDF

Seuls template_id et data sont obligatoires ; tous les autres champs sont facultatifs.

SDK REST

Copier

request = TemplateFox::CreatePdfRequest.new(
template_id: 'YOUR_TEMPLATE_ID',
data: {
  customer_name:  'John Doe',
  invoice_number: 'INV-001',
  amount:         '$1,234.56'
}
)

response = api.create_pdf(request)
puts response.url                # signed URL valid 24h
puts response.credits_remaining  # credits left on the team

response = tf_post('/v1/pdf/create', {
template_id: 'YOUR_TEMPLATE_ID',
data: {
  customer_name:  'John Doe',
  invoice_number: 'INV-001',
  amount:         '$1,234.56'
}
})

puts response['url']
puts response['credits_remaining']

Tous les paramètres sont détaillés dans Créer un PDF.

Enregistrer le PDF dans un fichier

SDK REST

Copier

require 'open-uri'

response = api.create_pdf(request)
URI.open(response.url) do |pdf|
File.open('invoice.pdf', 'wb') { |f| f.write(pdf.read) }
end

uri  = URI(BASE_URL + '/v1/pdf/create')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
req  = Net::HTTP::Post.new(uri, HEADERS)
req.body = {
template_id: 'YOUR_TEMPLATE_ID',
data: { customer_name: 'Jane Doe' },
export_type: 'binary'   # PDF bytes returned directly
}.to_json

File.open('invoice.pdf', 'wb') { |f| f.write(http.request(req).body) }

Envoyer le PDF dans votre bucket S3

Configurez l’intégration S3 une fois dans le tableau de bord, puis passez store_s3: true dans n’importe quel appel.

SDK REST

Copier

request = TemplateFox::CreatePdfRequest.new(
template_id:  'YOUR_TEMPLATE_ID',
data:         { invoice_number: 'INV-001' },
filename:     'invoice-001',           # no extension, .pdf appended
store_s3:     true,                     # upload to your configured bucket
s3_filepath:  'invoices/2026/04/'      # key prefix (optional)
# s3_bucket:  'custom-bucket'          # override bucket from integration
)

response = api.create_pdf(request)
puts "#{response.s3_bucket}/#{response.s3_key}"

response = tf_post('/v1/pdf/create', {
template_id:  'YOUR_TEMPLATE_ID',
data:         { invoice_number: 'INV-001' },
filename:     'invoice-001',           # no extension
store_s3:     true,                     # upload to your configured bucket
s3_filepath:  'invoices/2026/04/'      # key prefix (optional)
# s3_bucket:  'custom-bucket'          # override bucket
})

puts "#{response['s3_bucket']}/#{response['s3_key']}"

Conformité PDF/A

Pour l’archivage ou les usages juridiques, demandez une variante PDF/A.

SDK REST

Copier

request = TemplateFox::CreatePdfRequest.new(
template_id: 'YOUR_TEMPLATE_ID',
data:        { customer_name: 'John Doe' },
pdf_variant: 'pdf/a-2b'   # "pdf/a-1b" | "pdf/a-2b" | "pdf/a-3b"
)

response = api.create_pdf(request)

response = tf_post('/v1/pdf/create', {
template_id: 'YOUR_TEMPLATE_ID',
data:        { customer_name: 'John Doe' },
pdf_variant: 'pdf/a-2b'   # "pdf/a-1b" | "pdf/a-2b" | "pdf/a-3b"
})

Génération asynchrone avec webhooks

Pour les gros documents ou les traitements par lots, passez par l’endpoint asynchrone. Le déroulé complet est décrit dans Créer un PDF (asynchrone).

REST

Copier

response = tf_post('/v1/pdf/create-async', {
template_id:    'YOUR_TEMPLATE_ID',
data:           { invoice_number: 'INV-001' },
webhook_url:    'https://example.com/webhooks/pdf',
webhook_secret: 'whk_a1b2c3d4e5f6g7h8i9j0k1l2'   # HMAC-SHA256 signing
})

job_id = response['job_id']
# Poll GET /v1/pdf/jobs/{job_id} or wait for the webhook.

L’exemple ci-dessus appelle l’API REST directement, avec net/http.

Gestion des erreurs

SDK REST

Copier

begin
response = api.create_pdf(request)
rescue TemplateFox::ApiError => e
puts "status=#{e.code} body=#{e.response_body}"
end

uri  = URI(BASE_URL + '/v1/pdf/create')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
req  = Net::HTTP::Post.new(uri, HEADERS)
req.body = { template_id: 'INVALID_ID', data: {} }.to_json

res = http.request(req)
if res.code.to_i >= 400
puts "status=#{res.code} body=#{res.body}"
end

La liste complète est dans Codes d’erreur.

Principales méthodes du SDK

Classe	Méthode	Endpoint
PDFApi	create_pdf	POST /v1/pdf/create
TemplatesApi	list_templates	GET /v1/templates
TemplatesApi	get_template_fields	GET /v1/templates/{id}/fields
AccountApi	get_account	GET /v1/account
AccountApi	list_transactions	GET /v1/account/transactions
IntegrationsApi	save_s3_config	POST /v1/integrations/s3
IntegrationsApi	get_s3_config	GET /v1/integrations/s3
IntegrationsApi	delete_s3_config	DELETE /v1/integrations/s3
IntegrationsApi	test_s3_connection	POST /v1/integrations/s3/test

Tous les endpoints REST sont documentés dans la référence API.

Pour aller plus loin

• Créer un PDF — chaque paramètre en détail
• Créer un PDF (asynchrone) — webhooks et suivi des tâches
• Dépôt GitHub — code source, historique des versions, tickets
• Collection Postman — testez les endpoints de façon interactive