Developer documentation

Integrate billing, payments, readings, webhooks and the CLI with Gota.

Quickstart

What the API gives you

Start paths

Try it out

Three requests to a fresh sandbox and exactly what it answered. Replace $API_KEY with your sk_test_ key.

See the available APIs

curl
curl -sS "https://api.gota.umbeluzi.com/.well-known/api-catalog"
Response 200
{
  "linkset": [
    {
      "anchor": "$AUTH_API",
      "title": "auth",
      "service-desc": [
        {
          "href": "https://api.gota.umbeluzi.com/api/openapi.json",
          "type": "application/openapi+json"
        }
      ]
    },
    {
      "anchor": "$PUBLIC_API",
      "title": "public",
      "service-desc": [
        {
          "href": "https://api.gota.umbeluzi.com/api/openapi.json",
          "type": "application/openapi+json"
        }
      ]
    }
  ]
}

List the sandbox customers

curl
curl -sS "$BUSINESS_API/customers?limit=2" \
  -H "Authorization: Bearer $API_KEY"
Response 200
{
  "data": [
    {
      "id": "cus_3MLupmhWdRajYPwnuUOCwY7VqsZ",
      "tenant_id": "ten_3MLupIyFVsyKFMbbYU3xHJImRGU",
      "customer_type": "individual",
      "category": "residential",
      "display_name": "Ana Macuácua",
      "phone": "+258841234567",
      "status": "active",
      "created_at": "2026-11-20T02:39:13.451136081Z",
      "updated_at": "2026-11-20T02:39:13.451136081Z"
    },
    {
      "id": "cus_3MLupXLzxDoMCAhiGCB689k3qgC",
      "tenant_id": "ten_3MLupIyFVsyKFMbbYU3xHJImRGU",
      "customer_type": "individual",
      "category": "residential",
      "display_name": "Amélia Tivane",
      "tax_number": "460227018",
      "phone": "+258 85 672 5953",
      "status": "active",
      "created_at": "2026-11-20T02:39:11.239879973Z",
      "updated_at": "2026-11-20T02:39:11.239879973Z"
    }
  ],
  "has_more": true,
  "next_cursor": "Y3VzXzNNTHVwWEx6eERvTUNBaGlHQ0I2ODlrM3FnQ3wxNzk1MTQyMzUxMjM5ODc5OTcz"
}

List the sandbox invoices

curl
curl -sS "$BUSINESS_API/invoices?limit=2" \
  -H "Authorization: Bearer $API_KEY"
