Qu’est-ce qu’un Snippet dans PDFMonkey ?

Un Snippet est un bloc de code HTML + Liquid nommé, stocké dans un espace de travail. Tous les modèles de cet espace de travail peuvent le charger avec le tag load_snippets et l’insérer avec le tag include.

Comment lister les snippets avec l’API PDFMonkey ?

Envoyez une requête GET à /api/v1/snippets avec un paramètre q[workspace_id]. Sans ce paramètre, l’API renvoie une liste vide. Vous pouvez affiner les résultats avec q[folders] et q[search].

Deux snippets peuvent-ils avoir le même nom ?

Pas dans le même espace de travail. Les modèles font référence à un snippet par son identifier, qui doit donc être unique dans son espace de travail. L’API renvoie une erreur 422 si l’identifier est déjà utilisé.

API Snippets : lister, récupérer, créer, modifier et supprimer des snippets

Référence complète de l’API pour lister, récupérer, créer, modifier et supprimer des snippets dans PDFMonkey.

Vous découvrez les snippets ?

Les snippets permettent de partager du code entre plusieurs modèles. Consultez Réutiliser du code pour savoir comment les charger et les inclure dans un modèle. L’API Snippets est utile lorsque vous gérez vos snippets par programmation, par exemple pour les synchroniser depuis un dépôt Git. Pour les modifier au quotidien, la CLI est souvent l’option la plus simple.

Authentification #

Toutes les requêtes nécessitent un token Bearer dans l’en-tête Authorization :

Authorization: Bearer YOUR_SECRET_KEY

Consultez Authentification pour savoir comment trouver votre clé API.

L’objet Snippet #

Un Snippet est un bloc de code HTML + Liquid nommé, qui appartient à un espace de travail. Les modèles le désignent par son identifier :

{%- load_snippets 'invoice-header' -%}
{% include 'invoice-header', company: company %}

Attributs #

{
  id: "b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b",
  workspace_id: "3161c5e5-9966-4630-9b07-63f718092784",
  identifier: "invoice-header",
  code: '<header class="invoice-header"><h1>{{ company.name }}</h1></header>',
  snippet_folder_id: null,
  creator_id: "0f6d2a8e-1c3b-4e5f-9a7d-2b4c6e8f0a1c",
  creator_name: "Jane Doe",
  updater_id: "0f6d2a8e-1c3b-4e5f-9a7d-2b4c6e8f0a1c",
  updater_name: "Jane Doe",
  created_at: "2050-01-02T03:04:05.678+02:00",
  updated_at: "2050-01-02T03:04:05.678+02:00",
  deleted_at: null,
}

Attribut	Type	Description
`id`	UUID	Identifiant unique.
`workspace_id`	UUID	Identifiant unique de l’espace de travail du snippet.
`identifier`	String	Nom utilisé pour charger le snippet dans les modèles (1 à 100 caractères). Unique dans l’espace de travail.
`code`	String	Code HTML + Liquid du snippet. Doit être du Liquid valide.
`snippet_folder_id`	UUID ou `null`	ID du dossier de snippets qui contient le snippet.
`creator_id`	UUID	ID de l’utilisateur qui a créé le snippet.
`creator_name`	String	Nom affiché de l’utilisateur qui a créé le snippet.
`updater_id`	UUID	ID du dernier utilisateur à avoir modifié le snippet. Déterminé par la clé API utilisée pour la requête.
`updater_name`	String	Nom affiché du dernier utilisateur à avoir modifié le snippet.
`created_at`	String (ISO 8601)	Date de création du snippet.
`updated_at`	String (ISO 8601)	Date de dernière modification du snippet.
`deleted_at`	String (ISO 8601) ou `null`	Toujours `null` pour les snippets renvoyés par l’API.

Lister les snippets #

GET /api/v1/snippets

Renvoie une liste paginée des snippets d’un espace de travail, code compris.

Paramètres de requête #

Nom	Type	Requis	Description
`q[workspace_id]`	String (UUID)	Oui	L’espace de travail dont lister les snippets. Accepte aussi `q[workspaceId]`, `q[app_id]` ou `q[appId]`. Sans ce paramètre, la liste est vide.
`q[folders]`	String	Non	Liste d’ID de dossiers séparés par des virgules. Utilisez `"none"` pour les snippets hors dossier, ou `"all"` (par défaut) pour tous.
`q[search]`	String	Non	Ne renvoie que les snippets dont l’`identifier` contient ce texte (sans tenir compte de la casse).
`page`	Integer	Non	Numéro de page (24 snippets par page). Utilisez `all` pour obtenir tous les snippets en une seule réponse, sans `meta`.
`sort`	String	Non	Attribut de tri, par exemple `identifier`. Préfixez-le par `-` pour un tri décroissant, par exemple `-updated_at`.

