Créer un client

Commencez par créer un client avec POST /v1/customers. Le SIRET est validé via l'algorithme de Luhn côté serveur. Si le SIRET est connu de l'API Sirene, la raison sociale et l'adresse sont auto-complétées.

SIRET validé Luhn — rejeté si invalide (erreur 422)

Auto-complétion Sirene — raison sociale et adresse pré-remplies

Numéro TVA — vérifié via VIES pour les clients intracommunautaires

$ curl -X POST https://facturino.com/api/v1/customers \
  -H "Authorization: Bearer fac_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Durand & Associés SARL",
    "siret": "00012345500008",
    "vatNumber": "FR31000123455",
    "address": {
      "line1": "15 rue de la Paix",
      "city": "Paris",
      "postalCode": "75002",
      "country": "FR"
    },
    "contacts": [{ "email": "compta@durand-associes.fr" }]
  }'

# Réponse
{
  "id": "cus_8f2k4m9n",
  "name": "Durand & Associés SARL",
  "siret": "00012345500008",
  "vatNumber": "FR31000123455",
  "livemode": false
}

import Facturino from '@facturino/node'

const facturino = new Facturino('fac_test_...')

const customer = await facturino.customers.create({
  name: 'Durand & Associés SARL',
  siret: '00012345500008',
  vatNumber: 'FR31000123455',
  address: {
    line1: '15 rue de la Paix',
    city: 'Paris',
    postalCode: '75002',
    country: 'FR',
  },
  contacts: [{ email: 'compta@durand-associes.fr' }],
})

console.log(customer.id) // cus_8f2k4m9n

from facturino import Facturino

client = Facturino("fac_test_...")

customer = client.customers.create(
    name="Durand & Associés SARL",
    siret="00012345500008",
    vatNumber="FR31000123455",
    address={
        "line1": "15 rue de la Paix",
        "city": "Paris",
        "postalCode": "75002",
        "country": "FR",
    },
    contacts=[{"email": "compta@durand-associes.fr"}],
)

print(customer.id)  # cus_8f2k4m9n

\Facturino\Facturino::setApiKey('fac_test_...');

$customer = \Facturino\Customer::create([
    'name' => 'Durand & Associés SARL',
    'siret' => '00012345500008',
    'vatNumber' => 'FR31000123455',
    'address' => [
        'line1' => '15 rue de la Paix',
        'city' => 'Paris',
        'postalCode' => '75002',
        'country' => 'FR',
    ],
    'contacts' => [['email' => 'compta@durand-associes.fr']],
]);

echo $customer['id']; // cus_8f2k4m9n

import "github.com/facturino/facturino-go"

client := facturino.New("fac_test_...")

customer, _ := client.Customers.Create(
  &facturino.CustomerParams{
    Name:      "Durand & Associés SARL",
    SIRET:     "00012345500008",
    VATNumber: "FR31000123455",
    Address: &facturino.Address{
      Line1:      "15 rue de la Paix",
      City:       "Paris",
      PostalCode: "75002",
      Country:    "FR",
    },
    Contacts: []facturino.Contact{{
      Email: "compta@durand-associes.fr",
    }},
  },
)

fmt.Println(customer.ID) // cus_8f2k4m9n

2

Demander la décision fiscale

Décrivez l'opération avec POST /v1/tax-decisions : Facturino décide la TVA, les montants exacts et les trois obligations de transmission, puis fige le tout dans une décision immuable. Le header Idempotency-Key y est obligatoire.

taxSource: facturino — la TVA est déterminée par Facturino

taxSource: integration — la TVA est fournie par votre intégration ; Facturino la valide et refuse toute contradiction, sans jamais corriger en silence (détail)

amountToCharge — le montant exact à encaisser, décidé côté serveur, quel que soit le moyen de paiement

