From 77acfa25ab17a5487e1c46f4c37e536f088bbe71 Mon Sep 17 00:00:00 2001 From: yenchiafeng Date: Thu, 11 Dec 2025 09:42:49 -0800 Subject: [PATCH] docs: Add Where to Find Document IDs for Bills via APIs --- ...to-find-document-ids-for-bills-via-apis.md | 135 ++++++++++++++++++ 1 file changed, 135 insertions(+) create mode 100644 docs/general/where-to-find-document-ids-for-bills-via-apis.md diff --git a/docs/general/where-to-find-document-ids-for-bills-via-apis.md b/docs/general/where-to-find-document-ids-for-bills-via-apis.md new file mode 100644 index 0000000..930917d --- /dev/null +++ b/docs/general/where-to-find-document-ids-for-bills-via-apis.md @@ -0,0 +1,135 @@ +# Where to Find Document IDs for Bills via APIs + +## Overview + +This guide explains where document IDs for bills are available, how they are currently exposed via existing APIs, and what needs to be done to access them through the GraphQL layer. + +## Prerequisites + +- Access to the BriteBill APIs (both: + - the API that returns document IDs, and + - the API that retrieves the actual BriteBill document). +- Access to the updated Bill Summary API (sometimes referred to as the “new bill summary API” or a new version of the existing Bill Summary API) that includes document IDs for the last five bills. +- Contact with the owner/maintainer of the GraphQL billing endpoint (currently referenced as “Gopi” in the conversation). +- Access to “highside” (secure environment) if additional context or documentation is stored there. + +> Note: Specific URLs, endpoints, and request/response schemas were not provided in the original discussion and will need to be obtained from the relevant service owners or internal documentation. + +## Explanation of Available APIs + +### 1. BriteBill APIs + +There are two separate BriteBill REST APIs involved: + +1. **Document ID Retrieval API** + - Purpose: Returns document IDs for bills. + - Status: This is the primary source for document IDs when not using the new Bill Summary API. + - Shape: Request and response formats are not specified in the conversation and must be obtained from BriteBill API documentation or the owning team. + +2. **BriteBill Document Retrieval API** + - Purpose: Retrieves the actual BriteBill document (e.g., PDF) using a document ID. + - Shape: Request and response formats are not specified and must be obtained from BriteBill API documentation or the owning team. + +These two APIs are conceptually separate but often used together: first to obtain the document ID, then to fetch the corresponding document. + +### 2. Existing GraphQL BriteBill Endpoint + +- There is an existing **GraphQL endpoint** that “bundles” the BriteBill functionality. +- This endpoint was set up by Gopi and currently exposes some BriteBill-related data. +- **Important**: As of the conversation, **document IDs are not exposed via the existing GraphQL API**. + To access document IDs through GraphQL, the GraphQL schema and resolvers must be updated. + +### 3. Updated Bill Summary API (New Version) + +- There is a **new or updated Bill Summary API** that: + - Includes **document IDs for the last five bills**. + - Is sometimes referred to as the “new bill summary API” or a new version of the existing Bill Summary API. +- This API appears to be part of the “Billing Hub” or related billing services, but this is not fully confirmed in the conversation. +- Access to this API and its documentation (including request and response shapes) is currently restricted to those with “highside” access. + +## How to Obtain Document IDs for Bills + +1. **Using the Updated Bill Summary API (Preferred, if available)** + - Confirm with your billing platform owner (e.g., Vashisht or the Billing Hub team) that you have access to the **updated Bill Summary API**. + - Obtain: + - The endpoint URL. + - Authentication requirements. + - Request parameters (e.g., account identifier, date range). + - Response schema, specifically the field(s) that contain document IDs for the last five bills. + - Call the updated Bill Summary API to retrieve bill summaries, including document IDs. + +2. **Using BriteBill APIs Directly (If Bill Summary API Is Not Available)** + - Call the **BriteBill Document ID Retrieval API** to obtain document IDs for the relevant bills. + - Use the returned document IDs to call the **BriteBill Document Retrieval API** to fetch the actual bill documents. + - Refer to internal BriteBill API documentation for: + - Base URLs. + - HTTP methods. + - Request/response JSON schemas. + +3. **Exposing Document IDs via GraphQL** + + If your client or service needs document IDs through GraphQL: + + 1. **Engage the GraphQL Owner (Gopi)** + - Request an update to the GraphQL schema to: + - Add fields that expose document IDs (either from BriteBill APIs or from the updated Bill Summary API). + - Implement resolvers that call the underlying REST APIs (BriteBill and/or Bill Summary). + - Confirm: + - Which underlying API will be the source of truth for document IDs. + - Any performance or caching considerations. + + 2. **Update Client Integrations** + - Once the GraphQL schema is updated, adjust your client queries to request the new document ID fields. + - Validate that the returned document IDs match those from the underlying REST APIs. + +## Important Notes and Caveats + +- **No existing GraphQL API for document IDs**: As of the discussion, there is **no GraphQL API that directly returns document IDs**; this must be added. +- **Two separate BriteBill APIs**: One for document IDs and one for the actual document; both may be required depending on your use case. +- **Access restrictions**: + - Some team members do not have access to “highside” and therefore cannot view or share details of the new Bill Summary API. + - You may need appropriate permissions or to work with someone who has highside access to obtain the full API specification. +- **Terminology confusion**: + - “New bill summary API” may be a new version of the existing Bill Summary API. + - It may or may not be the same as the “Billing Hub API”; this needs confirmation from the billing platform team. + +## Troubleshooting and Open Questions + +If you encounter issues or missing information, consider the following: + +1. **Cannot find request/response shapes for document IDs** + - Contact: + - The BriteBill API owners for BriteBill documentation. + - The Billing Hub or billing platform team (e.g., Vashisht) for the updated Bill Summary API specification. + - Ask specifically for: + - Endpoint URLs. + - Authentication details. + - JSON schemas for responses that include document IDs. + +2. **GraphQL does not return document IDs** + - Confirm with Gopi (or the current GraphQL owner): + - Whether document IDs have been added to the GraphQL schema. + - Whether the resolvers are wired to the updated Bill Summary API or BriteBill APIs. + - If not yet implemented, request a change to: + - Add document ID fields to the relevant GraphQL types. + - Implement resolvers that call the appropriate REST APIs. + +3. **Unclear which “Bill Summary API” to use** + - Clarify with the billing team: + - Whether the “new bill summary API” is: + - A new version of the existing Bill Summary API, or + - A separate Billing Hub API. + - Which version is considered the source of truth for document IDs for the last five bills. + +4. **Missing or restricted documentation** + - If documentation is only available on highside and you do not have access: + - Request a summary or non-sensitive schema details from someone who does have access. + - Ask for sanitized examples of request and response payloads that you can use for development. + +> Additional information needed: +> - Exact endpoint URLs and HTTP methods for the BriteBill APIs. +> - Exact endpoint URL, version, and schema for the updated Bill Summary API. +> - Current GraphQL schema definition and any planned changes to expose document IDs. + +--- +*Source: [Original Slack thread](https://distylai.slack.com/archives/impl-tower-billing/p1749690704887559)*