Integration Best Practices with the Fatoora Platform

This guide is aimed at developers and technical integration teams connecting their systems to the Fatoora platform as part of e-invoicing in Saudi Arabia. Its single topic: the engineering best practices that make your integration with the Fatoora platform’s APIs secure, stable, and maintainable over the long term. We do not explain here how to build a single request, but how to build a complete integration system that does not collapse at the first spike or the first authority update.

In this guide we wrote down what we learned from running a real integration at the scale of thousands of invoices per day. Every practice here addresses a common mistake we have seen in real integrations. We link each section to its detailed guide among the sibling guides, so you start here as a general map and then go deeper where you need to.

We assume you already know the connection basics: where the Cryptographic Stamp Identifier (CSID) comes from, the difference between the sandbox and production environments, and that the platform uses Basic Authentication, not OAuth. If you are not sure about these basics, start with the authentication in the invoicing API guide, then come back here.

The governing idea in everything that follows: the authority’s APIs are not an ordinary third-party service you can retry against without accountability. They are a government gateway with strict rules on identity, issuance, and rate limits. The practices below respect these rules rather than colliding with them.

Why do you even need best practices, not just an integration that works?

Many integration teams build a first version that succeeds in the test environment, then release it to production feeling reassured. After a few weeks the problems begin: an invoice that did not arrive within its time window, an invoice recorded twice, a certificate that expired suddenly on a holiday, or a queue that piled up until it stalled. The problem is not in code that «works», but in code that did not prepare for failure.

Integration with the authority operates in an environment where you do not control every variable. The network drops, the gateway sometimes slows down, rate limits change, certificates expire, and versions evolve. A good integration assumes that each of these things will happen, and builds itself to withstand them rather than collapse.

The real cost of a bad integration is not in development hours, but in invoices that were not reported on time and their consequences before the authority, in nightly diagnostic hours, and in management’s trust in the system. Every practice in this guide buys you peace of mind in production in exchange for a little discipline during the build.

We organized the practices into four layers that build on one another: security, then reliability, then visibility, then validity before sending. Start from security because it is an irreversible foundation, then move up. Any layer you skip reveals its gap later in production, often at the worst time.

Credential security: protecting the CSID certificate

The most dangerous asset in your integration is the Cryptographic Stamp Identifier (CSID) and its accompanying secret. This data is static and does not expire automatically before the certificate is renewed, unlike the short-lived access token in OAuth. Leaking it means anyone can impersonate your organization on the authority’s gateway for a long time. Therefore treat it with stricter rigor than any other secret in your system.

The first rule: never write credentials in the code at all. Not in a source file, nor in a config file pushed to the code repository, nor in an environment variable exposed in deployment logs. Store them in a dedicated encrypted secrets store, and read them only at runtime.

The second rule: fully separate credentials across environments. The Compliance CSID for testing, and the production certificate (PCSID) for live operation, each with a different identifier and secret. Mixing data between the two environments is a very common cause of a 401 status code in production.

The third rule: have a plan to reissue the certificate. On any suspicion of a leak, or when an employee with access leaves, or as expiry approaches, reissue the certificate immediately. Make this process documented and rehearsed, not something you discover in the moment of a crisis.

The fourth rule: apply the principle of least privilege. The service that sends the invoices is the only one that reads the credentials, and no other component needs access to them. The narrower the circle of who reaches the secret, the smaller the risk surface. Do not make the secret available to every service in the system just for convenience.

The fifth rule: monitor the certificate’s validity proactively. The CSID certificate has an expiry date, and its expiry stops your entire integration all at once. Set an automatic alert far enough before expiry to allow renewal without a rush. Discovering the certificate’s expiry from a wave of 401 errors in production is the worst way to find out.

Credential security checklist

[ ] CSID and secret stored in an encrypted secrets store (Vault / KMS / Secrets Manager)
[ ] No credentials whatsoever in the code or in uploaded config files
[ ] Sandbox data fully separated from production data
[ ] Access to the secrets restricted to only the service that needs it
[ ] Automatic alert far enough before the certificate's expiry
[ ] Documented and rehearsed procedure to reissue the certificate on a leak
[ ] Periodic review of the access log to the secrets store

Idempotency: a stable UUID for every invoice

Every invoice you send to the authority carries a unique identifier (UUID). This identifier is not a cosmetic detail; it is the foundation of idempotency in your integration. Idempotency means that sending the same request more than once does not produce a duplicate effect. This property is essential because retrying is a natural part of any network integration.

Imagine the common scenario: you send an invoice, and the connection drops before the response reaches you. You now do not know: did the invoice reach the authority or not? If you resend with a new UUID, the invoice may be recorded twice. If you resend with the same identifier, the gateway recognizes it as the same invoice, so no duplication occurs.

