Skip to content

sheets endpoints — Google Sheets settings & invoices

Endpoints to configure and interact with the Google Sheets used as the invoice source. The router exposes settings management, invoice retrieval, confirmation updates and a connection test endpoint.

Routes

  • POST /settings — Update Google Sheets settings
  • Body: SheetSettingsUpdate (JSON). Typical fields: spreadsheet_id, sheet_id, date_column, invoice_number_column, confirmation_column, order_place_column, confirmation_success_value, confirmation_fail_value.

  • Returns: updated SheetSettings.

  • GET /settings — Get current sheet settings

  • Returns: SheetSettings object.

  • DELETE /settings — Reset sheet settings to defaults

  • Returns: SheetSettings (reset state).

  • GET /invoices/{year}/{month} — Get invoices for a month

  • Path params: year (int), month (int).

  • Returns: InvoicesResponse with count and invoices (list of Invoice objects with sheet_row, invoice_number, order_place, date, confirmation_status).

  • POST /invoices/confirmation — Update a single invoice confirmation

  • Body/form: row (int), status (str).

  • Behavior: calls Sheets_Manager.update_invoice_confirmation and returns InvoiceConfirmationResponse.

  • POST /invoices/confirmation/bulk — Bulk confirmation updates

  • Body: BulkConfirmationUpdate (JSON) containing list of { row:int, status:str } entries.

  • Behavior: calls Sheets_Manager.bulk_update_confirmations (uses batchUpdate under the hood) and returns BulkConfirmationResponse.

  • GET /test-connection — Test configured Sheets connection

  • Returns: ConnectionTestResponse containing spreadsheet_title, spreadsheet_id, sheets list, and configured_sheet_id.

Operational notes

  • get_invoices_for_month uses an optimized bulk approach: it finds matching rows by scanning the configured date column, then fetches the minimal rectangular range needed in a single API call and constructs Invoice objects for each invoice number found.
  • Ensure SheetSettings are configured correctly before calling invoice endpoints — missing spreadsheet_id or column mappings will fail.
  • Use bulk update when updating many rows to minimize API calls; bulk_update_confirmations maps row+status into a batchUpdate call.

Examples

  • Fetch invoices for March 2024:
curl "http://localhost:8000/api/v1/invoice/invoices/2024/3"
  • Update a single confirmation:
curl -X POST "http://localhost:8000/api/v1/invoice/invoices/confirmation" \
  -d "row=123" -d "status=SUCCESS"