Support for

FLAPI: Jobs

Alistair Wilson
by Alistair Wilson 3 months ago
 

Quick Reference

Available to: FLAPI, M-FLAPI
Jobs
GET /jobs/<job>
POST /jobs
PUT /jobs/<job>
Job payments
GET /jobs/<job>/payments
Specifying job despatch (before despatch)
GET /jobs/<job>/despatches
GET /jobs/<job>/despatches/<despatch>
Logging actual job despatch (on despatch)
POST /jobs/<job>/despatches
Download JobMaker Pack
GET /jobs/<job>/jobmaker
Deallocate or Cancel Job
GET /jobs/<job>/deallocate

Job Structure

  • workgroup
    • customer categories
      • customer
        • job
          • job revenue items
          • job finishes
          • job despatches
            • consignments
          • (customer addresses)
          • (notes)
          • (orientation)

FLAPI: Job Main Details FLAPI: Job Main Details

FLAPI: JobMaker packs FLAPI: JobMaker packs

FLAPI: Job Despatch FLAPI: Job Despatch

FLAPI: Job Finances FLAPI: Job Finances

FLAPI: Jobs

Quick Reference

Available to: FLAPI, M-FLAPI
Jobs
GET /jobs/<job>
POST /jobs
PUT /jobs/<job>
Job payments
GET /jobs/<job>/payments
Specifying job despatch (before despatch)
GET /jobs/<job>/despatches
GET /jobs/<job>/despatches/<despatch>
Logging actual job despatch (on despatch)
POST /jobs/<job>/despatches
Download JobMaker Pack
GET /jobs/<job>/jobmaker
Deallocate or Cancel Job
GET /jobs/<job>/deallocate

Job Structure

  • workgroup
    • customer categories
      • customer
        • job
          • job revenue items
          • job finishes
          • job despatches
            • consignments
          • (customer addresses)
          • (notes)
          • (orientation)

FLAPI: Job Main Details

Contents

  • Request all jobs
  • Request job by id
  • Create a job
  • Change a job

Request all jobs

Not supported.

Request job by id

GET path
/jobs/<job.id>

Retrieves the requested job, along with relevant details. 

Note that the returned job.addreses contains the despatch specification for the job, and job.despatches contains completed despatches.

 

Parameter Description
format json or xml
include Specify details to be embedded in the response.
HTTP request
GET http://dev.flyerlink.com/api.php/jobs/855086?format=json
HTTP response (JSON)
{
    "job" : {
        "id" : "855086",
        "status" : "081",
        "customer" : "TESTME",
        "contact" : "315401",
        "quantity_allocated" : "2000",
        "quantity_printed" : "2000",
        "quantity_despatched" : "2000",
        "total_transfer" : "102.48",
        "total_selling" : "172.00",
        "total" : "172.00",
        "product_code" : "LEGA40T",
        "client_reference" : "47742",
        "title" : "My doc holder 2014",
        "category" : "899",
        "quantity" : "2000",
        "auto081" : false,
        "service" : "N",
        "status_text" : "PDF'd and sent",
        "complete" : "yes",
        "multifile" : "no",
        "expected_despatch_date" : "23\/05\/2008",
        "front_filename" : "855086_A01.PDF",
        "reverse_filename" : null,
        "fee_charged_on_job" : 1234567
        "pages" : 1,
        "despatches" : [{
                "id" : "270608",
                "quantity" : "2000",
                "cartons" : "2",
                "weight" : "20.0940",
                "consignment" : "01149464",
                "consignment_url" : "http:\/\/cgi.tnt.co.uk\/trackntrace\/conenquiry.asp?ACTION=TRACK&TYPE=C&QUERY=01249422",
                "date" : "2014-05-23",
                "time" : "00:56:24",
                "line" : "1201211"
            }
        ],
        "addresses" : [{
                "name" : "Five Lives Ltd",
                "addr1" : "",
                "addr2" : "Hope Lane",
                "addr3" : "",
                "addr4" : "Felixtown",
                "addr5" : "",
                "addr6" : "United Kingdom",
                "postcode" : "M33 3OW",
                "countrycode" : "GB",
                "contact" : "Dave McTavish",
                "telephone" : "0161 2289977",
                "line" : "1201211"
            }
        ],
        "revenue" : [ {
                "costing" : "NDY",
                "quantity" : "2000",
                "units" : "1",
                "unitcost" : "0.00",
                "unitrev" : "9.00",
                "cost" : "0.00",
                "revenue" : "9.00",
                "prcost" : "0.00",
                "unitprcost" : "0.00",
                "vat" : "0.000",
                "vatcode" : "Z",
                "vattotal" : "0.000",
                "name" : "STANDARD DELIVERY",
                "customname" : "",
                "voucher" : "f",
                "template" : "f"
            }, {
                "costing" : "PR",
                "quantity" : "2000",
                "units" : "250",
                "unitcost" : "12.81",
                "unitrev" : "20.38",
                "cost" : "102.48",
                "revenue" : "163.00",
                "prcost" : "0.00",
                "unitprcost" : "0.00",
                "vat" : "0.000",
                "vatcode" : "Z",
                "vattotal" : "0.000",
                "name" : "PRINTING",
                "customname" : "",
                "voucher" : "f",
                "template" : "f"
            }
        ],
        "notes" : {
            "brief" : null
        },
        "finishes" : [],
        "orientation" : {
            "front" : "Portrait",
            "back" : "Portrait"
        },
        "jobmaker_pack" : {
            "full_pack" : "http:\/\/dev.flyerlink.com\/api.php\/jobs\/855086\/jobmaker",
            "orderlist_csv" : "http:\/\/dev.flyerlink.com\/api.php\/jobs\/855086\/jobmaker?file=csv",
            "orderlist_xml" : "http:\/\/dev.flyerlink.com\/api.php\/jobs\/855086\/jobmaker?file=xml",
            "worksheet" : "http:\/\/dev.flyerlink.com\/api.php\/jobs\/855086\/jobmaker?file=sheet",
            "packing_slip_draft" : "http:\/\/dev.flyerlink.com\/api.php\/jobs\/855086\/jobmaker?file=slip"
        }
    }
}
Response Item Description
job Container item.
  id Unique identifier for the job.
