Documentation

Intégrer Printaya à votre application

Envoyer un document depuis votre code vers une imprimante posée chez votre client, à l'autre bout de la ville ou du pays. Quatre appels suffisent.

Le principe

Votre application ne parle jamais à l'imprimante. Elle envoie le document à Printaya, qui le transmet à l'agent installé sur le poste de votre client.

L'agent se connecte vers Printaya, jamais l'inverse : rien à ouvrir sur le réseau de votre client, pas de VPN, pas d'adresse IP fixe. Et le document lui-même ne circule pas en clair sur la file d'attente - seule une URL signée, valable quelques minutes, permet à l'agent d'aller le chercher.

Avant de commencer

Trois choses doivent exister avant le premier appel :

• Un compte Printaya, et l'agent installé sur le poste où se trouve l'imprimante.
• Un jeton d'API, créé depuis votre tableau de bord, onglet Intégration.
• L'imprimante allumée au moins une fois depuis l'installation de l'agent : c'est ainsi qu'il apprend à la joindre.

Toutes les adresses de cette page partent de :

https://api.printaya.com

C'est l'adresse des machines, différente de celle de votre tableau de bord. Elle ne changera jamais : inscrivez-la sans crainte dans votre configuration.

1. Votre jeton

Chaque appel porte votre jeton dans l'en-tête Authorization. Il identifie votre organisation : vous ne voyez que vos postes, vos imprimantes et vos documents.

Authorization: Bearer VOTRE_JETON

Un jeton s'utilise depuis votre serveur, jamais depuis un navigateur ni une application mobile. Qui l'obtient peut imprimer chez tous vos clients. Gardez-le dans vos variables d'environnement, pas dans votre code.

2. Choisir l'imprimante

Chaque imprimante a un identifiant, le printer_id. Vous l'obtenez une fois et le conservez - il ne change pas tant que l'imprimante n'est pas réinstallée.

curl https://api.printaya.com/api/v1/printers \
  -H "Authorization: Bearer $PRINTAYA_TOKEN"

# 200 OK
[
  {
    "id": 12,
    "name": "EPSON WF-3820 Series",
    "status": "online",
    "is_default": true,
    "agent": { "id": 4, "name": "POSTE-COMPTOIR" }
  }
]

status vaut online (prête), offline (éteinte, ou injoignable), unverified (vue par le poste, mais son état ne peut pas être vérifié : imprimante USB, ou sans adresse réseau connue) ou unknown (le poste ne la voit plus). Vous pouvez envoyer un document à une imprimante éteinte : il attendra qu'elle revienne. Une imprimante unverified reçoit aussi les documents, mais rien ne garantit qu'elle est allumée : préférez une imprimante online quand vous avez le choix.

3. Envoyer un document

L'envoi se fait en multipart/form-data, puisqu'il porte un fichier. Seuls file et printer_id sont obligatoires.

curl https://api.printaya.com/api/v1/jobs \
  -H "Authorization: Bearer $PRINTAYA_TOKEN" \
  -F file=@facture-2291.pdf \
  -F printer_id=12 \
  -F copies=2 \
  -F idempotency_key=facture-2291

# 201 Created
{
  "id": 4817,
  "status": "queued",
  "printer_id": 12,
  "copies": 2
}

Le même appel en PHP, avec le client HTTP de Laravel :

// Le jeton vient de l'environnement, jamais du code.
$reponse = Http::withToken(config('services.printaya.token'))
    ->attach('file', file_get_contents($chemin), 'facture-2291.pdf')
    ->post('https://api.printaya.com/api/v1/jobs', [
        'printer_id' => 12,
        'copies' => 2,
        // Votre propre référence : elle empêche le double envoi.
        'idempotency_key' => 'facture-2291',
    ]);

$job = $reponse->json();
// Conservez $job['id'] : c'est par lui que vous suivrez l'impression.

Le PDF est accepté jusqu'à 50 Mo. copies va de 1 à 99, color vaut true ou false, et title remplace le nom du fichier dans l'historique.

4. Suivre l'impression

L'envoi rend la main immédiatement : le document est accepté, pas encore imprimé. Interrogez son état avec l'identifiant reçu.

curl https://api.printaya.com/api/v1/jobs/4817 \
  -H "Authorization: Bearer $PRINTAYA_TOKEN"

# 200 OK
"status": "completed"

Les états possibles

Tant qu'un état n'est pas définitif, il peut encore changer. Interrogez toutes les quelques secondes, pas en boucle serrée : une impression prend le temps qu'il faut à l'imprimante.

completed signifie que le spouleur Windows a terminé d'envoyer le document. C'est le signal le plus fiable qu'un système d'impression puisse donner - aucun protocole courant ne permet de savoir qu'une feuille est physiquement sortie du bac.

Le document est supprimé du stockage dès que son état est définitif, y compris to_verify - la date est dans document_purged_at. Gardez donc votre copie : réimprimer, c'est renvoyer le fichier par un nouvel appel à POST /api/v1/jobs.

Ne jamais imprimer deux fois

C'est le point le plus important de cette page. Une feuille sortie ne se rattrape pas. Si votre appel échoue sur une coupure réseau, vous ne savez pas si Printaya l'a reçu - et réessayer risque de sortir le document en double.

D'où idempotency_key : votre propre référence pour ce document. Renvoyez le même appel avec la même clé, et Printaya vous rend le job déjà créé au lieu d'en créer un second.

# Premier appel
-F idempotency_key=facture-2291     → 201 Created, job 4817

# Même appel après une coupure réseau
-F idempotency_key=facture-2291     → 200 OK, job 4817 (le même)

Utilisez une valeur stable et propre à votre métier : un numéro de facture, un identifiant de commande. Pas un horodatage, qui changerait à chaque tentative et annulerait la protection.

Les erreurs