{"openapi":"3.1.0","info":{"title":"auma.dev API","version":"1.0.0","summary":"Aumatex developer platform: shared backend for the Aumatex apps and public Italian validators.","description":"Read-only JSON over HTTPS. No authentication for now; responses carry Cache-Control headers so repeated calls are served by the CDN. Errors always have the shape `{ \"error\": { \"code\", \"message\", \"details\"? } }`.","contact":{"name":"Aumatex SRLS","url":"https://aumatex.it"}},"servers":[{"url":"https://auma.dev"}],"tags":[{"name":"fx","description":"Daily fiat and crypto exchange rates (340+ currencies), from the open fawazahmed0/currency-api dataset."},{"name":"it","description":"Italian identifiers: codice fiscale, partita IVA, IBAN. Pure computation, no data leaves the request."},{"name":"apps","description":"Remote configuration for the Aumatex iOS apps."},{"name":"platform","description":"Service metadata."}],"paths":{"/v1/fx/latest":{"get":{"operationId":"fxLatest","tags":["fx"],"summary":"Latest rates for a base currency","description":"Rates to convert one unit of `base` into every other currency (or only `symbols`). Codes are uppercase; crypto codes such as BTC and ETH are included. Refreshed hourly, the dataset itself updates daily.","parameters":[{"name":"base","in":"query","description":"Base currency code.","schema":{"type":"string","default":"EUR","example":"EUR"}},{"name":"symbols","in":"query","description":"Comma-separated list of codes to return. Unknown codes yield 404.","schema":{"type":"string","example":"USD,GBP,BTC"}}],"responses":{"200":{"description":"Rates document","content":{"application/json":{"example":{"base":"EUR","date":"2026-09-16","count":3,"rates":{"USD":1.154,"GBP":0.86,"BTC":0.0000152},"source":{"name":"fawazahmed0/currency-api","url":"https://github.com/fawazahmed0/currency-api","license":"CC0-1.0"}}}}},"404":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_request","message":"Request validation failed","details":[{"path":"cf","message":"cf is required"}]}}}}},"502":{"description":"Rates provider unavailable"}},"x-example":"/v1/fx/latest?base=EUR&symbols=USD,GBP,BTC"}},"/v1/fx/currencies":{"get":{"operationId":"fxCurrencies","tags":["fx"],"summary":"Supported currencies","description":"Every code the rates endpoint understands, with its display name.","responses":{"200":{"description":"Currency list","content":{"application/json":{"example":{"count":340,"currencies":[{"code":"BTC","name":"Bitcoin"},{"code":"EUR","name":"Euro"}]}}}}},"x-example":"/v1/fx/currencies"}},"/v1/fx/currencies/{code}.json":{"get":{"operationId":"fxMirror","tags":["fx"],"summary":"Upstream-compatible rates document","description":"Byte-for-byte mirror of the `@fawazahmed0/currency-api` wire format (`{ \"date\": ..., \"eur\": { \"usd\": 1.15 } }`). Also available: `/v1/fx/currencies/{code}.min.json`, `/v1/fx/currencies.json`, `/v1/fx/currencies.min.json`. Clients already written against that dataset only need to change their base URL to `https://auma.dev/v1/fx/`.","parameters":[{"name":"code","in":"path","required":true,"description":"Lowercase base currency code.","schema":{"type":"string","example":"eur"}}],"responses":{"200":{"description":"Upstream document"},"404":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_request","message":"Request validation failed","details":[{"path":"cf","message":"cf is required"}]}}}}}},"x-example":"/v1/fx/currencies/eur.json"}},"/v1/it/codice-fiscale/validate":{"get":{"operationId":"itCodiceFiscaleValidate","tags":["it"],"summary":"Validate and decode a codice fiscale","description":"Checks length, format and the check character, then decodes sex, birth date (century inferred from the two-digit year), and the Belfiore code of the birth place. Omocodia substitutions are recognised and reversed in `canonical`. Eleven-digit codes of companies and entities are validated with the partita IVA checksum.","parameters":[{"name":"cf","in":"query","required":true,"description":"The code, case and spaces do not matter.","schema":{"type":"string","example":"RSSMRA85T10A562S"}}],"responses":{"200":{"description":"Validation result (also for invalid input, see `valid` and `reason`)","content":{"application/json":{"example":{"valid":true,"kind":"person","normalized":"RSSMRA85T10A562S","omocodia":false,"sex":"M","birthDate":"1985-12-10","birthYearTwoDigits":85,"belfiore":"A562","canonical":"RSSMRA85T10A562S"}}}},"400":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_request","message":"Request validation failed","details":[{"path":"cf","message":"cf is required"}]}}}}}},"x-example":"/v1/it/codice-fiscale/validate?cf=RSSMRA85T10A562S"}},"/v1/it/codice-fiscale/calculate":{"post":{"operationId":"itCodiceFiscaleCalculate","tags":["it"],"summary":"Calculate a codice fiscale","description":"Computes the code from personal data using the official algorithm. `belfiore` is the codice catastale of the birth place (H501 for Roma, F205 for Milano). The result is the *expected* code: the Agenzia delle Entrate may have assigned a different one in case of omocodia.","requestBody":{"required":true,"content":{"application/json":{"example":{"firstName":"Mario","lastName":"Rossi","sex":"M","birthDate":"1985-12-10","belfiore":"A562"}}}},"responses":{"200":{"description":"Calculated code","content":{"application/json":{"example":{"codiceFiscale":"RSSMRA85T10A562S"}}}},"400":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_request","message":"Request validation failed","details":[{"path":"cf","message":"cf is required"}]}}}}}},"x-example":"/v1/it/codice-fiscale/calculate"}},"/v1/it/partita-iva/validate":{"get":{"operationId":"itPartitaIvaValidate","tags":["it"],"summary":"Validate a partita IVA","description":"Eleven digits with the Luhn-style check digit. An `IT` prefix, spaces and dots are ignored. `office` is the code of the issuing office (digits 8–10). VIES lookup is not performed.","parameters":[{"name":"piva","in":"query","required":true,"description":"The number to check.","schema":{"type":"string","example":"06363391001"}}],"responses":{"200":{"description":"Validation result","content":{"application/json":{"example":{"valid":true,"normalized":"06363391001","office":"100"}}}},"400":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_request","message":"Request validation failed","details":[{"path":"cf","message":"cf is required"}]}}}}}},"x-example":"/v1/it/partita-iva/validate?piva=IT06363391001"}},"/v1/it/iban/validate":{"get":{"operationId":"itIbanValidate","tags":["it"],"summary":"Validate an IBAN","description":"ISO 7064 mod 97-10 checksum plus the country length from the IBAN registry (unknown countries are checked by checksum only). Italian and San Marino IBANs are also split into CIN, ABI, CAB and account, and the domestic CIN check letter is verified.","parameters":[{"name":"iban","in":"query","required":true,"description":"The IBAN, spaces allowed.","schema":{"type":"string","example":"IT60X0542811101000000123456"}}],"responses":{"200":{"description":"Validation result","content":{"application/json":{"example":{"valid":true,"normalized":"IT60X0542811101000000123456","formatted":"IT60 X054 2811 1010 0000 0123 456","country":"IT","countryKnown":true,"checkDigits":"60","bban":"X0542811101000000123456","it":{"cin":"X","cinValid":true,"abi":"05428","cab":"11101","account":"000000123456"}}}}},"400":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_request","message":"Request validation failed","details":[{"path":"cf","message":"cf is required"}]}}}}}},"x-example":"/v1/it/iban/validate?iban=IT60%20X054%202811%201010%200000%200123%20456"}},"/v1/apps/{app}/config":{"get":{"operationId":"appsConfig","tags":["apps"],"summary":"Remote configuration for an Aumatex app","description":"Minimum and latest version, kill switch, announcement and feature flags for `moneys`, `koinvert`, `globetrail`, `keyring`. Edited in the repository, served through the CDN.","parameters":[{"name":"app","in":"path","required":true,"description":"App identifier.","schema":{"type":"string","example":"koinvert"}}],"responses":{"200":{"description":"Configuration","content":{"application/json":{"example":{"app":"koinvert","name":"Koinvert","platform":"ios","bundleId":"aumadev.Koinvert","minimumVersion":"1.0.0","latestVersion":"1.2.2","storeUrl":"https://apps.apple.com/app/koinvert/id6760571482","killSwitch":{"enabled":false,"message":null},"announcement":null,"flags":{},"updatedAt":"2026-09-16","servedAt":"2026-09-16T12:00:00.000Z"}}}},"404":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_request","message":"Request validation failed","details":[{"path":"cf","message":"cf is required"}]}}}}}},"x-example":"/v1/apps/koinvert/config"}},"/v1/health":{"get":{"operationId":"health","tags":["platform"],"summary":"Service health","description":"Version, deployed commit and serving region.","responses":{"200":{"description":"Healthy","content":{"application/json":{"example":{"status":"ok","service":"auma.dev","version":"1.0.0","commit":"abc1234","region":"fra1","time":"2026-09-16T12:00:00.000Z"}}}}},"x-example":"/v1/health"}}}}