Référence API

L'API REST Hisab

Authentifiez-vous avec une clé API, créez et finalisez des factures, gérez clients et factures récurrentes. Chaque endpoint ci-dessous est en production.

31endpoints|https://hisab.ma/api/v1

Démarrage

L'API Hisab est une API REST JSON servie en HTTPS. Chaque requête est authentifiée par clé API et limitée à votre organisation.

URL de base

https://hisab.ma/api/v1

L'accès API est inclus dans les offres Professional et Fiduciaire. Comparer les offres

Limites de débit

Les requêtes sont limitées par minute et par clé API. Au-delà, l'API renvoie 429 RATE_LIMIT_EXCEEDED avec un en-tête Retry-After.

Offre	Requêtes	Clés API
Professional	120 req/min	10
Fiduciaire	300 req/min	Illimitées

Chaque réponse indique votre consommation dans ces en-têtes :

headers

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1780750800

Authentification

Les clés API se créent depuis le tableau de bord : Paramètres, puis Clés API. Vous choisissez les permissions à la création, et le secret complet n'est affiché qu'une seule fois.

Envoyez la clé en jeton Bearer dans l'en-tête Authorization :

cURL

curl https://hisab.ma/api/v1/invoices \
  -H "Authorization: Bearer hisab_live_***"

hisab_live_***

Clé de production. Agit sur vos données réelles.

hisab_test_***

Clé de test. Même format, pour vos environnements de staging.

Les clés sont stockées hachées (SHA-256) de notre côté et révocables à tout moment depuis le tableau de bord. Un 401 signifie que la clé est absente, invalide ou révoquée :

401

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Permissions

Chaque clé porte une liste explicite de permissions (scopes). Une requête qui exige une permission absente renvoie 403 FORBIDDEN, avec les permissions requises dans les détails de l'erreur.

invoices:readinvoices:writeinvoices:finalizeinvoices:sendinvoices:paymentinvoices:voidinvoices:exportrecurring:readrecurring:writerecurring:deletecustomers:readcustomers:writecustomers:deleteorganization:readorganization:writewebhooks:readwebhooks:writeorganizations:readorganizations:writeorganizations:archive

À la création d'une clé, le tableau de bord propose trois ensembles (lecture seule, facturation, accès complet), et vous pouvez toujours choisir les permissions une à une.

Pagination

Les endpoints de liste acceptent page et per_page (max 100) et renvoient le bloc pagination dans meta :

JSON

{
  "success": true,
  "data": [ ... ],
  "meta": {
    "pagination": { "total": 128, "page": 1, "perPage": 20, "totalPages": 7 }
  }
}

Erreurs

Toutes les erreurs partagent la même forme : success vaut false, et error porte un code stable, un message lisible et des détails optionnels par champ. Les codes standards :

`VALIDATION_ERROR`	400
`INVALID_JSON`	400
`UNAUTHORIZED`	401
`FORBIDDEN`	403
`API_DISABLED`	403
`SUBSCRIPTION_EXPIRED`	403
`API_TIER_NOT_SUPPORTED`	403
`ORG_HEADER_REQUIRED`	400
`ACCOUNT_KEY_REQUIRED`	403
`ENTITY_CAP_REACHED`	403
`NOT_FOUND`	404
`RATE_LIMIT_EXCEEDED`	429
`INTERNAL_ERROR`	500

Webhooks

Hisab signe et envoie un événement à votre endpoint à chaque changement de facture ou de client. Les webhooks se configurent depuis le tableau de bord : Paramètres, puis Webhooks.

invoice.createdinvoice.updatedinvoice.finalizedinvoice.sentinvoice.paidinvoice.voidedcustomer.createdcustomer.updatedcustomer.deleted

Lire le guide des webhooks

Factures

Créez des brouillons, finalisez-les pour obtenir le numéro officiel, puis suivez envoi, paiement et annulation. Les factures finalisées s'exportent en PDF et XML UBL 2.1.

GET/api/v1/invoices

Lister les factures

Renvoie les factures de votre organisation, les plus récentes d'abord. Filtrez par statut, client ou date d'émission.

Permissionsinvoices:read

Paramètres de requête