Customer
  customer A customer.code
  category The customer_category.id for this customer.
  contact user.id for the person who ordered the item (a contact).
Specification
  title A human-readable name to help you and your customer identify this job. May be non-unique.
  client_reference Customer’s reference for the job, e.g. a purchase order number.
  product_code product.code
  product Container for product details, when &include=product is requested.
See GET /product.
  auto_081 t for products that progress automatically to production as soon as they are ordered (generally for simple products that need no further preparation).
  service Service level code (internal to Flyerlink). Indicates accelerated, normal, or slower turnaround.
  quantity The number of items ordered. This will be a multiple of the product’s batch quantity.
  finishes

Container item for finish items.

If a job uses a product that has finishing choices, then for that job, one finish from each finishing choice must be chosen.

    finish Container item.
      id finish.code, identifying the option or process.
      quantity Number of items to be processed.
      name The name of the finish, in the current language.
      memo Special instructions to the operator who processes the finish.
Design and Communications
  notes

Container item.

    brief The design brief (memo).
  orientation

Container item.

    front Optional: portrait or landscape.
    back Optional: portrait or landscape.
  jobmaker_pack

Container item. Points to downloadable resources for this job.

    full_pack URL for the API call to download a zip containing all the resources pointed at by orderlist_csv, orderlist_xml, worksheet, packing_slip_draft.
    orderlist_csv URL for the API call to download the order list as a CSV file.
    orderlist_xml URL for the API call to download the order list as an XML file.
    worksheet URL for the API call to download the worksheet as a PDF.
    packing_slip_draft URL for the API call to download the packing slip as a PDF.
Revenue Items
  total_transfer Net amount charged to the selling workgroup, excluding taxes.
  total_selling Net amount charged to the customer, excluding taxes.
  fee_charged_on_job The job.code for the template fee charged (or null). Use /jobs/ to examine it.
  total Gross amount charged to the customer, including taxes.
  revenue Container item for revenue lines
    line Container item
      costing The costing.code, identifying the extra goods or services
      quantity The number of items covered by line
      units Number of times this costing is charged
      unitcost Transfer price, per unit
      unitrev Selling price, per unit
      unitprcost Production cost, per unit
      cost Total transfer price, for this line, = unitcost * units
      revenue Total selling price, for this line, = unitrev * units
      prcost Total production price, for this line, = unitprcost * units
      vat Total tax amount for this line
      vatcode The id of the tax type. These IDs vary by geographic location
      vattotal The currency amount, for taxes
      name The standard name for this costing, in the current language
      customname Where revenue editing is allowed for the costing, this may contain the edited name.
      voucher t when this line accounts for voucher adjustments.
      template t when this line accounts for template charges
