Add a task to process returned letter lists

Adds an API endpoint `/letters/returned` that accepts a list of
notification references and creates a task to update their status.

Adds a new task that uses the list of references to update the status
of notifications to 'returned-letter'.

The update is currently done using a single query and logs the
number of changed records (including notification history records).
This could potentially be done within the `/letters/returned` endpoint,
but creating a job right away allows us to extend this more easily
in the future (e.g. logging missing notifications or adding callbacks).

The job is using the database tasks queue.

app/letters/letter_schemas.py

@@ -13,3 +13,22 @@ letter_job_ids = {
     },
     "required": ["job_ids"]
 }
+
+
+letter_references = {
+    "$schema": "http://json-schema.org/draft-04/schema#",
+    "description": "list of letter notification references",
+    "type": "object",
+    "title": "references",
+    "properties": {
+        "references": {
+            "type": "array",
+            "items": {
+                "type": "string",
+                "pattern": "^[0-9A-Z]{16}$"
+            },
+            "minItems": 1
+        },
+    },
+    "required": ["references"]
+}

app/letters/rest.py

@@ -2,11 +2,12 @@ from flask import Blueprint, jsonify
 from flask import request
 
 from app import notify_celery
+from app.celery.tasks import process_returned_letters_list
 from app.config import QueueNames, TaskNames
 from app.dao.jobs_dao import dao_get_all_letter_jobs
 from app.schemas import job_schema
 from app.v2.errors import register_errors
-from app.letters.letter_schemas import letter_job_ids
+from app.letters.letter_schemas import letter_job_ids, letter_references
 from app.schema_validation import validate
 
 letter_job = Blueprint("letter-job", __name__)
@@ -27,3 +28,12 @@ def get_letter_jobs():
     data = job_schema.dump(letter_jobs, many=True).data
 
     return jsonify(data=data), 200
+
+
+@letter_job.route('/letters/returned', methods=['POST'])
+def create_process_returned_letters_job():
+    references = validate(request.get_json(), letter_references)
+
+    process_returned_letters_list.apply_async([references['references']], queue=QueueNames.DATABASE)
+
+    return jsonify(references=references['references']), 200