Accès à l'API

Pour commencer, rendez-vous sur votre espace personnel pdf.kiwi pour récupérer la clé d'API (token) associée à votre abonnement. C'est une chaîne de 32 caractères.

api access example

Ensuite, il vous suffit d'envoyer une requête HTTP POST à l'adresse de votre choix :

  • https://pdf.kiwi/api/convert/html pour convertir du contenu HTML en PDF.
  • https://pdf.kiwi/api/convert/url pour convertir une page web en PDF.

api request post endpoint

Pour plus de détails à propos des différents points d'entrée de l'API et leurs paramètres, consultez la page Méthodes / Points d'entrée.

Les paramètres POST qu'il faut impérativement passer à l'API (au format form-data) sont les suivants :

  • email : L'adresse email associée au compte,
  • token : La clé API (token) associée à l'abonnement,
  • html : Le contenu HTML qui sera rendu dans le corps de page du PDF
      ou
  • url : L'adresse de la page web qui sera rendue dans le corps du PDF

Le paramètre options, permettant de personnaliser le rendu du PDF, est facultatif :

  • options : Tableau associatif des options à passer.
    (par ex. options[header_html] ou options[orientation])

La liste des options que l'on peut passer est détaillée sur cette page.

Utilisation avec PHP

Si vous comptez utiliser pdf.kiwi au sein d'une application PHP, nous vous conseillons d'utiliser la librairie open-source, disponible sur Github : pdfkiwi/php-lib.
Voici un exemple :

<?php
use PdfKiwi\PdfKiwi;

try {
    $pdfKiwi = new PdfKiwi('email@example.net', '5a4b84c611eab7dd953b47aa6f89fb3');

    $pdfKiwi->setPageMargins('10mm', '20mm', '10mm', '20mm');
    $pdfKiwi->setOrientation('landscape');

    $pdf = $pdfKiwi->convertHtml('<h1>Testing pdf.kiwi awesomness</h1>');

    file_put_contents('downloads/test.pdf', $pdf);
} catch (PdfKiwiException $e) {
    echo sprintf("pdf.kiwi error %s:\n%s", $e->getCode(), $e->getMessage());
}

Utilisation avec Node.js

Si vous comptez utiliser pdf.kiwi au sein d'une application écrite en JS avec Node.js, nous vous conseillons d'utiliser la librairie open-source, disponible sur Github : pdfkiwi/node-lib.
Voici un exemple :

const pdf = require('pdfkiwi');

const client = new pdf.Pdfkiwi('email@example.net', '5a4b84c611eab7dd953b47aa6f89fb3');

client.convertHtml('<h1>Testing pdf.kiwi awesomness</h1>', { 'orientation': 'landscape' })
    .then(pdf.saveToFile('./test.pdf'))
    .then(() => { console.log('done !'); })
    .catch((err) => {
        console.log(err.code, err.message);
    });

Réponses de l'API

200 OK

pdf logo

Si tout se passe bien, la réponse de l'API (HTTP code 200 OK) ne contiendra que le PDF lui-même. Il ne vous restera alors plus qu'à enregistrer cette réponse dans un fichier avec l'extension .pdf.

Erreurs

En revanche si une erreur survient, l'API répondra par un code HTTP approprié, avec un JSON expliquant l'erreur. Par exemple, pour le cas où l'adresse email est inconnue :

HTTP CODE 401 UNAUTHORIZED

{
    "success" : false,
    "error"   : {
        "code"    : 40,
        "message" : "No customer account found with given email address."
    }
}

Vous pouvez consulter la liste des erreurs possibles pour plus d'informations sur les erreurs que peut renvoyer l'API.

Exemple avec Postman

Voici une petite collection Postman pour essayer pdf.kiwi. N'oubliez pas de renseigner l'adresse email de votre compte, ainsi que la clé API dans les champs email et token :

{
    "variables": [],
    "info": {
        "name": "pdf.kiwi examples",
        "_postman_id": "866a7396-e79e-1d53-1735-2c4e4e22e419",
        "description": "",
        "schema": "https://schema.getpostman.com/json/collection/v2.0.0/collection.json"
    },
    "item": [
        {
            "name": "pdf.kiwi example",
            "request": {
                "url": "pdf.kiwi/api/convert/html",
                "method": "POST",
                "header": [],
                "body": {
                    "mode": "formdata",
                    "formdata": [
                        {
                            "key": "email",
                            "value": "",
                            "type": "text",
                            "enabled": true
                        },
                        {
                            "key": "token",
                            "value": "",
                            "type": "text",
                            "enabled": true
                        },
                        {
                            "key": "html",
                            "value": "<head>\n<style>h3{color:green;}</style>\n</head>\n<body>\n<h3>Hello World</h3>\n<p>Lorem ipsum dolor sit amet.</p>\n</body>",
                            "type": "text",
                            "enabled": true
                        },
                        {
                            "key": "options[footer_text_center]",
                            "value": "Page {{page}} / {{topage}}",
                            "type": "text",
                            "enabled": true
                        },
                        {
                            "key": "options[header_text_right]",
                            "value": "Testing pdf.Kiwi from Postman",
                            "type": "text",
                            "enabled": true
                        },
                        {
                            "key": "options[page_size]",
                            "value": "A4",
                            "type": "text",
                            "enabled": true
                        }
                    ]
                },
                "description": "Example of use of pdf.kiwi API.\n\nDon't forget to give it an email and a token."
            },
            "response": []
        }
    ]
}

résultats pour ""

    Aucun résultat pour ""