Reference
Reference for shared request and response behavior.
This reference summarizes the conventions shared by the current Angola utility surface, including validation, geo, finance, salary, time, and document routes alongside the original upstream-backed endpoints.
Published endpoints
28
Success format
JSON only
Binary responses
PDF on POST documents
Endpoint catalog
#| Route | Method | Purpose | Key input |
|---|---|---|---|
| /api/v1/validate/* | GET | Validate Angolan IBAN and local bank-account structures. | iban or account query |
| /api/v1/phone/* | GET | Parse phone numbers, validate format, and detect operators. | phone query |
| /api/v1/address/* + /api/v1/geo/* | GET | Normalize addresses and read Angola location registries. | q, province, municipality, address |
| /api/v1/calendar/* | GET | Return holidays and business-day calculations. | year, from/to, date/days |
| /api/v1/finance/* | GET | Run VAT, invoice, and inflation calculations. | amount or lines query |
| /api/v1/salary/* | GET | Estimate payroll net, gross, and employer-cost values. | gross or net query |
| /api/v1/time/* | GET | Read current time, convert timezones, and check business hours. | timezone, datetime, start/end |
| /api/v1/documents/* | POST | Generate invoice, receipt, and contract PDFs. | JSON body |
| /api/nif/{nif} | GET | Look up Angolan taxpayer identity fields. | NIF path parameter |
| /api/translate | POST | Translate text and return detected source language. | JSON body: text, to, optional from |
| /api/exchange/{base} | GET | Return exchange rates, optionally multiplied by amount. | base path parameter, optional amount query |
Response patterns
#Success payloads are endpoint-specific, but they stay flat and application-oriented. Calculator endpoints surface derived values plus the assumptions or basis used to produce them.
Document routes are the main exception: they return binary PDF responses with attachment headers. Most other endpoints return JSON and an error envelope when something goes wrong.
Typical error response
Status codes and intent
#| Status | Meaning | Typical action |
|---|---|---|
| 200 | Validated request succeeded. | Use the payload directly. |
| 400 | Input is missing, malformed, or unsupported. | Fix the request; no retry. |
| 404 | Requested resource could not be found upstream. | Show a clear not-found state. |
| 502 | Upstream service failed or returned malformed data. | Retry with backoff or degrade gracefully. |
| 504 | Upstream dependency timed out. | Retry if the user flow can tolerate it. |
| 500 | Unexpected internal failure. | Log, alert, and treat as retryable only if your UX allows. |
Operational notes
#- All route handlers are marked dynamic, so you should not rely on build-time pre-rendered responses.
- User-Agent headers are explicitly set for the upstream-backed legacy requests to improve provider compatibility.
- Input sanitization is conservative: route parameters are trimmed and normalized before request dispatch.
- Bank validation responses include a generated bank image badge so front ends can render a recognizable visual without extra lookups.
- Document endpoints are synchronous; keep payloads compact and perform downstream storage asynchronously in your own system when needed.