Does the API cost extra?

No. The API and webhooks are included in every pack (Starter, Pro, Group) at no extra cost. Only the features of your pack are reachable through the API.

How can I test safely?

Create a free 14-day trial account: it is a separate company where you can create keys, send test invoices and plug your webhooks. Validated invoices are numbered there exactly as in production.

Is there a rate limit?

Yes, a rate limit protects the service; beyond it the API answers 429 and you simply retry a little later. For large volumes (initial sync), batch your calls and use the Excel/CSV import.

What is the difference between read and write keys?

A read key can only look things up. A write key can create and update, within the role chosen for the key (for example accountant or sales).

I run a web agency: how do I integrate SOGESTIO for a client?

Your client creates an API key in their company and gives it to you. You connect their website or shop to the API and, if needed, receive their events by webhook. SOGESTIO stays at the heart of their management: legal invoicing, VAT, stock and accounting.

Do Shopify and WooCommerce shops need the API?

No: SOGESTIO already imports Shopify and WooCommerce orders automatically. The API is for everything else: custom websites, business apps, reporting tools.

Developers & web agencies

The SOGESTIO API

Connect your website, your shop, your business application or your client's tool to SOGESTIO. A documented REST API, per-company API keys, signed webhooks and the same business rules as the app: numbering, VAT, stock and accounting stay handled by SOGESTIO.

API reference (OpenAPI)Create a test account

Per-company API keys

The owner or an administrator creates a key under Integrations, read-only or read-write, with an expiry date. Send it in the Authorization: Bearer header. A key can be revoked at any time and stops working if its creator is deactivated.

OpenAPI 3.1 reference

Every route is described with schemas generated from the server's own validation, so the docs cannot drift from the real behaviour. Amounts in centimes (integers), ISO dates, errors with a stable code.

Signed webhooks

Get an HTTP call when an invoice is validated, a payment recorded or a customer created. Every delivery is signed (HMAC-SHA256 with a timestamp) and retried automatically for about 72 hours on failure.

Idempotency

Send an Idempotency-Key header on your creations: if the call is replayed (network cut, retry), SOGESTIO returns the same result without creating a duplicate.

Isolation and rights

Each key only reaches its own company's data, with the rights of the role chosen for the key. Legal invoice numbers are assigned by the server at validation, never by the integration.

Explicit errors

Every refusal carries a machine-readable code (e.g. invalid_input, amount_mismatch, period_locked) and, for inputs, the field concerned. Paging with page and pageSize (200 max).

Examples

List customers, create an invoice from an order on your website, then verify a webhook signature server-side (PHP).

List customers (curl)

curl https://sogestio.ma/api/customers?pageSize=50 \
  -H "Authorization: Bearer sgk_xxxxxxxxxxxx_votre_secret"

Create a draft invoice (Node.js)

const res = await fetch("https://sogestio.ma/api/invoices", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SOGESTIO_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": order.id, // safe to retry: never creates a duplicate
  },
  body: JSON.stringify({
    kind: "invoice",
    customerId: "c_123",
    customerName: "Supérette Al Baraka",
    issueDate: "2026-10-07",
    currency: "MAD",
    lines: [{ label: "Terminal de caisse", quantity: 1, unitPriceHt: 490000, vatRate: 20 }],
  }),
});
const invoice = await res.json(); // amounts in centimes: 490000 = 4 900,00 DH

Verify a webhook (PHP)

$payload = file_get_contents('php://input');
$header  = $_SERVER['HTTP_X_SOGESTIO_SIGNATURE']; // "t=1760000000,v1=ab12…"
parse_str(str_replace(',', '&', $header), $sig);
$expected = hash_hmac('sha256', $sig['t'] . '.' . $payload, getenv('SOGESTIO_WEBHOOK_SECRET'));
if (!hash_equals($expected, $sig['v1']) || abs(time() - (int)$sig['t']) > 300) {
  http_response_code(400); exit;
}
$event = json_decode($payload, true); // $_SERVER['HTTP_X_SOGESTIO_EVENT'] = "invoice.validated"

Available events

Subscribe an HTTPS URL to one or more events under Integrations. The body holds the object concerned; the X-Sogestio-Event header gives its type.

invoice.validated
creditNote.validated
quote.validated
order.validated
delivery.validated
purchase.validated
payment.created
payment.deleted
customer.created

Frequently asked questions

Does the API cost extra?: No. The API and webhooks are included in every pack (Starter, Pro, Group) at no extra cost. Only the features of your pack are reachable through the API.
How can I test safely?: Create a free 14-day trial account: it is a separate company where you can create keys, send test invoices and plug your webhooks. Validated invoices are numbered there exactly as in production.
Is there a rate limit?: Yes, a rate limit protects the service; beyond it the API answers 429 and you simply retry a little later. For large volumes (initial sync), batch your calls and use the Excel/CSV import.
What is the difference between read and write keys?: A read key can only look things up. A write key can create and update, within the role chosen for the key (for example accountant or sales).
I run a web agency: how do I integrate SOGESTIO for a client?: Your client creates an API key in their company and gives it to you. You connect their website or shop to the API and, if needed, receive their events by webhook. SOGESTIO stays at the heart of their management: legal invoicing, VAT, stock and accounting.
Do Shopify and WooCommerce shops need the API?: No: SOGESTIO already imports Shopify and WooCommerce orders automatically. The API is for everything else: custom websites, business apps, reporting tools.