Skip to content

gmail endpoints — Settings & downloads

This router manages Gmail settings mappings (order_place → search query) and exposes endpoints to trigger invoice downloads via Gmail.

Key endpoints

  • Get all settings: GET /settings — returns list of GmailSettings.
  • Get setting by id: GET /settings/{setting_id} — returns GmailSettings.
  • Get by order place: GET /settings/order-place/{order_place} — find setting by order place key.
  • Create setting: POST /settings — body: GmailSettingsCreate (must include search_query containing NUMBER placeholder).
  • Update setting: PUT /settings/{setting_id} — body: GmailSettingsUpdate.
  • Delete setting: DELETE /settings/{setting_id}.
  • List order places: GET /settings/order-places — returns configured order place names.
  • Get active settings: GET /settings/active — returns only active mappings.

  • Toggle setting active: PUT /settings/{setting_id}/toggle — activate/deactivate a mapping.

  • Download invoices (batch): POST /download-invoices

  • Body: JSON array of Invoice objects (see schemas.invoice.Invoice). Each invoice should include at least invoice_number and order_place.

  • Behavior: attaches to the active Google credential, authenticates Gmail, calls Gmail_Manager.download_invoices_async and returns a result summary grouped by order_place.

  • Test connection: GET /test/{order_place}?query=...&invoice_number=... — runs a live search using active credential and returns parsed metadata for quick validation.

  • Test special-case logic: POST /test/special-case — body parameters: order_place, invoice_number — runs order-place-specific special-case handlers.

Validation/Notes

  • search_query must contain the literal NUMBER placeholder; it's replaced with the invoice number when searching.
  • Endpoints rely on an active GoogleCredentials record. If none exists or authentication fails, endpoints return 404 / 401 accordingly.

Example: trigger a single batch download via curl

curl -X POST "http://localhost:8000/api/v1/invoice/download-invoices" \
  -H "Content-Type: application/json" \
  -d '[{"invoice_number":"12345","order_place":"shopx","date":"2024-03-12"}]'