A visible service site is not an invoice completeness check

Your finance team requests invoices for three service locations. An operator opens a supplier account, sees two locations, and saves two documents. The collection job reports success because every visible location was processed.

The implementation has reconciled its own observations. It has not reconciled the request.

I work on BrowserAct. While preparing a guide to Republic Services invoice history, the useful engineering question was how to represent account and service-site scope after a document has been obtained. This article develops that application-side check. It does not automate Republic's website, download customer files, parse supplier PDFs, or demonstrate a supplier integration. The Python example uses fictional identifiers and synthetic records only.

Define the request outside the collection loop

Republic's documented native account flow distinguishes a linked customer account from the selected service site. Its guide describes switching a site from the dashboard before using the relevant invoice history. That is a useful reason to keep account and location separate in an archive, rather than using one supplier name as the document key.

For this example, the input is a finance-approved list of specific requested documents. Each entry contains an internal company reference, customer-account reference, service-site reference, billing period, and invoice reference. These are our application fields; they are not a claimed Republic export schema.

The request must not be rebuilt from whichever sites happen to appear during collection. A missing site would then disappear from both the expected and observed sets, creating a false success.

If finance only knows “all October invoices,” the specific-document inventory is not yet established. Keep that request open for inventory review. Do not invent one invoice per site or infer that every period has exactly one document.

Keep evidence separate from a filename

An archive path can contain the right account number while holding the wrong document. A filename is a label, not evidence of the supplier's document identity.

The observation below therefore records both a requested key and a key checked against the saved document. An authorized reviewer supplies the latter. The example does not implement OCR or claim that a text extractor can validate financial documents automatically.

The file_saved flag is also a fact supplied by the archive layer after its own file checks. This function does not open the path or verify storage. Keeping that boundary explicit makes a passing unit test much harder to mistake for successful document retrieval.

from collections import defaultdict

FIELDS = ("company", "account", "site", "period", "invoice")


def key(record):
    values = tuple(record.get(field) for field in FIELDS)
    if any(not isinstance(v, str) or not v.strip() for v in values):
        raise ValueError("Every document key needs five nonempty strings")
    return values


def reconcile(requests, observations):
    expected = [key(item) for item in requests]
    if len(set(expected)) != len(expected):
        raise ValueError("Duplicate requested document")

    grouped = defaultdict(list)
    unexpected = []
    for observation in observations:
        requested_key = key(observation["requested"])
        if requested_key not in expected:
            unexpected.append(observation)
        else:
            grouped[requested_key].append(observation)

    results = []
    for requested_key in expected:
        candidates = grouped[requested_key]
        if not candidates:
            status = "not_observed"
        elif len(candidates) > 1:
            status = "multiple_observations_review"
        else:
            item = candidates[0]
            if item.get("file_saved") is not True:
                status = "file_not_confirmed"
            elif item.get("identity_reviewed") is not True:
                status = "document_review_required"
            elif key(item["document_identity"]) != requested_key:
                status = "document_identity_mismatch"
            else:
                status = "requested_document_confirmed"
        results.append({"key": requested_key, "status": status})
    return {"results": results, "unexpected": unexpected}

Malformed keys raise an error rather than becoming a successful empty result. In a service, catch that error at the input boundary, record the rejected batch, and return an actionable validation response. Do not catch it and mark the request complete.

Test the ways a plausible success can be wrong

The important tests exercise the boundary between the requested document and the observed file. This example was checked locally with synthetic cases, not with Republic accounts or actual invoices.

Synthetic case	Expected outcome
Requested site never appears in observations	not_observed
Viewer was opened but saving was not confirmed	file_not_confirmed
Saved file has no completed identity review	document_review_required
Reviewed file belongs to another service site	document_identity_mismatch
Same invoice reference belongs to another company	document_identity_mismatch
Two observations claim one requested document	multiple_observations_review
An unrequested document arrives	Separate unexpected entry

Two observations are not automatically two invoices, nor are they automatically safe duplicates. They could be repeated downloads or different versions. This small function routes them to review instead of silently retaining whichever record was written last.

Retry the unresolved request, not every visible site

Store each result against a stable request revision. A retry can target an unresolved document while leaving already reviewed files intact. If finance changes the requested company, site, period, or invoice reference, create a revised request rather than editing the historical evidence to fit the new expectation.

The UI should expose the unresolved reason. “Site not observed” can mean missing access, the wrong account context, or a genuinely absent listing; this function cannot choose among those explanations. “Document identity mismatch” asks for a different file, while “file not confirmed” asks the archive layer to investigate delivery.

Completing every result proves only that the explicitly requested documents have matching reviewed observations. It does not prove that the supplier issued no additional invoices, that a payment cleared, or that every company location was included in the finance request.

Choose the acquisition method separately

An accounting application can apply this contract to files obtained manually, through an established email process, or through a separately permitted integration. Implementing reconciliation does not grant permission to automate a supplier portal.

Our Republic guide covers the native account and site context and keeps automated access conditional on supplier permission. There is no validated Republic collector or bulk-download claim here. BrowserAct is my affiliation, not evidence that this particular integration exists.

The broader design lesson is to make the expected document set independent of the collector's view. Otherwise the system can turn the very thing it failed to see into the reason it believes the work is complete.

Source and native retrieval context: Find Republic Services invoices for multiple sites.