Response 200
{
  "data": [
    {
      "id": "inv_3MLupmvDlRi4wXFkERUOgaJjrIs",
      "tenant_id": "ten_3MLupIyFVsyKFMbbYU3xHJImRGU",
      "invoice_number": "INV-000001",
      "customer_id": "cus_3MLupXLzxDoMCAhiGCB689k3qgC",
      "customer_name": "Amélia Tivane",
      "account_id": "act_3MLupRAJjSkkg1T21gBKzpndUDy",
      "account_number": "CTA-000006",
      "account_holder_name": "Amélia Tivane",
      "meter_id": "mtr_3MLupRNareSGQFb5tCdIn2sFADB",
      "meter_serial": "SBX-000006",
      "meter_holder_name": "Amélia Tivane",
      "billing_run_id": "brn_3MLupmBaXwUyEBlr6MCrLMt1zgR",
      "consumption_id": "cns_3MLupmUHQGbfw7nmdsJqFUYkCKN",
      "from_reading_id": "rdg_3MLupXENzCHX1WPilsZUIwvxuZG",
      "to_reading_id": "rdg_3MLupZ3zPlljlF180HEM2tgJb1h",
      "period_start": "2026-10-01T00:00:00Z",
      "period_end": "2026-10-31T23:59:59Z",
      "consumption_m3": 35.657,
      "tariff_version_id": "trf_3MLupQ79WCC5xzEodl02RHsXwBg",
      "subtotal_cents": 265913,
      "sanitation_cents": 26591,
      "tax_cents": 46801,
      "total_cents": 339305,
      "balance_cents": 339305,
      "amount_due_cents": 339305,
      "currency": "MZN",
      "status": "open",
      "due_date": "2026-11-20T23:59:59Z",
      "issued_at": "2026-11-20T02:39:13.072064739Z",
      "line_items": [
        {
          "id": "inv_3MLupmvDlRi4wXFkERUOgaJjrIs_1",
          "invoice_id": "inv_3MLupmvDlRi4wXFkERUOgaJjrIs",
          "description": "Taxa fixa de abastecimento de água",
          "description_code": "invoice_line.fixed_fee",
          "quantity": 1,
          "unit_price_cents": 15000,
          "total_cents": 15000,
          "line_type": "fixed_meter_charge",
          "charge_code": "FIXED"
        },
        {
          "id": "inv_3MLupmvDlRi4wXFkERUOgaJjrIs_2",
          "invoice_id": "inv_3MLupmvDlRi4wXFkERUOgaJjrIs",
          "description": "Volumetric Consumption Tier 1 (0.00m³ - 10.00m³)",
          "description_code": "invoice_line.volumetric_tier",
          "description_params": {
            "from": "0.00",
            "tier": "1",
            "to": "10.00"
          },
          "quantity": 10,
          "unit_price_cents": 4500,
          "total_cents": 45000,
          "line_type": "volumetric_tier",
          "tier_number": 1
        }
      ],
      "created_at": "2026-11-20T02:39:13.072064739Z",
      "updated_at": "2026-11-20T02:39:13.072064739Z"
    },
    {
      "id": "inv_3MLupmbvp22M0CycHOsOHdGFHYo",
      "tenant_id": "ten_3MLupIyFVsyKFMbbYU3xHJImRGU",
      "invoice_number": "INV-000002",
      "customer_id": "cus_3MLupXETe6jSTPyDGaYZPNzj0YE",
      "customer_name": "Secretaria Distrital de Boane",
      "account_id": "act_3MLupSdoc4uILPMUUM0WWqlzsTE",
      "account_number": "CTA-000004",
      "account_holder_name": "Secretaria Distrital de Boane",
      "meter_id": "mtr_3MLupQYsW7RiRoVzivFDhR15KTv",
      "meter_serial": "SBX-000004",
      "meter_holder_name": "Secretaria Distrital de Boane",
      "billing_run_id": "brn_3MLupmBaXwUyEBlr6MCrLMt1zgR",
      "consumption_id": "cns_3MLupgPG006La1dPeg0gIB0Q3bJ",
      "from_reading_id": "rdg_3MLupVHHYyQsx1CpyFcyds4XW4l",
      "to_reading_id": "rdg_3MLupauGBbBrC1Z4RO7nDyEqv7O",
      "period_start": "2026-10-01T00:00:00Z",
      "period_end": "2026-10-31T23:59:59Z",
      "consumption_m3": 27.216,
      "tariff_version_id": "trf_3MLupJ2e6kvjlShUEHaoNP38kuV",
      "subtotal_cents": 264120,
      "sanitation_cents": 26412,
      "tax_cents": 46485,
      "total_cents": 337017,
      "balance_cents": 337017,
      "amount_due_cents": 337017,
      "currency": "MZN",
      "status": "open",
      "due_date": "2026-11-20T23:59:59Z",
      "issued_at": "2026-11-20T02:39:13.072064739Z",
      "line_items": [
        {
          "id": "inv_3MLupmbvp22M0CycHOsOHdGFHYo_1",
          "invoice_id": "inv_3MLupmbvp22M0CycHOsOHdGFHYo",
          "description": "Taxa fixa de abastecimento de água",
          "description_code": "invoice_line.fixed_fee",
          "quantity": 1,
          "unit_price_cents": 60000,
          "total_cents": 60000,
          "line_type": "fixed_meter_charge",
          "charge_code": "FIXED"
        },
        {
          "id": "inv_3MLupmbvp22M0CycHOsOHdGFHYo_2",
          "invoice_id": "inv_3MLupmbvp22M0CycHOsOHdGFHYo",
          "description": "Volumetric Consumption Tier 1 (0.00m³ - 0.00m³)",
          "description_code": "invoice_line.volumetric_tier",
          "description_params": {
            "from": "0.00",
            "tier": "1"
          },
          "quantity": 27.216,
          "unit_price_cents": 7500,
          "total_cents": 204120,
          "line_type": "volumetric_tier",
          "tier_number": 1
        }
      ],
      "created_at": "2026-11-20T02:39:13.072064739Z",
      "updated_at": "2026-11-20T02:39:13.072064739Z"
    }
  ],
  "has_more": true,
  "next_cursor": "inv_3MLupmbvp22M0CycHOsOHdGFHYo"
}