FastAPI BackgroundTasks: Tarefas Após a Resposta

BackgroundTasks agenda uma função para rodar depois que a resposta é enviada. É útil para ações pequenas no mesmo processo, como uma notificação simples, quando o cliente não precisa esperar pelo resultado.

from fastapi import BackgroundTasks, FastAPI, status

app = FastAPI()

def enviar_confirmacao(pedido_id: int) -> None:
    print(f"confirmar pedido {pedido_id}")

@app.post("/pedidos/{pedido_id}", status_code=status.HTTP_202_ACCEPTED)
async def criar_pedido(
    pedido_id: int,
    tarefas: BackgroundTasks,
) -> dict[str, int]:
    tarefas.add_task(enviar_confirmacao, pedido_id)
    return {"pedido_id": pedido_id}

A função pode ser síncrona ou assíncrona e recebe argumentos por add_task(). Retornar HTTP 202 comunica aceitação, não conclusão. Registre um identificador e ofereça status quando o resultado posterior fizer parte do contrato.

Boas práticas

Não trate BackgroundTasks como fila durável. Reinícios podem perder trabalho e várias réplicas não compartilham estado. Use Celery ou outro sistema persistente quando precisar de retry, agendamento, carga alta ou execução distribuída. Torne tarefas idempotentes e registre falhas sem dados sensíveis.

Veja Celery em Python para filas persistentes e injeção de dependências no FastAPI para organizar serviços.

A documentação oficial de BackgroundTasks do FastAPI, consultada em 22 de julho de 2026, detalha a API e seus limites.