$ curl -X POST https://facturino.com/api/v1/tax-decisions \
  -H "Authorization: Bearer fac_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: qs-dec-001" \
  -d '{
    "taxSource": "facturino",
    "customerId": "cus_8f2k4m9n",
    "effectiveAt": "2026-09-25",
    "currency": "eur",
    "priceMode": "tax_exclusive",
    "lines": [
      {
        "reference": "conseil",
        "description": "Prestation de conseil",
        "category": "services", "rateCategory": "standard",
        "unitAmount": 150000, "quantity": "1"
      }
    ]
  }'

# Réponse — la TVA, les montants et les trois obligations, décidés et figés
{
  "id": "taxdec_9k2f7p1m",
  "object": "tax_decision",
  "taxSource": "facturino",
  "status": "final",
  "totals": { "totalHT": 150000, "totalVAT": 30000, "totalTTC": 180000 },
  "amountToCharge": 180000,
  "invoiceChannel": "einvoicing",
  "transactionReporting": "none",
  "paymentReporting": "fr212"
}

const decision = await facturino.taxDecisions.create({
  taxSource: 'facturino',
  customerId: 'cus_8f2k4m9n',
  effectiveAt: '2026-09-25',
  currency: 'eur',
  priceMode: 'tax_exclusive',
  lines: [
    {
      reference: 'conseil',
      description: 'Prestation de conseil',
      category: 'services', rateCategory: 'standard',
      unitAmount: 150000, quantity: '1',
    },
  ],
}, { idempotencyKey: 'qs-dec-001' })

// decision.status === 'final' → decision.amountToCharge = 180000 (centimes)

decision = client.tax_decisions.create(
    tax_source="facturino",
    customer_id="cus_8f2k4m9n",
    effective_at="2026-09-25",
    currency="eur",
    price_mode="tax_exclusive",
    lines=[
        {
            "reference": "conseil",
            "description": "Prestation de conseil",
            "category": "services", "rate_category": "standard",
            "unit_amount": 150000, "quantity": "1",
        }
    ],
    idempotency_key="qs-dec-001",
)

# decision["status"] == "final" → decision["amountToCharge"] == 180000

$decision = \Facturino\TaxDecision::create([
    'taxSource' => 'facturino',
    'customerId' => 'cus_8f2k4m9n',
    'effectiveAt' => '2026-09-25',
    'currency' => 'eur',
    'priceMode' => 'tax_exclusive',
    'lines' => [
        [
            'reference' => 'conseil',
            'description' => 'Prestation de conseil',
            'category' => 'services', 'rateCategory' => 'standard',
            'unitAmount' => 150000, 'quantity' => '1',
        ],
    ],
], 'qs-dec-001');

// $decision['status'] === 'final' → $decision['amountToCharge'] === 180000

decision, _ := client.TaxDecisions.Create(&facturino.TaxDecisionParams{
	TaxSource:      "facturino",
	CustomerID:     "cus_8f2k4m9n",
	EffectiveAt:    "2026-09-25",
	Currency:       "eur",
	PriceMode:      "tax_exclusive",
	Lines: []facturino.TaxDecisionLineParams{
		{
			Reference:    "conseil",
			Description:  "Prestation de conseil",
			Category:     "services",
			RateCategory: "standard",
			UnitAmount:   150000,
			Quantity:     "1",
		},
	},
	IdempotencyKey: "qs-dec-001",
})

// decision.IsFinal() → decision.AmountToCharge = 180000 (centimes)

3

Créer la facture depuis la décision

Créez le brouillon avec POST /v1/invoices : taxDecisionId lie la décision, decisionLines ne porte que la présentation (unité, produit catalogue). La TVA, les montants et les mentions viennent de la décision, copiés tels quels.

Une décision, une facture — une décision finale adosse exactement une facture. Pour une nouvelle opération, demandez une nouvelle décision.

Montants en centimes — 180000 = 1 800,00 EUR. Aucun flottant, aucun arrondi ambigu.

Contenu fiscal figé — seuls l'échéance, les conditions, les notes et les métadonnées restent modifiables

Acomptes et échéancier — réglés contre le montant décidé, sans jamais le modifier