Requête #

curl -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  'https://api.pdfmonkey.io/api/v1/snippets?q[workspace_id]=3161c5e5-9966-4630-9b07-63f718092784'

const response = await fetch("https://api.pdfmonkey.io/api/v1/snippets?q[workspace_id]=3161c5e5-9966-4630-9b07-63f718092784", {
  headers: {
    Authorization: "Bearer YOUR_SECRET_KEY",
  },
});

const data = await response.json();
console.log(data.snippets);

import requests

response = requests.get(
    'https://api.pdfmonkey.io/api/v1/snippets',
    headers={
        'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
    params={
        'q[workspace_id]': '3161c5e5-9966-4630-9b07-63f718092784',
    },
)

data = response.json()
print(data['snippets'])

<?php
$ch = curl_init('https://api.pdfmonkey.io/api/v1/snippets?q[workspace_id]=3161c5e5-9966-4630-9b07-63f718092784');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_SECRET_KEY',
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data['snippets']);

Réponse #

{
  "snippets": [
    {
      "id": "b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b",
      "workspace_id": "3161c5e5-9966-4630-9b07-63f718092784",
      "identifier": "invoice-header",
      "code": "<header class=\"invoice-header\"><h1>{{ company.name }}</h1></header>",
      "snippet_folder_id": null,
      "creator_id": "0f6d2a8e-1c3b-4e5f-9a7d-2b4c6e8f0a1c",
      "creator_name": "Jane Doe",
      "updater_id": "0f6d2a8e-1c3b-4e5f-9a7d-2b4c6e8f0a1c",
      "updater_name": "Jane Doe",
      "created_at": "2050-01-02T03:04:05.678+02:00",
      "updated_at": "2050-01-02T03:04:05.678+02:00",
      "deleted_at": null
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1
  }
}

Récupérer un snippet #

GET /api/v1/snippets/{id}

Renvoie un objet Snippet.

Requête #

curl -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  https://api.pdfmonkey.io/api/v1/snippets/b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b

snippet = Pdfmonkey::Snippet.fetch('b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b')

puts snippet.identifier
puts snippet.code

const response = await fetch("https://api.pdfmonkey.io/api/v1/snippets/b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b", {
  headers: {
    Authorization: "Bearer YOUR_SECRET_KEY",
  },
});

const data = await response.json();
console.log(data.snippet);

import requests

response = requests.get(
    'https://api.pdfmonkey.io/api/v1/snippets/b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b',
    headers={
        'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
)

data = response.json()
print(data['snippet'])

<?php
$ch = curl_init('https://api.pdfmonkey.io/api/v1/snippets/b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_SECRET_KEY',
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data['snippet']);

Réponse #

Renvoie 200 OK avec un objet snippet :

{
  "snippet": {
    "id": "b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b",
    "workspace_id": "3161c5e5-9966-4630-9b07-63f718092784",
    "identifier": "invoice-header",
    "code": "<header class=\"invoice-header\"><h1>{{ company.name }}</h1></header>",
    "snippet_folder_id": null,
    "creator_id": "0f6d2a8e-1c3b-4e5f-9a7d-2b4c6e8f0a1c",
    "creator_name": "Jane Doe",
    "updater_id": "0f6d2a8e-1c3b-4e5f-9a7d-2b4c6e8f0a1c",
    "updater_name": "Jane Doe",
    "created_at": "2050-01-02T03:04:05.678+02:00",
    "updated_at": "2050-01-02T03:04:05.678+02:00",
    "deleted_at": null
  }
}

Créer un snippet #

POST /api/v1/snippets

Crée un nouveau snippet dans un espace de travail.

Paramètres #

Tous les paramètres sont imbriqués sous une clé snippet.

Nom	Type	Requis	Description
`workspace_id`	String (UUID)	Oui	L’espace de travail dans lequel créer le snippet.
`identifier`	String	Oui	Nom utilisé pour charger le snippet (1 à 100 caractères). Unique dans l’espace de travail.
`code`	String	Non	Code HTML + Liquid. Doit être du Liquid valide.
`snippet_folder_id`	String (UUID)	Non	Dossier de snippets dans lequel placer le snippet. Doit appartenir au même espace de travail.

Requête #

curl https://api.pdfmonkey.io/api/v1/snippets \
  -X POST \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "snippet": {
      "workspace_id": "3161c5e5-9966-4630-9b07-63f718092784",
      "identifier": "invoice-header",
      "code": "<header class=\"invoice-header\"><h1>{{ company.name }}</h1></header>"
    }
  }'

snippet = Pdfmonkey::Snippet.create(
  workspace_id: '3161c5e5-9966-4630-9b07-63f718092784',
  identifier: 'invoice-header',
  code: '<header class="invoice-header"><h1>{{ company.name }}</h1></header>',
)

puts snippet.id

const response = await fetch("https://api.pdfmonkey.io/api/v1/snippets", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_SECRET_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    snippet: {
      workspace_id: "3161c5e5-9966-4630-9b07-63f718092784",
      identifier: "invoice-header",
      code: '<header class="invoice-header"><h1>{{ company.name }}</h1></header>',
    },
  }),
});

