Polling Fallback¶

The polling task exists because webhooks are best-effort. If Alanube fails to deliver — network blips, our endpoint being briefly unavailable, retry exhaustion on their side — we still need to know the document's final status.

The task¶

app/graphql/invoices/tasks/pac_status_poll_task.py

Registered with the taskiq broker. Enqueued by the invoice mutations after a successful submission.

Flow¶

flowchart TD
    Start[Task starts
document_id, pac_company_id] --> Loop
    Loop[Attempt N of 60] --> Get[GET /pan/v1/invoices/id
?documents=pdf]
    Get --> Update[Update invoice.legal_status]
    Update --> Pdf{legal_status in
PAC/DGI_AUTHORIZED
and pdf url present?}
    Pdf -- Yes --> Attach[Download PDF
FileService.create_file]
    Pdf -- No --> Term
    Attach --> Term
    Term{Terminal status?}
    Term -- Yes --> Done[Return]
    Term -- No --> Wait[Sleep 5s]
    Wait --> Inc{N == 60?}
    Inc -- No --> Loop
    Inc -- Yes --> Timeout[Log warning
Return]

Interaction with webhooks¶

The task and the webhook handler can both run concurrently. They both:

• Update legal_status.
• Download and attach the PDF.

This is intentionally redundant. Whichever lands first updates the row; the other becomes a no-op (status overwrite is idempotent) or creates a duplicate file attachment. See the duplicate-PDF wart in Webhooks.

Why 5 minutes?¶

Most documents reach DGI_AUTHORIZED within 10–30 seconds. The 5-minute window covers the long tail. Beyond that, the document is genuinely stuck and requires manual intervention via attach_pac_pdf or a re-poll.

Tuning¶

• Lower max_attempts if you'd rather fail fast.
• Increase the sleep interval if rate-limiting becomes an issue.
• Switch to exponential backoff if Alanube starts pushing back. (Currently fixed 5s.)

Operational note¶

The poll loop runs in a single taskiq worker invocation. If the worker dies mid-poll, the document is left in whatever state Alanube last reported, and the webhook is the only remaining path. If both fail, the operator must call attach_pac_pdf manually.