$ curl -X POST https://facturino.com/api/v1/invoices \
  -H "Authorization: Bearer fac_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: qs-inv-001" \
  -d '{
    "customerId": "cus_8f2k4m9n",
    "taxDecisionId": "taxdec_9k2f7p1m",
    "decisionLines": [
      { "taxLineRef": "conseil", "unit": "flat_rate" }
    ],
    "buyer": {
      "companyName": "Durand & Associés SARL",
      "siret": "00012345500008",
      "address": { "line1": "15 rue de la Paix", "postalCode": "75002", "city": "Paris", "country": "FR" }
    },
    "dates": { "issued": "2026-09-25", "due": "2026-10-25" },
    "payment": {
      "terms": "30 jours net", "termsDays": 30, "method": "transfer",
      "latePaymentRate": "3 fois le taux légal", "collectionFee": "40.00 EUR"
    },
    "notes": "Merci pour votre confiance."
  }'

# Réponse — la TVA décidée est copiée telle quelle et figée (centimes entiers)
{
  "id": "inv_3p7r2x5q",
  "object": "invoice",
  "status": "draft",
  "taxSource": "facturino",
  "taxDecisionId": "taxdec_9k2f7p1m",
  "totals": {
    "totalHT": 150000,
    "totalVAT": 30000,
    "totalTTC": 180000
  }
}

const invoice = await facturino.invoices.create({
  customerId: 'cus_8f2k4m9n',
  taxDecisionId: decision.id,
  decisionLines: [{ taxLineRef: 'conseil', unit: 'flat_rate' }],
  buyer: {
    companyName: 'Durand & Associés SARL',
    siret: '00012345500008',
    address: { line1: '15 rue de la Paix', postalCode: '75002', city: 'Paris', country: 'FR' },
  },
  dates: { issued: '2026-09-25', due: '2026-10-25' },
  payment: {
    terms: '30 jours net', termsDays: 30, method: 'transfer',
    latePaymentRate: '3 fois le taux légal', collectionFee: '40.00 EUR',
  },
})

invoice = client.invoices.create(
    customer_id="cus_8f2k4m9n",
    tax_decision_id=decision["id"],
    decision_lines=[{"tax_line_ref": "conseil", "unit": "flat_rate"}],
    buyer={
        "company_name": "Durand & Associés SARL",
        "siret": "00012345500008",
        "address": {"line1": "15 rue de la Paix", "postal_code": "75002", "city": "Paris", "country": "FR"},
    },
    dates={"issued": "2026-09-25", "due": "2026-10-25"},
    payment={
        "terms": "30 jours net", "terms_days": 30, "method": "transfer",
        "late_payment_rate": "3 fois le taux légal", "collection_fee": "40.00 EUR",
    },
)

$invoice = \Facturino\Invoice::create([
    'customerId' => 'cus_8f2k4m9n',
    'taxDecisionId' => $decision['id'],
    'decisionLines' => [
        ['taxLineRef' => 'conseil', 'unit' => 'flat_rate'],
    ],
    'buyer' => [
        'companyName' => 'Durand & Associés SARL',
        'siret' => '00012345500008',
        'address' => ['line1' => '15 rue de la Paix', 'postalCode' => '75002', 'city' => 'Paris', 'country' => 'FR'],
    ],
    'dates' => ['issued' => '2026-09-25', 'due' => '2026-10-25'],
    'payment' => [
        'terms' => '30 jours net', 'termsDays' => 30, 'method' => 'transfer',
        'latePaymentRate' => '3 fois le taux légal', 'collectionFee' => '40.00 EUR',
    ],
]);

invoice, _ := client.Invoices.Create(&facturino.InvoiceParams{
	CustomerID:    "cus_8f2k4m9n",
	TaxDecisionID: decision.ID,
	DecisionLines: []facturino.DecisionLineParams{
		{TaxLineRef: "conseil", Unit: "flat_rate"},
	},
	Buyer: &facturino.BuyerParams{
		CompanyName: "Durand & Associés SARL",
		SIRET:       "00012345500008",
		Address:     &facturino.AddressParams{Line1: "15 rue de la Paix", PostalCode: "75002", City: "Paris", Country: "FR"},
	},
	Dates:   &facturino.InvoiceDatesParams{Issued: "2026-09-25", Due: "2026-10-25"},
	Payment: &facturino.PaymentTermsParams{Terms: "30 jours net", TermsDays: 30, Method: "transfer", LatePaymentRate: "3 fois le taux légal", CollectionFee: "40.00 EUR"},
})