Production and Despatch
  status The job’s current status, char(3). See Enumerated types.
  status_text Description of the status
  complete t when the job is invoiced and despatched.
  expected_desaptch_date Date and time, as text: <date> at <time>
  front_filename Filenames, as uploaded, and as presented in the Job Pack download.
  reverse_filename
  quantity_allocated Items grouped (committed) ready for production
  quantity_printed Items processed in production
  quantity_despatched Items packed and processed for despatched
  addresses Container item for address items
    address Container item; see customers:addresses.
      line despatch.id; use /jobs/…/despatches/.../line for detail
  despatches Completed despatches (container item for despatch items)
    despatch
Container item; see customers:addresses.
Each despatch item corresponds to a completed ‘packing and despatch’ operation.
      id despatch.line.id
      quantity Number of items in this despatch (some or all of job.quantity)
      cartons Number of separate boxes or deliverable packages
      weight Weight of the boxes in this despatch for this job, local units (kg or lbs).
      consignment Consignment ID, likely to have been issued by the carrier’s own systems.
      consignment_url Tracking URL, for customers to see the progress of their delivery.
      date Timestamp, local hub time.
      time

Create 'job'

Creates a new job. Note that other data items will need to be in place before creating a job, e.g. category, customer, product. You may optionally specify the despatches you have completed, along with auto081=true.

Parameter Description
format json or xml
title text; familiar name for the job; visible to customer.
customer customer.id
contact contact.id
product_code product.code
quantity a multiple of the product’s batch quantity
category category.code. Obtain this from customer.
order (optional) order.id; Add the created job to this order.
auto081 (optional) When true, the job will automatically progress to production; incompatible with order.
finishes (as required) See GET /products/<product.code>
HTTP request
POST http://dev.flyerlink.com/api.php/jobs
title=Job%20Created%20via%20API&customer=TEST&category=503&contact=12443&product=CSBUS&quantity=1000&auto081=true&despatch_address=000001&despatch_method=1&despatch_quantity=500&format=xml

FLAPI: JobMaker packs

Download a JobMaker pack

GET path
/jobs/<job.id>/jobmaker

Responds with the the requested job's files, packed into a ZIP file. If no arguments are presented, the graphic PDFs will also be included.

Parameter Description
file Default: all.
Possible values: csv|xml|sheet|slip
HTTP request
GET http://dev.flyerlink.com/api.php/jobs/266386/jobmaker

FLAPI: Job Despatch

Contents

  • List despatches by job id
  • Request a despatch by job id and despatch id
  • Add a despatch specification to a job
  • Log a despatch as completed

About Despatches

There are two aspects to despatches:

  • /jobs/<job.id>/despatches/ — (noun) specifying despatches, during the ordering process, 
  • /jobs/<job.id>/despatch/ — (verb) logging that a consignment has been despatched.

List despatches by job id

GET path
/jobs/<job.id>/despatches

List the entries for a requested job’s despatch specification. Note that all quantities will be a multiple of the batch quantity of the product of the job.

Parameter Description
format json or xml
HTTP request
GET http://dev.flyerlink.com/api.php/jobs/1792840/despatches?format=json
HTTP response (JSON)
{
    "despatches" : [
        {
            "id" : "2316091",
            "account" : "FRIMPTME",
            "despatch_method" : "DU",
            "quantity" : "500",
            "address" : null,
            "job" : "1792840"
        }
    ]
}
Response Item Description
despatches Container item for despatch item.
  id despatch.line.id
  account customer.code
  despatch_method despatch_method.code for your workgroup, usually 1.
  quantity Number of items in this despatch (some or all of job.quantity)
  address null for the customer’s default address, or an address.id for another address.
  job job.code; the same as specified in the request parameter.

Retrieve a despatch by job id and despatch id

GET path
/jobs/<job.id>/despatches/<despatch.id>

Retrieves the specified entry for a requested job’s despatch specification.