const data = await response.json();
console.log(data.snippet);

import requests

response = requests.post(
    'https://api.pdfmonkey.io/api/v1/snippets',
    headers={
        'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
    json={
        'snippet': {
            'workspace_id': '3161c5e5-9966-4630-9b07-63f718092784',
            'identifier': 'invoice-header',
            'code': '<header class="invoice-header"><h1>{{ company.name }}</h1></header>',
        },
    },
)

data = response.json()
print(data['snippet'])

<?php
$ch = curl_init('https://api.pdfmonkey.io/api/v1/snippets');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_SECRET_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'snippet' => [
            'workspace_id' => '3161c5e5-9966-4630-9b07-63f718092784',
            'identifier' => 'invoice-header',
            'code' => '<header class="invoice-header"><h1>{{ company.name }}</h1></header>',
        ],
    ]),
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data['snippet']);

Réponse #

Renvoie 201 Created avec l’objet snippet complet. L’en-tête Location contient l’URL du nouveau snippet.

Erreurs de validation #

Si un champ est manquant ou invalide, l’API renvoie 422 Unprocessable Entity. Un code Liquid invalide est signalé sous la clé code, avec le message de l’analyseur Liquid.

{
  "errors": {
    "identifier": ["has already been taken"]
  }
}

Modifier un snippet #

PUT /api/v1/snippets/{id}

Modifie un snippet existant. Seuls les champs présents dans le corps de la requête sont modifiés. PATCH est également accepté.

Paramètres #

Tous les paramètres sont imbriqués sous une clé snippet. Les champs acceptés sont les mêmes que pour Créer un snippet. Envoyez "snippet_folder_id": null pour sortir un snippet de son dossier.

Renommer un snippet

Les modèles chargent les snippets par leur identifier. Si vous renommez un snippet, mettez à jour les tags load_snippets et include des modèles qui l’utilisent.

Requête #

curl https://api.pdfmonkey.io/api/v1/snippets/b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b \
  -X PUT \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "snippet": {
      "code": "<header class=\"invoice-header\"><img src=\"{{ company.logo_url }}\"><h1>{{ company.name }}</h1></header>"
    }
  }'

snippet = Pdfmonkey::Snippet.fetch('b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b')

snippet.update!(
  code: '<header class="invoice-header"><img src="{{ company.logo_url }}"><h1>{{ company.name }}</h1></header>',
)

const response = await fetch("https://api.pdfmonkey.io/api/v1/snippets/b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b", {
  method: "PUT",
  headers: {
    Authorization: "Bearer YOUR_SECRET_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    snippet: {
      code: '<header class="invoice-header"><img src="{{ company.logo_url }}"><h1>{{ company.name }}</h1></header>',
    },
  }),
});

const data = await response.json();
console.log(data.snippet);

import requests

response = requests.put(
    'https://api.pdfmonkey.io/api/v1/snippets/b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b',
    headers={
        'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
    json={
        'snippet': {
            'code': '<header class="invoice-header"><img src="{{ company.logo_url }}"><h1>{{ company.name }}</h1></header>',
        },
    },
)

data = response.json()
print(data['snippet'])

<?php
$ch = curl_init('https://api.pdfmonkey.io/api/v1/snippets/b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'PUT',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_SECRET_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'snippet' => [
            'code' => '<header class="invoice-header"><img src="{{ company.logo_url }}"><h1>{{ company.name }}</h1></header>',
        ],
    ]),
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data['snippet']);

Réponse #

Renvoie 200 OK avec l’objet snippet modifié.

Supprimer un snippet #

DELETE /api/v1/snippets/{id}

Supprime un snippet. Il n’apparaît plus ni dans l’API ni dans le Dashboard.

Requête #

curl https://api.pdfmonkey.io/api/v1/snippets/b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b \
  -X DELETE \
  -H 'Authorization: Bearer YOUR_SECRET_KEY'

Pdfmonkey::Snippet.delete('b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b')

const response = await fetch("https://api.pdfmonkey.io/api/v1/snippets/b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b", {
  method: "DELETE",
  headers: {
    Authorization: "Bearer YOUR_SECRET_KEY",
  },
});