4

Finaliser la facture

Appelez POST /v1/invoices/:id/finalize pour verrouiller la facture. Un numéro séquentiel définitif est attribué (ex: FAC2026-00001) et un hash SHA-256 est calculé pour la chaîne d'archivage.

La finalisation est irréversible. Une facture finalisée ne peut plus être modifiée. Pour corriger une erreur, vous devrez émettre un avoir (POST /v1/credit-notes).

Numéro définitif — séquentiel, sans trou (transaction atomique)

Hash SHA-256 — intégrité vérifiable via /verify

Mentions légales — auto-générées selon CGI et régime TVA

$ curl -X POST https://facturino.com/api/v1/invoices/inv_3p7r2x5q/finalize \
  -H "Authorization: Bearer fac_test_..."

# Réponse
{
  "id": "inv_3p7r2x5q",
  "status": "finalized",
  "number": "FAC2026-00001",
  "totals": {
    "totalHT": 207000,
    "totalVAT": 41400,
    "totalTTC": 248400
  },
  // La chaîne de hash d'archivage est scellée à la génération du
  // Factur-X (étape suivante) ; vérifiable ensuite via GET /invoices/:id/verify
  "dates": {
    "issued": "2026-03-24T14:30:00Z",
    "due": "2026-04-30T00:00:00Z"
  }
}

const finalized = await facturino.invoices.finalize(invoice.id)

console.log(finalized.status)       // finalized
console.log(finalized.number)       // FAC2026-00001 (numéro légal attribué)

finalized = client.invoices.finalize(invoice.id)

print(finalized.status)        # finalized
print(finalized.number)        # FAC2026-00001 (numéro légal attribué)

$finalized = \Facturino\Invoice::finalize($invoice['id']);

echo $finalized['status'];               // finalized
echo $finalized['number'];               // FAC2026-00001 (numéro légal attribué)

finalized, _ := client.Invoices.Finalize(invoice.ID)

fmt.Println(finalized.Status)       // finalized
fmt.Println(finalized.Number)       // FAC2026-00001 (numéro légal attribué)

5

Envoyer via la PA

Transmettez la facture à votre destinataire via POST /v1/invoices/:id/send. Facturino transmet la facture à la PA connectée par le client — un connecteur dédié (Super PDP, Iopole, B2Brouter, Seqino) ou le connecteur générique AFNOR pour toute autre PA, configuré côté interface. Vous pouvez aussi télécharger la facture (GET /v1/invoices/:id/facturx) pour dépôt manuel. Les changements de statut sont notifiés en temps réel via webhooks.

En mode sandbox (fac_test_), l'envoi est simulé. Aucune facture n'est transmise à une PA réelle. Utilisez /v1/sandbox/simulate-status pour tester les transitions de statut.

14 statuts DGFiP — de deposited à paid, en temps réel

Webhooks — invoice.status.* à chaque transition

Exactly-once — idempotency key PA pour éviter les doublons

$ curl -X POST https://facturino.com/api/v1/invoices/inv_3p7r2x5q/send \
  -H "Authorization: Bearer fac_test_..."

# Réponse 202 — envoi en cours
{
  "id": "inv_3p7r2x5q",
  "object": "invoice",
  "status": "sending"
}

# Suivre le statut PA via GET /status
$ curl https://facturino.com/api/v1/invoices/inv_3p7r2x5q/status \
  -H "Authorization: Bearer fac_test_..."

{
  "status": "deposited",
  "einvoicing": {
    "paStatus": "deposited",
    "paId": "42"
  },
  "dates": {
    "due": "2026-04-30",
    "finalizedAt": "2026-03-25T10:00:00Z"
  }
}

