SDK Go et exemples REST — TemplateFox

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

• SDK (github.com/TemplateFoxPDF/gosdk) — client typé, généré automatiquement depuis notre spécification OpenAPI.
• REST — le paquet 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

go get github.com/TemplateFoxPDF/gosdk

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

Configuration

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

SDK REST

Copier

import (
  "context"
  "os"

  templatefox "github.com/TemplateFoxPDF/gosdk"
)

config := templatefox.NewConfiguration()
config.AddDefaultHeader("x-api-key", os.Getenv("TEMPLATEFOX_API_KEY"))

client := templatefox.NewAPIClient(config)
ctx := context.Background()

import (
  "net/http"
  "os"
)

const baseURL = "https://api.templatefox.com"

func setHeaders(req *http.Request) {
  req.Header.Set("x-api-key", os.Getenv("TEMPLATEFOX_API_KEY"))
  req.Header.Set("Content-Type", "application/json")
}

Générer un PDF

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

SDK REST

Copier

request := templatefox.CreatePdfRequest{
  TemplateId: "YOUR_TEMPLATE_ID",
  Data: map[string]interface{}{
      "customer_name":  "John Doe",
      "invoice_number": "INV-001",
      "amount":         "$1,234.56",
  },
}

response, _, err := client.PDFApi.CreatePdf(ctx, request)
if err != nil {
  log.Fatal(err)
}

fmt.Println(*response.Url)              // signed URL valid 24h
fmt.Println(*response.CreditsRemaining) // credits left on the team

payload, _ := json.Marshal(map[string]any{
  "template_id": "YOUR_TEMPLATE_ID",
  "data": map[string]string{
      "customer_name":  "John Doe",
      "invoice_number": "INV-001",
      "amount":         "$1,234.56",
  },
})

req, _ := http.NewRequest("POST", baseURL+"/v1/pdf/create", bytes.NewReader(payload))
setHeaders(req)

resp, err := http.DefaultClient.Do(req)
if err != nil {
  log.Fatal(err)
}
defer resp.Body.Close()

var result struct {
  URL              string `json:"url"`
  CreditsRemaining int    `json:"credits_remaining"`
}
json.NewDecoder(resp.Body).Decode(&result)

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

Enregistrer le PDF dans un fichier

SDK REST

Copier

response, _, err := client.PDFApi.CreatePdf(ctx, templatefox.CreatePdfRequest{
  TemplateId: "YOUR_TEMPLATE_ID",
  Data:       map[string]interface{}{"customer_name": "Jane Doe"},
})
if err != nil {
  log.Fatal(err)
}

pdfResp, _ := http.Get(*response.Url)
defer pdfResp.Body.Close()

file, _ := os.Create("invoice.pdf")
defer file.Close()
io.Copy(file, pdfResp.Body)

payload, _ := json.Marshal(map[string]any{
  "template_id": "YOUR_TEMPLATE_ID",
  "data":        map[string]string{"customer_name": "Jane Doe"},
  "export_type": "binary", // PDF bytes returned directly
})

req, _ := http.NewRequest("POST", baseURL+"/v1/pdf/create", bytes.NewReader(payload))
setHeaders(req)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

file, _ := os.Create("invoice.pdf")
defer file.Close()
io.Copy(file, resp.Body)

Envoyer le PDF dans votre bucket S3

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

SDK REST

Copier

storeS3 := true
filepath := "invoices/2026/04/"   // key prefix (optional)
filename := "invoice-001"          // no extension, .pdf appended

request := templatefox.CreatePdfRequest{
  TemplateId: "YOUR_TEMPLATE_ID",
  Data:       map[string]interface{}{"invoice_number": "INV-001"},
  Filename:   &filename,
  StoreS3:    &storeS3,
  S3Filepath: &filepath,
  // S3Bucket:  &bucket,    // override bucket from integration
}

response, _, _ := client.PDFApi.CreatePdf(ctx, request)
fmt.Println(*response.S3Bucket, *response.S3Key)

payload, _ := json.Marshal(map[string]any{
  "template_id":  "YOUR_TEMPLATE_ID",
  "data":         map[string]string{"invoice_number": "INV-001"},
  "filename":     "invoice-001",           // no extension
  "store_s3":     true,                     // upload to your bucket
  "s3_filepath":  "invoices/2026/04/",     // key prefix (optional)
  // "s3_bucket": "custom-bucket",         // override bucket
})

req, _ := http.NewRequest("POST", baseURL+"/v1/pdf/create", bytes.NewReader(payload))
setHeaders(req)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

Conformité PDF/A

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

SDK REST

Copier

variant := "pdf/a-2b"   // "pdf/a-1b" | "pdf/a-2b" | "pdf/a-3b"

response, _, _ := client.PDFApi.CreatePdf(ctx, templatefox.CreatePdfRequest{
  TemplateId: "YOUR_TEMPLATE_ID",
  Data:       map[string]interface{}{"customer_name": "John Doe"},
  PdfVariant: &variant,
})

payload, _ := json.Marshal(map[string]any{
  "template_id": "YOUR_TEMPLATE_ID",
  "data":        map[string]string{"customer_name": "John Doe"},
  "pdf_variant": "pdf/a-2b",   // "pdf/a-1b" | "pdf/a-2b" | "pdf/a-3b"
})

req, _ := http.NewRequest("POST", baseURL+"/v1/pdf/create", bytes.NewReader(payload))
setHeaders(req)

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

payload, _ := json.Marshal(map[string]any{
  "template_id":    "YOUR_TEMPLATE_ID",
  "data":           map[string]string{"invoice_number": "INV-001"},
  "webhook_url":    "https://example.com/webhooks/pdf",
  "webhook_secret": "whk_a1b2c3d4e5f6g7h8i9j0k1l2",   // HMAC-SHA256 signing
})

req, _ := http.NewRequest("POST", baseURL+"/v1/pdf/create-async", bytes.NewReader(payload))
setHeaders(req)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result struct{ JobId string `json:"job_id"` }
json.NewDecoder(resp.Body).Decode(&result)
// 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

response, httpResp, err := client.PDFApi.CreatePdf(ctx, request)
if err != nil {
  if apiErr, ok := err.(templatefox.GenericOpenAPIError); ok {
      fmt.Printf("status=%d body=%s\n", httpResp.StatusCode, apiErr.Body())
  }
  log.Fatal(err)
}

resp, err := http.DefaultClient.Do(req)
if err != nil {
  log.Fatal(err)
}
defer resp.Body.Close()

if resp.StatusCode >= 400 {
  body, _ := io.ReadAll(resp.Body)
  log.Fatalf("status=%d body=%s", resp.StatusCode, string(body))
}

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

Principales méthodes du SDK

Service	Méthode	Endpoint
PDFApi	CreatePdf	POST /v1/pdf/create
TemplatesApi	ListTemplates	GET /v1/templates
TemplatesApi	GetTemplateFields	GET /v1/templates/{id}/fields
AccountApi	GetAccount	GET /v1/account
AccountApi	ListTransactions	GET /v1/account/transactions
IntegrationsApi	SaveS3Config	POST /v1/integrations/s3
IntegrationsApi	GetS3Config	GET /v1/integrations/s3
IntegrationsApi	DeleteS3Config	DELETE /v1/integrations/s3
IntegrationsApi	TestS3Connection	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