Therefore the rule is clear: generate the invoice’s UUID once when it is created, save it in your database paired with the invoice, and use the same identifier in every send attempt for that invoice. Do not generate a new identifier inside the retry loop. This specific mistake turns a simple network drop into duplicated invoices in the authority’s records.

Link each invoice’s status in your database to its lifecycle: «being created», then «sent», then «accepted» or «rejected». Do not consider the invoice successfully sent until you receive an explicit response saying so. Until the response reaches you, the invoice remains resendable with its stable identifier.

// Correct pattern: generate the identifier once and store it
invoice.uuid = generateUUID();        // once, at creation
saveToDatabase(invoice);              // saved with the invoice

// On every send attempt, use the same stored identifier
function submit(invoice) {
  return fataaraApi.send({
    uuid: invoice.uuid,               // stable across all attempts
    payload: invoice.signedXml
  });
}

To go deeper into how to build the retry loop itself, see the retry logic guide, which explains when to retry and when to stop.

Retry with exponential backoff

Transient network failures are inevitable. The server sometimes responds with a 503, or the connection drops, or the response is delayed. The right practice is not to retry immediately in a tight loop, but to retry with exponential backoff: you increase the wait time between attempts gradually.

Exponential backoff means you wait one second before the second attempt, then two, then four, then eight, and so on. Add to that a small random element (jitter) that prevents all your clients from synchronizing on the same retry moment and hitting the gateway all at once.

The decisive rule: do not retry on every error. Retry only on transient errors (5xx, connection drops, timeouts, and the rate-limit-exceeded code 429). As for client errors (4xx such as 400, 401, and 403), they mean that your request itself is wrong, and resending it as is will fail the same way. Fix the cause; do not repeat the error.

Set a cap on the number of attempts. After the attempts are exhausted, move the invoice to the manual processing queue or the Dead Letter Queue instead of leaving it spinning endlessly. Silent failure is worse than visible failure.

// Exponential backoff with jitter and a maximum number of attempts
async function submitWithRetry(invoice, maxAttempts = 5) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const res = await fataaraApi.send(invoice);
    if (res.ok) return res;

    // client errors are not retried
    if (res.status >= 400 && res.status < 500 && res.status !== 429) {
      throw new ClientError(res);
    }

    const base = Math.min(1000 * 2 ** (attempt - 1), 30000);
    const jitter = Math.random() * 500;
    await sleep(base + jitter);
  }
  moveToManualQueue(invoice);   // after attempts are exhausted
}

If you specifically encounter the 429 status code, you have exceeded the rate limits. See the API rate limits guide to understand how to distribute your requests so you do not hit this ceiling in the first place.

Structured logging without leaking secrets

Logs are your eyes on the integration in production. When an invoice fails at three in the morning, the log alone tells you why. But a bad log becomes a security hole in itself. The right practice: log everything you need for diagnosis, and never log anything sensitive.

Log in a structured format (JSON, for example), not free text. A structured log is searchable, filterable, and supports automatic alerting. Make every log line carry the invoice identifier (UUID), the timestamp, the status code, the request identifier if present, and the attempt number. These fields are enough to trace any invoice's journey from start to finish.

What is never logged? The CSID certificate secret, the full value of the Authorization header, and any private key. So that these values do not leak into the logs by logging the full request, apply redaction to the sensitive fields before writing. The practical rule: if the log appeared on someone's screen, it must not contain anything that allows impersonating your identity.

// A structured log line after redacting sensitive fields
{
  "timestamp": "2026-06-24T03:14:22Z",
  "invoice_uuid": "a1b2c3d4-...-e5f6",
  "attempt": 2,
  "status": 503,
  "request_id": "req_88f1",
  "authorization": "[REDACTED]",   // never log the actual value
  "outcome": "retry_scheduled"
}

Keep the logs long enough for auditing and diagnosis, and restrict access to them. Production logs that reveal your integration's structure are no less sensitive than the credentials themselves.

Monitoring and proactive alerting

Logging tells you what happened after you go looking. Monitoring tells you what is happening now before you go looking. The difference between them is the difference between discovering a failure from a customer complaint, and discovering it from an automatic alert before anyone notices.

Monitor the metrics that reflect the health of the integration, not just the health of the server. The most important are: the send success rate, the average response time, the number of invoices stuck in the retry queue, the rate of 401 errors (which reveals a certificate problem), and the rate of 429 errors (which reveals you are approaching the rate limits).

Set realistic alert thresholds on these metrics. A sudden rise in 401 usually means an expired certificate or wrong credentials. A rise in 429 means you are hitting the gateway faster than allowed. A buildup in the retry queue means a temporary failure has turned into a persistent one. Every alert should lead to a clear action.

