Sonar GRAPHQL

Sonar GraphQL API

Execute GraphQL queries against Sonar ISP software.

Authentication

# Bearer token authentication
headers = {
    "Authorization": f"Bearer {SONAR_API_KEY}",
    "Content-Type": "application/json"
}

Environment variables:

• SONAR_URL - Base URL (e.g., https://your-sonar.com)
• SONAR_API_KEY - API key for Bearer token auth

Endpoint: {SONAR_URL}/api/graphql

Using the Client

from src.apis.sonar_client import SonarGraphQLClient
from src.config.settings import config

client = SonarGraphQLClient(config)

# Test connection
if client.test_connection():
    print("Connected!")

# Execute custom query
response = client.execute_query(query_string, variables={})
if response.success and response.data:
    entities = response.data.get("accounts", {}).get("entities", [])

Query Patterns

Single Entity by ID

query {
    accounts(id: 123) {
        entities {
            id
            name
            account_status_id
        }
    }
}

Paginated List

query {
    accounts(paginator: {page: 1, records_per_page: 100}) {
        entities {
            id
            name
        }
        page_info {
            page
            total_pages
            total_count
        }
    }
}

With Filter

query {
    accounts(
        account_status_id: 1,
        paginator: {page: 1, records_per_page: 100}
    ) {
        entities { id, name }
    }
}

Nested Relationships

query {
    accounts(id: 123) {
        entities {
            id
            name
            contacts {
                entities {
                    id
                    name
                    email_address
                }
            }
            addresses {
                entities {
                    id
                    line1
                    city
                }
            }
        }
    }
}

Polymorphic Union Types

query {
    credits(account_id: 123) {
        entities {
            id
            amount
            creditable {
                ... on Payment {
                    description
                    payment_type
                }
                ... on Discount {
                    description
                    type
                }
            }
        }
    }
}

Aliased Batch Query (25 items per request)

query GetTaxesBatch {
    d0: tax_transactions(taxtransactionable_id: 100, taxtransactionable_type: Debit) {
        entities { id, amount }
    }
    d1: tax_transactions(taxtransactionable_id: 101, taxtransactionable_type: Debit) {
        entities { id, amount }
    }
    # ... up to d24
}

Common Entities

Live Mode Fetch

Fetch complete customer data in one call:

# Returns dict with all customer data: profile, services, billing, tickets, etc.
customer_data = client.fetch_customer_live(customer_id)

# Access nested data
services = customer_data.get("account_services", {}).get("entities", [])
invoices = customer_data.get("invoices", [])
payments = customer_data.get("payments", [])
tickets = customer_data.get("tickets", [])

Pagination Loop

page = 1
all_records = []

while True:
    query = f"""
    query {{
        accounts(paginator: {{page: {page}, records_per_page: 500}}) {{
            entities {{ id, name }}
            page_info {{ total_pages }}
        }}
    }}
    """

    response = client.execute_query(query)
    if not response.success:
        break

    entities = response.data.get("accounts", {}).get("entities", [])
    all_records.extend(entities)

    total_pages = response.data.get("accounts", {}).get("page_info", {}).get("total_pages", 1)
    if page >= total_pages:
        break
    page += 1

Error Handling

response = client.execute_query(query)

if response.success and response.data:
    # Process data
    entities = response.data.get("accounts", {}).get("entities", [])
else:
    # Handle error
    print(f"Error: {response.errors}")

Response Structure

@dataclass
class GraphQLResponse:
    data: Optional[Dict[str, Any]]      # Query result
    errors: Optional[List[Dict]]        # GraphQL errors
    success: bool                        # Overall success

Reference

• Client implementation: src/apis/sonar_client.py
• Config: src/config/settings.py
• Test: python -c "from src.apis.sonar_client import SonarGraphQLClient; from src.config.settings import config; print(SonarGraphQLClient(config).test_connection())"