`page`	integerdefault: 1
`per_page`	integerdefault: 20 (max 100)
`order`	stringdefault: desc `ascdesc`
`status`	string `draftfinalizedsentpaidvoid`
`customer_id`	uuid
`date_from`	date (YYYY-MM-DD)
`date_to`	date (YYYY-MM-DD)

cURL

curl https://hisab.ma/api/v1/invoices \
  -H "Authorization: Bearer hisab_live_***"

GET/api/v1/invoices/:id

Récupérer une facture

Renvoie une facture avec son client, ses lignes et ses totaux.

Permissionsinvoices:read

cURL

curl https://hisab.ma/api/v1/invoices/{id} \
  -H "Authorization: Bearer hisab_live_***"

POST/api/v1/invoices

Créer une facture

Crée un brouillon. Totaux et taxes sont calculés côté serveur à partir des lignes.

Permissionsinvoices:writeinvoice.created

Paramètres du corps

`customer_id`required	uuid
`issue_date`required	date (YYYY-MM-DD)
`due_date`	date (YYYY-MM-DD)
`currency`	stringdefault: MAD
`payment_terms`	string
`notes`	string
`internal_notes`	string
`items[].description`required	string
`items[].quantity`required	number
`items[].unit_price`required	number
`items[].tax_rate`	numberdefault: 20

cURL

curl https://hisab.ma/api/v1/invoices \
  -X POST \
  -H "Authorization: Bearer hisab_live_***" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_2b81fe",
    "issue_date": "2026-06-05",
    "items": [
      {
        "description": "Integration services",
        "quantity": 8,
        "unit_price": 1300,
        "tax_rate": 20
      }
    ]
  }'

PATCH/api/v1/invoices/:id

Modifier une facture

Modifie un brouillon. Les factures finalisées sont immuables ; l'appel renvoie INVOICE_NOT_EDITABLE.

Permissionsinvoices:writeinvoice.updated

Paramètres du corps

`customer_id`	uuid
`issue_date`	date (YYYY-MM-DD)
`due_date`	date (YYYY-MM-DD)
`currency`	string
`payment_terms`	string
`notes`	string
`items[].description`	string
`items[].quantity`	number
`items[].unit_price`	number
`items[].tax_rate`	numberdefault: 20

Erreurs spécifiquesINVOICE_NOT_EDITABLE

cURL

curl https://hisab.ma/api/v1/invoices/{id} \
  -X PATCH \
  -H "Authorization: Bearer hisab_live_***" \
  -H "Content-Type: application/json" \
  -d '{
    "due_date": "2026-08-05"
  }'

POST/api/v1/invoices/:id/finalize

Finaliser une facture

Attribue le numéro séquentiel officiel et verrouille la facture. C'est l'étape d'émission légale.

Permissionsinvoices:finalizeinvoice.finalized

Erreurs spécifiquesINVOICE_NOT_DRAFTVALIDATION_ERROR

cURL

curl https://hisab.ma/api/v1/invoices/{id}/finalize \
  -X POST \
  -H "Authorization: Bearer hisab_live_***"

POST/api/v1/invoices/:id/send

Marquer comme envoyée

Enregistre que la facture finalisée a été transmise au client.

Permissionsinvoices:writeinvoice.sent

Erreurs spécifiquesINVALID_STATUS_TRANSITION

cURL

curl https://hisab.ma/api/v1/invoices/{id}/send \
  -X POST \
  -H "Authorization: Bearer hisab_live_***"

POST/api/v1/invoices/:id/pay

Marquer comme payée

Enregistre un paiement, avec méthode et référence optionnelles.

Permissionsinvoices:writeinvoice.paid

Paramètres du corps

`paid_at`	datetime (ISO 8601)
`payment_method`	string
`payment_reference`	string

Erreurs spécifiquesINVALID_STATUS_TRANSITION

cURL

curl https://hisab.ma/api/v1/invoices/{id}/pay \
  -X POST \
  -H "Authorization: Bearer hisab_live_***" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": "bank_transfer",
    "payment_reference": "VIR-20260605"
  }'

POST/api/v1/invoices/:id/void

Annuler une facture

Annule une facture finalisée avec un motif obligatoire. Une facture payée ne peut pas être annulée.

Permissionsinvoices:writeinvoice.voided

Paramètres du corps

reasonrequired string

Erreurs spécifiquesCANNOT_VOID_PAIDALREADY_VOIDED

cURL

