Customs Integration API
National revenue authority · West Africa
A production REST API bridging a national weighbridge programme to the country's customs platform, with public health and status surfaces.
Thirty-plus endpoints covering weighbridge tickets, declaration status, appointments, terminal and port registries, analytics and reporting — with a public status surface so the authority can see the state of every integration without asking us. Authentication is JWT and PBKDF2 built on the Node standard library, with no external auth dependency to audit or keep patched.
Outcomes
- Thirty-plus endpoints running in production
- Public health, status and integration surfaces
- Zero external authentication dependencies
Stack
- Next.js
- MySQL
- SQL Server
- Zod
- JWT
- nginx
- PM2
Engagement
Client named under NDA. Several engagements are active public-sector contracts, so we describe the mechanism rather than the customer.
Source, references and a walkthrough can be arranged for serious evaluation.
A national weighbridge programme and a national customs platform, each authoritative in its own domain, each holding a different half of the same consignment. Officers reconciled the two by hand. Every reconciliation was an opportunity for the numbers to disagree, and when they did there was no neutral record to appeal to.
The customs platform was not ours to change, ran on a different database engine, and modelled documents differently — a weighbridge ticket and a customs declaration do not share a schema, a lifecycle or a vocabulary. Neither side could be taken offline while the two were joined.
- 01
Integrate at the document, not the database
The bridge maps declaration documents between the two systems rather than syncing tables. Documents are what both sides already agree are authoritative, and what an auditor asks to see. Table-level replication would have coupled two release cycles that must stay independent.
- 02
Publish the health of the integration
Integrations fail quietly, and the usual first symptom is an officer insisting the system is broken while a dashboard says it is fine. Health, integration status and a public status surface are first-class endpoints, so the authority can see the state of every connection without calling us.
- 03
No authentication dependency
JWT and PBKDF2 are implemented on the Node standard library. For a system inside a revenue authority, an auth library is a supply-chain question and a patching obligation for whoever inherits it. A hundred lines we own is easier to audit than a dependency tree we do not.
The technical dossier for this engagement
This page describes the shape of the work. The dossier describes how it was actually built — and goes to a named person at a named institution rather than onto a public URL.
- System architecture, including the integration boundaries and why they were drawn there
- The data model for the records the system is accountable for
- Security posture: authentication, authorisation, audit trail and key handling
- Deployment topology, failover behaviour and what happens during an outage
- The measured before-and-after, where the client has cleared it for release
- Named CVs for the engineers who did the work
Sent under a mutual NDA. Client names and locations are redacted unless that client has given written consent, which some have and some have not. Prepared individually — expect it within two working days, not instantly.
Next project
Border Weighbridge System
Start here
Bring us the problem
nobody has solved.
A 30-minute technical briefing. We will tell you what we would build, roughly what it costs, and honestly whether we are the right people for it.