Integrating your management system, e-commerce and invoicing with APIs: an architecture that lasts

Connecting an online shop to a management system is easy to show in a demo: an order comes in, it appears on the other side. The real work starts when the system's API takes thirty seconds to reply, the webhook arrives twice, a product is renamed, e-invoicing rejects a document and nobody notices for a week. A reliable integration is designed for those cases, not the happy one.

The first decision: the source of truth

Every piece of data needs a single authoritative system. Is stock born in the management system or the shop? Prices? The customer register? Two-way sync on the same field is the main source of conflicts: two systems correcting each other until one wins at random. The rule I follow: every field has an owner, and the other systems read it.

Events, not polling

Querying an API every five minutes to see whether anything changed (polling) is simple but slow, costly and fragile under rate limits. Where systems allow it, I use events: the payment provider, the shop or the management system send a webhook when something happens.

Webhooks must be handled carefully:

• signature verification, to accept only genuine calls;
• immediate response with the work moved to a queue, because senders have short timeouts and retry if they get no reply;
• deduplication, because the same event can arrive more than once;
• ordering is not guaranteed: an update can arrive before the creation, and the code must cope.

Queues, retries and idempotency

Between systems I put a queue. Each message is processed, and if the destination does not respond it is retried with growing delays. After a number of attempts it goes to an error queue, visible and recoverable, with an alert to a person.

Every write is idempotent: it has a unique identifier, and re-running it does not create a second order, a second invoice or a second stock movement. That property is what makes retries safe.

The most common connections

• E-commerce and management system: orders to the system, stock and prices to the shop. Watch out for variants, kits and bundles, where the two systems' models rarely match.
• Electronic invoicing: generating the right document (invoice, receipt, credit note) and handling receipts and rejections from the national exchange system, which must be reported back to the source system.
• Payments: the order status is updated from the provider's webhook, not from the browser returning to the confirmation page, which may never happen.
• Couriers: creating shipments, labels, tracking codes and delivery statuses.
• CRM and newsletter: with care over consent, which follows its own rules.

Mapping and transformations

Each system has its own model: VAT codes, units of measure, variants, addresses, order statuses. The mapping between them must be written, documented and tested with real cases, including awkward ones: deleted products, customers without a VAT number, foreign addresses, partial returns.

Reconciliation and monitoring

Even the best integration will eventually lose a message. That is why I always add periodic reconciliation: a process that compares orders, stock and documents across systems and reports differences. And a dashboard or report with the outcome of each sync, so the first to discover a problem is not a customer.

Security

Dedicated credentials for each integration, with minimum permissions, stored outside the code and rotatable. Encrypted communication, signed webhooks, logs without personal data in clear where it is not needed.

An example: the journey of an order

1. The customer pays. The payment provider sends a signed webhook: the system verifies it, records it with its identifier and responds immediately.
2. A queued process creates the order in the management system with an idempotency key: if the message arrives twice, there is still one order.
3. The management system reduces stock and returns its own order number, which is stored alongside the shop's.
4. The correct tax document is generated; the outcome of submission to the e-invoicing exchange system comes back to the source system, with an alert on rejection.
5. A shipment is created with the courier, with label and tracking code.
6. Delivery statuses update the order and trigger customer notifications.
7. Every night, reconciliation compares orders, documents and stock movements and reports differences.

Every step can fail, and each has an automatic retry, an error queue and an owner.

My take

I treat integrations as software in every sense, not configuration. That is why I write them as versioned services in a repository, with tests on edge cases and controlled deploys, rather than leaving them to chains of connectors nobody can reconstruct any more. In the Altura Vela management app, for example, Stripe payments are handled by the provider's webhook, not the browser's return: it is a detail, but it is the detail that prevents bookings paid for and never recorded.

My rule of thumb: an integration is finished when you can answer "what happened to order 1234?" in five minutes.

Finally, I always document integrations: flows, mappings and recovery procedures, so whoever comes next does not have to reconstruct them from the code.

Why work with me

I have been programming since 1999, delivered more than 300 projects and work as an external developer with about 30 agencies, from Rome and remotely. I design integrations between e-commerce, management systems, invoicing, payments and couriers with queues, idempotency and reconciliation.

If your systems do not talk to each other, or talk badly, get in touch: in a call of about 20 minutes we map the flows and find where they break. The service is in API integrations.