Parameter Description
format json or xml
HTTP request
GET http://dev.flyerlink.com/api.php/jobs/1792840/despatches/546816?format=json
HTTP response (JSON)
{
    "despatches" : [
        {
            "id" : "546816",
            "account" : "PRODDEPT",
            "despatch_method" : "D",
            "quantity" : "5000",
            "address" : null,
            "job" : "266386"
        }
    ]
}

Add a despatch spec to a job

POST path
/jobs/<job.id>/despatches

Specifies the despatch instructions for a job.

To remove a existing entry, specify the account + address + despatch_method, with a quantity of 0.

Parameter Description
format json or xml
account customer.id
address address.id, if not the customer’s own address.
quantity The number of items despatched; a multiple of the product’s batch quantity.
despatch_method despatchmethod.id
notes A 30-character delivery hint, usually printed on a despatch label.
HTTP request
POST http://dev.flyerlink.com/api.php/jobs/1792840/despatches
account=TESTCUST&address=000001&quantity=500&despatch_method=1&notes=Despatch%20created?format=json

Log job as fully despatched

 

POST path
/jobs/<job.id>/despatch

Logs the despatch of a job.

Parameter Description
format json or xml
all true
consignment a courier's consignment ID
tracking_url The url to find delivery tracking from a courier
HTTP request
POST http://dev.flyerlink.com/api.php/jobs/1792840/despatch
?format=json&all=true&consignment=12345&tracking_url=https://www.mycourier.com/tracking/12345

Log a despatch line as partially despatched

POST path
/jobs/<job.id>/despatch

Logs a partial despatch of a job.

Parameter Description
format json or xml
line id for the despatch
quantity The quantity of items in the despatch
boxes The number of boxes/cartons/containers used to despatch this quantity.
run run.id
consignment a courier's consignment ID
tracking_url The url to find delivery tracking from a courier
HTTP request
POST http://dev.flyerlink.com/api.php/jobs/1792840/despatch
line=2316091&quantity=1&boxes=1&run=521445&consignment=12345&tracking_url=https://www.mycourier.com/tracking/12345&format=json

FLAPI: Job Finances

Contents

  • List finance lines by job id and costing id
  • Add a finance lines to a job
  • Change a finance line
  • Remove a finance line

List finances by job id and costing id

GET path
/jobs/<job.id>/finances/<costing.id>

Retrieves the requested job finance lines, which are the items that comprise the total charge, e.g. individual goods and services.

Note that the costing.id is case sensitive, so the example below would fail with pr as an argument.
Parameter Description
format json or xml
HTTP request
GET http://dev.flyerlink.com/api.php/jobs/266386/finances/PR?format=json
HTTP response (JSON)
{
    "finance" : {
        "job" : "266386",
        "costing" : "PR",
        "quantity" : "5000",
        "units" : "500",
        "unitcost" : "69.00",
        "unitrev" : "39.00",
        "cost" : "217.35",
        "revenue" : "390.00",
        "prcost" : "0.00",
        "unitprcost" : "0.00",
        "vat" : "20.00",
        "vatcode" : "1",
        "vattotal" : "78.000",
        "name" : "PRINTING",
        "customname" : null,
        "voucher" : "f",
        "template" : "f"
    }
}

Add finances to job

POST path
/jobs/<job.id>/finances

Adds a job finance line. Returns an error message if a line with matching <job.id> and <costing.code>​ already exists.

Parameter Description
format json or xml
costing (required) costing.code.
revenue (required) currency amount for the Selling Price.
HTTP request
POST http://dev.flyerlink.com/api.php/jobs/266386/finances
costing=AAA&revenue=56&format=xml

Change a job finance line

PUT path
/jobs/<job.id>/finances/<costing.code>

Changes a job finance line.

Parameter Description
format json or xml
revenue (required) currency amount for the Selling Price.
HTTP request
PUT http://dev.flyerlink.com/api.php/jobs/266386/finances/C?revenue=56&format=xml

Delete a job finance line

DELETE path
/jobs/<job.id>/finances/<costing.code>

Removes the existing job finance line that matches <job.id> and <costing.code>.

Parameter Description
format json or xml
HTTP request
DELETE http://dev.flyerlink.com/api.php/jobs/2247469/finances/AAA&format=xml
 
 

Jump to contents page of

Flyerlink API Guide

 
 
 

All content is (c) Nettl Systems Limited, 2024 and may not be used, copied or distributed without permission.