const sent = await facturino.invoices.send(invoice.id)
console.log(sent.status) // "sending"

// Suivre le statut PA (webhook ou polling)
const status = await facturino.invoices.getStatus(invoice.id)
console.log(status.status)             // "deposited"
console.log(status.einvoicing.paId)    // "42"

sent = client.invoices.send(invoice.id)
print(sent.status)  # "sending"

# Suivre le statut PA (webhook ou polling)
status = client.invoices.get_status(invoice.id)
print(status.status)              # "deposited"
print(status.einvoicing.paId)    # "42"

$sent = \Facturino\Invoice::send($invoice['id']);
echo $sent['status']; // "sending"

// Suivre le statut PA (webhook ou polling)
$status = \Facturino\Invoice::getStatus($invoice['id']);
echo $status['status'];                          // "deposited"
echo $status['einvoicing']['paId'];   // "42"

sent, _ := client.Invoices.Send(invoice.ID)
fmt.Println(sent.Status) // "sending"

// Suivre le statut PA (webhook ou polling)
status, _ := client.Invoices.GetStatus(invoice.ID)
fmt.Println(status.Status)            // "deposited"
fmt.Println(status.Einvoicing.PAID)   // "42"

6

Télécharger le Factur-X

Récupérez le Factur-X avec GET /v1/invoices/:id/facturx. Le fichier est un PDF/A-3b avec le XML CII D22B intégré en pièce jointe. Profil EN 16931, validation Schematron CIUS-FR automatique, métadonnées XMP conformes.

PDF/A-3b — archivable, lisible par tout lecteur PDF

XML CII intégré — factur-x.xml, AFRelationship "Alternative"

Profil EN 16931 — conforme CIUS-FR, ZUGFeRD 2.4

Aussi disponible — /pdf et /xml séparément

# 1. Recuperer l'URL signee (JSON, pas le binaire)
$ curl https://facturino.com/api/v1/invoices/inv_3p7r2x5q/facturx \
  -H "Authorization: Bearer fac_test_..."

# 200 -> fichier pret :
{ "object": "file_url", "url": "https://storage.../facture.pdf?...", "expires_in": 900 }
# 202 -> generation en cours : { "object": "job", "id": "job_...", "status": "pending" }
#        (repoller l'endpoint jusqu'a recevoir "file_url")

# 2. Telecharger le PDF/A-3b depuis l'URL signee (valide 15 min)
$ curl -o facture-FAC2026-00001.pdf "https://storage.../facture.pdf?..."

# PDF/A-3b avec XML CII integre, profil EN16931, CIUS-FR
# Metadata XMP : conformance "B", factur-x.xml

const facturx = await facturino.invoices.getFacturx(invoice.id)

// URL de telechargement signee (valide 1h)
console.log(facturx.url)

// Ou sauvegarder directement
const fs = await import('fs/promises')
const response = await fetch(facturx.url)
const buffer = Buffer.from(await response.arrayBuffer())
await fs.writeFile('facture.pdf', buffer)

facturx = client.invoices.get_facturx(invoice.id)

# URL de telechargement signee (valide 1h)
print(facturx.url)

# Ou sauvegarder directement
import requests
response = requests.get(facturx.url)
with open("facture.pdf", "wb") as f:
    f.write(response.content)

$facturx = \Facturino\Invoice::getFacturx($invoice['id']);

// URL de telechargement signee (valide 1h)
echo $facturx['url'];

// Ou sauvegarder directement
$content = file_get_contents($facturx['url']);
file_put_contents('facture.pdf', $content);

fx, _ := client.Invoices.GetFacturX(invoice.ID)

// URL de telechargement signee (valide 1h)
fmt.Println(fx.URL)

// Ou sauvegarder directement
resp, _ := http.Get(fx.URL)
defer resp.Body.Close()
data, _ := io.ReadAll(resp.Body)
os.WriteFile("facture.pdf", data, 0644)

Concepts clés

Les conventions essentielles de l'API Facturino pour bien démarrer.

