# Telecom Roaming Audit API

> 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.

Each POST has a fixed USDC price on Base, paid with the x402 exact scheme. The request is validated first, and payment settles only after a successful (2xx) result. Failed calls are not charged.

1. POST JSON matching the requestBody. Invalid input returns 400 with no payment challenge.
2. A valid unpaid call returns 402 with the exact amount and payTo.
3. Pay and retry with payment-signature. Payment settles only if the operation returns 2xx. A 4xx/5xx is not charged.

- Product: https://www.brainiac.software/api/telecom-billing
- Docs: https://www.brainiac.software/api/telecom-billing/docs
- OpenAPI: https://www.brainiac.software/api/telecom-billing/openapi.json
- Contact: support@brainiac.software (https://www.brainiac.software/contact)

## Operations

### POST /api/v1/telecom-billing/roaming-charge-audit

$0.04 USDC. 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.

Inputs: usage, tariffs?, packages?, zones?, billed_charges

Docs: https://www.brainiac.software/api/telecom-billing/docs#telecom-billing-roaming-charge-audit

Example request:

```json
{
  "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"
    }
  ]
}
```

Example response:

```json
{
  "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."
  ]
}
```