Morocco E-Invoicing REST API: Overview

Base URL

Versioning

The API is versioned via URL path prefix. The current version is v1.

/v1/invoices

OpenAPI Specification

The complete API contract for public endpoints (invoices and webhooks) is available in OpenAPI 3.1 format. Import it into Postman, Insomnia, or Bruno to explore the API, or generate client SDKs in your language using openapi-generator. Official SDKs are generated from this exact specification.

Authentication

All requests must include your secret API key in the Authorization header:

Authorization: Bearer efact_sk_xxx

The key resolves your organization server-side: no organization ID is ever passed in request bodies. See Authentication for complete details.

Request format

Response format

Every response, whether success or error, uses the same envelope: { code, message, data, errors }. Official SDKs automatically unwrap data and throw typed exceptions on errors.

Success

{
  "code": "OK",
  "message": "Invoice created",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "invoiceNumber": "INV-2026-042",
    "status": "SIGNED",
    "currency": "MAD",
    "amountHt": 12000.00,
    "amountVat": 2400.00,
    "amountTtc": 14400.00,
    "createdAt": "2026-04-07T10:00:00Z"
  },
  "errors": null
}

Error

{
  "code": "VALIDATION_ERROR",
  "message": "Validation failed",
  "data": null,
  "errors": [
    {
      "field": "buyerIce",
      "message": "buyerIce must be exactly 15 digits"
    }
  ]
}

HTTP status codes

Business error codes

The code field in the response envelope provides a machine-readable error code. Key codes:

Idempotency

Idempotency on creation relies on the invoiceNumber, which is unique per organization:

// invoiceNumber is unique per organization: replaying the same
// creation returns 409 INVOICE_NUMBER_EXISTS instead of creating a duplicate.
POST /v1/invoices
{ "invoiceNumber": "INV-2026-042", ... }

If uncertain following a network timeout, replay the request: either it succeeds or you receive 409 INVOICE_NUMBER_EXISTS - meaning the invoice exists and can be queried. SDKs never replay a POST automatically.

Rate limiting

Beyond that, the API returns 429 with a Retry-After header (in seconds). Official SDKs handle this automatically using exponential back-off.

Pagination

List endpoints use zero-based page pagination:

GET /v1/invoices?status=ACCEPTED&page=0&size=20&sort=createdAt,desc

Parameters

Response

{
  "code": "OK",
  "message": "Invoices retrieved",
  "data": {
    "content": [ ... ],
    "page": 0,
    "size": 20,
    "totalElements": 42,
    "totalPages": 3,
    "first": true,
    "last": false
  },
  "errors": null
}

Available endpoints

Frequently asked questions