Integration runbook template
Copy this into a document, fill it in, and return it with your key request. It is the Appendix A inventory: what your agency issues, what it charges, who operates it, and who to call at 2am.
Why this exists
The platform can only gate what it has been told about. Every configured process — what an agency issues, what it charges, and which clearance stands in front of it — starts as an answer on this form. Filling it in properly is the difference between a gate that works on day one and a counter that quietly issues around it.
1. The agency and its people
- Agency name and revenue head code as it appears on the chart of accounts.
- Accounting officer, the officer who signs off this integration, and a 24-hour technical contact.
- The vendor or in-house team that will hold the key, with a named individual.
2. What the agency issues
- Every document, permit, certificate or approval the agency issues, with its legal basis.
- For each: who applies, what they must already hold, and what the agency charges.
- Which of them may not issue to a taxpayer without a current clearance (that is the gate list).
- Annual volume for each, and the busiest month.
3. What the agency charges
- Every fee, its amount or formula, and the revenue code it is posted to.
- Whether the fee is collected before or after the document is issued today.
- Any fee currently collected outside the state collection platform, and by whom.
4. The system holding it today
- Name, vendor, version, hosting and whether it can make outbound HTTPS calls.
- The reference the system uses for a case (this becomes external_ref).
- Whether the system can store and display a returned document number.
- Whether it can receive a webhook, or must poll.
5. Cutover and fallback
- The date the gate becomes mandatory, and who announces it.
- What the counter does when the platform is unreachable (degraded queue, or stop).
- Who may override, on what authority, and where that is recorded.
- The rollback decision: who takes it and within how long.
6. Sign-off
- The completed UAT script with request ids and verification ids for every case.
- Named sign-off by the agency and by BIR, with dates.
One row per process
Copy this table and add a row for every document, permit or approval the agency issues.
| Process | What issues | Legal basis | Clearance required? | Value-bearing? | Fees and codes | Volume / year |
|---|---|---|---|---|---|---|
| LND-COFO | Certificate of occupancy | Land Use Act | Yes — entity and directors | Yes — capital gains on the declared value | Ground rent, processing fee | 1,200 |
"Value-bearing" means the transaction has a price — a sale, a lease, a contract sum. Those processes drive capital gains and stamp duty, and a declared value above the basis of the clearance held raises an additional assessment automatically. Say so plainly here, because it decides how the process is configured.
Two questions people forget
- What happens at the counter when the platform is unreachable? The honest answers are "queue it and issue nothing" or "stop taking cases". Anything that ends in issuing first and reconciling later has to be written down here so it can be argued about now rather than discovered later.
- Who may override, and where is it recorded? Every override is a person's name against a decision. If the agency has no such person, the process has no override — which is a perfectly good answer.
Send the completed runbook to the BIR integration desk with the agency's key request, then run the UAT script.