Tie every alert to a clear action known to whoever receives it. An alert «401 rate has risen» should come with a first step: check the certificate's validity. An alert «retry queue buildup» comes with: check the gateway's status and review the last logged errors. An alert that does not lead to an action turns over time into noise the team ignores, so it loses all its value.

Separate, in your view, the health of your system from the health of the gateway. Sometimes the fault is on your side (an expired certificate, code building the request wrong), and sometimes it is on the authority's side (the gateway is slow or temporarily down). Distinguishing between them saves you hours of diagnosis in the wrong direction. Always log whether the error was on your side or an explicit response from the gateway.

The goal of monitoring is not to collect pretty dashboards, but to shorten the time between a problem occurring and you knowing about it. Every minute of difference here may mean an invoice that did not reach the authority within its time window.

Processing via a queue, not a direct request

The most common architectural mistake is sending the invoice to the authority at the very moment the user clicks the save button, synchronously. This pattern ties the user experience to the health of the gateway: if the authority slows down, the user's screen freezes, and if the gateway goes down, the operation fails in front of them directly.

The sturdier practice: separate creating the invoice from sending it. On save, store the invoice with a «pending send» status and give the user immediate confirmation. Then an independent background service takes over pulling invoices from the queue and sending them to the authority at its own pace, with retries on failure. This way the user feels no slowdown in the gateway.

This separation also gives you control over the pace. The background service can distribute requests to stay under the rate limits, batch invoices at peak, automatically pause when it detects the gateway is down, then resume when it returns. A direct synchronous request deprives you of all this control.

Provide a path to review stuck invoices. Every invoice that has exhausted its attempts or exceeded an expected time should surface to a specific team that intervenes manually. A queue that swallows invoices without exposing the stuck ones is a queue that hides problems instead of solving them.

Comprehensive testing in the sandbox environment

The sandbox environment is not a formal step you pass through quickly before production. It is the only place where you discover your integration's problems without costing you a real invoice before the authority. The right practice: do not move to production before you test every document type and every error path in the sandbox.

Test all document types, not just the ordinary invoice. The B2B tax invoice that requires Clearance before delivery to the buyer. The simplified tax invoice (B2C) that is Reported within twenty-four hours. And the credit note and the debit note. Each type has its own path, and testing one of them does not guarantee the rest.

Test the error paths as you test the success path. Send a document with missing fields to see how the gateway rejects it. Try wrong credentials to see the 401 response. Deliberately exceed the rate limit to see 429. An integration that has not been tested for failure will collapse at the first real failure.

Remember that the sandbox environment's data is completely separate from production. You pass compliance in the sandbox and obtain a test certificate, then you request the production certificate with its different data. Do not move one environment's data to another. Environment setup details are in the sandbox for developers.

Validate before submit

Every request you send to the authority consumes from the rate limit, increases your chance of hitting a 429, and slows down your queue processing. Therefore the cheapest error is the one you catch before sending. Validate the document locally first, and send only what you expect to be accepted.

Check the completeness of the mandatory fields, the validity of the tax number, the correctness of the XML file structure and its conformance to the required schema, that the signature is built correctly, and that the UUID is present. These are quick local checks that cost no network request, yet they stop dozens of errors before they reach the gateway.

Pre-validation turns gateway errors (which cost a full network round trip and consume rate limit) into immediate, cheap local errors. Every error you catch before sending is a request you did not waste and a rate limit you did not drain.

Make your local validation match the authority's rules as closely as you can, no less. If the gateway rejects a tax number in a certain format, make your local rule do the same. The closer your local check is to the gateway's check, the fewer surprises you discover late. Update the validation rules whenever you discover a new rejection reason from the gateway, so it does not recur.

Distinguishing warnings from errors

The authority's response may carry warnings alongside errors, and confusing them is a serious integration mistake. An error means the document was rejected and not accepted. A warning means the document was accepted, but there is a note that should be addressed in the future.

The common wrong practice: treating a warning as a failure, so you resend an invoice that was already accepted, causing duplication or confusing your internal state. Or the opposite: ignoring real errors because your code does not distinguish between the two types, so you think your invoices are accepted when they are rejected.

Read the response structure precisely, and separate in your logic between the list of errors and the list of warnings. An error stops the invoice and calls for a correction. A warning is logged and monitored without stopping the acceptance. For full details on response types and how to read them, see the API error handling.

guide. Accumulate the warnings and monitor their trend over time. A warning that appears once may be transient, but a warning that recurs on every invoice reveals a flaw in the way you build the document that deserves handling before it one day turns into an error that stops acceptance. Treat a recurring warning as technical debt you pay off early, not a note you ignore.