console.log(response.status); // => 204

import requests

response = requests.delete(
    'https://api.pdfmonkey.io/api/v1/snippets/b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b',
    headers={
        'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
)

print(response.status_code)  # => 204

<?php
$ch = curl_init('https://api.pdfmonkey.io/api/v1/snippets/b2f1c3a4-5d6e-4f70-8a9b-0c1d2e3f4a5b');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_SECRET_KEY',
    ],
]);

curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE); // => 204
curl_close($ch);

Réponse #

Renvoie 204 No Content avec un corps vide.

Dossiers de snippets #

Les dossiers de snippets regroupent les snippets d’un espace de travail, comme les dossiers de modèles regroupent les modèles. Un snippet ne peut se trouver que dans un seul dossier, défini par son snippet_folder_id.

L’objet SnippetFolder #

{
  "id": "7e3a9c1d-2b4f-4a6e-8c0d-1f2e3a4b5c6d",
  "workspace_id": "3161c5e5-9966-4630-9b07-63f718092784",
  "identifier": "Factures",
  "created_at": "2050-01-02T03:04:05.678+02:00",
  "updated_at": "2050-01-02T03:04:05.678+02:00"
}

Attribut	Type	Description
`id`	UUID	Identifiant unique.
`workspace_id`	UUID	Identifiant unique de l’espace de travail du dossier.
`identifier`	String	Nom du dossier (1 à 100 caractères).
`created_at`	String (ISO 8601)	Date de création du dossier.
`updated_at`	String (ISO 8601)	Date de dernière modification du dossier.

Endpoints #

Méthode	Chemin	Description
`GET`	`/api/v1/snippet_folders`	Liste les dossiers d’un espace de travail. Nécessite `q[workspace_id]`, comme Lister les snippets.
`GET`	`/api/v1/snippet_folders/{id}`	Récupère un dossier.
`POST`	`/api/v1/snippet_folders`	Crée un dossier. Envoyez `workspace_id` et `identifier` sous une clé `snippet_folder`.
`PUT`	`/api/v1/snippet_folders/{id}`	Renomme un dossier. Envoyez `identifier` sous une clé `snippet_folder`.
`DELETE`	`/api/v1/snippet_folders/{id}`	Supprime un dossier et tous les snippets qu’il contient. Renvoie `204 No Content`.

Les réponses placent le dossier sous une clé snippet_folder, ou la liste des dossiers sous une clé snippet_folders.

curl https://api.pdfmonkey.io/api/v1/snippet_folders \
  -X POST \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "snippet_folder": {
      "workspace_id": "3161c5e5-9966-4630-9b07-63f718092784",
      "identifier": "Factures"
    }
  }'

Supprimer un dossier supprime ses snippets

Pour conserver les snippets d’un dossier que vous allez supprimer, sortez-les d’abord du dossier en modifiant chacun d’eux avec "snippet_folder_id": null.

Réutiliser du code — Chargez et incluez des snippets dans vos modèles.
CLI — Modifiez vos snippets en local et synchronisez-les avec PDFMonkey.
Authentification — Trouvez votre clé API et authentifiez vos requêtes.
API Templates — Créez, listez et gérez vos modèles.
SDK Ruby et SDK Node.js — Gérez vos snippets depuis votre code.

Questions fréquentes

Qu’est-ce qu’un Snippet dans PDFMonkey ?: Un Snippet est un bloc de code HTML + Liquid nommé, stocké dans un espace de travail. Tous les modèles de cet espace de travail peuvent le charger avec le tag load_snippets et l’insérer avec le tag include.
Comment lister les snippets avec l’API PDFMonkey ?: Envoyez une requête GET à /api/v1/snippets avec un paramètre q[workspace_id]. Sans ce paramètre, l’API renvoie une liste vide. Vous pouvez affiner les résultats avec q[folders] et q[search].
Deux snippets peuvent-ils avoir le même nom ?: Pas dans le même espace de travail. Les modèles font référence à un snippet par son identifier, qui doit donc être unique dans son espace de travail. L’API renvoie une erreur 422 si l’identifier est déjà utilisé.

API Snippets : lister, récupérer, créer, modifier et supprimer des snippets

Authentification #

L’objet Snippet #

Attributs #

Lister les snippets #

Paramètres de requête #

Requête #

Réponse #

Récupérer un snippet #

Requête #

Réponse #

Créer un snippet #

Paramètres #

Requête #

Réponse #

Erreurs de validation #

Modifier un snippet #

Paramètres #

Requête #

Réponse #

Supprimer un snippet #

Requête #

Réponse #

Dossiers de snippets #

L’objet SnippetFolder #

Endpoints #

Pages associées #

Questions fréquentes