Get started with the published ORB3X Utils API routes.
ORB3X Utils API now combines the original NIF, translation, and exchange endpoints with Angola-focused validation, phone, address, geo, calendar, finance, salary, time, and document utilities. All routes are dynamic and default to no-store caching.
Runtime
Node.js handlers
Cache policy
No-store responses
Endpoint styles
24 GET, 4 POST
Start with the platform model
#Most of the new endpoints are local calculators, registries, or normalizers backed by typed internal datasets. The existing tax, translation, and exchange routes still call live upstream providers.
That split is useful in client design: local-data endpoints are deterministic and fast, while upstream-backed routes need stronger retry, timeout, and observability handling.
- Expect JSON for both success and failure responses.
- Treat NIF, translation, and exchange responses as dynamic and time-sensitive.
- Treat salary, VAT, and inflation outputs as assumption-driven calculators and persist the year or rate inputs you used.
- Read the returned error code, not just the HTTP status, when deciding retries.
- Normalize your own user input before calling the endpoints to reduce avoidable 400 responses.
Shared request conventions
#| Concern | Behavior |
|---|---|
| Transport | HTTPS JSON API designed for server-side and browser-side consumers. |
| Caching | Responses set Cache-Control to no-store across the board so integrations always read live results. |
| Timeout profile | Handlers allow up to 30 seconds; only a subset of legacy routes depend on third-party upstream calls. |
| Validation | Query parameters, path values, and POST bodies are sanitized before business logic runs. |
| Error handling | Validation errors return 400-level codes with stable machine-readable error.code values. |
Make a first successful request
#Run one request per route before you integrate them into application code.
- Verify document routes from the exact runtime you deploy because PDF generation runs server-side.
- Log request IDs and upstream error codes for the NIF, translation, and exchange endpoints.
- Build response guards around assumption-driven outputs such as salary, inflation, and numbering-plan availability.
Production launch checklist
#- Centralize base URL configuration so staging and production environments can be switched without code edits.
- Capture non-200 responses with structured logging that stores HTTP status, endpoint, code, and request context.
- Define retry policy only for upstream timeouts and availability failures; do not retry invalid input errors.
- Store the calculation year or rate inputs whenever financial outputs flow into invoices, payroll, or reporting.
- Validate POST payloads for document generation before you pass user input into persistence or delivery workflows.
- Keep a lightweight contract test for each endpoint in CI to catch accidental response-shape regressions.