Montants en centimes

Tous les montants sont des entiers en centimes d'euros. 150000 = 1 500,00 EUR. Aucun flottant, aucune perte de précision.

TVA en centièmes de pourcent

Les taux sont en centièmes de pourcent. 2000 = 20,00 %, 550 = 5,50 %. Arrondi conforme EN 16931, au plus proche.

Cycle de vie (14 statuts)

De draft à paid, en passant par deposited, transmitted et approved. Transitions validées côté serveur.

Mode test vs mode live

Préfixe fac_test_ pour le sandbox (données isolées, aucun envoi réel). Préfixe fac_live_ pour la production. Les environnements sont strictement cloisonnés.

Idempotency keys

Header Idempotency-Key sur les POST. Même clé = même résultat pendant 24h. Indispensable pour les retries réseau.

Format d'erreurs structuré

Chaque erreur contient type, code, message, doc_url et hint.

Tableau de conversion rapide

Champ	Valeur API	Affichage	Convention
unitPrice	65000	650,00 EUR	Centimes
vatRate	2000	20,00 %	Centièmes %
vatRate	550	5,50 %	Centièmes %
discountPercent	500	5,00 %	Centièmes %
totalTTC	248400	2 484,00 EUR	Centimes

Arrondi : chaque ligne est arrondie à 2 décimales (mode demi-vers-le-haut, le 0,5 monte), puis les lignes sont sommées. Conforme à la norme EN 16931.

Récapitulatif du flux

Les 6 étapes en un coup d'oeil, avec les endpoints et statuts correspondants.

1 Client

2 draft

3 items

4 finalized

5 sending

6 PDF

Étape	Méthode	Endpoint	Résultat
1. Client	POST	/v1/customers	cus_xxx créé
2. Décision	POST	/v1/tax-decisions	TVA + montants + obligations figés
3. Facture	POST	/v1/invoices	status: draft, TVA figée
4. Finaliser	POST	/v1/invoices/:id/finalize	number + hash
5. Envoyer	POST	/v1/invoices/:id/send	status: sending
6. Factur-X	GET	/v1/invoices/:id/facturx	PDF/A-3 + XML

Factur-X

PDF/A-3b + XML CII

CII D22B

Cross-Industry Invoice

UBL 2.1

Universal Business Language

PDF

PDF classique lisible

Et après ?

Votre première facture est envoyée. Voici les prochaines étapes pour aller plus loin.

Prêt à facturer en règle ?

Créez votre compte, obtenez une clé API test et envoyez votre première facture conforme en quelques minutes. Plan gratuit sans carte bancaire.

Créer un compte gratuit Référence API

Besoin d'aide ? Contacter le support

Votre première facture
en 5 minutes

Prérequis

Créer un client

Demander la décision fiscale

Créer la facture depuis la décision

Finaliser la facture

Envoyer via la PA

Télécharger le Factur-X

Concepts clés

Montants en centimes

TVA en centièmes de pourcent

Cycle de vie (14 statuts)

Mode test vs mode live

Idempotency keys

Format d'erreurs structuré

Tableau de conversion rapide

Récapitulatif du flux

Et après ?

Exemples Factur-X

Référence API interactive

SDKs officiels

Webhooks et événements

Devis et avoirs

Sandbox et simulation

Format Factur-X

Prêt à facturer en règle ?

Votre première facture en 5 minutes

Prérequis

Créer un client

Demander la décision fiscale

Créer la facture depuis la décision

Finaliser la facture

Envoyer via la PA

Télécharger le Factur-X

Concepts clés

Montants en centimes

TVA en centièmes de pourcent

Cycle de vie (14 statuts)

Mode test vs mode live

Idempotency keys

Format d'erreurs structuré

Tableau de conversion rapide

Récapitulatif du flux

Et après ?

Exemples Factur-X

Référence API interactive

SDKs officiels

Webhooks et événements

Devis et avoirs

Sandbox et simulation

Format Factur-X

Prêt à facturer en règle ?

Votre première facture
en 5 minutes