{"openapi":"3.1.0","info":{"title":"Telecom Roaming Audit API","version":"1.0.0","description":"Independently recalculate international roaming charges from usage records, tariff rules, packages, country zones, and billed charges. Missing or ambiguous tariffs are reported instead of assumed. Overbilling is estimated per currency without FX conversion. Paid with x402 exact USDC on Base. No account is required.","contact":{"email":"support@brainiac.software"},"x-guidance":"BRAINIAC.software is a pay-per-call API for software agents. No account or API key is required.\nPayment uses the x402 protocol with exact USDC on Base (chain id 8453). Each POST operation has a fixed USD price.\nHow to call an operation:\n1. POST JSON matching the requestBody. Invalid input returns 400 with no payment challenge.\n2. A valid unpaid call returns 402 with the exact amount and payTo.\n3. Pay and retry with payment-signature. Payment settles only if the operation returns 2xx. A 4xx/5xx is not charged.\nInclude an Idempotency-Key header of 64 hex characters from 32 random bytes. Reuse that key only for retries of the same operation and request body.\nAll outputs are compliance prechecks, drafts, or data lookups for human review. They are not official determinations, legal advice, identity confirmation, or certified filings. Verify time-sensitive or official data with the cited source before acting."},"servers":[{"url":"https://www.brainiac.software"}],"paths":{"/api/v1/telecom-billing/roaming-charge-audit":{"post":{"operationId":"audit_roaming_charges","summary":"Audit roaming charges","description":"Recalculate international roaming charges from caller-supplied usage, tariff rules, packages, country zones, and billed charges. A usage row is priced only when exactly one tariff matches. Missing or ambiguous tariffs are reported and never assumed. Daily-pass packages zero incremental usage. Positive actual-minus-expected deltas form estimated overbilling by currency. No FX conversion is applied.","tags":["telecom-billing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"usage":{"minItems":1,"maxItems":10000,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":120},"type":{"type":"string","enum":["call","sms","data"]},"country":{"type":"string","pattern":"^[A-Z]{2}$"},"started_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$"},"ended_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$"},"units":{"type":"integer","minimum":1,"maximum":9007199254740991},"unit_kind":{"type":"string","enum":["seconds","messages","bytes"]}},"required":["id","type","country","started_at","units","unit_kind"],"additionalProperties":false}},"tariffs":{"maxItems":2000,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":120},"type":{"type":"string","enum":["call","sms","data","daily_pass"]},"country":{"type":"string","pattern":"^[A-Z]{2}$"},"zone":{"type":"string","minLength":1,"maxLength":80},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"rate_per_unit":{"type":"integer","minimum":0,"maximum":9007199254740991},"unit_kind":{"type":"string","enum":["seconds","messages","bytes","day"]},"effective_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"effective_to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"daily_cap":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","type","currency","rate_per_unit","effective_from"],"additionalProperties":false}},"packages":{"maxItems":500,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":120},"type":{"type":"string","enum":["call","sms","data","daily_pass"]},"country":{"type":"string","pattern":"^[A-Z]{2}$"},"zone":{"type":"string","minLength":1,"maxLength":80},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"allowance_units":{"type":"integer","minimum":0,"maximum":9007199254740991},"unit_kind":{"type":"string","enum":["seconds","messages","bytes","day"]},"price":{"type":"integer","minimum":0,"maximum":9007199254740991},"effective_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"effective_to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["id","type","currency","price","effective_from"],"additionalProperties":false}},"zones":{"maxItems":1000,"type":"array","items":{"type":"object","properties":{"zone":{"type":"string","minLength":1,"maxLength":80},"country":{"type":"string","pattern":"^[A-Z]{2}$"}},"required":["zone","country"],"additionalProperties":false}},"billed_charges":{"minItems":1,"maxItems":10000,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":120},"usage_id":{"type":"string","minLength":1,"maxLength":120},"package_id":{"type":"string","minLength":1,"maxLength":120},"type":{"type":"string","enum":["call","sms","data","daily_pass","other"]},"country":{"type":"string","pattern":"^[A-Z]{2}$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"amount":{"type":"integer","minimum":0,"maximum":9007199254740991},"billed_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$"},"detail":{"type":"string","minLength":1,"maxLength":240}},"required":["id","type","currency","amount","billed_at"],"additionalProperties":false}}},"required":["usage","billed_charges"],"additionalProperties":false},"example":{"usage":[{"id":"u1","type":"data","country":"FR","started_at":"2026-11-05T10:00:00.000Z","units":5000000,"unit_kind":"bytes"},{"id":"u2","type":"call","country":"DE","started_at":"2026-11-05T11:00:00.000Z","units":120,"unit_kind":"seconds"},{"id":"u3","type":"sms","country":"FR","started_at":"2026-11-05T12:00:00.000Z","units":2,"unit_kind":"messages"}],"zones":[{"zone":"eu","country":"FR"},{"zone":"eu","country":"DE"}],"tariffs":[{"id":"tf-data","type":"data","zone":"eu","currency":"EUR","rate_per_unit":1,"unit_kind":"bytes","effective_from":"2026-01-01","daily_cap":2000000},{"id":"tf-call","type":"call","country":"DE","currency":"EUR","rate_per_unit":5,"unit_kind":"seconds","effective_from":"2026-01-01"}],"packages":[{"id":"pass-fr","type":"daily_pass","country":"FR","currency":"EUR","price":500,"effective_from":"2026-01-01"}],"billed_charges":[{"id":"b1","usage_id":"u1","type":"data","country":"FR","currency":"EUR","amount":1000,"billed_at":"2026-11-06T00:00:00.000Z"},{"id":"b2","usage_id":"u2","type":"call","country":"DE","currency":"EUR","amount":900,"billed_at":"2026-11-06T00:00:00.000Z"},{"id":"b3","usage_id":"u2","type":"call","country":"DE","currency":"EUR","amount":900,"billed_at":"2026-11-06T00:01:00.000Z"},{"id":"b4","package_id":"pass-fr","type":"daily_pass","country":"FR","currency":"EUR","amount":500,"billed_at":"2026-11-05T23:00:00.000Z"}]}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. Conditional fields depend on the result and data-source availability.","content":{"application/json":{"schema":{"type":"object","properties":{"expected_charges":{"type":"array","items":{"type":"object","properties":{"usage_id":{"type":"string"},"type":{"type":"string"},"country":{"type":"string"},"currency":{"type":"string"},"expected_amount":{"type":"number"},"tariff_id":{"type":"string"},"status":{"type":"string"},"evidence":{"type":"array","items":{"type":"string"}}},"additionalProperties":true}},"differences":{"type":"array","items":{"type":"object","properties":{"usage_id":{"type":"string"},"billed_id":{"type":"string"},"kind":{"type":"string"},"currency":{"type":"string"},"expected_amount":{"type":"number"},"actual_amount":{"type":"number"},"delta":{"type":"number"},"evidence":{"type":"array","items":{"type":"string"}}},"additionalProperties":true}},"incorrectly_applied_rules":{"type":"array","items":{}},"duplicate_charges":{"type":"array","items":{"type":"object","properties":{"usage_id":{"type":"string"},"billed_ids":{"type":"array","items":{"type":"string"}},"detail":{"type":"string"}},"additionalProperties":true}},"allowance_violations":{"type":"array","items":{}},"estimated_overbilling":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string"},"amount":{"type":"number"}},"additionalProperties":true}},"summary":{"type":"object","properties":{"usage_records":{"type":"number"},"billed_charges":{"type":"number"},"priced_usage":{"type":"number"},"unpriced_usage":{"type":"number"},"differences":{"type":"number"},"duplicate_charges":{"type":"number"},"allowance_violations":{"type":"number"}},"additionalProperties":true},"explanations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"expected_charges":[{"usage_id":"u1","type":"data","country":"FR","currency":"EUR","expected_amount":0,"tariff_id":"pass-fr","status":"priced","evidence":["Covered by daily_pass package pass-fr on 2026-11-05; incremental usage charge is 0 under that package."]},{"usage_id":"u2","type":"call","country":"DE","currency":"EUR","expected_amount":600,"tariff_id":"tf-call","status":"priced","evidence":["expected_amount = units 120 * rate_per_unit 5 under tariff tf-call."]},{"usage_id":"u3","type":"sms","country":"FR","currency":"EUR","expected_amount":0,"tariff_id":"pass-fr","status":"priced","evidence":["Covered by daily_pass package pass-fr on 2026-11-05; incremental usage charge is 0 under that package."]}],"differences":[{"usage_id":"u1","billed_id":"b1","kind":"amount_difference","currency":"EUR","expected_amount":0,"actual_amount":1000,"delta":1000,"evidence":["actual 1000 - expected 0 = 1000."]},{"usage_id":"u2","billed_id":"b2","kind":"amount_difference","currency":"EUR","expected_amount":600,"actual_amount":900,"delta":300,"evidence":["actual 900 - expected 600 = 300."]}],"incorrectly_applied_rules":[],"duplicate_charges":[{"usage_id":"u2","billed_ids":["b2","b3"],"detail":"Multiple billed charges reference the same usage_id."}],"allowance_violations":[],"estimated_overbilling":[{"currency":"EUR","amount":1300}],"summary":{"usage_records":3,"billed_charges":4,"priced_usage":3,"unpriced_usage":0,"differences":2,"duplicate_charges":1,"allowance_violations":0},"explanations":["A usage row is priced only when exactly one tariff matches its type, country/zone, and effective dates. Missing or ambiguous tariffs are reported and never assumed.","expected_amount = usage.units * tariff.rate_per_unit, optionally capped by tariff.daily_cap.","Daily-pass packages zero incremental usage charges for covered country/zone days; package price itself is compared when billed.","delta = actual_amount - expected_amount. Positive delta contributes to estimated_overbilling by currency.","No FX conversion is performed across currencies."]}}}},"400":{"description":"Invalid JSON or request schema."},"402":{"description":"Payment required. The JSON body is the x402 PaymentRequired object: x402Version, resource with the operation description, accepts with the price and network, and extensions.bazaar with the input schema, input example, output schema, and output example."},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Reusing the key cannot trigger a second charge."},"413":{"description":"Request body exceeds the 24 MB limit."},"500":{"description":"Operation failed before settlement, so no payment is taken. Reuse the same idempotency key to retrieve the stored error without paying again."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.04"},"protocols":[{"x402":{"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}],"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}}},"components":{"schemas":{"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}