A public service is not a form rendered on top of an agency database. It is a long-running, multi-channel case that must prove identity, reuse authorized data, collect evidence, coordinate institutions, accept payments, expose status, notify people, support appeals, and remain auditable years later.
The portal is one channel. The service exists across web, mobile, assisted desks, call centers, kiosks, messaging, internal case tools, and agency systems. Start from the citizen outcome and legal process: who may request it, what evidence is required, which institution decides, what deadlines apply, how payment works, what status can be disclosed, and how a person corrects or appeals a decision.
A citizen should receive one public reference and one status timeline even when five agencies participate. Internally, preserve agency identifiers and correlation IDs, but do not expose integration complexity as five disconnected protocols. The case record owns current state, requested service version, applicant, representation, evidence manifest, decisions, payment references, deadlines, communications, and audit pointers.
Brazil's gov.br and Chile's ClaveÚnica illustrate centralized authentication through OpenID Connect-style integrations. The relying service still decides whether the person may act, which identity assurance is sufficient, and whether they represent a child, company, estate, or another person. ID tokens identify the session; APIs receive appropriate access tokens. RFC 9700 security guidance, exact redirect URIs, PKCE, short-lived tokens, scoped access, key rotation, and environment separation belong in the platform baseline.
Conecta GOV.BR and Peru's PIDE reflect the goal of secure data exchange so people do not repeatedly submit facts government already holds. That does not mean copying every register into one lake. Query the authoritative source for a declared purpose, return the minimum fields, preserve source and freshness, distinguish fact from inference, record consent or legal basis, and provide a correction route when data is wrong.
Represent questions, validation, conditional sections, evidence requirements, help text, language, and accessibility metadata as versioned schemas. Save drafts without forcing the highest assurance level too early. Support slow connections, resumable uploads, keyboard navigation, screen readers, clear errors, human assistance, and printable or offline alternatives. A redesign must not make old cases uninterpretable.
Do not expose raw workflow engine states such as QUEUE_17_RETRY. Map operational states into a stable public vocabulary with last update, expected next step, responsible institution, deadline, and citizen action. Every transition needs actor, timestamp, reason, prior state, new state, and evidence.
Create an obligation or payment intent tied to the case, amount, currency, fee rule, payer, expiry, and idempotency key. Treat redirect success as presentation, not settlement truth. Process signed provider callbacks, poll when necessary, reconcile with statements, issue receipts, handle exemptions and partial refunds, and prevent a duplicate callback from issuing two documents.
Email, SMS, push, WhatsApp, and government inboxes can fail, arrive late, or be accessed by someone else. Notifications carry minimal sensitive data and link to the authenticated status view. Store template/version, channel, destination token, send time, provider result, delivery result, language, accessibility preference, and the event that triggered the message.
OpenAPI describes endpoints but cannot resolve institutional meaning by itself. Define canonical identifiers, field semantics, data owners, lawful purpose, schema lifecycle, error taxonomy, rate limits, support contacts, sandbox data, deprecation windows, and change notifications. Adapters isolate legacy SOAP, files, queues, or proprietary systems from the citizen-facing service contract.
| Capability | Authoritative record | API contract | Failure behavior | Audit evidence |
|---|---|---|---|---|
| Digital identity | Identity provider plus service authorization. | OIDC/OAuth metadata, claims, scopes, assurance, representation. | Preserve draft; offer assisted channel; never weaken silently. | Authentication event, assurance, consent, token metadata. |
| Registry lookup | Owning agency register. | Purpose-bound query, minimum response, freshness and provenance. | Queue retry or request evidence; do not invent “not found.” | Requester, purpose, fields, source version, response hash. |
| Application | Case service and versioned form schema. | Draft, submit, amend, upload, validate, withdraw. | Idempotent retry and resumable evidence upload. | Submitted snapshot, declarations, signature, timestamps. |
| Payment | Treasury/payment ledger. | Intent, callback, settlement, receipt, refund, reconciliation. | Pending state until financial confirmation. | Provider IDs, amount, state transitions, reconciliation batch. |
| Decision | Authorized agency decision record. | Reason codes, document, effective date, conditions, appeal. | Escalate overdue or conflicting decisions. | Actor, authority, rule/policy version, evidence considered. |
| Notification | Case status remains authoritative. | Template event, channel preference, send and delivery receipt. | Retry by policy; switch channel only with permission. | Template, trigger, destination token, provider receipts. |
Separate business history, security telemetry, records management, and analytics. Use append-only transition records, tamper-evident storage where required, synchronized clocks, actor identity, purpose, data provenance, decision reason, policy version, and correlation IDs. Access to a citizen's case is itself auditable. Logs should support investigation without becoming an uncontrolled copy of sensitive documents.
Agency systems will be unavailable. Use durable queues, timeouts, circuit breakers, idempotency, replay, dead-letter review, cached reference data with explicit staleness, and a visible “awaiting institution” state. Preserve drafts locally and server-side. Do not turn a downstream timeout into a denial or force the citizen to restart.
WCAG 2.2 is a baseline, not the full inclusion strategy. Test with assistive technology and real users, support regional language and literacy needs, avoid arbitrary session expiry, let people save and resume, expose progress in plain language, and allow a trained official to assist with explicit attribution. The assisted channel should use the same service APIs and state model, not a shadow process.
Measure discover-to-start conversion, draft completion, field errors, evidence rejection, assisted-channel use, payment reconciliation delay, agency queue time, end-to-end completion, deadline breaches, notification delivery, appeal and reversal rates, accessibility defects, repeat contacts, and cost per successful outcome. Completion by demographic, geography, device, connectivity, language, and channel reveals exclusion hidden by aggregate uptime.
A shared platform with identity and representation adapters, a service catalog, schema-driven forms, evidence storage, case state machine, workflow orchestration, interoperability gateway, payment ledger adapter, document/signature service, status API, notification hub, audit/provenance stream, accessibility test harness, support console, and analytics model. Agencies own policy and decisions; the platform team owns reusable contracts and reliability.
Good GovTech hides institutional fragmentation without hiding accountability. A person should understand what government needs, what it already knows, who is acting, what happens next, how long it should take, what was decided, and how to correct or appeal it.
Article about digital public services and GovTech APIs in Latin America, identity, forms, evidence, payments, document status, notification, interoperability, accessibility, and auditability.