Retour au blog
Développeurs 6 min de lecture

SDKs Node.js, Python, PHP, Go : démarrage rapide

L'API REST Facturino est accessible depuis n'importe quel langage via HTTP. Mais pour une intégration plus rapide et plus confortable, nous proposons 4 SDKs officiels qui encapsulent l'authentification, la sérialisation, la gestion d'erreurs et les retries automatiques.

Installation

Une seule commande suffit pour chaque langage :

Node.js / TypeScript (>= 18 LTS)

npm install @facturino/node

Python (>= 3.9)

pip install facturino

PHP (>= 8.1)

composer require facturino/facturino-php

Go (>= 1.21)

go get github.com/facturino/facturino-go

Node.js / TypeScript

Le SDK Node.js est le plus complet. Il fournit un typage TypeScript intégral, des itérateurs de pagination et une gestion automatique des retries. 

import Facturino from '@facturino/node';

const facturino = new Facturino('fac_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx');

// Créer un client
const customer = await facturino.customers.create({
  type: 'company',
  name: 'Acme SAS',
  siret: '73282932000074',
  email: 'comptabilite@acme.fr',
  address: {
    line1: '15 rue de la Paix',
    city: 'Paris',
    postalCode: '75002',
    country: 'FR'
  }
});

// Créer et finaliser une facture
const invoice = await facturino.invoices.create({
  customerId: customer.id,
  buyer: {
    companyName: 'Acme SAS',
    siret: '73282932000074',
    address: {
      line1: '15 rue de la Paix',
      city: 'Paris',
      postalCode: '75002',
      country: 'FR'
    }
  },
  dates: { issued: '2026-05-05', due: '2026-06-05' },
  payment: {
    terms: 'Paiement à 30 jours',
    termsDays: 30,
    method: 'transfer',
    latePaymentRate: '10.00',
    collectionFee: '40.00'
  },
  lines: [
    {
      description: 'Développement module API',
      quantity: '3',
      unit: 'day',
      unitPrice: 75000,   // 750,00 EUR
      vatRate: 2000,      // 20 %
      vatCode: 'S'
    }
  ]
});

await facturino.invoices.finalize(invoice.id);

// Récupérer l'URL de téléchargement du Factur-X
const pdf = await facturino.invoices.getPdf(invoice.id);
console.log(pdf.url);  // URL signée du PDF/A-3b

Python

Le SDK Python est idiomatique, avec des dataclasses typées et une API synchrone et asynchrone (via asyncio). 

import facturino

client = facturino.Client("fac_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx")

# Créer un client
customer = client.customers.create(
    type="company",
    name="Acme SAS",
    siret="73282932000074",
    email="comptabilite@acme.fr",
    address={
        "line1": "15 rue de la Paix",
        "city": "Paris",
        "postalCode": "75002",
        "country": "FR"
    }
)

# Créer, finaliser et récupérer le PDF
invoice = client.invoices.create(
    customerId=customer["id"],
    buyer={
        "companyName": "Acme SAS",
        "siret": "73282932000074",
        "address": {
            "line1": "15 rue de la Paix",
            "city": "Paris",
            "postalCode": "75002",
            "country": "FR"
        }
    },
    dates={"issued": "2026-05-05", "due": "2026-06-05"},
    payment={
        "terms": "Paiement à 30 jours",
        "termsDays": 30,
        "method": "transfer",
        "latePaymentRate": "10.00",
        "collectionFee": "40.00"
    },
    lines=[{
        "description": "Audit sécurité",
        "quantity": "1",
        "unit": "flat_rate",
        "unitPrice": 350000,
        "vatRate": 2000,
        "vatCode": "S"
    }]
)

client.invoices.finalize(invoice["id"])
pdf = client.invoices.get_pdf(invoice["id"])
print(pdf["url"])  # URL signée du PDF/A-3b

PHP

Le SDK PHP suit les conventions PSR-4 et PSR-18 (HTTP client). Il s'intègre naturellement avec Laravel, Symfony ou tout projet PHP moderne. 

<?php
require 'vendor/autoload.php';

\Facturino\Facturino::setApiKey('fac_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx');

// Créer un client
$customer = \Facturino\Customer::create([
    'type' => 'company',
    'name' => 'Acme SAS',
    'siret' => '73282932000074',
    'email' => 'comptabilite@acme.fr',
    'address' => [
        'line1' => '15 rue de la Paix',
        'city' => 'Paris',
        'postalCode' => '75002',
        'country' => 'FR'
    ]
]);

// Créer, finaliser et récupérer le PDF
$invoice = \Facturino\Invoice::create([
    'customerId' => $customer['id'],
    'buyer' => [
        'companyName' => 'Acme SAS',
        'siret' => '73282932000074',
        'address' => [
            'line1' => '15 rue de la Paix',
            'city' => 'Paris',
            'postalCode' => '75002',
            'country' => 'FR'
        ]
    ],
    'dates' => ['issued' => '2026-05-05', 'due' => '2026-06-05'],
    'payment' => [
        'terms' => 'Paiement à 30 jours',
        'termsDays' => 30,
        'method' => 'transfer',
        'latePaymentRate' => '10.00',
        'collectionFee' => '40.00'
    ],
    'lines' => [[
        'description' => 'Maintenance serveur',
        'quantity' => '1',
        'unit' => 'month',
        'unitPrice' => 45000,
        'vatRate' => 2000,
        'vatCode' => 'S'
    ]]
]);