Set the response language to Arabic via the Accept-Language header with the value ar when your team is Arabic. Clear error and warning messages in the team's language shorten diagnosis time, so you do not translate or guess the meaning of a message in a language whoever handles the problem does not read.

// Separate warnings from errors in your logic
const res = await fataaraApi.send(invoice);

if (res.errors && res.errors.length > 0) {
  invoice.status = "rejected";       // invoice rejected, fix and rebuild
  logErrors(invoice.uuid, res.errors);
} else {
  invoice.status = "accepted";       // accepted even if it carried warnings
  if (res.warnings && res.warnings.length > 0) {
    logWarnings(invoice.uuid, res.warnings);  // monitored, does not stop acceptance
  }
}

Pinning the API version (Accept-Version)

The Accept-Version header specifies the API version your integration was built on, and its value for Phase 2 of e-invoicing is V2. Pinning the version explicitly is a fundamental defensive practice: your system stays tied to the version you tested, so it is not suddenly affected by a change in the gateway's behavior when a new version is rolled out.

Omitting this header may lead to the request being rejected, or to a response in an unexpected default version that breaks your parsing of the result. Therefore always send it with an explicit value, and do not let the gateway choose on your behalf.

Make a version upgrade a conscious decision, not a surprise. When the authority announces a new version, test it fully in the sandbox environment, then update the header value, then deploy. A pinned version gives you a time window to transition calmly instead of being forced to adapt suddenly in production.

// Pin the version explicitly in every request
const headers = {
  "Authorization": buildBasicAuth(csid, secret),
  "Accept-Version": "V2",            // do not let the gateway choose
  "Content-Type": "application/json",
  "Accept-Language": "ar"            // error messages in Arabic
};

A summary of best practices in a single list

Gather this list into a pre-launch review of your integration. Every item in it addresses a real failure we have seen in integrations that reached production without adequate preparation:

Security
  [ ] CSID and secret in an encrypted secrets store, not in the code
  [ ] Full separation between sandbox and production data
  [ ] A certificate reissuance plan ready and rehearsed

Reliability
  [ ] A stable UUID per invoice, generated once and stored
  [ ] Retry with exponential backoff, jitter, and a maximum
  [ ] Retry only on transient errors, not on 4xx
  [ ] A manual processing queue for what exhausts its attempts

Visibility
  [ ] Structured logging carrying the UUID, the status, and the attempt number
  [ ] Redacting sensitive fields before any write to the log
  [ ] Monitoring the success rate, 401, 429, and queue length
  [ ] Alerts with realistic thresholds that lead to a clear action

Validity before sending
  [ ] Local validation of the document before any network request
  [ ] Separating warnings from errors in the logic
  [ ] Testing all document types in the sandbox
  [ ] Accept-Version pinned explicitly to V2

A successful integration with the Fatoora platform is not just a request that succeeds once in the test environment. It is a system that withstands thousands of times a day under pressure, failures, and gateway changes. The practices above are the difference between an integration that works today and collapses tomorrow, and an integration you sleep soundly trusting.

Frequently asked questions

Why should I use a stable UUID instead of generating a new one on every attempt?

Because a stable identifier achieves idempotency. If the connection drops before the response arrives and you resend with the same identifier, the gateway recognizes it as the same invoice, so no duplication occurs. Generating a new identifier on every attempt turns a simple drop into duplicated invoices in the authority's records.

Which errors do I retry on, and on which do I stop?

Retry on transient errors: 5xx codes, connection drops, timeouts, and the rate-limit-exceeded code 429. Stop on client errors 4xx (such as 400, 401, and 403) because they mean your request itself is wrong, so resending it as is will fail the same way. Fix the cause instead of repeating the error.

Which fields must never appear in the logs?

The CSID certificate secret, the full value of the Authorization header, and any private key. Apply redaction to these fields before writing. The practical rule: if the log appeared on someone's screen, it must not contain anything that allows impersonating your organization's identity on the gateway.

What is the difference between a warning and an error in the authority's response?

An error means the document was rejected and not accepted, and it calls for a correction and rebuild. A warning means the document was accepted with a note that should be addressed in the future, so it is logged and monitored without stopping acceptance. Confusing them leads either to resending an accepted invoice, or to ignoring a real rejection.

Why do I pin the Accept-Version value explicitly?

Because pinning the version keeps your integration tied to the version you tested (V2 for Phase 2), so it is not suddenly affected by a change in the gateway when a new version is rolled out. Omitting the header may lead to the request being rejected or to a response in an unexpected default version that breaks your parsing of the result.

Why do I validate the invoice locally before sending it to the authority?

Because every request consumes from the rate limit and increases your chance of hitting a 429. Local validation of field completeness, tax number validity, XML structure, and the signature stops dozens of errors before they reach the gateway, turning costly network errors into immediate, cheap local errors.