curl https://hisab.ma/api/v1/invoices/{id}/void \
  -X POST \
  -H "Authorization: Bearer hisab_live_***" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Duplicate billing"
  }'

GET/api/v1/invoices/:id/pdf

Télécharger le PDF

Renvoie le PDF validé en français, anglais ou arabe. Disponible une fois la facture finalisée.

Permissionsinvoices:export

Paramètres de requête

locale

stringdefault: fr

frenar

Erreurs spécifiquesPDF_NOT_AVAILABLE

cURL

curl https://hisab.ma/api/v1/invoices/{id}/pdf \
  -H "Authorization: Bearer hisab_live_***"

GET/api/v1/invoices/:id/xml

Télécharger le XML

Renvoie le XML UBL 2.1 de la facture finalisée.

Permissionsinvoices:export

Erreurs spécifiquesXML_NOT_AVAILABLE

cURL

curl https://hisab.ma/api/v1/invoices/{id}/xml \
  -H "Authorization: Bearer hisab_live_***"

Clients

Clients B2B et B2C avec identifiants marocains (ICE, RC). L'archivage préserve l'historique de facturation.

GET/api/v1/customers

Lister les clients

Renvoie les clients, avec recherche sur le nom, l'email et l'ICE.

Permissionscustomers:read

Paramètres de requête

`page`	integerdefault: 1
`per_page`	integerdefault: 20 (max 100)
`order`	stringdefault: desc `ascdesc`
`search`	string
`type`	string `b2bb2c`
`status`	string `activeinactivearchived`

cURL

curl https://hisab.ma/api/v1/customers \
  -H "Authorization: Bearer hisab_live_***"

GET/api/v1/customers/:id

Récupérer un client

Renvoie un client avec ses coordonnées et son adresse.

Permissionscustomers:read

cURL

curl https://hisab.ma/api/v1/customers/{id} \
  -H "Authorization: Bearer hisab_live_***"

POST/api/v1/customers

Créer un client

Les clients B2B doivent porter leur ICE à 15 chiffres. Les doublons d'ICE sont rejetés au sein de votre organisation.

Permissionscustomers:writecustomer.created

Paramètres du corps

`name`required	string
`type`required	string `b2bb2c`
`ice`	string (15 digits)
`legal_name`	string
`rc`	string
`email`	string
`phone`	string
`address.street`	string
`address.city`	string
`address.postal_code`	string
`address.country`	stringdefault: MA
`notes`	string
`tags`	string[]

cURL

curl https://hisab.ma/api/v1/customers \
  -X POST \
  -H "Authorization: Bearer hisab_live_***" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MERIT Sarl",
    "type": "b2b",
    "ice": "001234567000089",
    "email": "compta@example.ma"
  }'

PATCH/api/v1/customers/:id

Modifier un client

Mise à jour partielle : n'envoyez que les champs qui changent.

Permissionscustomers:writecustomer.updated

Paramètres du corps

`name`	string
`type`	string `b2bb2c`
`ice`	string (15 digits)
`email`	string
`phone`	string
`address`	object
`notes`	string
`tags`	string[]
`status`	string `activeinactivearchived`

cURL

curl https://hisab.ma/api/v1/customers/{id} \
  -X PATCH \
  -H "Authorization: Bearer hisab_live_***" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "finance@example.ma"
  }'

DELETE/api/v1/customers/:id

Archiver un client

Suppression douce. Le client est archivé et son historique de factures reste intact.

Permissionscustomers:deletecustomer.deleted

Erreurs spécifiquesALREADY_ARCHIVED

cURL

curl https://hisab.ma/api/v1/customers/{id} \
  -X DELETE \
  -H "Authorization: Bearer hisab_live_***"

Factures récurrentes

Des planifications qui génèrent les factures automatiquement, de hebdomadaire à annuelle, avec finalisation et envoi automatiques optionnels.

GET/api/v1/recurring-invoices

Lister les planifications

Renvoie les planifications de factures récurrentes. Filtrez par statut, client ou fréquence.

Permissionsinvoices:read

Paramètres de requête

`page`	integerdefault: 1
`per_page`	integerdefault: 20 (max 100)
`order`	stringdefault: desc `ascdesc`
`status`	string `activepausedcompletedcancelled`
`customer_id`	uuid
`frequency`	string `weeklybiweeklymonthlyquarterlybiannuallyyearly`
`search`	string

