Generate an invoice PDF via API: the step-by-step tutorial

Step 1 — the API key, with no developer signup

There is no developer console and no manual approval. The merchant opens their Fatora-Bot WhatsApp conversation and writes “api”: the bot replies with their personal key, in the fk_ format followed by 40 characters. That is the key your application stores and passes in the Authorization: Bearer header.

The key is specific to each merchant: it issues in THEIR numbering and only sees THEIR documents. “api reset” rotates it at any time — the old one is revoked immediately. A GET /v1/account is the simplest way to check that a key pasted by the user is valid: it returns the company profile, the plan and the remaining quota.

Step 2 — issue the document

A single call: POST /v1/documents, with the customer’s name (and their ICE in B2B), then the lines — description, quantity, unit price. The API computes VAT line by line, applies the merchant’s tax regime, generates the PDF with logo and stamp, and answers 201 with the assigned number, the net/VAT/gross totals, the PDF link and a QR code URL.

Two options change everyday life. "type": "quote" issues a quote (numbered DEV-, valid 30 days, outside the quota) instead of an invoice. "priceIsTtc": true tells the API your amounts are tax-inclusive: it rebuilds the net base itself — essential when your selling prices are displayed with tax.

To correct an already-issued document, there is no update schema to learn: the modification endpoint accepts a free-text instruction (“replace the training with 3 days at 1200 dh per day”) and applies it on the same number, PDF regenerated, totals recomputed.

Numbering stays continuous: modifying never creates a gap in the sequence, and cancelling goes through a credit note — as Moroccan regulation requires.

Step 3 — deliver the invoice to the customer

Generating the PDF is pointless if the customer never receives it. Three channels are available, at creation ("sendToPhone" and "sendToEmail" fields) or afterwards through the send endpoint:

• WhatsApp: the PDF lands in the customer’s conversation, in the merchant’s name.
• Email: a polished message with the invoice attached.
• QR code: every document exposes a public PNG image — display it at the counter, print it on the receipt, the customer scans and downloads their invoice.

The errors your code should handle

The API always returns a JSON with two fields: "error" (a stable machine code) and "message" (an explanation displayable as-is). Four cases deserve specific handling in your UI: 402 quota reached (the response carries used and limit — display them, the merchant upgrades in two WhatsApp messages), 401 invalid key (often a key rotated by “api reset” — ask for the new one), 422 instruction not understood (offer to rephrase, nothing was modified), and 429 beyond 60 requests per minute (queue and retry).

The full list of codes, each with a sample response, is on the site’s API page — every example there was replayed against the production API.