Factures

REST API — Tous les endpoints nécessitent une authentification par Bearer token. Incluez Authorization: Bearer {token} dans chaque requête. Les tokens sont gérés dans Paramètres GitScrum → API. Base URL: https://services.gitscrum.com — Tous les chemins de requête dans cette documentation sont relatifs à cette URL de base.

Créez, gérez et suivez les factures tout au long de leur cycle de vie : brouillon, émission, envoi et marquage comme payée.

Lister les factures

GET /company-invoices?company_slug={slug}

Retourne toutes les factures du workspace.

Paramètres de requête

Réponse

{
  "data": [
    {
      "uuid": "inv-abc-123",
      "title": "January 2026 Services",
      "status": "sent",
      "client": {
        "uuid": "client-abc-123",
        "name": "Acme Corp"
      },
      "due_date": "2026-02-28",
      "currency": "USD",
      "subtotal": 8500,
      "tax": 0,
      "total": 8500,
      "issued_at": "2026-02-01T10:00:00Z",
      "paid_at": null,
      "created_at": "2026-01-28T09:00:00Z"
    }
  ]
}

Obtenir une facture

GET /company-invoices/{uuid}?company_slug={slug}

Retourne les détails complets de la facture incluant les lignes.

Paramètres de chemin

Réponse

{
  "data": {
    "uuid": "inv-abc-123",
    "title": "January 2026 Services",
    "status": "sent",
    "client": {
      "uuid": "client-abc-123",
      "name": "Acme Corp"
    },
    "due_date": "2026-02-28",
    "currency": "USD",
    "subtotal": 8500,
    "tax": 0,
    "total": 8500,
    "items": [
      {
        "description": "Frontend development",
        "quantity": 40,
        "unit_price": 150,
        "total": 6000
      },
      {
        "description": "Code review & QA",
        "quantity": 10,
        "unit_price": 250,
        "total": 2500
      }
    ],
    "issued_at": "2026-02-01T10:00:00Z",
    "paid_at": null,
    "created_at": "2026-01-28T09:00:00Z"
  }
}

Créer une facture

POST /company-invoices

Crée une nouvelle facture en statut brouillon.

Corps de la requête

Chaque élément du tableau items :

Exemple

curl -X POST https://services.gitscrum.com/company-invoices \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "company_slug": "acme",
    "contact_company_uuid": "client-abc-123",
    "title": "February 2026 Services",
    "due_date": "2026-03-31",
    "currency": "USD",
    "items": [
      {
        "description": "Development hours",
        "quantity": 60,
        "unit_price": 150
      }
    ]
  }'

Mettre à jour une facture

PUT /company-invoices/{uuid}

Met à jour une facture existante. Accepte les mêmes champs optionnels que la création plus company_slug.

Paramètres de chemin

Émettre une facture

POST /company-invoices/{uuid}/issue?company_slug={slug}

Change le statut de la facture de draft à issued.

Paramètres de chemin

Envoyer une facture

POST /company-invoices/{uuid}/send?company_slug={slug}

Envoie la facture au client par email.

Paramètres de chemin

Marquer comme payée

POST /company-invoices/{uuid}/paid?company_slug={slug}

Marque la facture comme payée.

Paramètres de chemin

Réponse

{
  "data": {
    "uuid": "inv-abc-123",
    "status": "paid",
    "paid_at": "2026-02-07T14:00:00Z"
  }
}

Supprimer une facture

DELETE /company-invoices/{uuid}?company_slug={slug}

Supprime définitivement une facture.

Paramètres de chemin

Statistiques des factures

GET /company-invoices/stats?company_slug={slug}

Retourne les statistiques des factures du workspace.

Réponse

{
  "data": {
    "total": 45,
    "draft": 3,
    "issued": 2,
    "sent": 8,
    "paid": 32,
    "total_value": 185000,
    "paid_value": 142000
  }
}

Ajouter une ligne

POST /company-invoices/{uuid}/item?company_slug={slug}

Ajoute une ligne à une facture.

Paramètres de chemin

Corps de la requête

Lister les lignes

GET /company-invoices/{uuid}/items?company_slug={slug}

Retourne toutes les lignes d'une facture.

Paramètres de chemin

Supprimer une ligne

DELETE /company-invoices/{uuid}/item/{id}?company_slug={slug}

Supprime une ligne d'une facture.

Paramètres de chemin

Marquer comme remboursée

POST /company-invoices/{uuid}/refunded?company_slug={slug}

Marque la facture comme remboursée.

Paramètres de chemin

Cycle de vie d'une facture

draft → issued → sent → paid

1. Créer — la facture commence en draft
2. Émettre — verrouille la facture, change le statut en issued
3. Envoyer — livre au client, change le statut en sent
4. Marquer comme payée — enregistre le paiement, change le statut en paid

Référence des champs