cURL

curl https://hisab.ma/api/v1/recurring-invoices \
  -H "Authorization: Bearer hisab_live_***"

GET/api/v1/recurring-invoices/:id

Récupérer une planification

Renvoie une planification avec son dernier historique de génération.

Permissionsinvoices:read

cURL

curl https://hisab.ma/api/v1/recurring-invoices/{id} \
  -H "Authorization: Bearer hisab_live_***"

POST/api/v1/recurring-invoices

Créer une planification

Définit la fréquence, la date de début et les lignes des futures factures.

Permissionsinvoices:write

Paramètres du corps

`customer_id`required	uuid
`frequency`required	string `weeklybiweeklymonthlyquarterlybiannuallyyearly`
`start_date`required	date (YYYY-MM-DD)
`name`	string
`interval_count`	integer (1-12)default: 1
`day_of_month`	integer (1-28)
`day_of_week`	integer (0-6)
`end_date`	date (YYYY-MM-DD)
`max_occurrences`	integer
`auto_finalize`	booleandefault: false
`auto_send`	booleandefault: false
`days_until_due`	integer (0-365)default: 30
`currency`	stringdefault: MAD
`items[].description`required	string
`items[].quantity`required	number
`items[].unit_price`required	number
`items[].tax_rate`	numberdefault: 20

Erreurs spécifiquesQUOTA_EXCEEDED

cURL

curl https://hisab.ma/api/v1/recurring-invoices \
  -X POST \
  -H "Authorization: Bearer hisab_live_***" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_2b81fe",
    "frequency": "monthly",
    "start_date": "2026-07-01",
    "auto_finalize": true,
    "items": [
      {
        "description": "Monthly retainer",
        "quantity": 1,
        "unit_price": 10400,
        "tax_rate": 20
      }
    ]
  }'

PUT/api/v1/recurring-invoices/:id

Modifier une planification

Ajuste une planification active ou en pause. Les planifications terminées ou annulées sont en lecture seule.

Permissionsinvoices:write

Paramètres du corps

`frequency`	string `weeklybiweeklymonthlyquarterlybiannuallyyearly`
`end_date`	date (YYYY-MM-DD)
`auto_finalize`	boolean
`auto_send`	boolean
`days_until_due`	integer (0-365)
`items`	array

Erreurs spécifiquesINVALID_STATE

cURL

curl https://hisab.ma/api/v1/recurring-invoices/{id} \
  -X PUT \
  -H "Authorization: Bearer hisab_live_***" \
  -H "Content-Type: application/json" \
  -d '{
    "auto_send": true
  }'

DELETE/api/v1/recurring-invoices/:id

Supprimer une planification

Supprime la planification et son historique. Les factures déjà générées ne sont pas affectées.

Permissionsinvoices:write

cURL

curl https://hisab.ma/api/v1/recurring-invoices/{id} \
  -X DELETE \
  -H "Authorization: Bearer hisab_live_***"

POST/api/v1/recurring-invoices/:id/generate

Générer maintenant

Crée la prochaine facture immédiatement, en respectant finalisation et envoi automatiques.

Permissionsinvoices:write

Paramètres du corps

issue_date date (YYYY-MM-DD)default: today

Erreurs spécifiquesINVALID_STATECUSTOMER_INACTIVE

cURL

curl https://hisab.ma/api/v1/recurring-invoices/{id}/generate \
  -X POST \
  -H "Authorization: Bearer hisab_live_***"

GET/api/v1/recurring-invoices/:id/history

Historique de génération

Liste les exécutions passées avec les numéros de factures générées et leur statut.

Permissionsinvoices:read

Paramètres de requête

limit integerdefault: 20 (max 100)

cURL

curl https://hisab.ma/api/v1/recurring-invoices/{id}/history \
  -H "Authorization: Bearer hisab_live_***"

POST/api/v1/recurring-invoices/:id/pause

Mettre en pause

Suspend la génération jusqu'à la reprise de la planification.

Permissionsinvoices:write

Erreurs spécifiquesINVALID_STATE

cURL

curl https://hisab.ma/api/v1/recurring-invoices/{id}/pause \
  -X POST \
  -H "Authorization: Bearer hisab_live_***"

POST/api/v1/recurring-invoices/:id/resume

Reprendre