\Facturino\Invoice::finalize($invoice['id']);
$pdf = \Facturino\Invoice::getPdf($invoice['id']);
echo $pdf['url'];

Go

Le SDK Go est fortement typé avec des structs pour chaque ressource. Il s'initialise avec facturino.New(apiKey) et utilise le pattern functional options pour la configuration (par exemple facturino.WithBaseURL(...)). 

package main

import (
    "fmt"
    facturino "github.com/facturino/facturino-go"
)

func main() {
    client := facturino.New("fac_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx")

    // Créer un client
    customer, _ := client.Customers.Create(&facturino.CustomerParams{
        Type:  "company",
        Name:  "Acme SAS",
        SIRET: "73282932000074",
        Email: "comptabilite@acme.fr",
        Address: &facturino.Address{
            Line1:      "15 rue de la Paix",
            City:       "Paris",
            PostalCode: "75002",
            Country:    "FR",
        },
    })

    // Créer, finaliser et récupérer le PDF
    invoice, _ := client.Invoices.Create(&facturino.InvoiceParams{
        Customer: customer.ID,
        Buyer: &facturino.BuyerParams{
            CompanyName: "Acme SAS",
            Siret:       "73282932000074",
            Address: &facturino.Address{
                Line1:      "15 rue de la Paix",
                City:       "Paris",
                PostalCode: "75002",
                Country:    "FR",
            },
        },
        Dates: &facturino.InvoiceDatesParams{Issued: "2026-05-05", Due: "2026-06-05"},
        Payment: &facturino.PaymentTermsParams{
            Terms:           "Paiement à 30 jours",
            TermsDays:       30,
            Method:          "transfer",
            LatePaymentRate: "10.00",
            CollectionFee:   "40.00",
        },
        Items: []*facturino.ItemParams{{
            Description: "Consulting DevOps",
            Quantity:    "5",
            Unit:        "day",
            UnitPrice:   80000,
            VATRate:     2000,
            VATCode:     "S",
        }},
    })

    client.Invoices.Finalize(invoice.ID)
    pdf, _ := client.Invoices.GetPDF(invoice.ID)
    fmt.Println(pdf.URL) // URL signée du PDF/A-3b
}

Fonctionnalités communes

Les quatre SDKs partagent les mêmes capacités :

Fonctionnalité Description
Typage complet Types natifs dans chaque langage (TypeScript, type hints Python, PHPDoc, structs Go)
Authentification automatique Le header Authorization est ajouté à chaque requête
Retries automatiques Backoff exponentiel sur les erreurs 5xx (3 tentatives par défaut)
Itérateurs de pagination Parcourez toutes les pages sans gérer les curseurs manuellement
Mode sandbox Utilisez une clé fac_test_ — le SDK détecte l'environnement automatiquement
Gestion d'erreurs Exceptions/erreurs typées avec code, message, paramètre et lien vers la doc

Pagination automatique

Parcourir toute une collection sans se soucier des curseurs : 

// Node.js — itérateur automatique
for await (const invoice of facturino.invoices.list({ limit: 100 })) {
  console.log(invoice.number, invoice.status);
}

# Python — itérateur automatique
for invoice in client.invoices.list(limit=100):
    print(invoice.number, invoice.status)

Gestion d'erreurs typées

// Node.js
import Facturino, { ValidationError } from '@facturino/node';

try {
  await facturino.invoices.finalize('inv_invalid');
} catch (err) {
  if (err instanceof ValidationError) {
    console.log(err.code);    // "missing_required_field"
    console.log(err.param);   // "buyer.siret"
    console.log(err.docUrl);  // lien vers la documentation
  }
}

Écrits à la main, alignés sur l'API

Les SDKs sont écrits à la main pour offrir une ergonomie idiomatique dans chaque langage (typage, conventions de nommage, gestion d'erreurs). Ils sont maintenus en phase avec l'API REST et sa spécification OpenAPI 3.1 (GET /v1/openapi.json), qui reste la source de vérité pour tous les champs et endpoints.

Prochains SDKs

Quatre SDKs supplémentaires sont prévus pour les prochaines versions :

  • Ruby (gem facturino)
  • Java (Maven : com.facturino:facturino-java)
  • .NET (NuGet : Facturino)
  • Rust (crates.io : facturino)

En attendant, l'API REST est accessible directement depuis n'importe quel langage via HTTP.

Disponibilité

Les SDKs sont disponibles sur tous les plans, y compris le plan gratuit. Aucune fonctionnalité n'est restreinte par le choix du SDK — la seule différence entre les plans concerne les quotas API et les fonctionnalités métier (webhooks, e-reporting, Stripe Connect...).

Installez le SDK de votre langage, initialisez-le avec votre clé fac_test_, et créez votre première facture conforme en moins de 10 lignes de code.

Prêt à passer à la facturation électronique ?

Créez votre compte Facturino gratuitement et commencez à émettre des factures conformes en quelques minutes.

Essai gratuit Voir la documentation

Articles connexes

Qu'est-ce que la facturation électronique obligatoire ? 8 min de lecture Calendrier 2026-2027 : les dates clés 6 min de lecture Les 30 mentions obligatoires d'une facture 10 min de lecture
Tous les articles