Relance une planification en pause, éventuellement à partir d'une nouvelle date.

Permissionsinvoices:write

Paramètres du corps

next_run_date date (YYYY-MM-DD)

Erreurs spécifiquesINVALID_STATE

cURL

curl https://hisab.ma/api/v1/recurring-invoices/{id}/resume \
  -X POST \
  -H "Authorization: Bearer hisab_live_***"

Organisation

Le profil de votre organisation, l'état de l'abonnement et les quotas API.

GET/api/v1/organization

Récupérer l'organisation

Renvoie identifiants légaux, coordonnées, abonnement et quotas API.

Permissionsorganization:read

cURL

curl https://hisab.ma/api/v1/organization \
  -H "Authorization: Bearer hisab_live_***"

PATCH/api/v1/organization

Modifier l'organisation

Met à jour identifiants légaux, coordonnées et adresse de facturation.

Permissionsorganization:write

Paramètres du corps

`legal_name`	string
`ice`	string
`rc`	string
`if_number`	string
`vat_number`	string
`phone`	string
`email`	string
`website`	string (URL)
`billing_address`	object

cURL

curl https://hisab.ma/api/v1/organization \
  -X PATCH \
  -H "Authorization: Bearer hisab_live_***" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+212 5 22 00 00 01"
  }'

apiDocsPage.nav.organizations

Gestion des organisations pour les intégrations multi-entités. Ces endpoints exigent une clé de COMPTE (hisab_acct_). Après le provisionnement, opérez chaque entité sur les endpoints habituels en envoyant l'en-tête X-Organization-Id avec la même clé de compte. Un ICE déjà enregistré sur la plateforme ne peut pas être réutilisé, même par un autre compte - il identifie exactement une entité légale.

GET/api/v1/organizations

Lister vos organisations

Retourne toutes les organisations que possède le propriétaire de la clé. Les entités archivées sont exclues sauf include_archived=true.

Permissionsorganizations:read

Paramètres de requête

include_archived booleandefault: false

Erreurs spécifiquesACCOUNT_KEY_REQUIRED

cURL

curl https://hisab.ma/api/v1/organizations \
  -H "Authorization: Bearer hisab_live_***"

POST/api/v1/organizations

Créer une organisation

Provisionne une nouvelle entité légale sous votre compte. Le plafond d'entités de votre forfait s'applique ; contactez le support pour l'augmenter.

Permissionsorganizations:write

Paramètres du corps

`legal_name`required	string
`ice`	string (15 digits)
`rc`	string
`if_number`	string
`phone`	string
`email`	string
`address_street`	string
`address_city`	string
`address_postal_code`	string

Erreurs spécifiquesACCOUNT_KEY_REQUIREDENTITY_CAP_REACHED

cURL

curl https://hisab.ma/api/v1/organizations \
  -X POST \
  -H "Authorization: Bearer hisab_live_***" \
  -H "Content-Type: application/json" \
  -d '{
    "legal_name": "Filiale Casablanca SARL",
    "ice": "002345678000071"
  }'

GET/api/v1/organizations/{id}

Obtenir une organisation

Retourne une organisation possédée. Les identifiants inconnus ou étrangers renvoient 404.

Permissionsorganizations:read

Erreurs spécifiquesACCOUNT_KEY_REQUIRED

cURL

curl https://hisab.ma/api/v1/organizations/{id} \
  -H "Authorization: Bearer hisab_live_***"

POST/api/v1/organizations/{id}/archive

Archiver une organisation

Archive douce : l'entité est gelée partout (API, tableau de bord, crons) mais rien n'est supprimé. Entièrement réversible.

Permissionsorganizations:archive

Erreurs spécifiquesACCOUNT_KEY_REQUIREDALREADY_ARCHIVED

cURL

curl https://hisab.ma/api/v1/organizations/{id}/archive \
  -X POST \
  -H "Authorization: Bearer hisab_live_***"

POST/api/v1/organizations/{id}/restore

Restaurer une organisation

Annule un archivage ; l'entité reprend immédiatement son fonctionnement normal.

Permissionsorganizations:archive

Erreurs spécifiquesACCOUNT_KEY_REQUIREDNOT_ARCHIVED

cURL

curl https://hisab.ma/api/v1/organizations/{id}/restore \
  -X POST \
  -H "Authorization: Bearer hisab_live_***"