Receipt Analysis version 3.0
https://api.kweeri.io/v2
About this API
Use this API to send image and get analyzed data from Aboutgoods Receipt Analyzer.
🔑 Security
You need to be authenticated for each request see our Authentication guide here. Your personal keys and credentials are furnished to you by our team or on the Kweeri SAAS platform, so feel free to send us a mail at support@aboutgoods.net if you don't have them.
⚠️ General infos
We support as of today JPEG
for image, but we can read also PDF
and PNG
.
Double check our recommendations about picture taking good practices for better analysis performances
🛍 Categories
🔗 Checkout our list of Categories that can be inferred from product by clicking here
⛑ Support
If you need any help please send a ticket at support@aboutgoods.net
🤔 User guide
Find a more friendly and detailed guide about this API here
🙋♂️ New Users API
Follow this link in order to have access to the Users API documentation
/documents
Document
This is an entity representing a document which passed through our analysis process. A document is either an image and the data associated with it. So you will get many informations about it, including meta data on how process went, and data detected
Get the list of documents by filters
Request to create a new document
get /documents
Get the list of documents by filters
OAuth2.0 authentification required
Query Parameters
- page: (integer)
Specify the page that you want to retrieve
- per_page: (integer - default: 10 - minimum: 10 - maximum: 1000)
Specify the amount of items that will be retrieved per page
- sort: (one of uid, createdAt, updatedAt, name, campaignUid, endpointUid, status, userPseudoId, uuid)
Sort by filter/type
- sort_direction: (one of asc, desc)
Specify sort direction
- filter: (string)
List of properties, comma separated with their filter values. Available filters:
- uid
- createdAt
- updatedAt
- name
- campaignUid
- endpointUid
- status: (WAITING_FOR_DOCUMENT|, WAITING_FOR_PROCESS, PROCESSING, PROCESSED, NOT_EXPLOITABLE, SUBSCRIPTION_ISSUE)
- userPseudoId
- uuid
Example:
&filter=campaignUid:8c4e55e2-5ff7-4584-8a37-59c8f149271b,status:PROCESSING &filter=status:PROCESSING|PROCESSED &filter=status:WAITING*
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- countPerPage: required(integer)
Number of result returned by this page
- totalEntities: required(integer)
Total number of results available for this request
- totalPages: required(integer)
Total number of pages available for this request
- nextPageUri: required(string)
Request URI (URL without hostname) that allow to go to the next page of result, can be empty if there is no next page
Example:
/{entity}?page=1&per_page=3
- prevPageUri: required(string)
Request URI (URL without hostname) that allow to go to the previous page of result, can be empty if no previous page
Example:
/{entity}?page=1&per_page=3
- results: required(array of document)
Items: document
- uid: required(string)
Aboutgoods generated unique ID
- createdAt: required(datetime)
When this object has been registered in AG system
- updatedAt: required(datetime)
The last time this entity had been updated in AG system
- dominantLanguage: required(string)
A locale format with the following pattern
{iso 639-1}-{ISO 3166-1}
- Usage : specifiy on which language the Receipt Analyzer should treat receipts
Example:
fr-FR
- status: required(one of WAITING_FOR_DOCUMENT, WAITING_FOR_PROCESS, PROCESSING, PROCESSED, NOT_EXPLOITABLE, SUBSCRIPTION_ISSUE)
As of today we have 6 status for differents states of an image in our systems, when everything is fine PROCESSED
- processReport: required(one of NO_ERROR, BAD_QUALITY_IMAGE, NOT_ENOUGH_TEXT, MULTIPLE_RECEIPT, UNREADABLE, BAD_LOCALE, NOT_RECEIPT, ERROR_JPG, BAD_URL, NOT_ANALYZED)
Process Report represent a more detailled reason about why a receipt has not been analyzed correctly A key to let the client knows what happened during analysis, helps you understand the status
NO_ERROR
=> Everything is fine, this come with thePROCESSED
status by defaultBAD_QUALITY_IMAGE
=> We detected a too blurry image or too dark, it can also be the resolution of the imageNOT_ENOUGH_TEXT
=> Self explicit, we have a threshold for the text recognition in image, if our OCR did not found enough text to generate a satisfiable amount of data, we abandon the ProcessMULTIPLE_RECEIPT
=> We do not handle multiple receipt in one image, when we detect this case, we stop the processUNREADABLE
=> Our OCR could not determine any Text in the imageBAD_LOCALE
=> We could not find any language for the detection to operate. This means that the Language or country is currently not supported by our systemNOT_RECEIPT
=> We didn't find any receipt in the imageERROR_IMAGE_FORMAT
=> The image format is not valid (not one of jpg, pdf, png)BAD_URL
=> No image has been found at the given URL (internal error)NOT_ANALYZED
=> The document has not been analyzed for the moment, this comes with theWAITING_FOR_DOCUMENT
,WAITING_FOR_PROCESS
orPROCESSING
statuses
- anomalyReport: (object)
Result of the anomaly analysis
- flags: required(array of string)
Array of flags. List of the available flags:
ORIGINAL_RECEIPT
=> No clues detectedIDENTICAL_EXISTING_FILE
=> Same MD5 already present in company's receiptsBARCODE_ALREADY_EXISTS
=> Same barcode already presentHIGH_FILE_SIMILARITY
=> Similar phash already presentSAME_SHOP_SAME_MOMENT
=> Receipt with same shop at same buyTime already presentEXISTING_PRODUCT_LIST
=> Receipt with same product list already presentHIGH_GLOBAL_CONTENT_SIMILARITY
=> Combination of the 2 previous flagsBANNED_SOFTWARE
=> Receipt with one of the editing software of the list present in its exifs- Adobe Photoshop
- Windows Photo Editor
- paint.net
- PhotoFiltre
- PicsArt
- PaintShop
- GIMP
- TouchRetouch
- Snapseed
- PhotoStudio
- ACDSee
- PhotoScape
- Aviary
- potentialDuplicateReceipts: required(array of duplicateReceipt)
Items: duplicateReceipt
- uid: required(string)
Uid of the duplicated receipt
- flags: required(array of string)
Array of flags that were found for this duplicated document regarding the original receipt.
Example:
{ "uid": "e67c9571-47a7-42cd-8439-c94bc9d5e478", "flags": ["SAME_SHOP_SAME_MOMENT", "EXISTING_PRODUCT_LIST", "HIGH_GLOBAL_CONTENT_SIMILARITY"] }
- uid: required(string)
Example:
{ "flags": [ "BARCODE_ALREADY_EXISTS", "SAME_SHOP_SAME_MOMENT", "EXISTING_PRODUCT_LIST", "HIGH_GLOBAL_CONTENT_SIMILARITY" ], "potentialDuplicateReceipts": [ { "uid": "e67c9571-47a7-42cd-8439-c94bc9d5e478", "flags": ["SAME_SHOP_SAME_MOMENT", "EXISTING_PRODUCT_LIST", "HIGH_GLOBAL_CONTENT_SIMILARITY"] }, { "uid": "c1b2997b-c6a1-48c2-819e-300fe61db5e9", "flags": ["SAME_SHOP_SAME_MOMENT", "BARCODE_ALREADY_EXISTS"] } ] }
- flags: required(array of string)
- imageUrl: required(string)
URL for getting image from a cdn repository
- name: required(string)
Id of this document that client (aka you) had set when sending the image of document in the first place.
- Helps you to retrieve a document by it's name
- endpointUid: (string)
Endpoint id that had served this document
- campaignUid: (string)
If this document is a part of promotion campaign, id of campaign is displayed here
- userPseudoId: (string)
This ID correspond to a custom and client managed id specified by the developer of the application that had setup AGKit SDK (aka you in general).
- This can also come from an userId that you sent over this very API when sending a receipt
- processedRules: (object)
- name: required(string)
Name of the whole rule, must be unique for a given campaign
- uid: required(string)
unique uid of the rule
- priceRule: (object)
rule that defines rule on prices
- eligibleOnly: required(number)
minimum price of all matched items
- totalAmount: (number)
minimum total amount of receipt
- isMatched: required(boolean)
tells if the rule is matched in receipt
Example:
{ "eligibleOnly": 20.25, "totalAmount": 40, "isMatched": false }
- eligibleOnly: required(number)
- itemRule: required(object)
rule that defines terms to search and various conditions of search (or, and)
- term: (string)
Just a simple rule to look for this term in the receipt. Mutually exclusive with AND and TERM.
- quantityRequired: (integer)
minimum required quantity of term or clause (AND/OR) to find. Is added by Rulio by default = 1.
- strategy: (string)
strategy used to count the item for quantityRequired
Example:
QUANTITY | BUNDLE | QUANTITY_TIMES_BUNDLE
- or: (array of object)
The result of running OR Rule with itemsMatched and isMatched.
Items:
- and: (array of object)
The result of running AND Rule with itemsMatched and isMatched.
Items:
- not: (array of object)
The result of running NOT Rule with itemsMatched and isMatched.
Items:
- isMatched: required(boolean)
tells if the rule is matched in receipt
- itemsMatched: (array of string)
List of IDs of items that were matched by term. Even if the rule is false (quantityRequired is not met), can have some IDs.
- quantityMatched: (integer)
quantity of term or terms in clause (AND/OR) found (even if the quantityRequired is not met). Can be different from the number of items in itemsMatched (one product line - but bought twice)
Example:
{ "quantityRequired": 2, "strategy": "QUANTITY", "or": [ { "term": "Labeyrie", "quantityRequired": 1, "strategy": "QUANTITY", "itemsMatched": [ "3" ], "isMatched": true, "quantityMatched": 1 }, { "term": "Blini", "quantityRequired": 1, "strategy": "QUANTITY", "itemsMatched": [ "1", "2" ], "quantityMatched": 2, "isMatched": true } ], "not": [ { "isMatched": true, "term": "Auchan", "itemsMatched": [ "2" ], "quantityMatched": 1 }, { "isMatched": false, "term": "Cora", "itemsMatched": [], "quantityMatched": 0 }, { "isMatched": false, "term": "Carrefour", "itemsMatched": [], "quantityMatched": 0 } ], "itemsMatched": [ "3", "1" ], "quantityMatched": 2, "isMatched": true }
- term: (string)
- signRule: (object)
rule that defines the list of signs for a given promotion
- signList: required(array of string)
List of sign eligible for the promotion.
- isMatched: required(boolean)
tells if the rule is matched in receipt
Example:
{ "signList": [ "Auchan", "Cora" ], "isMatched": true }
- signList: required(array of string)
- dateRule: required(object)
rule that defines range of dates for a given promotion
- min: required(string)
start date of the promotion/campaign
- max: required(string)
last date of the promotion/campaign
- isMatched: required(boolean)
tells if the rule is matched in receipt
Example:
{ "min": "2019-01-01", "max": "2019-11-01", "isMatched": true }
- min: required(string)
- allRulesMatched: required(boolean)
summarizes all rules matching, true if all rules are matched
- totalPriceOfMatchedItems: required(number)
total price of items that matched ItemRule
Example:
{ "name": "Labeyrie", "uid": "123", "itemRule": { "quantityRequired": 2, "strategy": "QUANTITY", "or": [ { "term": "Labeyrie", "quantityRequired": 1, "strategy": "QUANTITY", "itemsMatched": [ "3" ], "isMatched": true, "quantityMatched": 1 }, { "term": "Blini", "quantityRequired": 1, "strategy": "QUANTITY", "itemsMatched": [ "1", "2" ], "quantityMatched": 2, "isMatched": true } ], "not": [ { "isMatched": true, "term": "Auchan", "itemsMatched": [ "2" ], "quantityMatched": 1 }, { "isMatched": false, "term": "Cora", "itemsMatched": [], "quantityMatched": 0 } ], "itemsMatched": [ "3", "1" ], "quantityMatched": 2, "isMatched": true }, "dateRule": { "min": "2019-01-01", "max": "2019-11-01", "isMatched": true }, "priceRule": { "eligibleOnly": 15, "isMatched": false }, "signRule": { "signList": [ "Cora", "Auchan", "Carrefour" ], "isMatched": true }, "allRulesMatched": false, "totalPriceOfMatchedItems": 9.74 }
- name: required(string)
- appId: (string)
If this document has been received from AGKit (our mobile application SDK), this field allow to identify the application which have been used to send the document
- introspectionData: (object)
Introspection data that is infered from a given image, those data are useful to identify an image / receipt from its binary data
- resolution: required(object)
Size of the image
- width: required(number)
- height: required(number)
- size: (number)
Size in a human readable format (Mb or Kb)
- exif: (object)
Exif extracted from the image, possible keys available:
- cameraMake
- cameraModel
- software
- bitsPerSample
- imageWidth
- imageHeight
- imageDescription
- imageOrientation
- imageCopyright
- imageDatetime
- originalDatetime
- digitizeDatetime
- subsecondTime
- fstop
- exposureProgram
- isoSpeed
- subjectDistance
- exposureBias
- flashUsed
- flashReturnedLight
- flashMode
- meteringMode
- focalLength
- focalLength35mm
- gpsAltitude
- gpsPrecision
- lensFocalLengthMin
- lensFocalLengthMax
- lensFstopMin
- lensFstopMax
- lensMake
- lensModel
- focalPlaneXRes
- focalPlaneYRes
- gpsCoordinate
- resolution: required(object)
- data: (object)
Actual data that has been extracted from the receipt content Note: This field will be empty on the first document post response, as the process is running asynchronously, expect this field to be filled with data when the Status is set to
PROCESSED
- buyHour: (time-only)
🕐 The hour displayed on the receipt (ISO 8601 Time 'hh:mm:ss')
- buyDate: (date-only)
🗓 Date of buy for the receipt (ISO 8601 Date 2018-10-22)
- articleCount: (number)
Number of items in cart for this receipt
- total: (number)
🆙 Total amount paid by the customer (can be negative !)
- totalMax: (number)
🆕 Total value of the merchandises for this receipt, this can be different from what user paid (total field).
- payment: (array of string)
🆕 Buying mode or payment methods, can have multiple payments methods for a receipt, "UNKNOWN" if nothing was found
Example:
["CARD", "CASH", "CHEQUE", "UNKNOWN"]
- locale: (string)
Locale specified for this receipt analysis
- shop: (object)
🏬 This object represent the store / shop we found for this receipt, most of the time it will be only one data per field, but we can also send a top 3 with some significative accuracy
- city: (string)
City where the store of this buy is located
- sign: (string)
Store name or sign name / Brand of the shop
- subSign: (string)
SubSign of the shop
- phone: (string)
Phone number of the store
- address: (string)
Exact address of the store
- postalCode: (string)
Postal code for the city where we found this store
- geoLocation: (string)
Latitude and longitude for the shop, following https://tools.ietf.org/html/rfc5870 standard (example 13.4125,103.8667)
Example:
{ "city": "Toulon", "sign": "CARREFOUR", "subSign": "MARKET", "phone": "0494419879", "address": "CENTRE CIAL MAYOL", "postalCode": "83000", "geoLocation" : "48.31763410000001,1.9993057" }
- city: (string)
- items: required(array of object)
Items with products detected
Items: items
- id: required(string)
An ID unique to this list of item. Mainly used to identify this particular item in this receipt for our rule processor to indicate which item has matched a given rule.
- rawLabel: (string)
Raw line read on the receipt by OCR
- shortLabel: (string)
Detected short label from rawLabel, we remove price and other non label data from rawLabel
- quantity: (number)
Quantity of item detected in receipt
- unitPrice: (number)
A price detected for one piece of this item
- packageUnity: (string)
Package unity for item, for example Kg
- mass: (number)
The mass detected for the package, example 5 (Kg from PackageUnity)
- flags: (array of string)
Some notable characteristics detected on the product, BIO for example, or gluten free or anything special
Example:
["bio", "aop"]
- price: (number)
Total price for this item, (if found quantity > 1, we multiply to get this data, or we read it from receipt)
- product: (object)
What we understood from the item, we link item data to a clean and well organized product from our database and we put informations about it here.
- category: (string)
A fully qualified AGCategory name for this product infered by our AI algorithm, retrieve the complete list of categories here https://doc.kweeri.io/resources/list-of-product-categories.html
- categoryUid: (string)
Reference UID from Aboutgoods taxonomy
- brand: (string)
Fully qualified Brand name of product if displayed in label infered by our AI algorithm
- brandUid: (string)
Reference UID from Aboutgoods brands taxonomy of product if displayed in label infered by our AI algorithm
- brandLine: (string)
⚠️ deprecated: this field will be removed in future releases
- gtin: (string)
If present on the receipt, we extract the GTIN (EAN 13) Code
Example:
{ "brand": "PETIT NAVIRE", "brandLine": "FILETS DE THON", "category" : "tinned_fish", "categoryUid" : "4e54e68c-637f-a7d9-d509-f7e32b849f60", "gtin" : "1234567890123" }
- category: (string)
- bundle: (number)
Number of products in a pack. 16 x 125g, 16 is the bundle, 125g is the mass.
Example:
{ "id": "fa2cb", "rawLabel": "x5506 OATS QUAKER BIO", "quantity": 1, "unitPrice": 1.64, "packageUnity": "Kg", "mass": 1, "flags": [ "bio" ], "price": 1.64, "bundle": 1, "product": { "category": "food > sweet_grocery > cereals > breakfast_cereals", "categoryUid": "33f92698-284b-fd44-575a-f1e9cea9973e", "brand": "QUAKER", "brandUid": "05a5069d-fd64-b97b-ac06-101dcfc1686c" } }
- id: required(string)
- barcodes: (array of object)
🆕 1D or 2D codes found in the image after cropping the document from the rest of image
Items: items
- type: required(one of EAN-2, EAN-5, EAN-8, UPC-E, ISBN-10, UPC-A, EAN-13, ISBN-13, COMPOSITE, I2/5, DataBar, DataBar-Exp, Codabar, CODE-39, CODE-93, CODE-128, PDF417, QR-Code, UNKNOWN)
type of code detected
- data: required(string)
Data read from the code
- location: required(object)
- x: required(number)
x
location of the code in image - y: required(number)
y
location of the code in image - width: required(number)
width
of the code in image - height: required(number)
height
of the code in image
- x: required(number)
Example:
[{ "type": "CODE-128", "data": "12456789", "location": { "x": 0.0, "y": 0.0, "width": 50, "height": 20 } }]
- type: required(one of EAN-2, EAN-5, EAN-8, UPC-E, ISBN-10, UPC-A, EAN-13, ISBN-13, COMPOSITE, I2/5, DataBar, DataBar-Exp, Codabar, CODE-39, CODE-93, CODE-128, PDF417, QR-Code, UNKNOWN)
Example:
{ "shop": { "city": "Toulon", "sign": "CARREFOUR", "subSign": "MARKET", "phone": "0494419879", "address": "CENTRE CIAL MAYOL", "postalCode": "83000" }, "articleCount": 2, "total": 4.25, "totalMax": 4, "buyDate": "2016-12-07", "buyHour": "11:08:00", "items": [ { "id": "fa2cb", "rawLabel": "x5506 OATS QUAKER", "quantity": 1, "unitPrice": 1.64, "packageUnity": "Kg", "mass": 1, "price": 1.64, "bundle": 1, "product": { "category": "breakfast_cereals", "brand": "QUAKER" } }, { "id": "9d7fb", "rawLabel": "4 BTE 6X33CL COCA CO 2,61", "shortLabel": "BTE 6X33CL COCA CO", "quantity": 1, "unitPrice": 2.61, "packageUnity": "CL", "mass": 33, "bundle": 6, "price": 2.61, "product": { "category": "soda", "categoryUid": "efb24280-2dd9-423d-91d3-263fc780b6df", "brand": "COCA COLA" } } ] }
- buyHour: (time-only)
Example:
{ "uid": "89cd32b8-15e9-4e63-af5e-9e85da188fa1", "createdAt": "2019-09-20T08:19:57Z", "updatedAt": "2019-09-20T08:20:09Z", "dominantLanguage": "fr-FR", "name": "receiptTest", "campaignUid": "fc928982-3acc-4aea-bca3-e50d22e0b6ca", "userPseudoId": "8335c8d1-5ae7-440c-90d1-50543c86d9b4", "status": "PROCESSED", "processReport": "NO_ERROR", "imageUrl": "https://receipt.agkit.io/v2/documents/89cd32b8-15e9-4e63-af5e-9e85da188fa1/show", "data": { "shop": { "city": "Toulon", "sign": "CARREFOUR", "subSign": "MARKET", "phone": "0494419879", "address": "CENTRE CIAL MAYOL", "postalCode": "83000", "geoLocation": "48.31763410000001,1.9993057" }, "articleCount": 3, "total": 6.51, "totalMax": 6.26, "buyDate": "2016-12-07", "buyHour": "11:08:00", "payment": [ "CASH", "CARD" ], "barcodes": [ { "type": "CODE-128", "data": "12456789", "location": { "x": 0, "y": 0, "width": 50, "height": 20 } } ], "items": [ { "id": "fa2cb", "rawLabel": "x5506 OATS QUAKER 1,64", "quantity": 1, "unitPrice": 1.64, "packageUnity": "Kg", "mass": 1, "price": 1.64, "bundle": 1, "product": { "category": "food > sweet_grocery > cereals > breakfast_cereals", "categoryUid": "33f92698-284b-fd44-575a-f1e9cea9973e", "brand": "QUAKER", "brandUid": "05a5069d-fd64-b97b-ac06-101dcfc1686c" } }, { "id": "47267", "rawLabel": "PEPSI REGULAR 2,26", "shortLabel": "PEPSI REGULAR", "quantity": 1, "unitPrice": 2.26, "bundle": 1, "price": 2.26, "product": { "category": "drink > alcohol_free > soda", "categoryUid": "efb24280-2dd9-423d-91d3-263fc780b6df", "brand": "PEPSI", "brandUid": "822ed5c0-1d5c-0ec1-0cf9-5b62b2caecca" } }, { "id": "9d7fb", "rawLabel": "4 BTE 6X33CL COCA CO 2,61", "shortLabel": "BTE 6X33CL COCA CO", "quantity": 1, "unitPrice": 2.61, "packageUnity": "CL", "mass": 33, "bundle": 6, "price": 2.61, "product": { "category": "drink > alcohol_free > soda", "categoryUid": "efb24280-2dd9-423d-91d3-263fc780b6df", "brand": "COCA COLA > CLASSIC", "brandUid": "f2eaa047-39d8-0855-b0e3-098b2bbec0d5" } } ] }, "processedRules": { "uid": "1234", "name": "Quaker", "dateRule": { "min": "2019-01-01", "max": "2019-11-01", "isMatched": false }, "signRule": { "signList": [ "Carrefour" ], "isMatched": true }, "itemRule": { "term": "Quaker", "quantityRequired": 1, "strategy": "QUANTITY", "isMatched": true, "itemsMatched": [ "fa2cb" ], "quantityMatched": 1 }, "allRulesMatched": false, "totalPriceOfMatchedItems": 1.64 }, "anomalyReport": { "flags": [ "BARCODE_ALREADY_EXISTS", "SAME_SHOP_SAME_MOMENT", "EXISTING_PRODUCT_LIST", "HIGH_GLOBAL_CONTENT_SIMILARITY" ], "potentialDuplicateReceipts": [ { "uid": "e67c9571-47a7-42cd-8439-c94bc9d5e478", "flags": [ "SAME_SHOP_SAME_MOMENT", "EXISTING_PRODUCT_LIST", "HIGH_GLOBAL_CONTENT_SIMILARITY" ] }, { "uid": "c1b2997b-c6a1-48c2-819e-300fe61db5e9", "flags": [ "BARCODE_ALREADY_EXISTS" ] } ] }, "introspectionData": { "resolution": { "width": 2608, "height": 4632 }, "size": 3564061, "exif": { "bitsPerSample": 8, "cameraMake": "", "cameraModel": "", "digitizeDatetime": "", "exposureBias": 0, "exposureProgram": 0, "flashMode": 0, "flashReturnedLight": 0, "flashUsed": 0, "focalLength": 0, "focalLength35mm": 0, "focalPlaneXRes": 0, "focalPlaneYRes": 0, "fstop": 0, "gpsAltitude": 0, "gpsCoordinate": "0.000000,0.000000", "gpsPrecision": 0, "imageCopyright": "", "imageDatetime": "", "imageDescription": "", "imageHeight": 0, "imageOrientation": 0, "imageWidth": 0, "isoSpeed": 0, "lensFocalLengthMax": 0, "lensFocalLengthMin": 0, "lensFstopMax": 0, "lensFstopMin": 0, "lensMake": "", "lensModel": "", "meteringMode": 0, "originalDatetime": "", "software": "", "subjectDistance": 0, "subsecondTime": "" } } }
- uid: required(string)
HTTP status code 400
Filter malformed or invalid filter key
HTTP status code 403
You cannot access this resources with this token
Secured by OAuth2.0 - Hydra
post /documents
Request to create a new document
OAuth2.0 authentification required
Query Parameters
- name: required(string)
This field represents a string that identify this document for the client perspective. Allowing him to retrieve a document by its own id. Id must be unique per company, the API will systematically refuse any duplicate id here for a given company
- endpointUid: (string)
Represents an access point for a given set of documents (image with data), you can send document to an endpoint and retrieve data extracted from it from this endpoint. An Endpoint can have document linked to a mobile application and / or to a promotion campaign.
- campaignUid: (string)
Campaign represents a promotion campaign valid during a certain period of time and linked to a set of rules that have to be matched during receipt analysis. Any document that goes through a campaign will be checked against the set of rules (detection of things in the document) that are specified within the campaign.
- dominantLanguage: (string)
A locale format with the following pattern {iso 639-1}-{ISO 3166-1}, this is used to specifiy on which language the system should analyse receipts, very important !
Example:
fr-FR
- userPseudoId: (string)
Client side user id that created this document image, this id is dependant of client.
Body
Media type: image/jpg
Type: file
Media type: image/png
Type: file
Media type: application/pdf
Type: file
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- uid: required(string)
Aboutgoods generated unique ID
- createdAt: required(datetime)
When this object has been registered in AG system
- updatedAt: required(datetime)
The last time this entity had been updated in AG system
- dominantLanguage: required(string)
A locale format with the following pattern
{iso 639-1}-{ISO 3166-1}
- Usage : specifiy on which language the Receipt Analyzer should treat receipts
Example:
fr-FR
- status: required(one of WAITING_FOR_DOCUMENT, WAITING_FOR_PROCESS, PROCESSING, PROCESSED, NOT_EXPLOITABLE, SUBSCRIPTION_ISSUE)
As of today we have 6 status for differents states of an image in our systems, when everything is fine PROCESSED
- processReport: required(one of NO_ERROR, BAD_QUALITY_IMAGE, NOT_ENOUGH_TEXT, MULTIPLE_RECEIPT, UNREADABLE, BAD_LOCALE, NOT_RECEIPT, ERROR_JPG, BAD_URL, NOT_ANALYZED)
Process Report represent a more detailled reason about why a receipt has not been analyzed correctly A key to let the client knows what happened during analysis, helps you understand the status
NO_ERROR
=> Everything is fine, this come with thePROCESSED
status by defaultBAD_QUALITY_IMAGE
=> We detected a too blurry image or too dark, it can also be the resolution of the imageNOT_ENOUGH_TEXT
=> Self explicit, we have a threshold for the text recognition in image, if our OCR did not found enough text to generate a satisfiable amount of data, we abandon the ProcessMULTIPLE_RECEIPT
=> We do not handle multiple receipt in one image, when we detect this case, we stop the processUNREADABLE
=> Our OCR could not determine any Text in the imageBAD_LOCALE
=> We could not find any language for the detection to operate. This means that the Language or country is currently not supported by our systemNOT_RECEIPT
=> We didn't find any receipt in the imageERROR_IMAGE_FORMAT
=> The image format is not valid (not one of jpg, pdf, png)BAD_URL
=> No image has been found at the given URL (internal error)NOT_ANALYZED
=> The document has not been analyzed for the moment, this comes with theWAITING_FOR_DOCUMENT
,WAITING_FOR_PROCESS
orPROCESSING
statuses
- anomalyReport: (object)
Result of the anomaly analysis
- flags: required(array of string)
Array of flags. List of the available flags:
ORIGINAL_RECEIPT
=> No clues detectedIDENTICAL_EXISTING_FILE
=> Same MD5 already present in company's receiptsBARCODE_ALREADY_EXISTS
=> Same barcode already presentHIGH_FILE_SIMILARITY
=> Similar phash already presentSAME_SHOP_SAME_MOMENT
=> Receipt with same shop at same buyTime already presentEXISTING_PRODUCT_LIST
=> Receipt with same product list already presentHIGH_GLOBAL_CONTENT_SIMILARITY
=> Combination of the 2 previous flagsBANNED_SOFTWARE
=> Receipt with one of the editing software of the list present in its exifs- Adobe Photoshop
- Windows Photo Editor
- paint.net
- PhotoFiltre
- PicsArt
- PaintShop
- GIMP
- TouchRetouch
- Snapseed
- PhotoStudio
- ACDSee
- PhotoScape
- Aviary
- potentialDuplicateReceipts: required(array of duplicateReceipt)
Items: duplicateReceipt
- uid: required(string)
Uid of the duplicated receipt
- flags: required(array of string)
Array of flags that were found for this duplicated document regarding the original receipt.
Example:
{ "uid": "e67c9571-47a7-42cd-8439-c94bc9d5e478", "flags": ["SAME_SHOP_SAME_MOMENT", "EXISTING_PRODUCT_LIST", "HIGH_GLOBAL_CONTENT_SIMILARITY"] }
- uid: required(string)
Example:
{ "flags": [ "BARCODE_ALREADY_EXISTS", "SAME_SHOP_SAME_MOMENT", "EXISTING_PRODUCT_LIST", "HIGH_GLOBAL_CONTENT_SIMILARITY" ], "potentialDuplicateReceipts": [ { "uid": "e67c9571-47a7-42cd-8439-c94bc9d5e478", "flags": ["SAME_SHOP_SAME_MOMENT", "EXISTING_PRODUCT_LIST", "HIGH_GLOBAL_CONTENT_SIMILARITY"] }, { "uid": "c1b2997b-c6a1-48c2-819e-300fe61db5e9", "flags": ["SAME_SHOP_SAME_MOMENT", "BARCODE_ALREADY_EXISTS"] } ] }
- flags: required(array of string)
- imageUrl: required(string)
URL for getting image from a cdn repository
- name: required(string)
Id of this document that client (aka you) had set when sending the image of document in the first place.
- Helps you to retrieve a document by it's name
- endpointUid: (string)
Endpoint id that had served this document
- campaignUid: (string)
If this document is a part of promotion campaign, id of campaign is displayed here
- userPseudoId: (string)
This ID correspond to a custom and client managed id specified by the developer of the application that had setup AGKit SDK (aka you in general).
- This can also come from an userId that you sent over this very API when sending a receipt
- processedRules: (object)
- name: required(string)
Name of the whole rule, must be unique for a given campaign
- uid: required(string)
unique uid of the rule
- priceRule: (object)
rule that defines rule on prices
- eligibleOnly: required(number)
minimum price of all matched items
- totalAmount: (number)
minimum total amount of receipt
- isMatched: required(boolean)
tells if the rule is matched in receipt
Example:
{ "eligibleOnly": 20.25, "totalAmount": 40, "isMatched": false }
- eligibleOnly: required(number)
- itemRule: required(object)
rule that defines terms to search and various conditions of search (or, and)
- term: (string)
Just a simple rule to look for this term in the receipt. Mutually exclusive with AND and TERM.
- quantityRequired: (integer)
minimum required quantity of term or clause (AND/OR) to find. Is added by Rulio by default = 1.
- strategy: (string)
strategy used to count the item for quantityRequired
Example:
QUANTITY | BUNDLE | QUANTITY_TIMES_BUNDLE
- or: (array of object)
The result of running OR Rule with itemsMatched and isMatched.
Items:
- and: (array of object)
The result of running AND Rule with itemsMatched and isMatched.
Items:
- not: (array of object)
The result of running NOT Rule with itemsMatched and isMatched.
Items:
- isMatched: required(boolean)
tells if the rule is matched in receipt
- itemsMatched: (array of string)
List of IDs of items that were matched by term. Even if the rule is false (quantityRequired is not met), can have some IDs.
- quantityMatched: (integer)
quantity of term or terms in clause (AND/OR) found (even if the quantityRequired is not met). Can be different from the number of items in itemsMatched (one product line - but bought twice)
Example:
{ "quantityRequired": 2, "strategy": "QUANTITY", "or": [ { "term": "Labeyrie", "quantityRequired": 1, "strategy": "QUANTITY", "itemsMatched": [ "3" ], "isMatched": true, "quantityMatched": 1 }, { "term": "Blini", "quantityRequired": 1, "strategy": "QUANTITY", "itemsMatched": [ "1", "2" ], "quantityMatched": 2, "isMatched": true } ], "not": [ { "isMatched": true, "term": "Auchan", "itemsMatched": [ "2" ], "quantityMatched": 1 }, { "isMatched": false, "term": "Cora", "itemsMatched": [], "quantityMatched": 0 }, { "isMatched": false, "term": "Carrefour", "itemsMatched": [], "quantityMatched": 0 } ], "itemsMatched": [ "3", "1" ], "quantityMatched": 2, "isMatched": true }
- term: (string)
- signRule: (object)
rule that defines the list of signs for a given promotion
- signList: required(array of string)
List of sign eligible for the promotion.
- isMatched: required(boolean)
tells if the rule is matched in receipt
Example:
{ "signList": [ "Auchan", "Cora" ], "isMatched": true }
- signList: required(array of string)
- dateRule: required(object)
rule that defines range of dates for a given promotion
- min: required(string)
start date of the promotion/campaign
- max: required(string)
last date of the promotion/campaign
- isMatched: required(boolean)
tells if the rule is matched in receipt
Example:
{ "min": "2019-01-01", "max": "2019-11-01", "isMatched": true }
- min: required(string)
- allRulesMatched: required(boolean)
summarizes all rules matching, true if all rules are matched
- totalPriceOfMatchedItems: required(number)
total price of items that matched ItemRule
Example:
{ "name": "Labeyrie", "uid": "123", "itemRule": { "quantityRequired": 2, "strategy": "QUANTITY", "or": [ { "term": "Labeyrie", "quantityRequired": 1, "strategy": "QUANTITY", "itemsMatched": [ "3" ], "isMatched": true, "quantityMatched": 1 }, { "term": "Blini", "quantityRequired": 1, "strategy": "QUANTITY", "itemsMatched": [ "1", "2" ], "quantityMatched": 2, "isMatched": true } ], "not": [ { "isMatched": true, "term": "Auchan", "itemsMatched": [ "2" ], "quantityMatched": 1 }, { "isMatched": false, "term": "Cora", "itemsMatched": [], "quantityMatched": 0 } ], "itemsMatched": [ "3", "1" ], "quantityMatched": 2, "isMatched": true }, "dateRule": { "min": "2019-01-01", "max": "2019-11-01", "isMatched": true }, "priceRule": { "eligibleOnly": 15, "isMatched": false }, "signRule": { "signList": [ "Cora", "Auchan", "Carrefour" ], "isMatched": true }, "allRulesMatched": false, "totalPriceOfMatchedItems": 9.74 }
- name: required(string)
- appId: (string)
If this document has been received from AGKit (our mobile application SDK), this field allow to identify the application which have been used to send the document
- introspectionData: (object)
Introspection data that is infered from a given image, those data are useful to identify an image / receipt from its binary data
- resolution: required(object)
Size of the image
- width: required(number)
- height: required(number)
- size: (number)
Size in a human readable format (Mb or Kb)
- exif: (object)
Exif extracted from the image, possible keys available:
- cameraMake
- cameraModel
- software
- bitsPerSample
- imageWidth
- imageHeight
- imageDescription
- imageOrientation
- imageCopyright
- imageDatetime
- originalDatetime
- digitizeDatetime
- subsecondTime
- fstop
- exposureProgram
- isoSpeed
- subjectDistance
- exposureBias
- flashUsed
- flashReturnedLight
- flashMode
- meteringMode
- focalLength
- focalLength35mm
- gpsAltitude
- gpsPrecision
- lensFocalLengthMin
- lensFocalLengthMax
- lensFstopMin
- lensFstopMax
- lensMake
- lensModel
- focalPlaneXRes
- focalPlaneYRes
- gpsCoordinate
- resolution: required(object)
- data: (object)
Actual data that has been extracted from the receipt content Note: This field will be empty on the first document post response, as the process is running asynchronously, expect this field to be filled with data when the Status is set to
PROCESSED
- buyHour: (time-only)
🕐 The hour displayed on the receipt (ISO 8601 Time 'hh:mm:ss')
- buyDate: (date-only)
🗓 Date of buy for the receipt (ISO 8601 Date 2018-10-22)
- articleCount: (number)
Number of items in cart for this receipt
- total: (number)
🆙 Total amount paid by the customer (can be negative !)
- totalMax: (number)
🆕 Total value of the merchandises for this receipt, this can be different from what user paid (total field).
- payment: (array of string)
🆕 Buying mode or payment methods, can have multiple payments methods for a receipt, "UNKNOWN" if nothing was found
Example:
["CARD", "CASH", "CHEQUE", "UNKNOWN"]
- locale: (string)
Locale specified for this receipt analysis
- shop: (object)
🏬 This object represent the store / shop we found for this receipt, most of the time it will be only one data per field, but we can also send a top 3 with some significative accuracy
- city: (string)
City where the store of this buy is located
- sign: (string)
Store name or sign name / Brand of the shop
- subSign: (string)
SubSign of the shop
- phone: (string)
Phone number of the store
- address: (string)
Exact address of the store
- postalCode: (string)
Postal code for the city where we found this store
- geoLocation: (string)
Latitude and longitude for the shop, following https://tools.ietf.org/html/rfc5870 standard (example 13.4125,103.8667)
Example:
{ "city": "Toulon", "sign": "CARREFOUR", "subSign": "MARKET", "phone": "0494419879", "address": "CENTRE CIAL MAYOL", "postalCode": "83000", "geoLocation" : "48.31763410000001,1.9993057" }
- city: (string)
- items: required(array of object)
Items with products detected
Items: items
- id: required(string)
An ID unique to this list of item. Mainly used to identify this particular item in this receipt for our rule processor to indicate which item has matched a given rule.
- rawLabel: (string)
Raw line read on the receipt by OCR
- shortLabel: (string)
Detected short label from rawLabel, we remove price and other non label data from rawLabel
- quantity: (number)
Quantity of item detected in receipt
- unitPrice: (number)
A price detected for one piece of this item
- packageUnity: (string)
Package unity for item, for example Kg
- mass: (number)
The mass detected for the package, example 5 (Kg from PackageUnity)
- flags: (array of string)
Some notable characteristics detected on the product, BIO for example, or gluten free or anything special
Example:
["bio", "aop"]
- price: (number)
Total price for this item, (if found quantity > 1, we multiply to get this data, or we read it from receipt)
- product: (object)
What we understood from the item, we link item data to a clean and well organized product from our database and we put informations about it here.
- category: (string)
A fully qualified AGCategory name for this product infered by our AI algorithm, retrieve the complete list of categories here https://doc.kweeri.io/resources/list-of-product-categories.html
- categoryUid: (string)
Reference UID from Aboutgoods taxonomy
- brand: (string)
Fully qualified Brand name of product if displayed in label infered by our AI algorithm
- brandUid: (string)
Reference UID from Aboutgoods brands taxonomy of product if displayed in label infered by our AI algorithm
- brandLine: (string)
⚠️ deprecated: this field will be removed in future releases
- gtin: (string)
If present on the receipt, we extract the GTIN (EAN 13) Code
Example:
{ "brand": "PETIT NAVIRE", "brandLine": "FILETS DE THON", "category" : "tinned_fish", "categoryUid" : "4e54e68c-637f-a7d9-d509-f7e32b849f60", "gtin" : "1234567890123" }
- category: (string)
- bundle: (number)
Number of products in a pack. 16 x 125g, 16 is the bundle, 125g is the mass.
Example:
{ "id": "fa2cb", "rawLabel": "x5506 OATS QUAKER BIO", "quantity": 1, "unitPrice": 1.64, "packageUnity": "Kg", "mass": 1, "flags": [ "bio" ], "price": 1.64, "bundle": 1, "product": { "category": "food > sweet_grocery > cereals > breakfast_cereals", "categoryUid": "33f92698-284b-fd44-575a-f1e9cea9973e", "brand": "QUAKER", "brandUid": "05a5069d-fd64-b97b-ac06-101dcfc1686c" } }
- id: required(string)
- barcodes: (array of object)
🆕 1D or 2D codes found in the image after cropping the document from the rest of image
Items: items
- type: required(one of EAN-2, EAN-5, EAN-8, UPC-E, ISBN-10, UPC-A, EAN-13, ISBN-13, COMPOSITE, I2/5, DataBar, DataBar-Exp, Codabar, CODE-39, CODE-93, CODE-128, PDF417, QR-Code, UNKNOWN)
type of code detected
- data: required(string)
Data read from the code
- location: required(object)
- x: required(number)
x
location of the code in image - y: required(number)
y
location of the code in image - width: required(number)
width
of the code in image - height: required(number)
height
of the code in image
- x: required(number)
Example:
[{ "type": "CODE-128", "data": "12456789", "location": { "x": 0.0, "y": 0.0, "width": 50, "height": 20 } }]
- type: required(one of EAN-2, EAN-5, EAN-8, UPC-E, ISBN-10, UPC-A, EAN-13, ISBN-13, COMPOSITE, I2/5, DataBar, DataBar-Exp, Codabar, CODE-39, CODE-93, CODE-128, PDF417, QR-Code, UNKNOWN)
Example:
{ "shop": { "city": "Toulon", "sign": "CARREFOUR", "subSign": "MARKET", "phone": "0494419879", "address": "CENTRE CIAL MAYOL", "postalCode": "83000" }, "articleCount": 2, "total": 4.25, "totalMax": 4, "buyDate": "2016-12-07", "buyHour": "11:08:00", "items": [ { "id": "fa2cb", "rawLabel": "x5506 OATS QUAKER", "quantity": 1, "unitPrice": 1.64, "packageUnity": "Kg", "mass": 1, "price": 1.64, "bundle": 1, "product": { "category": "breakfast_cereals", "brand": "QUAKER" } }, { "id": "9d7fb", "rawLabel": "4 BTE 6X33CL COCA CO 2,61", "shortLabel": "BTE 6X33CL COCA CO", "quantity": 1, "unitPrice": 2.61, "packageUnity": "CL", "mass": 33, "bundle": 6, "price": 2.61, "product": { "category": "soda", "categoryUid": "efb24280-2dd9-423d-91d3-263fc780b6df", "brand": "COCA COLA" } } ] }
- buyHour: (time-only)
Example:
{
"uid": "89cd32b8-15e9-4e63-af5e-9e85da188fa1",
"createdAt": "2019-09-20T08:19:57Z",
"updatedAt": "2019-09-20T08:20:09Z",
"dominantLanguage": "fr-FR",
"name": "receiptTest",
"campaignUid": "fc928982-3acc-4aea-bca3-e50d22e0b6ca",
"userPseudoId": "8335c8d1-5ae7-440c-90d1-50543c86d9b4",
"status": "PROCESSED",
"processReport": "NO_ERROR",
"imageUrl": "https://receipt.agkit.io/v2/documents/89cd32b8-15e9-4e63-af5e-9e85da188fa1/show",
"data": {
"shop": {
"city": "Toulon",
"sign": "CARREFOUR",
"subSign": "MARKET",
"phone": "0494419879",
"address": "CENTRE CIAL MAYOL",
"postalCode": "83000",
"geoLocation": "48.31763410000001,1.9993057"
},
"articleCount": 3,
"total": 6.51,
"totalMax": 6.26,
"buyDate": "2016-12-07",
"buyHour": "11:08:00",
"payment": [
"CASH",
"CARD"
],
"barcodes": [
{
"type": "CODE-128",
"data": "12456789",
"location": {
"x": 0,
"y": 0,
"width": 50,
"height": 20
}
}
],
"items": [
{
"id": "fa2cb",
"rawLabel": "x5506 OATS QUAKER 1,64",
"quantity": 1,
"unitPrice": 1.64,
"packageUnity": "Kg",
"mass": 1,
"price": 1.64,
"bundle": 1,
"product": {
"category": "food > sweet_grocery > cereals > breakfast_cereals",
"categoryUid": "33f92698-284b-fd44-575a-f1e9cea9973e",
"brand": "QUAKER",
"brandUid": "05a5069d-fd64-b97b-ac06-101dcfc1686c"
}
},
{
"id": "47267",
"rawLabel": "PEPSI REGULAR 2,26",
"shortLabel": "PEPSI REGULAR",
"quantity": 1,
"unitPrice": 2.26,
"bundle": 1,
"price": 2.26,
"product": {
"category": "drink > alcohol_free > soda",
"categoryUid": "efb24280-2dd9-423d-91d3-263fc780b6df",
"brand": "PEPSI",
"brandUid": "822ed5c0-1d5c-0ec1-0cf9-5b62b2caecca"
}
},
{
"id": "9d7fb",
"rawLabel": "4 BTE 6X33CL COCA CO 2,61",
"shortLabel": "BTE 6X33CL COCA CO",
"quantity": 1,
"unitPrice": 2.61,
"packageUnity": "CL",
"mass": 33,
"bundle": 6,
"price": 2.61,
"product": {
"category": "drink > alcohol_free > soda",
"categoryUid": "efb24280-2dd9-423d-91d3-263fc780b6df",
"brand": "COCA COLA > CLASSIC",
"brandUid": "f2eaa047-39d8-0855-b0e3-098b2bbec0d5"
}
}
]
},
"processedRules": {
"uid": "1234",
"name": "Quaker",
"dateRule": {
"min": "2019-01-01",
"max": "2019-11-01",
"isMatched": false
},
"signRule": {
"signList": [
"Carrefour"
],
"isMatched": true
},
"itemRule": {
"term": "Quaker",
"quantityRequired": 1,
"strategy": "QUANTITY",
"isMatched": true,
"itemsMatched": [
"fa2cb"
],
"quantityMatched": 1
},
"allRulesMatched": false,
"totalPriceOfMatchedItems": 1.64
},
"anomalyReport": {
"flags": [
"BARCODE_ALREADY_EXISTS",
"SAME_SHOP_SAME_MOMENT",
"EXISTING_PRODUCT_LIST",
"HIGH_GLOBAL_CONTENT_SIMILARITY"
],
"potentialDuplicateReceipts": [
{
"uid": "e67c9571-47a7-42cd-8439-c94bc9d5e478",
"flags": [
"SAME_SHOP_SAME_MOMENT",
"EXISTING_PRODUCT_LIST",
"HIGH_GLOBAL_CONTENT_SIMILARITY"
]
},
{
"uid": "c1b2997b-c6a1-48c2-819e-300fe61db5e9",
"flags": [
"BARCODE_ALREADY_EXISTS"
]
}
]
},
"introspectionData": {
"resolution": {
"width": 2608,
"height": 4632
},
"size": 3564061,
"exif": {
"bitsPerSample": 8,
"cameraMake": "",
"cameraModel": "",
"digitizeDatetime": "",
"exposureBias": 0,
"exposureProgram": 0,
"flashMode": 0,
"flashReturnedLight": 0,
"flashUsed": 0,
"focalLength": 0,
"focalLength35mm": 0,
"focalPlaneXRes": 0,
"focalPlaneYRes": 0,
"fstop": 0,
"gpsAltitude": 0,
"gpsCoordinate": "0.000000,0.000000",
"gpsPrecision": 0,
"imageCopyright": "",
"imageDatetime": "",
"imageDescription": "",
"imageHeight": 0,
"imageOrientation": 0,
"imageWidth": 0,
"isoSpeed": 0,
"lensFocalLengthMax": 0,
"lensFocalLengthMin": 0,
"lensFstopMax": 0,
"lensFstopMin": 0,
"lensMake": "",
"lensModel": "",
"meteringMode": 0,
"originalDatetime": "",
"software": "",
"subjectDistance": 0,
"subsecondTime": ""
}
}
}
HTTP status code 400
Body
Media type: application/json
Type: object
Properties- error: required(string)
Example:
{ "badRequest" : "You are missing some field or they are malformed" }
HTTP status code 401
Authentication with Auth0 failed
HTTP status code 402
Your quota has been exceeded
HTTP status code 404
Body
Media type: application/json
Type: object
Properties- error: required(string)
Example:
{ "notFound" : "resource has not been found on this system" }
HTTP status code 409
Document or name already exists for your company
Secured by OAuth2.0 - Hydra
Request to check the quality of an image
post /documents/check
Request to check the quality of an image
OAuth2.0 authentification required AND the feature 'QUALITY CHECK' must be activated
Query Parameters
- name: (string)
This field represents a string that identify this document for the client perspective. Allowing him to retrieve a document by its own id.
Body
Media type: image/jpg
Type: file
Media type: image/png
Type: file
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- uid: required(string)
UID of this receipt attributed by Aboutgoods System to managed receipts
- name: required(string)
Id given by the client to allow client to retrieve this exact document after analysis
- status: required(string)
Status of the image quality check (EXPLOITABLE or NOT_EXPLOITABLE)
- processReport: required(string)
Describe the reason of the status (NO_ERROR when EXPLOITABLE, BAD_QUALITY_IMAGE, MULTIPLE_RECEIPT, NOT_RECEIPT OR ERROR_IMAGE_FORMAT when NOT_EXPLOITABLE)
- imageQuality: required(object)
Set of key-value describing quality of image. Each of them are compared to a threshold value to determine the overall quality of the image.
- bluriness: required(integer)
- contrast: required(integer)
- luminosity: required(integer)
- goodSize: required(boolean)
Example:
{
"uid": "12345678-abcd-eeee-dcba-ab12ab12ab12",
"name": "the one passed in query parameters",
"status": "EXPLOITABLE",
"processReport": "NO_ERROR",
"imageQuality": {
"bluriness": 158,
"contrast": 31,
"goodSize": true,
"luminosity": 193
}
}
HTTP status code 400
Cannot read image data
Secured by OAuth2.0 - Hydra
Reprocess documents by filter
post /documents/reprocess
Reprocess documents by filter
OAuth2.0 authentification required
Headers
- webhook-only: (boolean)
Set to true to send documents to outgoing URL only
- rules-only: (boolean)
Set to true to send documents for rules analysis only
Query Parameters
- filter: (string)
List of properties, comma separated with their filter values. Available filters:
- uid
- createdAt
- updatedAt
- name
- campaignUid
- endpointUid
- status: (WAITING_FOR_DOCUMENT|, WAITING_FOR_PROCESS, PROCESSING, PROCESSED, NOT_EXPLOITABLE, SUBSCRIPTION_ISSUE)
- userPseudoId
- uuid
Example:
&filter=campaignUid:8c4e55e2-5ff7-4584-8a37-59c8f149271b,status:PROCESSING &filter=status:PROCESSING|PROCESSED &filter=status:WAITING*
HTTP status code 202
Secured by OAuth2.0 - Hydra
Get the document as formatted data
Delete the document
get /documents/{documentId}
Get the document as formatted data
OAuth2.0 authentification required
URI Parameters
- documentId: required(string)
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- uid: required(string)
Aboutgoods generated unique ID
- createdAt: required(datetime)
When this object has been registered in AG system
- updatedAt: required(datetime)
The last time this entity had been updated in AG system
- dominantLanguage: required(string)
A locale format with the following pattern
{iso 639-1}-{ISO 3166-1}
- Usage : specifiy on which language the Receipt Analyzer should treat receipts
Example:
fr-FR
- status: required(one of WAITING_FOR_DOCUMENT, WAITING_FOR_PROCESS, PROCESSING, PROCESSED, NOT_EXPLOITABLE, SUBSCRIPTION_ISSUE)
As of today we have 6 status for differents states of an image in our systems, when everything is fine PROCESSED
- processReport: required(one of NO_ERROR, BAD_QUALITY_IMAGE, NOT_ENOUGH_TEXT, MULTIPLE_RECEIPT, UNREADABLE, BAD_LOCALE, NOT_RECEIPT, ERROR_JPG, BAD_URL, NOT_ANALYZED)
Process Report represent a more detailled reason about why a receipt has not been analyzed correctly A key to let the client knows what happened during analysis, helps you understand the status
NO_ERROR
=> Everything is fine, this come with thePROCESSED
status by defaultBAD_QUALITY_IMAGE
=> We detected a too blurry image or too dark, it can also be the resolution of the imageNOT_ENOUGH_TEXT
=> Self explicit, we have a threshold for the text recognition in image, if our OCR did not found enough text to generate a satisfiable amount of data, we abandon the ProcessMULTIPLE_RECEIPT
=> We do not handle multiple receipt in one image, when we detect this case, we stop the processUNREADABLE
=> Our OCR could not determine any Text in the imageBAD_LOCALE
=> We could not find any language for the detection to operate. This means that the Language or country is currently not supported by our systemNOT_RECEIPT
=> We didn't find any receipt in the imageERROR_IMAGE_FORMAT
=> The image format is not valid (not one of jpg, pdf, png)BAD_URL
=> No image has been found at the given URL (internal error)NOT_ANALYZED
=> The document has not been analyzed for the moment, this comes with theWAITING_FOR_DOCUMENT
,WAITING_FOR_PROCESS
orPROCESSING
statuses
- anomalyReport: (object)
Result of the anomaly analysis
- flags: required(array of string)
Array of flags. List of the available flags:
ORIGINAL_RECEIPT
=> No clues detectedIDENTICAL_EXISTING_FILE
=> Same MD5 already present in company's receiptsBARCODE_ALREADY_EXISTS
=> Same barcode already presentHIGH_FILE_SIMILARITY
=> Similar phash already presentSAME_SHOP_SAME_MOMENT
=> Receipt with same shop at same buyTime already presentEXISTING_PRODUCT_LIST
=> Receipt with same product list already presentHIGH_GLOBAL_CONTENT_SIMILARITY
=> Combination of the 2 previous flagsBANNED_SOFTWARE
=> Receipt with one of the editing software of the list present in its exifs- Adobe Photoshop
- Windows Photo Editor
- paint.net
- PhotoFiltre
- PicsArt
- PaintShop
- GIMP
- TouchRetouch
- Snapseed
- PhotoStudio
- ACDSee
- PhotoScape
- Aviary
- potentialDuplicateReceipts: required(array of duplicateReceipt)
Items: duplicateReceipt
- uid: required(string)
Uid of the duplicated receipt
- flags: required(array of string)
Array of flags that were found for this duplicated document regarding the original receipt.
Example:
{ "uid": "e67c9571-47a7-42cd-8439-c94bc9d5e478", "flags": ["SAME_SHOP_SAME_MOMENT", "EXISTING_PRODUCT_LIST", "HIGH_GLOBAL_CONTENT_SIMILARITY"] }
- uid: required(string)
Example:
{ "flags": [ "BARCODE_ALREADY_EXISTS", "SAME_SHOP_SAME_MOMENT", "EXISTING_PRODUCT_LIST", "HIGH_GLOBAL_CONTENT_SIMILARITY" ], "potentialDuplicateReceipts": [ { "uid": "e67c9571-47a7-42cd-8439-c94bc9d5e478", "flags": ["SAME_SHOP_SAME_MOMENT", "EXISTING_PRODUCT_LIST", "HIGH_GLOBAL_CONTENT_SIMILARITY"] }, { "uid": "c1b2997b-c6a1-48c2-819e-300fe61db5e9", "flags": ["SAME_SHOP_SAME_MOMENT", "BARCODE_ALREADY_EXISTS"] } ] }
- flags: required(array of string)
- imageUrl: required(string)
URL for getting image from a cdn repository
- name: required(string)
Id of this document that client (aka you) had set when sending the image of document in the first place.
- Helps you to retrieve a document by it's name
- endpointUid: (string)
Endpoint id that had served this document
- campaignUid: (string)
If this document is a part of promotion campaign, id of campaign is displayed here
- userPseudoId: (string)
This ID correspond to a custom and client managed id specified by the developer of the application that had setup AGKit SDK (aka you in general).
- This can also come from an userId that you sent over this very API when sending a receipt
- processedRules: (object)
- name: required(string)
Name of the whole rule, must be unique for a given campaign
- uid: required(string)
unique uid of the rule
- priceRule: (object)
rule that defines rule on prices
- eligibleOnly: required(number)
minimum price of all matched items
- totalAmount: (number)
minimum total amount of receipt
- isMatched: required(boolean)
tells if the rule is matched in receipt
Example:
{ "eligibleOnly": 20.25, "totalAmount": 40, "isMatched": false }
- eligibleOnly: required(number)
- itemRule: required(object)
rule that defines terms to search and various conditions of search (or, and)
- term: (string)
Just a simple rule to look for this term in the receipt. Mutually exclusive with AND and TERM.
- quantityRequired: (integer)
minimum required quantity of term or clause (AND/OR) to find. Is added by Rulio by default = 1.
- strategy: (string)
strategy used to count the item for quantityRequired
Example:
QUANTITY | BUNDLE | QUANTITY_TIMES_BUNDLE
- or: (array of object)
The result of running OR Rule with itemsMatched and isMatched.
Items:
- and: (array of object)
The result of running AND Rule with itemsMatched and isMatched.
Items:
- not: (array of object)
The result of running NOT Rule with itemsMatched and isMatched.
Items:
- isMatched: required(boolean)
tells if the rule is matched in receipt
- itemsMatched: (array of string)
List of IDs of items that were matched by term. Even if the rule is false (quantityRequired is not met), can have some IDs.
- quantityMatched: (integer)
quantity of term or terms in clause (AND/OR) found (even if the quantityRequired is not met). Can be different from the number of items in itemsMatched (one product line - but bought twice)
Example:
{ "quantityRequired": 2, "strategy": "QUANTITY", "or": [ { "term": "Labeyrie", "quantityRequired": 1, "strategy": "QUANTITY", "itemsMatched": [ "3" ], "isMatched": true, "quantityMatched": 1 }, { "term": "Blini", "quantityRequired": 1, "strategy": "QUANTITY", "itemsMatched": [ "1", "2" ], "quantityMatched": 2, "isMatched": true } ], "not": [ { "isMatched": true, "term": "Auchan", "itemsMatched": [ "2" ], "quantityMatched": 1 }, { "isMatched": false, "term": "Cora", "itemsMatched": [], "quantityMatched": 0 }, { "isMatched": false, "term": "Carrefour", "itemsMatched": [], "quantityMatched": 0 } ], "itemsMatched": [ "3", "1" ], "quantityMatched": 2, "isMatched": true }
- term: (string)
- signRule: (object)
rule that defines the list of signs for a given promotion
- signList: required(array of string)
List of sign eligible for the promotion.
- isMatched: required(boolean)
tells if the rule is matched in receipt
Example:
{ "signList": [ "Auchan", "Cora" ], "isMatched": true }
- signList: required(array of string)
- dateRule: required(object)
rule that defines range of dates for a given promotion
- min: required(string)
start date of the promotion/campaign
- max: required(string)
last date of the promotion/campaign
- isMatched: required(boolean)
tells if the rule is matched in receipt
Example:
{ "min": "2019-01-01", "max": "2019-11-01", "isMatched": true }
- min: required(string)
- allRulesMatched: required(boolean)
summarizes all rules matching, true if all rules are matched
- totalPriceOfMatchedItems: required(number)
total price of items that matched ItemRule
Example:
{ "name": "Labeyrie", "uid": "123", "itemRule": { "quantityRequired": 2, "strategy": "QUANTITY", "or": [ { "term": "Labeyrie", "quantityRequired": 1, "strategy": "QUANTITY", "itemsMatched": [ "3" ], "isMatched": true, "quantityMatched": 1 }, { "term": "Blini", "quantityRequired": 1, "strategy": "QUANTITY", "itemsMatched": [ "1", "2" ], "quantityMatched": 2, "isMatched": true } ], "not": [ { "isMatched": true, "term": "Auchan", "itemsMatched": [ "2" ], "quantityMatched": 1 }, { "isMatched": false, "term": "Cora", "itemsMatched": [], "quantityMatched": 0 } ], "itemsMatched": [ "3", "1" ], "quantityMatched": 2, "isMatched": true }, "dateRule": { "min": "2019-01-01", "max": "2019-11-01", "isMatched": true }, "priceRule": { "eligibleOnly": 15, "isMatched": false }, "signRule": { "signList": [ "Cora", "Auchan", "Carrefour" ], "isMatched": true }, "allRulesMatched": false, "totalPriceOfMatchedItems": 9.74 }
- name: required(string)
- appId: (string)
If this document has been received from AGKit (our mobile application SDK), this field allow to identify the application which have been used to send the document
- introspectionData: (object)
Introspection data that is infered from a given image, those data are useful to identify an image / receipt from its binary data
- resolution: required(object)
Size of the image
- width: required(number)
- height: required(number)
- size: (number)
Size in a human readable format (Mb or Kb)
- exif: (object)
Exif extracted from the image, possible keys available:
- cameraMake
- cameraModel
- software
- bitsPerSample
- imageWidth
- imageHeight
- imageDescription
- imageOrientation
- imageCopyright
- imageDatetime
- originalDatetime
- digitizeDatetime
- subsecondTime
- fstop
- exposureProgram
- isoSpeed
- subjectDistance
- exposureBias
- flashUsed
- flashReturnedLight
- flashMode
- meteringMode
- focalLength
- focalLength35mm
- gpsAltitude
- gpsPrecision
- lensFocalLengthMin
- lensFocalLengthMax
- lensFstopMin
- lensFstopMax
- lensMake
- lensModel
- focalPlaneXRes
- focalPlaneYRes
- gpsCoordinate
- resolution: required(object)
- data: (object)
Actual data that has been extracted from the receipt content Note: This field will be empty on the first document post response, as the process is running asynchronously, expect this field to be filled with data when the Status is set to
PROCESSED
- buyHour: (time-only)
🕐 The hour displayed on the receipt (ISO 8601 Time 'hh:mm:ss')
- buyDate: (date-only)
🗓 Date of buy for the receipt (ISO 8601 Date 2018-10-22)
- articleCount: (number)
Number of items in cart for this receipt
- total: (number)
🆙 Total amount paid by the customer (can be negative !)
- totalMax: (number)
🆕 Total value of the merchandises for this receipt, this can be different from what user paid (total field).
- payment: (array of string)
🆕 Buying mode or payment methods, can have multiple payments methods for a receipt, "UNKNOWN" if nothing was found
Example:
["CARD", "CASH", "CHEQUE", "UNKNOWN"]
- locale: (string)
Locale specified for this receipt analysis
- shop: (object)
🏬 This object represent the store / shop we found for this receipt, most of the time it will be only one data per field, but we can also send a top 3 with some significative accuracy
- city: (string)
City where the store of this buy is located
- sign: (string)
Store name or sign name / Brand of the shop
- subSign: (string)
SubSign of the shop
- phone: (string)
Phone number of the store
- address: (string)
Exact address of the store
- postalCode: (string)
Postal code for the city where we found this store
- geoLocation: (string)
Latitude and longitude for the shop, following https://tools.ietf.org/html/rfc5870 standard (example 13.4125,103.8667)
Example:
{ "city": "Toulon", "sign": "CARREFOUR", "subSign": "MARKET", "phone": "0494419879", "address": "CENTRE CIAL MAYOL", "postalCode": "83000", "geoLocation" : "48.31763410000001,1.9993057" }
- city: (string)
- items: required(array of object)
Items with products detected
Items: items
- id: required(string)
An ID unique to this list of item. Mainly used to identify this particular item in this receipt for our rule processor to indicate which item has matched a given rule.
- rawLabel: (string)
Raw line read on the receipt by OCR
- shortLabel: (string)
Detected short label from rawLabel, we remove price and other non label data from rawLabel
- quantity: (number)
Quantity of item detected in receipt
- unitPrice: (number)
A price detected for one piece of this item
- packageUnity: (string)
Package unity for item, for example Kg
- mass: (number)
The mass detected for the package, example 5 (Kg from PackageUnity)
- flags: (array of string)
Some notable characteristics detected on the product, BIO for example, or gluten free or anything special
Example:
["bio", "aop"]
- price: (number)
Total price for this item, (if found quantity > 1, we multiply to get this data, or we read it from receipt)
- product: (object)
What we understood from the item, we link item data to a clean and well organized product from our database and we put informations about it here.
- category: (string)
A fully qualified AGCategory name for this product infered by our AI algorithm, retrieve the complete list of categories here https://doc.kweeri.io/resources/list-of-product-categories.html
- categoryUid: (string)
Reference UID from Aboutgoods taxonomy
- brand: (string)
Fully qualified Brand name of product if displayed in label infered by our AI algorithm
- brandUid: (string)
Reference UID from Aboutgoods brands taxonomy of product if displayed in label infered by our AI algorithm
- brandLine: (string)
⚠️ deprecated: this field will be removed in future releases
- gtin: (string)
If present on the receipt, we extract the GTIN (EAN 13) Code
Example:
{ "brand": "PETIT NAVIRE", "brandLine": "FILETS DE THON", "category" : "tinned_fish", "categoryUid" : "4e54e68c-637f-a7d9-d509-f7e32b849f60", "gtin" : "1234567890123" }
- category: (string)
- bundle: (number)
Number of products in a pack. 16 x 125g, 16 is the bundle, 125g is the mass.
Example:
{ "id": "fa2cb", "rawLabel": "x5506 OATS QUAKER BIO", "quantity": 1, "unitPrice": 1.64, "packageUnity": "Kg", "mass": 1, "flags": [ "bio" ], "price": 1.64, "bundle": 1, "product": { "category": "food > sweet_grocery > cereals > breakfast_cereals", "categoryUid": "33f92698-284b-fd44-575a-f1e9cea9973e", "brand": "QUAKER", "brandUid": "05a5069d-fd64-b97b-ac06-101dcfc1686c" } }
- id: required(string)
- barcodes: (array of object)
🆕 1D or 2D codes found in the image after cropping the document from the rest of image
Items: items
- type: required(one of EAN-2, EAN-5, EAN-8, UPC-E, ISBN-10, UPC-A, EAN-13, ISBN-13, COMPOSITE, I2/5, DataBar, DataBar-Exp, Codabar, CODE-39, CODE-93, CODE-128, PDF417, QR-Code, UNKNOWN)
type of code detected
- data: required(string)
Data read from the code
- location: required(object)
- x: required(number)
x
location of the code in image - y: required(number)
y
location of the code in image - width: required(number)
width
of the code in image - height: required(number)
height
of the code in image
- x: required(number)
Example:
[{ "type": "CODE-128", "data": "12456789", "location": { "x": 0.0, "y": 0.0, "width": 50, "height": 20 } }]
- type: required(one of EAN-2, EAN-5, EAN-8, UPC-E, ISBN-10, UPC-A, EAN-13, ISBN-13, COMPOSITE, I2/5, DataBar, DataBar-Exp, Codabar, CODE-39, CODE-93, CODE-128, PDF417, QR-Code, UNKNOWN)
Example:
{ "shop": { "city": "Toulon", "sign": "CARREFOUR", "subSign": "MARKET", "phone": "0494419879", "address": "CENTRE CIAL MAYOL", "postalCode": "83000" }, "articleCount": 2, "total": 4.25, "totalMax": 4, "buyDate": "2016-12-07", "buyHour": "11:08:00", "items": [ { "id": "fa2cb", "rawLabel": "x5506 OATS QUAKER", "quantity": 1, "unitPrice": 1.64, "packageUnity": "Kg", "mass": 1, "price": 1.64, "bundle": 1, "product": { "category": "breakfast_cereals", "brand": "QUAKER" } }, { "id": "9d7fb", "rawLabel": "4 BTE 6X33CL COCA CO 2,61", "shortLabel": "BTE 6X33CL COCA CO", "quantity": 1, "unitPrice": 2.61, "packageUnity": "CL", "mass": 33, "bundle": 6, "price": 2.61, "product": { "category": "soda", "categoryUid": "efb24280-2dd9-423d-91d3-263fc780b6df", "brand": "COCA COLA" } } ] }
- buyHour: (time-only)
Example:
{
"uid": "89cd32b8-15e9-4e63-af5e-9e85da188fa1",
"createdAt": "2019-09-20T08:19:57Z",
"updatedAt": "2019-09-20T08:20:09Z",
"dominantLanguage": "fr-FR",
"name": "receiptTest",
"campaignUid": "fc928982-3acc-4aea-bca3-e50d22e0b6ca",
"userPseudoId": "8335c8d1-5ae7-440c-90d1-50543c86d9b4",
"status": "PROCESSED",
"processReport": "NO_ERROR",
"imageUrl": "https://receipt.agkit.io/v2/documents/89cd32b8-15e9-4e63-af5e-9e85da188fa1/show",
"data": {
"shop": {
"city": "Toulon",
"sign": "CARREFOUR",
"subSign": "MARKET",
"phone": "0494419879",
"address": "CENTRE CIAL MAYOL",
"postalCode": "83000",
"geoLocation": "48.31763410000001,1.9993057"
},
"articleCount": 3,
"total": 6.51,
"totalMax": 6.26,
"buyDate": "2016-12-07",
"buyHour": "11:08:00",
"payment": [
"CASH",
"CARD"
],
"barcodes": [
{
"type": "CODE-128",
"data": "12456789",
"location": {
"x": 0,
"y": 0,
"width": 50,
"height": 20
}
}
],
"items": [
{
"id": "fa2cb",
"rawLabel": "x5506 OATS QUAKER 1,64",
"quantity": 1,
"unitPrice": 1.64,
"packageUnity": "Kg",
"mass": 1,
"price": 1.64,
"bundle": 1,
"product": {
"category": "food > sweet_grocery > cereals > breakfast_cereals",
"categoryUid": "33f92698-284b-fd44-575a-f1e9cea9973e",
"brand": "QUAKER",
"brandUid": "05a5069d-fd64-b97b-ac06-101dcfc1686c"
}
},
{
"id": "47267",
"rawLabel": "PEPSI REGULAR 2,26",
"shortLabel": "PEPSI REGULAR",
"quantity": 1,
"unitPrice": 2.26,
"bundle": 1,
"price": 2.26,
"product": {
"category": "drink > alcohol_free > soda",
"categoryUid": "efb24280-2dd9-423d-91d3-263fc780b6df",
"brand": "PEPSI",
"brandUid": "822ed5c0-1d5c-0ec1-0cf9-5b62b2caecca"
}
},
{
"id": "9d7fb",
"rawLabel": "4 BTE 6X33CL COCA CO 2,61",
"shortLabel": "BTE 6X33CL COCA CO",
"quantity": 1,
"unitPrice": 2.61,
"packageUnity": "CL",
"mass": 33,
"bundle": 6,
"price": 2.61,
"product": {
"category": "drink > alcohol_free > soda",
"categoryUid": "efb24280-2dd9-423d-91d3-263fc780b6df",
"brand": "COCA COLA > CLASSIC",
"brandUid": "f2eaa047-39d8-0855-b0e3-098b2bbec0d5"
}
}
]
},
"processedRules": {
"uid": "1234",
"name": "Quaker",
"dateRule": {
"min": "2019-01-01",
"max": "2019-11-01",
"isMatched": false
},
"signRule": {
"signList": [
"Carrefour"
],
"isMatched": true
},
"itemRule": {
"term": "Quaker",
"quantityRequired": 1,
"strategy": "QUANTITY",
"isMatched": true,
"itemsMatched": [
"fa2cb"
],
"quantityMatched": 1
},
"allRulesMatched": false,
"totalPriceOfMatchedItems": 1.64
},
"anomalyReport": {
"flags": [
"BARCODE_ALREADY_EXISTS",
"SAME_SHOP_SAME_MOMENT",
"EXISTING_PRODUCT_LIST",
"HIGH_GLOBAL_CONTENT_SIMILARITY"
],
"potentialDuplicateReceipts": [
{
"uid": "e67c9571-47a7-42cd-8439-c94bc9d5e478",
"flags": [
"SAME_SHOP_SAME_MOMENT",
"EXISTING_PRODUCT_LIST",
"HIGH_GLOBAL_CONTENT_SIMILARITY"
]
},
{
"uid": "c1b2997b-c6a1-48c2-819e-300fe61db5e9",
"flags": [
"BARCODE_ALREADY_EXISTS"
]
}
]
},
"introspectionData": {
"resolution": {
"width": 2608,
"height": 4632
},
"size": 3564061,
"exif": {
"bitsPerSample": 8,
"cameraMake": "",
"cameraModel": "",
"digitizeDatetime": "",
"exposureBias": 0,
"exposureProgram": 0,
"flashMode": 0,
"flashReturnedLight": 0,
"flashUsed": 0,
"focalLength": 0,
"focalLength35mm": 0,
"focalPlaneXRes": 0,
"focalPlaneYRes": 0,
"fstop": 0,
"gpsAltitude": 0,
"gpsCoordinate": "0.000000,0.000000",
"gpsPrecision": 0,
"imageCopyright": "",
"imageDatetime": "",
"imageDescription": "",
"imageHeight": 0,
"imageOrientation": 0,
"imageWidth": 0,
"isoSpeed": 0,
"lensFocalLengthMax": 0,
"lensFocalLengthMin": 0,
"lensFstopMax": 0,
"lensFstopMin": 0,
"lensMake": "",
"lensModel": "",
"meteringMode": 0,
"originalDatetime": "",
"software": "",
"subjectDistance": 0,
"subsecondTime": ""
}
}
}
HTTP status code 400
Body
Media type: application/json
Type: object
Properties- error: required(string)
Example:
{ "badRequest" : "You are missing some field or they are malformed" }
HTTP status code 404
Body
Media type: application/json
Type: object
Properties- error: required(string)
Example:
{ "notFound" : "resource has not been found on this system" }
Secured by OAuth2.0 - Hydra
delete /documents/{documentId}
Delete the document
OAuth2.0 authentification required
URI Parameters
- documentId: required(string)
HTTP status code 204
Image has been deleted
HTTP status code 403
You cannot access this resources with this token
HTTP status code 404
Body
Media type: application/json
Type: object
Properties- error: required(string)
Example:
{ "notFound" : "resource has not been found on this system" }
Secured by OAuth2.0 - Hydra
Render the image corresponding to the document
get /documents/{documentId}/show
Render the image corresponding to the document
URI Parameters
- documentId: required(string)
HTTP status code 200
Body
Media type: image/jpg
Type: file
Media type: image/png
Type: file
Media type: application/pdf
Type: file
HTTP status code 403
You cannot access this resources with this token
HTTP status code 404
Body
Media type: application/json
Type: object
Properties- error: required(string)
Example:
{ "notFound" : "resource has not been found on this system" }
/campaigns
Campaign
Campaign represents a promotion campaign valid during a certain period of time and linked to a set of rules that have to be matched during receipt analysis. Any document that goes through a campaign will be checked against the set of rules (detection of things in the document) that are specified within the campaign.
Get the list of campaigns by filters
Create a new campaign
get /campaigns
Get the list of campaigns by filters
OAuth2.0 authentification required AND the feature 'PROMOTIONS' must be activated
Query Parameters
- page: (integer)
Specify the page that you want to retrieve
- per_page: (integer - default: 10 - minimum: 10 - maximum: 1000)
Specify the amount of items that will be retrieved per page
- sort: (one of uid, createdAt, updatedAt, name)
Sort by filter/type
- sort_direction: (one of asc, desc)
Specify sort direction
- filter: (string)
List of properties, comma separated with their filter values. Available filters:
- uid
- createdAt
- updatedAt
- name
Example:
&filter=name:test3 &filter=name:test* &filter=name:test|test1|test2
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- countPerPage: required(integer)
Number of result returned by this page
- totalEntities: required(integer)
Total number of results available for this request
- totalPages: required(integer)
Total number of pages available for this request
- nextPageUri: required(string)
Request URI (URL without hostname) that allow to go to the next page of result, can be empty if there is no next page
Example:
/{entity}?page=1&per_page=3
- prevPageUri: required(string)
Request URI (URL without hostname) that allow to go to the previous page of result, can be empty if no previous page
Example:
/{entity}?page=1&per_page=3
- results: required(array of campaign)
Items: campaign
- uid: required(string)
UID of this receipt attributed by Aboutgoods System to managed receipts
- createdAt: required(datetime)
When this object has been registered in AG system
- updatedAt: required(datetime)
The last time this entity had been updated in AG system
- dominantLanguage: required(string)
A locale format with the following pattern
{iso 639-1}-{ISO 3166-1}
- Usage : specifiy on which language the Receipt Analyzer should treat receipts
Example:
fr-FR
- name: required(string)
Id given by the client to allow client to retrieve this exact document after analysis
- rules: required(object)
Rules for detection of data inside all documents that are process in the context of this campaign
- name: required(string)
Name of the whole rule, must be unique for a given campaign
- uid: required(string)
Unique uid of the rule
- priceRule: (object)
Rule that defines rule on prices
- eligibleOnly: required(number)
minimum price of all matched items. Float format.
- totalAmount: (number)
minimum total amount of receipt. Float format.
- eligibleOnly: required(number)
- itemRule: required(object)
Rule that defines terms to search and various conditions of search (or, and)
- quantityRequired: (integer - default: 1)
Minimum required quantity this item rule must be found
- strategy: (one of QUANTITY, BUNDLE, QUANTITY_TIMES_BUNDLE - default: QUANTITY_TIMES_BUNDLE)
Strategy used to count items for the quantityRequired field, to get description of each setting please read this article from our Knowledge Base
- and: (array of object)
AND Rule, means that this entity contains ItemRules that system will search in document to match them all. Mutually exclusive with OR and TERM.
Items:
- or: (array of object)
OR Rule, means that all ItemRules in array system will search in document with an inclusive OR. Mutually exclusive with AND and TERM.
Items:
- not: (array of object)
itemRules only containing terms. AND/OR are not allowed.
Items:
- term: (string)
Just a simple rule to look for this term in the receipt. Mutually exclusive with AND and TERM.
Example:
{ "and": [ { "term": "Dodot" }, { "or": [ { "term": "geant vert" }, { "term": "g vert" } ], "quantityRequired": 2, "strategy": "QUANTITY" } ], "not": [ { "term": "haricot vert" } ] }
- quantityRequired: (integer - default: 1)
- signRule: (object)
Rule that defines the list of signs for a given promotion
- signList: required(array of string)
List of sign eligible for the promotion.
Example:
{ "signList": [ "Auchan", "Cora" ] }
- signList: required(array of string)
- dateRule: required(object)
Rule that defines range of dates for a given promotion
- min: required(string)
start date of the promotion/campaign
- max: required(string)
last date of the promotion/campaign
- min: required(string)
Example:
{ "name": "Labeyrie", "uid": "123", "dateRule": { "min": "2019-01-01", "max": "2019-11-01" }, "priceRule": { "eligibleOnly": 20.25, "totalAmount": 40 }, "signRule": { "signList": [ "Cora", "Auchan", "Carrefour" ] }, "itemRule": { "or": [ { "term": "Labeyrie" }, { "term": "Blini" } ], "quantityRequired": 2, "strategy": "QUANTITY", "not": [ { "term": "Auchan" }, { "term": "Cora" } ] } }
- name: required(string)
- companyId: required(string)
ID of the company which owns this Campaign (automatically set with Auth0 connection)
- outgoingUrl: (string)
A URL that will be called when a document analysis is over. This URL must handle a document POST request with analysis in JSON.
A URL placeholder replacer allows you to specify the some values to be replaced when the outgoingUrl is triggered. Here are the possible values handled by our replacer:
{document_uid}
{document_name}
{endpoint_uid}
{endpoint_name}
{campaign_uid}
{campaign_name}
{company_uid}
For example, you can set the outgoingUrl to
https://myCallbackUrl/post/{endpoint_name}/{document_name}
to make it easier for you to retrieve the endpoint and the document, since the values will be replaced by the actual ones.
Example:
{ "uid": "003473db-f05b-4f72-a6a7-fffa39ed96b9", "createdAt": "2019-10-10T13:20:34Z", "updatedAt": "2019-10-10T13:20:34Z", "outgoingUrl": "https://myCallbackUrl/post", "dominantLanguage": "fr-FR", "name": "Test de campagne", "companyId": "myCompany", "rules": { "uid": "azertyuiop", "name": "Test de rules", "dateRule": { "min": "2010-09-01", "max": "2019-09-30" }, "priceRule": { "eligibleOnly": 5 }, "signRule": { "signList": [ "carrefour" ] }, "itemRule": { "quantityRequired": 1, "strategy": "QUANTITY", "or": [ { "quantityRequired": 1, "strategy": "QUANTITY", "term": "tomato" }, { "quantityRequired": 1, "strategy": "QUANTITY", "term": "carrots" } ] } } }
- uid: required(string)
HTTP status code 400
Filter malformed or invalid filter key
HTTP status code 403
You cannot access this resources with this token
Secured by OAuth2.0 - Hydra
post /campaigns
Create a new campaign
OAuth2.0 authentification required AND the feature 'PROMOTIONS' must be activated
Body
Media type: application/json
Type: object
Properties- name: required(string)
Name that client give to a promotion campaign to better retrieve it
Forbidden caracters when naming a campaign
: | & * # , ?
- rules: (object)
Rules for detection of data inside all documents that are process in the context of this campaign
- name: required(string)
Name of the whole rule, must be unique for a given campaign
- uid: required(string)
Unique uid of the rule
- priceRule: (object)
Rule that defines rule on prices
- eligibleOnly: required(number)
minimum price of all matched items. Float format.
- totalAmount: (number)
minimum total amount of receipt. Float format.
- eligibleOnly: required(number)
- itemRule: required(object)
Rule that defines terms to search and various conditions of search (or, and)
- quantityRequired: (integer - default: 1)
Minimum required quantity this item rule must be found
- strategy: (one of QUANTITY, BUNDLE, QUANTITY_TIMES_BUNDLE - default: QUANTITY_TIMES_BUNDLE)
Strategy used to count items for the quantityRequired field, to get description of each setting please read this article from our Knowledge Base
- and: (array of object)
AND Rule, means that this entity contains ItemRules that system will search in document to match them all. Mutually exclusive with OR and TERM.
Items:
- or: (array of object)
OR Rule, means that all ItemRules in array system will search in document with an inclusive OR. Mutually exclusive with AND and TERM.
Items:
- not: (array of object)
itemRules only containing terms. AND/OR are not allowed.
Items:
- term: (string)
Just a simple rule to look for this term in the receipt. Mutually exclusive with AND and TERM.
Example:
{ "and": [ { "term": "Dodot" }, { "or": [ { "term": "geant vert" }, { "term": "g vert" } ], "quantityRequired": 2, "strategy": "QUANTITY" } ], "not": [ { "term": "haricot vert" } ] }
- quantityRequired: (integer - default: 1)
- signRule: (object)
Rule that defines the list of signs for a given promotion
- signList: required(array of string)
List of sign eligible for the promotion.
Example:
{ "signList": [ "Auchan", "Cora" ] }
- signList: required(array of string)
- dateRule: required(object)
Rule that defines range of dates for a given promotion
- min: required(string)
start date of the promotion/campaign
- max: required(string)
last date of the promotion/campaign
- min: required(string)
Example:
{ "name": "Labeyrie", "uid": "123", "dateRule": { "min": "2019-01-01", "max": "2019-11-01" }, "priceRule": { "eligibleOnly": 20.25, "totalAmount": 40 }, "signRule": { "signList": [ "Cora", "Auchan", "Carrefour" ] }, "itemRule": { "or": [ { "term": "Labeyrie" }, { "term": "Blini" } ], "quantityRequired": 2, "strategy": "QUANTITY", "not": [ { "term": "Auchan" }, { "term": "Cora" } ] } }
- name: required(string)
- dominantLanguage: required(string)
A locale format with the following pattern
Example:
fr-FR
- outgoingUrl: (string)
A URL that will be called when a document analysis is over. This URL must handle a document POST request with analysis in JSON.
A URL placeholder replacer allows you to specify the some values to be replaced when the outgoingUrl is triggered. Here are the possible values handled by our replacer:
{document_uid}
{document_name}
{endpoint_uid}
{endpoint_name}
{campaign_uid}
{campaign_name}
{company_uid}
For example, you can set the outgoingUrl to
https://myCallbackUrl/post/{endpoint_name}/{document_name}
to make it easier for you to retrieve the endpoint and the document, since the values will be replaced by the actual ones.
Example:
{
"outgoingUrl": "https://myCallbackUrl/post",
"dominantLanguage": "fr-FR",
"name": "CampaignTest",
"rules": {
"uid": "azertyuiop",
"name": "RulesTest",
"dateRule": {
"min": "2010-09-01",
"max": "2019-09-30"
},
"priceRule": {
"eligibleOnly": 5
},
"signRule": {
"signList": [
"carrefour"
]
},
"itemRule": {
"quantityRequired": 1,
"strategy": "QUANTITY",
"or": [
{
"quantityRequired": 1,
"strategy": "QUANTITY",
"term": "tomato"
},
{
"quantityRequired": 1,
"strategy": "QUANTITY",
"term": "carrots"
}
]
}
}
}
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- uid: required(string)
UID of this receipt attributed by Aboutgoods System to managed receipts
- createdAt: required(datetime)
When this object has been registered in AG system
- updatedAt: required(datetime)
The last time this entity had been updated in AG system
- dominantLanguage: required(string)
A locale format with the following pattern
{iso 639-1}-{ISO 3166-1}
- Usage : specifiy on which language the Receipt Analyzer should treat receipts
Example:
fr-FR
- name: required(string)
Id given by the client to allow client to retrieve this exact document after analysis
- rules: required(object)
Rules for detection of data inside all documents that are process in the context of this campaign
- name: required(string)
Name of the whole rule, must be unique for a given campaign
- uid: required(string)
Unique uid of the rule
- priceRule: (object)
Rule that defines rule on prices
- eligibleOnly: required(number)
minimum price of all matched items. Float format.
- totalAmount: (number)
minimum total amount of receipt. Float format.
- eligibleOnly: required(number)
- itemRule: required(object)
Rule that defines terms to search and various conditions of search (or, and)
- quantityRequired: (integer - default: 1)
Minimum required quantity this item rule must be found
- strategy: (one of QUANTITY, BUNDLE, QUANTITY_TIMES_BUNDLE - default: QUANTITY_TIMES_BUNDLE)
Strategy used to count items for the quantityRequired field, to get description of each setting please read this article from our Knowledge Base
- and: (array of object)
AND Rule, means that this entity contains ItemRules that system will search in document to match them all. Mutually exclusive with OR and TERM.
Items:
- or: (array of object)
OR Rule, means that all ItemRules in array system will search in document with an inclusive OR. Mutually exclusive with AND and TERM.
Items:
- not: (array of object)
itemRules only containing terms. AND/OR are not allowed.
Items:
- term: (string)
Just a simple rule to look for this term in the receipt. Mutually exclusive with AND and TERM.
Example:
{ "and": [ { "term": "Dodot" }, { "or": [ { "term": "geant vert" }, { "term": "g vert" } ], "quantityRequired": 2, "strategy": "QUANTITY" } ], "not": [ { "term": "haricot vert" } ] }
- quantityRequired: (integer - default: 1)
- signRule: (object)
Rule that defines the list of signs for a given promotion
- signList: required(array of string)
List of sign eligible for the promotion.
Example:
{ "signList": [ "Auchan", "Cora" ] }
- signList: required(array of string)
- dateRule: required(object)
Rule that defines range of dates for a given promotion
- min: required(string)
start date of the promotion/campaign
- max: required(string)
last date of the promotion/campaign
- min: required(string)
Example:
{ "name": "Labeyrie", "uid": "123", "dateRule": { "min": "2019-01-01", "max": "2019-11-01" }, "priceRule": { "eligibleOnly": 20.25, "totalAmount": 40 }, "signRule": { "signList": [ "Cora", "Auchan", "Carrefour" ] }, "itemRule": { "or": [ { "term": "Labeyrie" }, { "term": "Blini" } ], "quantityRequired": 2, "strategy": "QUANTITY", "not": [ { "term": "Auchan" }, { "term": "Cora" } ] } }
- name: required(string)
- companyId: required(string)
ID of the company which owns this Campaign (automatically set with Auth0 connection)
- outgoingUrl: (string)
A URL that will be called when a document analysis is over. This URL must handle a document POST request with analysis in JSON.
A URL placeholder replacer allows you to specify the some values to be replaced when the outgoingUrl is triggered. Here are the possible values handled by our replacer:
{document_uid}
{document_name}
{endpoint_uid}
{endpoint_name}
{campaign_uid}
{campaign_name}
{company_uid}
For example, you can set the outgoingUrl to
https://myCallbackUrl/post/{endpoint_name}/{document_name}
to make it easier for you to retrieve the endpoint and the document, since the values will be replaced by the actual ones.
Example:
{
"uid": "003473db-f05b-4f72-a6a7-fffa39ed96b9",
"createdAt": "2019-10-10T13:20:34Z",
"updatedAt": "2019-10-10T13:20:34Z",
"outgoingUrl": "https://myCallbackUrl/post",
"dominantLanguage": "fr-FR",
"name": "Test de campagne",
"companyId": "myCompany",
"rules": {
"uid": "azertyuiop",
"name": "Test de rules",
"dateRule": {
"min": "2010-09-01",
"max": "2019-09-30"
},
"priceRule": {
"eligibleOnly": 5
},
"signRule": {
"signList": [
"carrefour"
]
},
"itemRule": {
"quantityRequired": 1,
"strategy": "QUANTITY",
"or": [
{
"quantityRequired": 1,
"strategy": "QUANTITY",
"term": "tomato"
},
{
"quantityRequired": 1,
"strategy": "QUANTITY",
"term": "carrots"
}
]
}
}
}
HTTP status code 400
Body
Media type: application/json
Type: object
Properties- error: required(string)
Example:
{ "notFound" : "resource has not been found on this system" }
HTTP status code 406
Body
Media type: application/json
Type: object
Properties- error: required(string)
Example:
{ "notAcceptable" : "Some fields contains invalid characters" }
Secured by OAuth2.0 - Hydra
Get statistics of campaigns by filters
get /campaigns/stats
Get statistics of campaigns by filters
OAuth2.0 authentification required AND the feature 'PROMOTIONS' must be activated
Query Parameters
- filter: (string)
List of properties, comma separated with their filter values. Available filters:
- uid
- createdAt
- updatedAt
- name
Example:
&filter=name:test3 &filter=name:test* &filter=name:test|test1|test2
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- countTotal: required(integer)
Number total of documents associated to the filtered request
- countByStatus: required(object)
- waitingForDocument: required(integer)
Number of documents with status WAITING_FOR_DOCUMENT
- waitingForProcess: required(integer)
Number of documents with status WAITING_FOR_PROCESS
- processing: required(integer)
Number of documents with status PROCESSING
- processed: required(integer)
Number of documents with status PROCESSED
- notExploitable: required(integer)
Number of documents with status NOT_EXPLOITABLE
- waitingForDocument: required(integer)
- countRulesMatched: required(integer)
Number of documents which matched a rule (at least one product matched in the document)
Example:
{
"countTotal": 9,
"countByStatus": {
"notExploitable": 1,
"processed": 1,
"processing": 1,
"waitingForDocument": 4,
"waitingForProcess": 2
},
"countRulesMatched": 1
}
Secured by OAuth2.0 - Hydra
Get campaign's information
Update data of a campaign
Delete the campaign and document(s) related
get /campaigns/{campaignId}
Get campaign's information
OAuth2.0 authentification required AND the feature 'PROMOTIONS' must be activated
URI Parameters
- campaignId: required(string)
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- uid: required(string)
UID of this receipt attributed by Aboutgoods System to managed receipts
- createdAt: required(datetime)
When this object has been registered in AG system
- updatedAt: required(datetime)
The last time this entity had been updated in AG system
- dominantLanguage: required(string)
A locale format with the following pattern
{iso 639-1}-{ISO 3166-1}
- Usage : specifiy on which language the Receipt Analyzer should treat receipts
Example:
fr-FR
- name: required(string)
Id given by the client to allow client to retrieve this exact document after analysis
- rules: required(object)
Rules for detection of data inside all documents that are process in the context of this campaign
- name: required(string)
Name of the whole rule, must be unique for a given campaign
- uid: required(string)
Unique uid of the rule
- priceRule: (object)
Rule that defines rule on prices
- eligibleOnly: required(number)
minimum price of all matched items. Float format.
- totalAmount: (number)
minimum total amount of receipt. Float format.
- eligibleOnly: required(number)
- itemRule: required(object)
Rule that defines terms to search and various conditions of search (or, and)
- quantityRequired: (integer - default: 1)
Minimum required quantity this item rule must be found
- strategy: (one of QUANTITY, BUNDLE, QUANTITY_TIMES_BUNDLE - default: QUANTITY_TIMES_BUNDLE)
Strategy used to count items for the quantityRequired field, to get description of each setting please read this article from our Knowledge Base
- and: (array of object)
AND Rule, means that this entity contains ItemRules that system will search in document to match them all. Mutually exclusive with OR and TERM.
Items:
- or: (array of object)
OR Rule, means that all ItemRules in array system will search in document with an inclusive OR. Mutually exclusive with AND and TERM.
Items:
- not: (array of object)
itemRules only containing terms. AND/OR are not allowed.
Items:
- term: (string)
Just a simple rule to look for this term in the receipt. Mutually exclusive with AND and TERM.
Example:
{ "and": [ { "term": "Dodot" }, { "or": [ { "term": "geant vert" }, { "term": "g vert" } ], "quantityRequired": 2, "strategy": "QUANTITY" } ], "not": [ { "term": "haricot vert" } ] }
- quantityRequired: (integer - default: 1)
- signRule: (object)
Rule that defines the list of signs for a given promotion
- signList: required(array of string)
List of sign eligible for the promotion.
Example:
{ "signList": [ "Auchan", "Cora" ] }
- signList: required(array of string)
- dateRule: required(object)
Rule that defines range of dates for a given promotion
- min: required(string)
start date of the promotion/campaign
- max: required(string)
last date of the promotion/campaign
- min: required(string)
Example:
{ "name": "Labeyrie", "uid": "123", "dateRule": { "min": "2019-01-01", "max": "2019-11-01" }, "priceRule": { "eligibleOnly": 20.25, "totalAmount": 40 }, "signRule": { "signList": [ "Cora", "Auchan", "Carrefour" ] }, "itemRule": { "or": [ { "term": "Labeyrie" }, { "term": "Blini" } ], "quantityRequired": 2, "strategy": "QUANTITY", "not": [ { "term": "Auchan" }, { "term": "Cora" } ] } }
- name: required(string)
- companyId: required(string)
ID of the company which owns this Campaign (automatically set with Auth0 connection)
- outgoingUrl: (string)
A URL that will be called when a document analysis is over. This URL must handle a document POST request with analysis in JSON.
A URL placeholder replacer allows you to specify the some values to be replaced when the outgoingUrl is triggered. Here are the possible values handled by our replacer:
{document_uid}
{document_name}
{endpoint_uid}
{endpoint_name}
{campaign_uid}
{campaign_name}
{company_uid}
For example, you can set the outgoingUrl to
https://myCallbackUrl/post/{endpoint_name}/{document_name}
to make it easier for you to retrieve the endpoint and the document, since the values will be replaced by the actual ones.
Example:
{
"uid": "003473db-f05b-4f72-a6a7-fffa39ed96b9",
"createdAt": "2019-10-10T13:20:34Z",
"updatedAt": "2019-10-10T13:20:34Z",
"outgoingUrl": "https://myCallbackUrl/post",
"dominantLanguage": "fr-FR",
"name": "Test de campagne",
"companyId": "myCompany",
"rules": {
"uid": "azertyuiop",
"name": "Test de rules",
"dateRule": {
"min": "2010-09-01",
"max": "2019-09-30"
},
"priceRule": {
"eligibleOnly": 5
},
"signRule": {
"signList": [
"carrefour"
]
},
"itemRule": {
"quantityRequired": 1,
"strategy": "QUANTITY",
"or": [
{
"quantityRequired": 1,
"strategy": "QUANTITY",
"term": "tomato"
},
{
"quantityRequired": 1,
"strategy": "QUANTITY",
"term": "carrots"
}
]
}
}
}
HTTP status code 403
You cannot access this resources with this token
HTTP status code 404
Body
Media type: application/json
Type: object
Properties- error: required(string)
Example:
{ "notFound" : "resource has not been found on this system" }
Secured by OAuth2.0 - Hydra
patch /campaigns/{campaignId}
Update data of a campaign
OAuth2.0 authentification required AND the feature 'PROMOTIONS' must be activated
URI Parameters
- campaignId: required(string)
Body
Media type: application/json
Type: object
Properties- name: required(string)
Name that client give to a promotion campaign to better retrieve it
Forbidden caracters when naming a campaign
: | & * # , ?
- rules: (object)
⚠️ You need to reprocess all the receipt if you want this change to be applied to already stored receipts ⚠️ Rules for detection of data inside all documents that are process in the context of this campaign
- name: required(string)
Name of the whole rule, must be unique for a given campaign
- uid: required(string)
Unique uid of the rule
- priceRule: (object)
Rule that defines rule on prices
- eligibleOnly: required(number)
minimum price of all matched items. Float format.
- totalAmount: (number)
minimum total amount of receipt. Float format.
- eligibleOnly: required(number)
- itemRule: required(object)
Rule that defines terms to search and various conditions of search (or, and)
- quantityRequired: (integer - default: 1)
Minimum required quantity this item rule must be found
- strategy: (one of QUANTITY, BUNDLE, QUANTITY_TIMES_BUNDLE - default: QUANTITY_TIMES_BUNDLE)
Strategy used to count items for the quantityRequired field, to get description of each setting please read this article from our Knowledge Base
- and: (array of object)
AND Rule, means that this entity contains ItemRules that system will search in document to match them all. Mutually exclusive with OR and TERM.
Items:
- or: (array of object)
OR Rule, means that all ItemRules in array system will search in document with an inclusive OR. Mutually exclusive with AND and TERM.
Items:
- not: (array of object)
itemRules only containing terms. AND/OR are not allowed.
Items:
- term: (string)
Just a simple rule to look for this term in the receipt. Mutually exclusive with AND and TERM.
Example:
{ "and": [ { "term": "Dodot" }, { "or": [ { "term": "geant vert" }, { "term": "g vert" } ], "quantityRequired": 2, "strategy": "QUANTITY" } ], "not": [ { "term": "haricot vert" } ] }
- quantityRequired: (integer - default: 1)
- signRule: (object)
Rule that defines the list of signs for a given promotion
- signList: required(array of string)
List of sign eligible for the promotion.
Example:
{ "signList": [ "Auchan", "Cora" ] }
- signList: required(array of string)
- dateRule: required(object)
Rule that defines range of dates for a given promotion
- min: required(string)
start date of the promotion/campaign
- max: required(string)
last date of the promotion/campaign
- min: required(string)
Example:
{ "name": "Labeyrie", "uid": "123", "dateRule": { "min": "2019-01-01", "max": "2019-11-01" }, "priceRule": { "eligibleOnly": 20.25, "totalAmount": 40 }, "signRule": { "signList": [ "Cora", "Auchan", "Carrefour" ] }, "itemRule": { "or": [ { "term": "Labeyrie" }, { "term": "Blini" } ], "quantityRequired": 2, "strategy": "QUANTITY", "not": [ { "term": "Auchan" }, { "term": "Cora" } ] } }
- name: required(string)
- dominantLanguage: (string)
⚠️ You need to reprocess all the receipt if you want this change to be applied to already stored receipts ⚠️ A locale format with the following pattern
Example:
fr-FR
- outgoingUrl: (string)
A URL that will be called when a document analysis is over. This URL must handle a document POST request with analysis in JSON.
A URL placeholder replacer allows you to specify the some values to be replaced when the outgoingUrl is triggered. Here are the possible values handled by our replacer:
{document_uid}
{document_name}
{endpoint_uid}
{endpoint_name}
{campaign_uid}
{campaign_name}
{company_uid}
For example, you can set the outgoingUrl to
https://myCallbackUrl/post/{endpoint_name}/{document_name}
to make it easier for you to retrieve the endpoint and the document, since the values will be replaced by the actual ones.
Example:
{
"outgoingUrl": "https://myCallbackUrl/post",
"dominantLanguage": "fr-FR",
"name": "CampaignTest",
"rules": {
"uid": "azertyuiop",
"name": "RulesTest",
"dateRule": {
"min": "2010-09-01",
"max": "2019-09-30"
},
"priceRule": {
"eligibleOnly": 5
},
"signRule": {
"signList": [
"carrefour"
]
},
"itemRule": {
"quantityRequired": 1,
"strategy": "QUANTITY",
"or": [
{
"quantityRequired": 1,
"strategy": "QUANTITY",
"term": "tomato"
},
{
"quantityRequired": 1,
"strategy": "QUANTITY",
"term": "carrots"
}
]
}
}
}
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- uid: required(string)
UID of this receipt attributed by Aboutgoods System to managed receipts
- createdAt: required(datetime)
When this object has been registered in AG system
- updatedAt: required(datetime)
The last time this entity had been updated in AG system
- dominantLanguage: required(string)
A locale format with the following pattern
{iso 639-1}-{ISO 3166-1}
- Usage : specifiy on which language the Receipt Analyzer should treat receipts
Example:
fr-FR
- name: required(string)
Id given by the client to allow client to retrieve this exact document after analysis
- rules: required(object)
Rules for detection of data inside all documents that are process in the context of this campaign
- name: required(string)
Name of the whole rule, must be unique for a given campaign
- uid: required(string)
Unique uid of the rule
- priceRule: (object)
Rule that defines rule on prices
- eligibleOnly: required(number)
minimum price of all matched items. Float format.
- totalAmount: (number)
minimum total amount of receipt. Float format.
- eligibleOnly: required(number)
- itemRule: required(object)
Rule that defines terms to search and various conditions of search (or, and)
- quantityRequired: (integer - default: 1)
Minimum required quantity this item rule must be found
- strategy: (one of QUANTITY, BUNDLE, QUANTITY_TIMES_BUNDLE - default: QUANTITY_TIMES_BUNDLE)
Strategy used to count items for the quantityRequired field, to get description of each setting please read this article from our Knowledge Base
- and: (array of object)
AND Rule, means that this entity contains ItemRules that system will search in document to match them all. Mutually exclusive with OR and TERM.
Items:
- or: (array of object)
OR Rule, means that all ItemRules in array system will search in document with an inclusive OR. Mutually exclusive with AND and TERM.
Items:
- not: (array of object)
itemRules only containing terms. AND/OR are not allowed.
Items:
- term: (string)
Just a simple rule to look for this term in the receipt. Mutually exclusive with AND and TERM.
Example:
{ "and": [ { "term": "Dodot" }, { "or": [ { "term": "geant vert" }, { "term": "g vert" } ], "quantityRequired": 2, "strategy": "QUANTITY" } ], "not": [ { "term": "haricot vert" } ] }
- quantityRequired: (integer - default: 1)
- signRule: (object)
Rule that defines the list of signs for a given promotion
- signList: required(array of string)
List of sign eligible for the promotion.
Example:
{ "signList": [ "Auchan", "Cora" ] }
- signList: required(array of string)
- dateRule: required(object)
Rule that defines range of dates for a given promotion
- min: required(string)
start date of the promotion/campaign
- max: required(string)
last date of the promotion/campaign
- min: required(string)
Example:
{ "name": "Labeyrie", "uid": "123", "dateRule": { "min": "2019-01-01", "max": "2019-11-01" }, "priceRule": { "eligibleOnly": 20.25, "totalAmount": 40 }, "signRule": { "signList": [ "Cora", "Auchan", "Carrefour" ] }, "itemRule": { "or": [ { "term": "Labeyrie" }, { "term": "Blini" } ], "quantityRequired": 2, "strategy": "QUANTITY", "not": [ { "term": "Auchan" }, { "term": "Cora" } ] } }
- name: required(string)
- companyId: required(string)
ID of the company which owns this Campaign (automatically set with Auth0 connection)
- outgoingUrl: (string)
A URL that will be called when a document analysis is over. This URL must handle a document POST request with analysis in JSON.
A URL placeholder replacer allows you to specify the some values to be replaced when the outgoingUrl is triggered. Here are the possible values handled by our replacer:
{document_uid}
{document_name}
{endpoint_uid}
{endpoint_name}
{campaign_uid}
{campaign_name}
{company_uid}
For example, you can set the outgoingUrl to
https://myCallbackUrl/post/{endpoint_name}/{document_name}
to make it easier for you to retrieve the endpoint and the document, since the values will be replaced by the actual ones.
Example:
{
"uid": "003473db-f05b-4f72-a6a7-fffa39ed96b9",
"createdAt": "2019-10-10T13:20:34Z",
"updatedAt": "2019-10-10T13:20:34Z",
"outgoingUrl": "https://myCallbackUrl/post",
"dominantLanguage": "fr-FR",
"name": "Test de campagne",
"companyId": "myCompany",
"rules": {
"uid": "azertyuiop",
"name": "Test de rules",
"dateRule": {
"min": "2010-09-01",
"max": "2019-09-30"
},
"priceRule": {
"eligibleOnly": 5
},
"signRule": {
"signList": [
"carrefour"
]
},
"itemRule": {
"quantityRequired": 1,
"strategy": "QUANTITY",
"or": [
{
"quantityRequired": 1,
"strategy": "QUANTITY",
"term": "tomato"
},
{
"quantityRequired": 1,
"strategy": "QUANTITY",
"term": "carrots"
}
]
}
}
}
HTTP status code 400
Body
Media type: application/json
Type: object
Properties- error: required(string)
Example:
{ "badRequest" : "You are missing some field or they are malformed" }
HTTP status code 404
Body
Media type: application/json
Type: object
Properties- error: required(string)
Example:
{ "notFound" : "resource has not been found on this system" }
HTTP status code 406
Body
Media type: application/json
Type: object
Properties- error: required(string)
Example:
{ "notAcceptable" : "Some fields contains invalid characters" }
Secured by OAuth2.0 - Hydra
delete /campaigns/{campaignId}
Delete the campaign and document(s) related
OAuth2.0 authentification required AND the feature 'PROMOTIONS' must be activated
URI Parameters
- campaignId: required(string)
HTTP status code 204
Image has been deleted
HTTP status code 403
You cannot access this resources with this token
HTTP status code 404
Body
Media type: application/json
Type: object
Properties- error: required(string)
Example:
{ "notFound" : "resource has not been found on this system" }
Secured by OAuth2.0 - Hydra
Export a zip Archive containing CSV of documents and items in documents.
get /campaigns/{campaignId}/export
Export a zip Archive containing CSV of documents and items in documents.
OAuth2.0 authentification required AND the feature 'CSV_EXPORT' must be activated
URI Parameters
- campaignId: required(string)
Query Parameters
- chunk: (integer - default: 100000)
Max sizes of every CSV files in archive. If exceeded the files will be splitted in multiple files.
- direction: (one of desc, asc - default: desc)
- limit: (integer)
Maximum number of receipts returned in the export.
- filter: (string)
List of properties, comma separated with their filter values. These properties can be pipe-joined. Available filters:
- uid
- date: requires a range of 2 dates
2020-01-01|2020-12-31
- campaignUid
- endpointUid
- status
- name
Example:
&filter=name:status:PROCESSED|NOT_EXPLOITABLE,date:2019-01-01|2019-12-31
- exportRules: (boolean - default: false)
Adds ProcessedRules to the general CSV.
- exportUsers: (boolean - default: false)
Adds Users csv to zip file.
- exportAnomalies: (boolean - default: false)
Adds AnomalyReport csv to zip file.
HTTP status code 200
A ZIP Archive containing two types of files:
general_data:
Contains all general infos on receipts (total, buyDate, shop...)
List of CSV fields:
- name
- processReport
- imageUrl
- sign
- subSign
- city
- address
- postalCode
- geoLocation
- phone
- total
- totalMax
- buyDate
- buyHour
- payment
- articleCount
items_data:
contains all data relative to items (shortLabel, quantity, brand, category...). Items are linked to the general data by the receipt name.
List of CSV fields:
- name (receipt's name)
- rawLabel
- shortLabel
- price
- bundle
- unitPrice
- mass
- packageUnity
- quantity
- brand
- brandLine
- category
- flags
Body
Media type: application/zip
Type: any
HTTP status code 403
Returned when the client is not allowed to access to the export feature
Body
Media type: application/json
Type: any
Example:
{
"reason": "You need to upgrade to next plan"
}
Secured by OAuth2.0 - Hydra
Reprocess documents by filter
post /campaigns/{campaignId}/reprocess
Reprocess documents by filter
OAuth2.0 authentification required AND the feature 'PROMOTIONS' must be activated
URI Parameters
- campaignId: required(string)
Headers
- webhook-only: (boolean)
Set to true to send documents to outgoing URL only
- rules-only: (boolean)
Set to true to send documents for rules analysis only
Query Parameters
- filter: (string)
List of properties, comma separated with their filter values. Available filters:
- uid
- createdAt
- updatedAt
- name
- campaignUid
- endpointUid
- status: (WAITING_FOR_DOCUMENT|, WAITING_FOR_PROCESS, PROCESSING, PROCESSED, NOT_EXPLOITABLE, SUBSCRIPTION_ISSUE)
- userPseudoId
- uuid
Example:
&filter=campaignUid:8c4e55e2-5ff7-4584-8a37-59c8f149271b,status:PROCESSING &filter=status:PROCESSING|PROCESSED &filter=status:WAITING*
HTTP status code 202
Secured by OAuth2.0 - Hydra
Get the list of documents by filters
Add document for a given campaign
get /campaigns/{campaignId}/documents
Get the list of documents by filters
OAuth2.0 authentification required AND the feature 'PROMOTIONS' must be activated
URI Parameters
- campaignId: required(string)
Query Parameters
- page: (integer)
Specify the page that you want to retrieve
- per_page: (integer - default: 10 - minimum: 10 - maximum: 1000)
Specify the amount of items that will be retrieved per page
- sort: (one of uid, createdAt, updatedAt, name)
Sort by filter/type
- sort_direction: (one of asc, desc)
Specify sort direction
- filter: (string)
List of properties, comma separated with their filter values. Available filters:
- uid
- createdAt
- updatedAt
- name
- campaignUid
- endpointUid
- status: (WAITING_FOR_DOCUMENT|, WAITING_FOR_PROCESS, PROCESSING, PROCESSED, NOT_EXPLOITABLE, SUBSCRIPTION_ISSUE)
- userPseudoId
- uuid
Example:
&filter=campaignUid:8c4e55e2-5ff7-4584-8a37-59c8f149271b,status:PROCESSING &filter=status:PROCESSING|PROCESSED &filter=status:WAITING*
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- countPerPage: required(integer)
Number of result returned by this page
- totalEntities: required(integer)
Total number of results available for this request
- totalPages: required(integer)
Total number of pages available for this request
- nextPageUri: required(string)
Request URI (URL without hostname) that allow to go to the next page of result, can be empty if there is no next page
Example:
/{entity}?page=1&per_page=3
- prevPageUri: required(string)
Request URI (URL without hostname) that allow to go to the previous page of result, can be empty if no previous page
Example:
/{entity}?page=1&per_page=3
- results: required(array of document)
Items: document
- uid: required(string)
Aboutgoods generated unique ID
- createdAt: required(datetime)
When this object has been registered in AG system
- updatedAt: required(datetime)
The last time this entity had been updated in AG system
- dominantLanguage: required(string)
A locale format with the following pattern
{iso 639-1}-{ISO 3166-1}
- Usage : specifiy on which language the Receipt Analyzer should treat receipts
Example:
fr-FR
- status: required(one of WAITING_FOR_DOCUMENT, WAITING_FOR_PROCESS, PROCESSING, PROCESSED, NOT_EXPLOITABLE, SUBSCRIPTION_ISSUE)
As of today we have 6 status for differents states of an image in our systems, when everything is fine PROCESSED
- processReport: required(one of NO_ERROR, BAD_QUALITY_IMAGE, NOT_ENOUGH_TEXT, MULTIPLE_RECEIPT, UNREADABLE, BAD_LOCALE, NOT_RECEIPT, ERROR_JPG, BAD_URL, NOT_ANALYZED)
Process Report represent a more detailled reason about why a receipt has not been analyzed correctly A key to let the client knows what happened during analysis, helps you understand the status
NO_ERROR
=> Everything is fine, this come with thePROCESSED
status by defaultBAD_QUALITY_IMAGE
=> We detected a too blurry image or too dark, it can also be the resolution of the imageNOT_ENOUGH_TEXT
=> Self explicit, we have a threshold for the text recognition in image, if our OCR did not found enough text to generate a satisfiable amount of data, we abandon the ProcessMULTIPLE_RECEIPT
=> We do not handle multiple receipt in one image, when we detect this case, we stop the processUNREADABLE
=> Our OCR could not determine any Text in the imageBAD_LOCALE
=> We could not find any language for the detection to operate. This means that the Language or country is currently not supported by our systemNOT_RECEIPT
=> We didn't find any receipt in the imageERROR_IMAGE_FORMAT
=> The image format is not valid (not one of jpg, pdf, png)BAD_URL
=> No image has been found at the given URL (internal error)NOT_ANALYZED
=> The document has not been analyzed for the moment, this comes with theWAITING_FOR_DOCUMENT
,WAITING_FOR_PROCESS
orPROCESSING
statuses
- anomalyReport: (object)
Result of the anomaly analysis
- flags: required(array of string)
Array of flags. List of the available flags:
ORIGINAL_RECEIPT
=> No clues detectedIDENTICAL_EXISTING_FILE
=> Same MD5 already present in company's receiptsBARCODE_ALREADY_EXISTS
=> Same barcode already presentHIGH_FILE_SIMILARITY
=> Similar phash already presentSAME_SHOP_SAME_MOMENT
=> Receipt with same shop at same buyTime already presentEXISTING_PRODUCT_LIST
=> Receipt with same product list already presentHIGH_GLOBAL_CONTENT_SIMILARITY
=> Combination of the 2 previous flagsBANNED_SOFTWARE
=> Receipt with one of the editing software of the list present in its exifs- Adobe Photoshop
- Windows Photo Editor
- paint.net
- PhotoFiltre
- PicsArt
- PaintShop
- GIMP
- TouchRetouch
- Snapseed
- PhotoStudio
- ACDSee
- PhotoScape
- Aviary
- potentialDuplicateReceipts: required(array of duplicateReceipt)
Items: duplicateReceipt
- uid: required(string)
Uid of the duplicated receipt
- flags: required(array of string)
Array of flags that were found for this duplicated document regarding the original receipt.
Example:
{ "uid": "e67c9571-47a7-42cd-8439-c94bc9d5e478", "flags": ["SAME_SHOP_SAME_MOMENT", "EXISTING_PRODUCT_LIST", "HIGH_GLOBAL_CONTENT_SIMILARITY"] }
- uid: required(string)
Example:
{ "flags": [ "BARCODE_ALREADY_EXISTS", "SAME_SHOP_SAME_MOMENT", "EXISTING_PRODUCT_LIST", "HIGH_GLOBAL_CONTENT_SIMILARITY" ], "potentialDuplicateReceipts": [ { "uid": "e67c9571-47a7-42cd-8439-c94bc9d5e478", "flags": ["SAME_SHOP_SAME_MOMENT", "EXISTING_PRODUCT_LIST", "HIGH_GLOBAL_CONTENT_SIMILARITY"] }, { "uid": "c1b2997b-c6a1-48c2-819e-300fe61db5e9", "flags": ["SAME_SHOP_SAME_MOMENT", "BARCODE_ALREADY_EXISTS"] } ] }
- flags: required(array of string)
- imageUrl: required(string)
URL for getting image from a cdn repository
- name: required(string)
Id of this document that client (aka you) had set when sending the image of document in the first place.
- Helps you to retrieve a document by it's name
- endpointUid: (string)
Endpoint id that had served this document
- campaignUid: (string)
If this document is a part of promotion campaign, id of campaign is displayed here
- userPseudoId: (string)
This ID correspond to a custom and client managed id specified by the developer of the application that had setup AGKit SDK (aka you in general).
- This can also come from an userId that you sent over this very API when sending a receipt
- processedRules: (object)
- name: required(string)
Name of the whole rule, must be unique for a given campaign
- uid: required(string)
unique uid of the rule
- priceRule: (object)
rule that defines rule on prices
- eligibleOnly: required(number)
minimum price of all matched items
- totalAmount: (number)
minimum total amount of receipt
- isMatched: required(boolean)
tells if the rule is matched in receipt
Example:
{ "eligibleOnly": 20.25, "totalAmount": 40, "isMatched": false }
- eligibleOnly: required(number)
- itemRule: required(object)
rule that defines terms to search and various conditions of search (or, and)
- term: (string)
Just a simple rule to look for this term in the receipt. Mutually exclusive with AND and TERM.
- quantityRequired: (integer)
minimum required quantity of term or clause (AND/OR) to find. Is added by Rulio by default = 1.
- strategy: (string)
strategy used to count the item for quantityRequired
Example:
QUANTITY | BUNDLE | QUANTITY_TIMES_BUNDLE
- or: (array of object)
The result of running OR Rule with itemsMatched and isMatched.
Items:
- and: (array of object)
The result of running AND Rule with itemsMatched and isMatched.
Items:
- not: (array of object)
The result of running NOT Rule with itemsMatched and isMatched.
Items:
- isMatched: required(boolean)
tells if the rule is matched in receipt
- itemsMatched: (array of string)
List of IDs of items that were matched by term. Even if the rule is false (quantityRequired is not met), can have some IDs.
- quantityMatched: (integer)
quantity of term or terms in clause (AND/OR) found (even if the quantityRequired is not met). Can be different from the number of items in itemsMatched (one product line - but bought twice)
Example:
{ "quantityRequired": 2, "strategy": "QUANTITY", "or": [ { "term": "Labeyrie", "quantityRequired": 1, "strategy": "QUANTITY", "itemsMatched": [ "3" ], "isMatched": true, "quantityMatched": 1 }, { "term": "Blini", "quantityRequired": 1, "strategy": "QUANTITY", "itemsMatched": [ "1", "2" ], "quantityMatched": 2, "isMatched": true } ], "not": [ { "isMatched": true, "term": "Auchan", "itemsMatched": [ "2" ], "quantityMatched": 1 }, { "isMatched": false, "term": "Cora", "itemsMatched": [], "quantityMatched": 0 }, { "isMatched": false, "term": "Carrefour", "itemsMatched": [], "quantityMatched": 0 } ], "itemsMatched": [ "3", "1" ], "quantityMatched": 2, "isMatched": true }
- term: (string)
- signRule: (object)
rule that defines the list of signs for a given promotion
- signList: required(array of string)
List of sign eligible for the promotion.
- isMatched: required(boolean)
tells if the rule is matched in receipt
Example:
{ "signList": [ "Auchan", "Cora" ], "isMatched": true }
- signList: required(array of string)
- dateRule: required(object)
rule that defines range of dates for a given promotion
- min: required(string)
start date of the promotion/campaign
- max: required(string)
last date of the promotion/campaign
- isMatched: required(boolean)
tells if the rule is matched in receipt
Example:
{ "min": "2019-01-01", "max": "2019-11-01", "isMatched": true }
- min: required(string)
- allRulesMatched: required(boolean)
summarizes all rules matching, true if all rules are matched
- totalPriceOfMatchedItems: required(number)
total price of items that matched ItemRule
Example:
{ "name": "Labeyrie", "uid": "123", "itemRule": { "quantityRequired": 2, "strategy": "QUANTITY", "or": [ { "term": "Labeyrie", "quantityRequired": 1, "strategy": "QUANTITY", "itemsMatched": [ "3" ], "isMatched": true, "quantityMatched": 1 }, { "term": "Blini", "quantityRequired": 1, "strategy": "QUANTITY", "itemsMatched": [ "1", "2" ], "quantityMatched": 2, "isMatched": true } ], "not": [ { "isMatched": true, "term": "Auchan", "itemsMatched": [ "2" ], "quantityMatched": 1 }, { "isMatched": false, "term": "Cora", "itemsMatched": [], "quantityMatched": 0 } ], "itemsMatched": [ "3", "1" ], "quantityMatched": 2, "isMatched": true }, "dateRule": { "min": "2019-01-01", "max": "2019-11-01", "isMatched": true }, "priceRule": { "eligibleOnly": 15, "isMatched": false }, "signRule": { "signList": [ "Cora", "Auchan", "Carrefour" ], "isMatched": true }, "allRulesMatched": false, "totalPriceOfMatchedItems": 9.74 }
- name: required(string)
- appId: (string)
If this document has been received from AGKit (our mobile application SDK), this field allow to identify the application which have been used to send the document
- introspectionData: (object)
Introspection data that is infered from a given image, those data are useful to identify an image / receipt from its binary data
- resolution: required(object)
Size of the image
- width: required(number)
- height: required(number)
- size: (number)
Size in a human readable format (Mb or Kb)
- exif: (object)
Exif extracted from the image, possible keys available:
- cameraMake
- cameraModel
- software
- bitsPerSample
- imageWidth
- imageHeight
- imageDescription
- imageOrientation
- imageCopyright
- imageDatetime
- originalDatetime
- digitizeDatetime
- subsecondTime
- fstop
- exposureProgram
- isoSpeed
- subjectDistance
- exposureBias
- flashUsed
- flashReturnedLight
- flashMode
- meteringMode
- focalLength
- focalLength35mm
- gpsAltitude
- gpsPrecision
- lensFocalLengthMin
- lensFocalLengthMax
- lensFstopMin
- lensFstopMax
- lensMake
- lensModel
- focalPlaneXRes
- focalPlaneYRes
- gpsCoordinate
- resolution: required(object)
- data: (object)
Actual data that has been extracted from the receipt content Note: This field will be empty on the first document post response, as the process is running asynchronously, expect this field to be filled with data when the Status is set to
PROCESSED
- buyHour: (time-only)
🕐 The hour displayed on the receipt (ISO 8601 Time 'hh:mm:ss')
- buyDate: (date-only)
🗓 Date of buy for the receipt (ISO 8601 Date 2018-10-22)
- articleCount: (number)
Number of items in cart for this receipt
- total: (number)
🆙 Total amount paid by the customer (can be negative !)
- totalMax: (number)
🆕 Total value of the merchandises for this receipt, this can be different from what user paid (total field).
- payment: (array of string)
🆕 Buying mode or payment methods, can have multiple payments methods for a receipt, "UNKNOWN" if nothing was found
Example:
["CARD", "CASH", "CHEQUE", "UNKNOWN"]
- locale: (string)
Locale specified for this receipt analysis
- shop: (object)
🏬 This object represent the store / shop we found for this receipt, most of the time it will be only one data per field, but we can also send a top 3 with some significative accuracy
- city: (string)
City where the store of this buy is located
- sign: (string)
Store name or sign name / Brand of the shop
- subSign: (string)
SubSign of the shop
- phone: (string)
Phone number of the store
- address: (string)
Exact address of the store
- postalCode: (string)
Postal code for the city where we found this store
- geoLocation: (string)
Latitude and longitude for the shop, following https://tools.ietf.org/html/rfc5870 standard (example 13.4125,103.8667)
Example:
{ "city": "Toulon", "sign": "CARREFOUR", "subSign": "MARKET", "phone": "0494419879", "address": "CENTRE CIAL MAYOL", "postalCode": "83000", "geoLocation" : "48.31763410000001,1.9993057" }
- city: (string)
- items: required(array of object)
Items with products detected
Items: items
- id: required(string)
An ID unique to this list of item. Mainly used to identify this particular item in this receipt for our rule processor to indicate which item has matched a given rule.
- rawLabel: (string)
Raw line read on the receipt by OCR
- shortLabel: (string)
Detected short label from rawLabel, we remove price and other non label data from rawLabel
- quantity: (number)
Quantity of item detected in receipt
- unitPrice: (number)
A price detected for one piece of this item
- packageUnity: (string)
Package unity for item, for example Kg
- mass: (number)
The mass detected for the package, example 5 (Kg from PackageUnity)
- flags: (array of string)
Some notable characteristics detected on the product, BIO for example, or gluten free or anything special
Example:
["bio", "aop"]
- price: (number)
Total price for this item, (if found quantity > 1, we multiply to get this data, or we read it from receipt)
- product: (object)
What we understood from the item, we link item data to a clean and well organized product from our database and we put informations about it here.
- category: (string)
A fully qualified AGCategory name for this product infered by our AI algorithm, retrieve the complete list of categories here https://doc.kweeri.io/resources/list-of-product-categories.html
- categoryUid: (string)
Reference UID from Aboutgoods taxonomy
- brand: (string)
Fully qualified Brand name of product if displayed in label infered by our AI algorithm
- brandUid: (string)
Reference UID from Aboutgoods brands taxonomy of product if displayed in label infered by our AI algorithm
- brandLine: (string)
⚠️ deprecated: this field will be removed in future releases
- gtin: (string)
If present on the receipt, we extract the GTIN (EAN 13) Code
Example:
{ "brand": "PETIT NAVIRE", "brandLine": "FILETS DE THON", "category" : "tinned_fish", "categoryUid" : "4e54e68c-637f-a7d9-d509-f7e32b849f60", "gtin" : "1234567890123" }
- category: (string)
- bundle: (number)
Number of products in a pack. 16 x 125g, 16 is the bundle, 125g is the mass.
Example:
{ "id": "fa2cb", "rawLabel": "x5506 OATS QUAKER BIO", "quantity": 1, "unitPrice": 1.64, "packageUnity": "Kg", "mass": 1, "flags": [ "bio" ], "price": 1.64, "bundle": 1, "product": { "category": "food > sweet_grocery > cereals > breakfast_cereals", "categoryUid": "33f92698-284b-fd44-575a-f1e9cea9973e", "brand": "QUAKER", "brandUid": "05a5069d-fd64-b97b-ac06-101dcfc1686c" } }
- id: required(string)
- barcodes: (array of object)
🆕 1D or 2D codes found in the image after cropping the document from the rest of image
Items: items
- type: required(one of EAN-2, EAN-5, EAN-8, UPC-E, ISBN-10, UPC-A, EAN-13, ISBN-13, COMPOSITE, I2/5, DataBar, DataBar-Exp, Codabar, CODE-39, CODE-93, CODE-128, PDF417, QR-Code, UNKNOWN)
type of code detected
- data: required(string)
Data read from the code
- location: required(object)
- x: required(number)
x
location of the code in image - y: required(number)
y
location of the code in image - width: required(number)
width
of the code in image - height: required(number)
height
of the code in image
- x: required(number)
Example:
[{ "type": "CODE-128", "data": "12456789", "location": { "x": 0.0, "y": 0.0, "width": 50, "height": 20 } }]
- type: required(one of EAN-2, EAN-5, EAN-8, UPC-E, ISBN-10, UPC-A, EAN-13, ISBN-13, COMPOSITE, I2/5, DataBar, DataBar-Exp, Codabar, CODE-39, CODE-93, CODE-128, PDF417, QR-Code, UNKNOWN)
Example:
{ "shop": { "city": "Toulon", "sign": "CARREFOUR", "subSign": "MARKET", "phone": "0494419879", "address": "CENTRE CIAL MAYOL", "postalCode": "83000" }, "articleCount": 2, "total": 4.25, "totalMax": 4, "buyDate": "2016-12-07", "buyHour": "11:08:00", "items": [ { "id": "fa2cb", "rawLabel": "x5506 OATS QUAKER", "quantity": 1, "unitPrice": 1.64, "packageUnity": "Kg", "mass": 1, "price": 1.64, "bundle": 1, "product": { "category": "breakfast_cereals", "brand": "QUAKER" } }, { "id": "9d7fb", "rawLabel": "4 BTE 6X33CL COCA CO 2,61", "shortLabel": "BTE 6X33CL COCA CO", "quantity": 1, "unitPrice": 2.61, "packageUnity": "CL", "mass": 33, "bundle": 6, "price": 2.61, "product": { "category": "soda", "categoryUid": "efb24280-2dd9-423d-91d3-263fc780b6df", "brand": "COCA COLA" } } ] }
- buyHour: (time-only)
Example:
{ "uid": "89cd32b8-15e9-4e63-af5e-9e85da188fa1", "createdAt": "2019-09-20T08:19:57Z", "updatedAt": "2019-09-20T08:20:09Z", "dominantLanguage": "fr-FR", "name": "receiptTest", "campaignUid": "fc928982-3acc-4aea-bca3-e50d22e0b6ca", "userPseudoId": "8335c8d1-5ae7-440c-90d1-50543c86d9b4", "status": "PROCESSED", "processReport": "NO_ERROR", "imageUrl": "https://receipt.agkit.io/v2/documents/89cd32b8-15e9-4e63-af5e-9e85da188fa1/show", "data": { "shop": { "city": "Toulon", "sign": "CARREFOUR", "subSign": "MARKET", "phone": "0494419879", "address": "CENTRE CIAL MAYOL", "postalCode": "83000", "geoLocation": "48.31763410000001,1.9993057" }, "articleCount": 3, "total": 6.51, "totalMax": 6.26, "buyDate": "2016-12-07", "buyHour": "11:08:00", "payment": [ "CASH", "CARD" ], "barcodes": [ { "type": "CODE-128", "data": "12456789", "location": { "x": 0, "y": 0, "width": 50, "height": 20 } } ], "items": [ { "id": "fa2cb", "rawLabel": "x5506 OATS QUAKER 1,64", "quantity": 1, "unitPrice": 1.64, "packageUnity": "Kg", "mass": 1, "price": 1.64, "bundle": 1, "product": { "category": "food > sweet_grocery > cereals > breakfast_cereals", "categoryUid": "33f92698-284b-fd44-575a-f1e9cea9973e", "brand": "QUAKER", "brandUid": "05a5069d-fd64-b97b-ac06-101dcfc1686c" } }, { "id": "47267", "rawLabel": "PEPSI REGULAR 2,26", "shortLabel": "PEPSI REGULAR", "quantity": 1, "unitPrice": 2.26, "bundle": 1, "price": 2.26, "product": { "category": "drink > alcohol_free > soda", "categoryUid": "efb24280-2dd9-423d-91d3-263fc780b6df", "brand": "PEPSI", "brandUid": "822ed5c0-1d5c-0ec1-0cf9-5b62b2caecca" } }, { "id": "9d7fb", "rawLabel": "4 BTE 6X33CL COCA CO 2,61", "shortLabel": "BTE 6X33CL COCA CO", "quantity": 1, "unitPrice": 2.61, "packageUnity": "CL", "mass": 33, "bundle": 6, "price": 2.61, "product": { "category": "drink > alcohol_free > soda", "categoryUid": "efb24280-2dd9-423d-91d3-263fc780b6df", "brand": "COCA COLA > CLASSIC", "brandUid": "f2eaa047-39d8-0855-b0e3-098b2bbec0d5" } } ] }, "processedRules": { "uid": "1234", "name": "Quaker", "dateRule": { "min": "2019-01-01", "max": "2019-11-01", "isMatched": false }, "signRule": { "signList": [ "Carrefour" ], "isMatched": true }, "itemRule": { "term": "Quaker", "quantityRequired": 1, "strategy": "QUANTITY", "isMatched": true, "itemsMatched": [ "fa2cb" ], "quantityMatched": 1 }, "allRulesMatched": false, "totalPriceOfMatchedItems": 1.64 }, "anomalyReport": { "flags": [ "BARCODE_ALREADY_EXISTS", "SAME_SHOP_SAME_MOMENT", "EXISTING_PRODUCT_LIST", "HIGH_GLOBAL_CONTENT_SIMILARITY" ], "potentialDuplicateReceipts": [ { "uid": "e67c9571-47a7-42cd-8439-c94bc9d5e478", "flags": [ "SAME_SHOP_SAME_MOMENT", "EXISTING_PRODUCT_LIST", "HIGH_GLOBAL_CONTENT_SIMILARITY" ] }, { "uid": "c1b2997b-c6a1-48c2-819e-300fe61db5e9", "flags": [ "BARCODE_ALREADY_EXISTS" ] } ] }, "introspectionData": { "resolution": { "width": 2608, "height": 4632 }, "size": 3564061, "exif": { "bitsPerSample": 8, "cameraMake": "", "cameraModel": "", "digitizeDatetime": "", "exposureBias": 0, "exposureProgram": 0, "flashMode": 0, "flashReturnedLight": 0, "flashUsed": 0, "focalLength": 0, "focalLength35mm": 0, "focalPlaneXRes": 0, "focalPlaneYRes": 0, "fstop": 0, "gpsAltitude": 0, "gpsCoordinate": "0.000000,0.000000", "gpsPrecision": 0, "imageCopyright": "", "imageDatetime": "", "imageDescription": "", "imageHeight": 0, "imageOrientation": 0, "imageWidth": 0, "isoSpeed": 0, "lensFocalLengthMax": 0, "lensFocalLengthMin": 0, "lensFstopMax": 0, "lensFstopMin": 0, "lensMake": "", "lensModel": "", "meteringMode": 0, "originalDatetime": "", "software": "", "subjectDistance": 0, "subsecondTime": "" } } }
- uid: required(string)
HTTP status code 400
Filter malformed or invalid filter key
HTTP status code 403
You cannot access this resources with this token
HTTP status code 404
Body
Media type: application/json
Type: object
Properties- error: required(string)
Example:
{ "notFound" : "resource has not been found on this system" }
Secured by OAuth2.0 - Hydra
post /campaigns/{campaignId}/documents
Add document for a given campaign
OAuth2.0 authentification required AND the feature 'PROMOTIONS' must be activated
URI Parameters
- campaignId: required(string)
Query Parameters
- name: required(string)
This field represent a string that identify this document for the client perspective. Allowing him to retrieve a document by it's own id. Id must be unique per company, the API will systematically refuse any duplicate id here for a given company
- dominantLanguage: (string)
A locale format with the following pattern {iso 639-1}-{ISO 3166-1}, this is used to specifiy on which language the system should analyse receipts, very important !
Example:
fr-FR
- userPseudoId: (string)
Client side user id that created this document image, this id is dependant of client.
Body
Media type: image/jpg
Type: file
Media type: image/png
Type: file
Media type: application/pdf
Type: file
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- uid: required(string)
Aboutgoods generated unique ID
- createdAt: required(datetime)
When this object has been registered in AG system
- updatedAt: required(datetime)
The last time this entity had been updated in AG system
- dominantLanguage: required(string)
A locale format with the following pattern
{iso 639-1}-{ISO 3166-1}
- Usage : specifiy on which language the Receipt Analyzer should treat receipts
Example:
fr-FR
- status: required(one of WAITING_FOR_DOCUMENT, WAITING_FOR_PROCESS, PROCESSING, PROCESSED, NOT_EXPLOITABLE, SUBSCRIPTION_ISSUE)
As of today we have 6 status for differents states of an image in our systems, when everything is fine PROCESSED
- processReport: required(one of NO_ERROR, BAD_QUALITY_IMAGE, NOT_ENOUGH_TEXT, MULTIPLE_RECEIPT, UNREADABLE, BAD_LOCALE, NOT_RECEIPT, ERROR_JPG, BAD_URL, NOT_ANALYZED)
Process Report represent a more detailled reason about why a receipt has not been analyzed correctly A key to let the client knows what happened during analysis, helps you understand the status
NO_ERROR
=> Everything is fine, this come with thePROCESSED
status by defaultBAD_QUALITY_IMAGE
=> We detected a too blurry image or too dark, it can also be the resolution of the imageNOT_ENOUGH_TEXT
=> Self explicit, we have a threshold for the text recognition in image, if our OCR did not found enough text to generate a satisfiable amount of data, we abandon the ProcessMULTIPLE_RECEIPT
=> We do not handle multiple receipt in one image, when we detect this case, we stop the processUNREADABLE
=> Our OCR could not determine any Text in the imageBAD_LOCALE
=> We could not find any language for the detection to operate. This means that the Language or country is currently not supported by our systemNOT_RECEIPT
=> We didn't find any receipt in the imageERROR_IMAGE_FORMAT
=> The image format is not valid (not one of jpg, pdf, png)BAD_URL
=> No image has been found at the given URL (internal error)NOT_ANALYZED
=> The document has not been analyzed for the moment, this comes with theWAITING_FOR_DOCUMENT
,WAITING_FOR_PROCESS
orPROCESSING
statuses
- anomalyReport: (object)
Result of the anomaly analysis
- flags: required(array of string)
Array of flags. List of the available flags:
ORIGINAL_RECEIPT
=> No clues detectedIDENTICAL_EXISTING_FILE
=> Same MD5 already present in company's receiptsBARCODE_ALREADY_EXISTS
=> Same barcode already presentHIGH_FILE_SIMILARITY
=> Similar phash already presentSAME_SHOP_SAME_MOMENT
=> Receipt with same shop at same buyTime already presentEXISTING_PRODUCT_LIST
=> Receipt with same product list already presentHIGH_GLOBAL_CONTENT_SIMILARITY
=> Combination of the 2 previous flagsBANNED_SOFTWARE
=> Receipt with one of the editing software of the list present in its exifs- Adobe Photoshop
- Windows Photo Editor
- paint.net
- PhotoFiltre
- PicsArt
- PaintShop
- GIMP
- TouchRetouch
- Snapseed
- PhotoStudio
- ACDSee
- PhotoScape
- Aviary
- potentialDuplicateReceipts: required(array of duplicateReceipt)
Items: duplicateReceipt
- uid: required(string)
Uid of the duplicated receipt
- flags: required(array of string)
Array of flags that were found for this duplicated document regarding the original receipt.
Example:
{ "uid": "e67c9571-47a7-42cd-8439-c94bc9d5e478", "flags": ["SAME_SHOP_SAME_MOMENT", "EXISTING_PRODUCT_LIST", "HIGH_GLOBAL_CONTENT_SIMILARITY"] }
- uid: required(string)
Example:
{ "flags": [ "BARCODE_ALREADY_EXISTS", "SAME_SHOP_SAME_MOMENT", "EXISTING_PRODUCT_LIST", "HIGH_GLOBAL_CONTENT_SIMILARITY" ], "potentialDuplicateReceipts": [ { "uid": "e67c9571-47a7-42cd-8439-c94bc9d5e478", "flags": ["SAME_SHOP_SAME_MOMENT", "EXISTING_PRODUCT_LIST", "HIGH_GLOBAL_CONTENT_SIMILARITY"] }, { "uid": "c1b2997b-c6a1-48c2-819e-300fe61db5e9", "flags": ["SAME_SHOP_SAME_MOMENT", "BARCODE_ALREADY_EXISTS"] } ] }
- flags: required(array of string)
- imageUrl: required(string)
URL for getting image from a cdn repository
- name: required(string)
Id of this document that client (aka you) had set when sending the image of document in the first place.
- Helps you to retrieve a document by it's name
- endpointUid: (string)
Endpoint id that had served this document
- campaignUid: (string)
If this document is a part of promotion campaign, id of campaign is displayed here
- userPseudoId: (string)
This ID correspond to a custom and client managed id specified by the developer of the application that had setup AGKit SDK (aka you in general).
- This can also come from an userId that you sent over this very API when sending a receipt
- processedRules: (object)
- name: required(string)
Name of the whole rule, must be unique for a given campaign
- uid: required(string)
unique uid of the rule
- priceRule: (object)
rule that defines rule on prices
- eligibleOnly: required(number)
minimum price of all matched items
- totalAmount: (number)
minimum total amount of receipt
- isMatched: required(boolean)
tells if the rule is matched in receipt
Example:
{ "eligibleOnly": 20.25, "totalAmount": 40, "isMatched": false }
- eligibleOnly: required(number)
- itemRule: required(object)
rule that defines terms to search and various conditions of search (or, and)
- term: (string)
Just a simple rule to look for this term in the receipt. Mutually exclusive with AND and TERM.
- quantityRequired: (integer)
minimum required quantity of term or clause (AND/OR) to find. Is added by Rulio by default = 1.
- strategy: (string)
strategy used to count the item for quantityRequired
Example:
QUANTITY | BUNDLE | QUANTITY_TIMES_BUNDLE
- or: (array of object)
The result of running OR Rule with itemsMatched and isMatched.
Items:
- and: (array of object)
The result of running AND Rule with itemsMatched and isMatched.
Items:
- not: (array of object)
The result of running NOT Rule with itemsMatched and isMatched.
Items:
- isMatched: required(boolean)
tells if the rule is matched in receipt
- itemsMatched: (array of string)
List of IDs of items that were matched by term. Even if the rule is false (quantityRequired is not met), can have some IDs.
- quantityMatched: (integer)
quantity of term or terms in clause (AND/OR) found (even if the quantityRequired is not met). Can be different from the number of items in itemsMatched (one product line - but bought twice)
Example:
{ "quantityRequired": 2, "strategy": "QUANTITY", "or": [ { "term": "Labeyrie", "quantityRequired": 1, "strategy": "QUANTITY", "itemsMatched": [ "3" ], "isMatched": true, "quantityMatched": 1 }, { "term": "Blini", "quantityRequired": 1, "strategy": "QUANTITY", "itemsMatched": [ "1", "2" ], "quantityMatched": 2, "isMatched": true } ], "not": [ { "isMatched": true, "term": "Auchan", "itemsMatched": [ "2" ], "quantityMatched": 1 }, { "isMatched": false, "term": "Cora", "itemsMatched": [], "quantityMatched": 0 }, { "isMatched": false, "term": "Carrefour", "itemsMatched": [], "quantityMatched": 0 } ], "itemsMatched": [ "3", "1" ], "quantityMatched": 2, "isMatched": true }
- term: (string)
- signRule: (object)
rule that defines the list of signs for a given promotion
- signList: required(array of string)
List of sign eligible for the promotion.
- isMatched: required(boolean)
tells if the rule is matched in receipt
Example:
{ "signList": [ "Auchan", "Cora" ], "isMatched": true }
- signList: required(array of string)
- dateRule: required(object)
rule that defines range of dates for a given promotion
- min: required(string)
start date of the promotion/campaign
- max: required(string)
last date of the promotion/campaign
- isMatched: required(boolean)
tells if the rule is matched in receipt
Example:
{ "min": "2019-01-01", "max": "2019-11-01", "isMatched": true }
- min: required(string)
- allRulesMatched: required(boolean)
summarizes all rules matching, true if all rules are matched
- totalPriceOfMatchedItems: required(number)
total price of items that matched ItemRule
Example:
{ "name": "Labeyrie", "uid": "123", "itemRule": { "quantityRequired": 2, "strategy": "QUANTITY", "or": [ { "term": "Labeyrie", "quantityRequired": 1, "strategy": "QUANTITY", "itemsMatched": [ "3" ], "isMatched": true, "quantityMatched": 1 }, { "term": "Blini", "quantityRequired": 1, "strategy": "QUANTITY", "itemsMatched": [ "1", "2" ], "quantityMatched": 2, "isMatched": true } ], "not": [ { "isMatched": true, "term": "Auchan", "itemsMatched": [ "2" ], "quantityMatched": 1 }, { "isMatched": false, "term": "Cora", "itemsMatched": [], "quantityMatched": 0 } ], "itemsMatched": [ "3", "1" ], "quantityMatched": 2, "isMatched": true }, "dateRule": { "min": "2019-01-01", "max": "2019-11-01", "isMatched": true }, "priceRule": { "eligibleOnly": 15, "isMatched": false }, "signRule": { "signList": [ "Cora", "Auchan", "Carrefour" ], "isMatched": true }, "allRulesMatched": false, "totalPriceOfMatchedItems": 9.74 }
- name: required(string)
- appId: (string)
If this document has been received from AGKit (our mobile application SDK), this field allow to identify the application which have been used to send the document
- introspectionData: (object)
Introspection data that is infered from a given image, those data are useful to identify an image / receipt from its binary data
- resolution: required(object)
Size of the image
- width: required(number)
- height: required(number)
- size: (number)
Size in a human readable format (Mb or Kb)
- exif: (object)
Exif extracted from the image, possible keys available:
- cameraMake
- cameraModel
- software
- bitsPerSample
- imageWidth
- imageHeight
- imageDescription
- imageOrientation
- imageCopyright
- imageDatetime
- originalDatetime
- digitizeDatetime
- subsecondTime
- fstop
- exposureProgram
- isoSpeed
- subjectDistance
- exposureBias
- flashUsed
- flashReturnedLight
- flashMode
- meteringMode
- focalLength
- focalLength35mm
- gpsAltitude
- gpsPrecision
- lensFocalLengthMin
- lensFocalLengthMax
- lensFstopMin
- lensFstopMax
- lensMake
- lensModel
- focalPlaneXRes
- focalPlaneYRes
- gpsCoordinate
- resolution: required(object)
- data: (object)
Actual data that has been extracted from the receipt content Note: This field will be empty on the first document post response, as the process is running asynchronously, expect this field to be filled with data when the Status is set to
PROCESSED
- buyHour: (time-only)
🕐 The hour displayed on the receipt (ISO 8601 Time 'hh:mm:ss')
- buyDate: (date-only)
🗓 Date of buy for the receipt (ISO 8601 Date 2018-10-22)
- articleCount: (number)
Number of items in cart for this receipt
- total: (number)
🆙 Total amount paid by the customer (can be negative !)
- totalMax: (number)
🆕 Total value of the merchandises for this receipt, this can be different from what user paid (total field).
- payment: (array of string)
🆕 Buying mode or payment methods, can have multiple payments methods for a receipt, "UNKNOWN" if nothing was found
Example:
["CARD", "CASH", "CHEQUE", "UNKNOWN"]
- locale: (string)
Locale specified for this receipt analysis
- shop: (object)
🏬 This object represent the store / shop we found for this receipt, most of the time it will be only one data per field, but we can also send a top 3 with some significative accuracy
- city: (string)
City where the store of this buy is located
- sign: (string)
Store name or sign name / Brand of the shop
- subSign: (string)
SubSign of the shop
- phone: (string)
Phone number of the store
- address: (string)
Exact address of the store
- postalCode: (string)
Postal code for the city where we found this store
- geoLocation: (string)
Latitude and longitude for the shop, following https://tools.ietf.org/html/rfc5870 standard (example 13.4125,103.8667)
Example:
{ "city": "Toulon", "sign": "CARREFOUR", "subSign": "MARKET", "phone": "0494419879", "address": "CENTRE CIAL MAYOL", "postalCode": "83000", "geoLocation" : "48.31763410000001,1.9993057" }
- city: (string)
- items: required(array of object)
Items with products detected
Items: items
- id: required(string)
An ID unique to this list of item. Mainly used to identify this particular item in this receipt for our rule processor to indicate which item has matched a given rule.
- rawLabel: (string)
Raw line read on the receipt by OCR
- shortLabel: (string)
Detected short label from rawLabel, we remove price and other non label data from rawLabel
- quantity: (number)
Quantity of item detected in receipt
- unitPrice: (number)
A price detected for one piece of this item
- packageUnity: (string)
Package unity for item, for example Kg
- mass: (number)
The mass detected for the package, example 5 (Kg from PackageUnity)
- flags: (array of string)
Some notable characteristics detected on the product, BIO for example, or gluten free or anything special
Example:
["bio", "aop"]
- price: (number)
Total price for this item, (if found quantity > 1, we multiply to get this data, or we read it from receipt)
- product: (object)
What we understood from the item, we link item data to a clean and well organized product from our database and we put informations about it here.
- category: (string)
A fully qualified AGCategory name for this product infered by our AI algorithm, retrieve the complete list of categories here https://doc.kweeri.io/resources/list-of-product-categories.html
- categoryUid: (string)
Reference UID from Aboutgoods taxonomy
- brand: (string)
Fully qualified Brand name of product if displayed in label infered by our AI algorithm
- brandUid: (string)
Reference UID from Aboutgoods brands taxonomy of product if displayed in label infered by our AI algorithm
- brandLine: (string)
⚠️ deprecated: this field will be removed in future releases
- gtin: (string)
If present on the receipt, we extract the GTIN (EAN 13) Code
Example:
{ "brand": "PETIT NAVIRE", "brandLine": "FILETS DE THON", "category" : "tinned_fish", "categoryUid" : "4e54e68c-637f-a7d9-d509-f7e32b849f60", "gtin" : "1234567890123" }
- category: (string)
- bundle: (number)
Number of products in a pack. 16 x 125g, 16 is the bundle, 125g is the mass.
Example:
{ "id": "fa2cb", "rawLabel": "x5506 OATS QUAKER BIO", "quantity": 1, "unitPrice": 1.64, "packageUnity": "Kg", "mass": 1, "flags": [ "bio" ], "price": 1.64, "bundle": 1, "product": { "category": "food > sweet_grocery > cereals > breakfast_cereals", "categoryUid": "33f92698-284b-fd44-575a-f1e9cea9973e", "brand": "QUAKER", "brandUid": "05a5069d-fd64-b97b-ac06-101dcfc1686c" } }
- id: required(string)
- barcodes: (array of object)
🆕 1D or 2D codes found in the image after cropping the document from the rest of image
Items: items
- type: required(one of EAN-2, EAN-5, EAN-8, UPC-E, ISBN-10, UPC-A, EAN-13, ISBN-13, COMPOSITE, I2/5, DataBar, DataBar-Exp, Codabar, CODE-39, CODE-93, CODE-128, PDF417, QR-Code, UNKNOWN)
type of code detected
- data: required(string)
Data read from the code
- location: required(object)
- x: required(number)
x
location of the code in image - y: required(number)
y
location of the code in image - width: required(number)
width
of the code in image - height: required(number)
height
of the code in image
- x: required(number)
Example:
[{ "type": "CODE-128", "data": "12456789", "location": { "x": 0.0, "y": 0.0, "width": 50, "height": 20 } }]
- type: required(one of EAN-2, EAN-5, EAN-8, UPC-E, ISBN-10, UPC-A, EAN-13, ISBN-13, COMPOSITE, I2/5, DataBar, DataBar-Exp, Codabar, CODE-39, CODE-93, CODE-128, PDF417, QR-Code, UNKNOWN)
Example:
{ "shop": { "city": "Toulon", "sign": "CARREFOUR", "subSign": "MARKET", "phone": "0494419879", "address": "CENTRE CIAL MAYOL", "postalCode": "83000" }, "articleCount": 2, "total": 4.25, "totalMax": 4, "buyDate": "2016-12-07", "buyHour": "11:08:00", "items": [ { "id": "fa2cb", "rawLabel": "x5506 OATS QUAKER", "quantity": 1, "unitPrice": 1.64, "packageUnity": "Kg", "mass": 1, "price": 1.64, "bundle": 1, "product": { "category": "breakfast_cereals", "brand": "QUAKER" } }, { "id": "9d7fb", "rawLabel": "4 BTE 6X33CL COCA CO 2,61", "shortLabel": "BTE 6X33CL COCA CO", "quantity": 1, "unitPrice": 2.61, "packageUnity": "CL", "mass": 33, "bundle": 6, "price": 2.61, "product": { "category": "soda", "categoryUid": "efb24280-2dd9-423d-91d3-263fc780b6df", "brand": "COCA COLA" } } ] }
- buyHour: (time-only)
Example:
{
"uid": "89cd32b8-15e9-4e63-af5e-9e85da188fa1",
"createdAt": "2019-09-20T08:19:57Z",
"updatedAt": "2019-09-20T08:20:09Z",
"dominantLanguage": "fr-FR",
"name": "receiptTest",
"campaignUid": "fc928982-3acc-4aea-bca3-e50d22e0b6ca",
"userPseudoId": "8335c8d1-5ae7-440c-90d1-50543c86d9b4",
"status": "PROCESSED",
"processReport": "NO_ERROR",
"imageUrl": "https://receipt.agkit.io/v2/documents/89cd32b8-15e9-4e63-af5e-9e85da188fa1/show",
"data": {
"shop": {
"city": "Toulon",
"sign": "CARREFOUR",
"subSign": "MARKET",
"phone": "0494419879",
"address": "CENTRE CIAL MAYOL",
"postalCode": "83000",
"geoLocation": "48.31763410000001,1.9993057"
},
"articleCount": 3,
"total": 6.51,
"totalMax": 6.26,
"buyDate": "2016-12-07",
"buyHour": "11:08:00",
"payment": [
"CASH",
"CARD"
],
"barcodes": [
{
"type": "CODE-128",
"data": "12456789",
"location": {
"x": 0,
"y": 0,
"width": 50,
"height": 20
}
}
],
"items": [
{
"id": "fa2cb",
"rawLabel": "x5506 OATS QUAKER 1,64",
"quantity": 1,
"unitPrice": 1.64,
"packageUnity": "Kg",
"mass": 1,
"price": 1.64,
"bundle": 1,
"product": {
"category": "food > sweet_grocery > cereals > breakfast_cereals",
"categoryUid": "33f92698-284b-fd44-575a-f1e9cea9973e",
"brand": "QUAKER",
"brandUid": "05a5069d-fd64-b97b-ac06-101dcfc1686c"
}
},
{
"id": "47267",
"rawLabel": "PEPSI REGULAR 2,26",
"shortLabel": "PEPSI REGULAR",
"quantity": 1,
"unitPrice": 2.26,
"bundle": 1,
"price": 2.26,
"product": {
"category": "drink > alcohol_free > soda",
"categoryUid": "efb24280-2dd9-423d-91d3-263fc780b6df",
"brand": "PEPSI",
"brandUid": "822ed5c0-1d5c-0ec1-0cf9-5b62b2caecca"
}
},
{
"id": "9d7fb",
"rawLabel": "4 BTE 6X33CL COCA CO 2,61",
"shortLabel": "BTE 6X33CL COCA CO",
"quantity": 1,
"unitPrice": 2.61,
"packageUnity": "CL",
"mass": 33,
"bundle": 6,
"price": 2.61,
"product": {
"category": "drink > alcohol_free > soda",
"categoryUid": "efb24280-2dd9-423d-91d3-263fc780b6df",
"brand": "COCA COLA > CLASSIC",
"brandUid": "f2eaa047-39d8-0855-b0e3-098b2bbec0d5"
}
}
]
},
"processedRules": {
"uid": "1234",
"name": "Quaker",
"dateRule": {
"min": "2019-01-01",
"max": "2019-11-01",
"isMatched": false
},
"signRule": {
"signList": [
"Carrefour"
],
"isMatched": true
},
"itemRule": {
"term": "Quaker",
"quantityRequired": 1,
"strategy": "QUANTITY",
"isMatched": true,
"itemsMatched": [
"fa2cb"
],
"quantityMatched": 1
},
"allRulesMatched": false,
"totalPriceOfMatchedItems": 1.64
},
"anomalyReport": {
"flags": [
"BARCODE_ALREADY_EXISTS",
"SAME_SHOP_SAME_MOMENT",
"EXISTING_PRODUCT_LIST",
"HIGH_GLOBAL_CONTENT_SIMILARITY"
],
"potentialDuplicateReceipts": [
{
"uid": "e67c9571-47a7-42cd-8439-c94bc9d5e478",
"flags": [
"SAME_SHOP_SAME_MOMENT",
"EXISTING_PRODUCT_LIST",
"HIGH_GLOBAL_CONTENT_SIMILARITY"
]
},
{
"uid": "c1b2997b-c6a1-48c2-819e-300fe61db5e9",
"flags": [
"BARCODE_ALREADY_EXISTS"
]
}
]
},
"introspectionData": {
"resolution": {
"width": 2608,
"height": 4632
},
"size": 3564061,
"exif": {
"bitsPerSample": 8,
"cameraMake": "",
"cameraModel": "",
"digitizeDatetime": "",
"exposureBias": 0,
"exposureProgram": 0,
"flashMode": 0,
"flashReturnedLight": 0,
"flashUsed": 0,
"focalLength": 0,
"focalLength35mm": 0,
"focalPlaneXRes": 0,
"focalPlaneYRes": 0,
"fstop": 0,
"gpsAltitude": 0,
"gpsCoordinate": "0.000000,0.000000",
"gpsPrecision": 0,
"imageCopyright": "",
"imageDatetime": "",
"imageDescription": "",
"imageHeight": 0,
"imageOrientation": 0,
"imageWidth": 0,
"isoSpeed": 0,
"lensFocalLengthMax": 0,
"lensFocalLengthMin": 0,
"lensFstopMax": 0,
"lensFstopMin": 0,
"lensMake": "",
"lensModel": "",
"meteringMode": 0,
"originalDatetime": "",
"software": "",
"subjectDistance": 0,
"subsecondTime": ""
}
}
}
HTTP status code 400
Body
Media type: application/json
Type: object
Properties- error: required(string)
Example:
{ "badRequest" : "You are missing some field or they are malformed" }
HTTP status code 401
Authentication with Auth0 failed
HTTP status code 402
Your quota has been exceeded
HTTP status code 404
Body
Media type: application/json
Type: object
Properties- error: required(string)
Example:
{ "notFound" : "resource has not been found on this system" }
HTTP status code 409
Document or name already exists for your company
Secured by OAuth2.0 - Hydra
/endpoints
Endpoints
Represent an access point for a given set of documents (image with data), you can send document to an endpoint and retrieve data extracted from it from this endpoint. An Endpoint can have document linked to a mobile application and / or to a promotion campaign.
Get the list of endpoints by filters
Create a new endpoint
get /endpoints
Get the list of endpoints by filters
OAuth2.0 authentification required
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- countPerPage: required(integer)
Number of result returned by this page
- totalEntities: required(integer)
Total number of results available for this request
- totalPages: required(integer)
Total number of pages available for this request
- nextPageUri: required(string)
Request URI (URL without hostname) that allow to go to the next page of result, can be empty if there is no next page
Example:
/{entity}?page=1&per_page=3
- prevPageUri: required(string)
Request URI (URL without hostname) that allow to go to the previous page of result, can be empty if no previous page
Example:
/{entity}?page=1&per_page=3
- results: required(array of endpoint)
Items: endpoint
- uid: required(string)
UID of this receipt attributed by Aboutgoods System to managed receipts
- createdAt: required(datetime)
When this object has been registered in AG system
- updatedAt: required(datetime)
The last time this entity had been updated in AG system
- dominantLanguage: required(string)
A locale format with the following pattern
{iso 639-1}-{ISO 3166-1}
- Usage : specifiy on which language the Receipt Analyzer should treat receipts
Example:
fr-FR
- outgoingUrl: (string)
A URL that will be called when a document analysis is over. This URL must handle a document POST request with analysis in JSON.
A URL placeholder replacer allows you to specify the some values to be replaced when the outgoingUrl is triggered. Here are the possible values handled by our replacer:
{document_uid}
{document_name}
{endpoint_uid}
{endpoint_name}
{campaign_uid}
{campaign_name}
{company_uid}
For example, you can set the outgoingUrl to
https://myCallbackUrl/post/{endpoint_name}/{document_name}
to make it easier for you to retrieve the endpoint and the document, since the values will be replaced by the actual ones. - name: required(string)
Name of the endpoint from the client perspective, easy way to retrieve an endpoint by it's name, must be unique to this client
- companyUid: (string)
ID of the company which owns this Endpoint (automatically set with Auth0 connection)
- uid: required(string)
HTTP status code 400
Filter malformed or invalid filter key
HTTP status code 403
You cannot access this resources with this token
Secured by OAuth2.0 - Hydra
post /endpoints
Create a new endpoint
OAuth2.0 authentification required
Body
Media type: application/json
Type: object
Properties- name: required(string)
Name of the endpoint from the client perspective, easy way to retrieve an endpoint by it's name, must be unique to this client
- outgoingUrl: (string)
A URL that will be called when a document analysis is over. This URL must handle a document POST request with analysis in JSON.
A URL placeholder replacer allows you to specify the some values to be replaced when the outgoingUrl is triggered. Here are the possible values handled by our replacer:
{document_uid}
{document_name}
{endpoint_uid}
{endpoint_name}
{campaign_uid}
{campaign_name}
{company_uid}
For example, you can set the outgoingUrl to
https://myCallbackUrl/post/{endpoint_name}/{document_name}
to make it easier for you to retrieve the endpoint and the document, since the values will be replaced by the actual ones. - dominantLanguage: required(string)
A locale format with the following pattern
Example:
fr-FR
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- uid: required(string)
UID of this receipt attributed by Aboutgoods System to managed receipts
- createdAt: required(datetime)
When this object has been registered in AG system
- updatedAt: required(datetime)
The last time this entity had been updated in AG system
- dominantLanguage: required(string)
A locale format with the following pattern
{iso 639-1}-{ISO 3166-1}
- Usage : specifiy on which language the Receipt Analyzer should treat receipts
Example:
fr-FR
- outgoingUrl: (string)
A URL that will be called when a document analysis is over. This URL must handle a document POST request with analysis in JSON.
A URL placeholder replacer allows you to specify the some values to be replaced when the outgoingUrl is triggered. Here are the possible values handled by our replacer:
{document_uid}
{document_name}
{endpoint_uid}
{endpoint_name}
{campaign_uid}
{campaign_name}
{company_uid}
For example, you can set the outgoingUrl to
https://myCallbackUrl/post/{endpoint_name}/{document_name}
to make it easier for you to retrieve the endpoint and the document, since the values will be replaced by the actual ones. - name: required(string)
Name of the endpoint from the client perspective, easy way to retrieve an endpoint by it's name, must be unique to this client
- companyUid: (string)
ID of the company which owns this Endpoint (automatically set with Auth0 connection)
HTTP status code 400
Body
Media type: application/json
Type: object
Properties- error: required(string)
Example:
{ "badRequest" : "You are missing some field or they are malformed" }
HTTP status code 404
Body
Media type: application/json
Type: object
Properties- error: required(string)
Example:
{ "notFound" : "resource has not been found on this system" }
Secured by OAuth2.0 - Hydra
Update informations about outgoing url
Get endpoint's informations
Delete the endpoint and all document(s) related
patch /endpoints/{endpointId}
Update informations about outgoing url
OAuth2.0 authentification required
URI Parameters
- endpointId: required(string)
Body
Media type: application/json
Type: object
Properties- outgoingUrl: (string)
- dominantLanguage: (string)
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- uid: required(string)
UID of this receipt attributed by Aboutgoods System to managed receipts
- createdAt: required(datetime)
When this object has been registered in AG system
- updatedAt: required(datetime)
The last time this entity had been updated in AG system
- dominantLanguage: required(string)
A locale format with the following pattern
{iso 639-1}-{ISO 3166-1}
- Usage : specifiy on which language the Receipt Analyzer should treat receipts
Example:
fr-FR
- outgoingUrl: (string)
A URL that will be called when a document analysis is over. This URL must handle a document POST request with analysis in JSON.
A URL placeholder replacer allows you to specify the some values to be replaced when the outgoingUrl is triggered. Here are the possible values handled by our replacer:
{document_uid}
{document_name}
{endpoint_uid}
{endpoint_name}
{campaign_uid}
{campaign_name}
{company_uid}
For example, you can set the outgoingUrl to
https://myCallbackUrl/post/{endpoint_name}/{document_name}
to make it easier for you to retrieve the endpoint and the document, since the values will be replaced by the actual ones. - name: required(string)
Name of the endpoint from the client perspective, easy way to retrieve an endpoint by it's name, must be unique to this client
- companyUid: (string)
ID of the company which owns this Endpoint (automatically set with Auth0 connection)
HTTP status code 400
Body
Media type: application/json
Type: object
Properties- error: required(string)
Example:
{ "notFound" : "resource has not been found on this system" }
HTTP status code 403
You cannot access this resources with this token
HTTP status code 404
Body
Media type: application/json
Type: object
Properties- error: required(string)
Example:
{ "notFound" : "resource has not been found on this system" }
Secured by OAuth2.0 - Hydra
get /endpoints/{endpointId}
Get endpoint's informations
OAuth2.0 authentification required
URI Parameters
- endpointId: required(string)
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- uid: required(string)
UID of this receipt attributed by Aboutgoods System to managed receipts
- createdAt: required(datetime)
When this object has been registered in AG system
- updatedAt: required(datetime)
The last time this entity had been updated in AG system
- dominantLanguage: required(string)
A locale format with the following pattern
{iso 639-1}-{ISO 3166-1}
- Usage : specifiy on which language the Receipt Analyzer should treat receipts
Example:
fr-FR
- outgoingUrl: (string)
A URL that will be called when a document analysis is over. This URL must handle a document POST request with analysis in JSON.
A URL placeholder replacer allows you to specify the some values to be replaced when the outgoingUrl is triggered. Here are the possible values handled by our replacer:
{document_uid}
{document_name}
{endpoint_uid}
{endpoint_name}
{campaign_uid}
{campaign_name}
{company_uid}
For example, you can set the outgoingUrl to
https://myCallbackUrl/post/{endpoint_name}/{document_name}
to make it easier for you to retrieve the endpoint and the document, since the values will be replaced by the actual ones. - name: required(string)
Name of the endpoint from the client perspective, easy way to retrieve an endpoint by it's name, must be unique to this client
- companyUid: (string)
ID of the company which owns this Endpoint (automatically set with Auth0 connection)
HTTP status code 403
You cannot access this resources with this token
HTTP status code 404
Body
Media type: application/json
Type: object
Properties- error: required(string)
Example:
{ "notFound" : "resource has not been found on this system" }
Secured by OAuth2.0 - Hydra
delete /endpoints/{endpointId}
Delete the endpoint and all document(s) related
OAuth2.0 authentification required
URI Parameters
- endpointId: required(string)
HTTP status code 204
Image has been deleted
HTTP status code 403
You cannot access this resources with this token
HTTP status code 404
Body
Media type: application/json
Type: object
Properties- error: required(string)
Example:
{ "notFound" : "resource has not been found on this system" }
Secured by OAuth2.0 - Hydra
Export a zip Archive containing CSV of documents and items in documents.
get /endpoints/{endpointId}/export
Export a zip Archive containing CSV of documents and items in documents.
OAuth2.0 authentification required AND the feature 'CSV_EXPORT' must be activated
URI Parameters
- endpointId: required(string)
Query Parameters
- chunk: (integer - default: 100000)
Max sizes of every CSV files in archive. If exceeded the files will be splitted in multiple files.
- direction: (one of desc, asc - default: desc)
- limit: (integer)
Maximum number of receipts returned in the export.
- filter: (string)
List of properties, comma separated with their filter values. These properties can be pipe-joined. Available filters:
- uid
- date: requires a range of 2 dates
2020-01-01|2020-12-31
- campaignUid
- endpointUid
- status
- name
Example:
&filter=name:status:PROCESSED|NOT_EXPLOITABLE,date:2019-01-01|2019-12-31
- exportRules: (boolean - default: false)
Adds ProcessedRules to the general CSV.
- exportUsers: (boolean - default: false)
Adds Users csv to zip file.
- exportAnomalies: (boolean - default: false)
Adds AnomalyReport csv to zip file.
HTTP status code 200
A ZIP Archive containing two types of files:
general_data:
Contains all general infos on receipts (total, buyDate, shop...)
List of CSV fields:
- name
- processReport
- imageUrl
- sign
- subSign
- city
- address
- postalCode
- geoLocation
- phone
- total
- totalMax
- buyDate
- buyHour
- payment
- articleCount
items_data:
contains all data relative to items (shortLabel, quantity, brand, category...). Items are linked to the general data by the receipt name.
List of CSV fields:
- name (receipt's name)
- rawLabel
- shortLabel
- price
- bundle
- unitPrice
- mass
- packageUnity
- quantity
- brand
- brandLine
- category
- flags
Body
Media type: application/zip
Type: any
HTTP status code 403
Returned when the client is not allowed to access to the export feature
Body
Media type: application/json
Type: any
Example:
{
"reason": "You need to upgrade to next plan"
}
Secured by OAuth2.0 - Hydra
Reprocess documents by filter
post /endpoints/{endpointId}/reprocess
Reprocess documents by filter
OAuth2.0 authentification required
URI Parameters
- endpointId: required(string)
Headers
- webhook-only: (boolean)
Set to true to send documents to outgoing URL only
- rules-only: (boolean)
Set to true to send documents for rules analysis only
Query Parameters
- filter: (string)
List of properties, comma separated with their filter values. Available filters:
- uid
- createdAt
- updatedAt
- name
- campaignUid
- endpointUid
- status: (WAITING_FOR_DOCUMENT|, WAITING_FOR_PROCESS, PROCESSING, PROCESSED, NOT_EXPLOITABLE, SUBSCRIPTION_ISSUE)
- userPseudoId
- uuid
Example:
&filter=campaignUid:8c4e55e2-5ff7-4584-8a37-59c8f149271b,status:PROCESSING &filter=status:PROCESSING|PROCESSED &filter=status:WAITING*
HTTP status code 202
HTTP status code 403
You cannot access this resources with this token
HTTP status code 404
Body
Media type: application/json
Type: object
Properties- error: required(string)
Example:
{ "notFound" : "resource has not been found on this system" }
Secured by OAuth2.0 - Hydra
Get the list of documents by filters
Add document for a given endpoint
get /endpoints/{endpointId}/documents
Get the list of documents by filters
OAuth2.0 authentification required
URI Parameters
- endpointId: required(string)
Query Parameters
- page: (integer)
Specify the page that you want to retrieve
- per_page: (integer - default: 10 - minimum: 10 - maximum: 1000)
Specify the amount of items that will be retrieved per page
- sort: (one of uid, createdAt, updatedAt, name, campaignUid, endpointUid, status, userPseudoId, uuid)
Sort by filter/type
- sort_direction: (one of asc, desc)
Specify sort direction
- filter: (string)
List of properties, comma separated with their filter values. Available filters:
- uid
- createdAt
- updatedAt
- name
- campaignUid
- endpointUid
- status: (WAITING_FOR_DOCUMENT|, WAITING_FOR_PROCESS, PROCESSING, PROCESSED, NOT_EXPLOITABLE, SUBSCRIPTION_ISSUE)
- userPseudoId
- uuid
Example:
&filter=campaignUid:8c4e55e2-5ff7-4584-8a37-59c8f149271b,status:PROCESSING &filter=status:PROCESSING|PROCESSED &filter=status:WAITING*
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- countPerPage: required(integer)
Number of result returned by this page
- totalEntities: required(integer)
Total number of results available for this request
- totalPages: required(integer)
Total number of pages available for this request
- nextPageUri: required(string)
Request URI (URL without hostname) that allow to go to the next page of result, can be empty if there is no next page
Example:
/{entity}?page=1&per_page=3
- prevPageUri: required(string)
Request URI (URL without hostname) that allow to go to the previous page of result, can be empty if no previous page
Example:
/{entity}?page=1&per_page=3
- results: required(array of document)
Items: document
- uid: required(string)
Aboutgoods generated unique ID
- createdAt: required(datetime)
When this object has been registered in AG system
- updatedAt: required(datetime)
The last time this entity had been updated in AG system
- dominantLanguage: required(string)
A locale format with the following pattern
{iso 639-1}-{ISO 3166-1}
- Usage : specifiy on which language the Receipt Analyzer should treat receipts
Example:
fr-FR
- status: required(one of WAITING_FOR_DOCUMENT, WAITING_FOR_PROCESS, PROCESSING, PROCESSED, NOT_EXPLOITABLE, SUBSCRIPTION_ISSUE)
As of today we have 6 status for differents states of an image in our systems, when everything is fine PROCESSED
- processReport: required(one of NO_ERROR, BAD_QUALITY_IMAGE, NOT_ENOUGH_TEXT, MULTIPLE_RECEIPT, UNREADABLE, BAD_LOCALE, NOT_RECEIPT, ERROR_JPG, BAD_URL, NOT_ANALYZED)
Process Report represent a more detailled reason about why a receipt has not been analyzed correctly A key to let the client knows what happened during analysis, helps you understand the status
NO_ERROR
=> Everything is fine, this come with thePROCESSED
status by defaultBAD_QUALITY_IMAGE
=> We detected a too blurry image or too dark, it can also be the resolution of the imageNOT_ENOUGH_TEXT
=> Self explicit, we have a threshold for the text recognition in image, if our OCR did not found enough text to generate a satisfiable amount of data, we abandon the ProcessMULTIPLE_RECEIPT
=> We do not handle multiple receipt in one image, when we detect this case, we stop the processUNREADABLE
=> Our OCR could not determine any Text in the imageBAD_LOCALE
=> We could not find any language for the detection to operate. This means that the Language or country is currently not supported by our systemNOT_RECEIPT
=> We didn't find any receipt in the imageERROR_IMAGE_FORMAT
=> The image format is not valid (not one of jpg, pdf, png)BAD_URL
=> No image has been found at the given URL (internal error)NOT_ANALYZED
=> The document has not been analyzed for the moment, this comes with theWAITING_FOR_DOCUMENT
,WAITING_FOR_PROCESS
orPROCESSING
statuses
- anomalyReport: (object)
Result of the anomaly analysis
- flags: required(array of string)
Array of flags. List of the available flags:
ORIGINAL_RECEIPT
=> No clues detectedIDENTICAL_EXISTING_FILE
=> Same MD5 already present in company's receiptsBARCODE_ALREADY_EXISTS
=> Same barcode already presentHIGH_FILE_SIMILARITY
=> Similar phash already presentSAME_SHOP_SAME_MOMENT
=> Receipt with same shop at same buyTime already presentEXISTING_PRODUCT_LIST
=> Receipt with same product list already presentHIGH_GLOBAL_CONTENT_SIMILARITY
=> Combination of the 2 previous flagsBANNED_SOFTWARE
=> Receipt with one of the editing software of the list present in its exifs- Adobe Photoshop
- Windows Photo Editor
- paint.net
- PhotoFiltre
- PicsArt
- PaintShop
- GIMP
- TouchRetouch
- Snapseed
- PhotoStudio
- ACDSee
- PhotoScape
- Aviary
- potentialDuplicateReceipts: required(array of duplicateReceipt)
Items: duplicateReceipt
- uid: required(string)
Uid of the duplicated receipt
- flags: required(array of string)
Array of flags that were found for this duplicated document regarding the original receipt.
Example:
{ "uid": "e67c9571-47a7-42cd-8439-c94bc9d5e478", "flags": ["SAME_SHOP_SAME_MOMENT", "EXISTING_PRODUCT_LIST", "HIGH_GLOBAL_CONTENT_SIMILARITY"] }
- uid: required(string)
Example:
{ "flags": [ "BARCODE_ALREADY_EXISTS", "SAME_SHOP_SAME_MOMENT", "EXISTING_PRODUCT_LIST", "HIGH_GLOBAL_CONTENT_SIMILARITY" ], "potentialDuplicateReceipts": [ { "uid": "e67c9571-47a7-42cd-8439-c94bc9d5e478", "flags": ["SAME_SHOP_SAME_MOMENT", "EXISTING_PRODUCT_LIST", "HIGH_GLOBAL_CONTENT_SIMILARITY"] }, { "uid": "c1b2997b-c6a1-48c2-819e-300fe61db5e9", "flags": ["SAME_SHOP_SAME_MOMENT", "BARCODE_ALREADY_EXISTS"] } ] }
- flags: required(array of string)
- imageUrl: required(string)
URL for getting image from a cdn repository
- name: required(string)
Id of this document that client (aka you) had set when sending the image of document in the first place.
- Helps you to retrieve a document by it's name
- endpointUid: (string)
Endpoint id that had served this document
- campaignUid: (string)
If this document is a part of promotion campaign, id of campaign is displayed here
- userPseudoId: (string)
This ID correspond to a custom and client managed id specified by the developer of the application that had setup AGKit SDK (aka you in general).
- This can also come from an userId that you sent over this very API when sending a receipt
- processedRules: (object)
- name: required(string)
Name of the whole rule, must be unique for a given campaign
- uid: required(string)
unique uid of the rule
- priceRule: (object)
rule that defines rule on prices
- eligibleOnly: required(number)
minimum price of all matched items
- totalAmount: (number)
minimum total amount of receipt
- isMatched: required(boolean)
tells if the rule is matched in receipt
Example:
{ "eligibleOnly": 20.25, "totalAmount": 40, "isMatched": false }
- eligibleOnly: required(number)
- itemRule: required(object)
rule that defines terms to search and various conditions of search (or, and)
- term: (string)
Just a simple rule to look for this term in the receipt. Mutually exclusive with AND and TERM.
- quantityRequired: (integer)
minimum required quantity of term or clause (AND/OR) to find. Is added by Rulio by default = 1.
- strategy: (string)
strategy used to count the item for quantityRequired
Example:
QUANTITY | BUNDLE | QUANTITY_TIMES_BUNDLE
- or: (array of object)
The result of running OR Rule with itemsMatched and isMatched.
Items:
- and: (array of object)
The result of running AND Rule with itemsMatched and isMatched.
Items:
- not: (array of object)
The result of running NOT Rule with itemsMatched and isMatched.
Items:
- isMatched: required(boolean)
tells if the rule is matched in receipt
- itemsMatched: (array of string)
List of IDs of items that were matched by term. Even if the rule is false (quantityRequired is not met), can have some IDs.
- quantityMatched: (integer)
quantity of term or terms in clause (AND/OR) found (even if the quantityRequired is not met). Can be different from the number of items in itemsMatched (one product line - but bought twice)
Example:
{ "quantityRequired": 2, "strategy": "QUANTITY", "or": [ { "term": "Labeyrie", "quantityRequired": 1, "strategy": "QUANTITY", "itemsMatched": [ "3" ], "isMatched": true, "quantityMatched": 1 }, { "term": "Blini", "quantityRequired": 1, "strategy": "QUANTITY", "itemsMatched": [ "1", "2" ], "quantityMatched": 2, "isMatched": true } ], "not": [ { "isMatched": true, "term": "Auchan", "itemsMatched": [ "2" ], "quantityMatched": 1 }, { "isMatched": false, "term": "Cora", "itemsMatched": [], "quantityMatched": 0 }, { "isMatched": false, "term": "Carrefour", "itemsMatched": [], "quantityMatched": 0 } ], "itemsMatched": [ "3", "1" ], "quantityMatched": 2, "isMatched": true }
- term: (string)
- signRule: (object)
rule that defines the list of signs for a given promotion
- signList: required(array of string)
List of sign eligible for the promotion.
- isMatched: required(boolean)
tells if the rule is matched in receipt
Example:
{ "signList": [ "Auchan", "Cora" ], "isMatched": true }
- signList: required(array of string)
- dateRule: required(object)
rule that defines range of dates for a given promotion
- min: required(string)
start date of the promotion/campaign
- max: required(string)
last date of the promotion/campaign
- isMatched: required(boolean)
tells if the rule is matched in receipt
Example:
{ "min": "2019-01-01", "max": "2019-11-01", "isMatched": true }
- min: required(string)
- allRulesMatched: required(boolean)
summarizes all rules matching, true if all rules are matched
- totalPriceOfMatchedItems: required(number)
total price of items that matched ItemRule
Example:
{ "name": "Labeyrie", "uid": "123", "itemRule": { "quantityRequired": 2, "strategy": "QUANTITY", "or": [ { "term": "Labeyrie", "quantityRequired": 1, "strategy": "QUANTITY", "itemsMatched": [ "3" ], "isMatched": true, "quantityMatched": 1 }, { "term": "Blini", "quantityRequired": 1, "strategy": "QUANTITY", "itemsMatched": [ "1", "2" ], "quantityMatched": 2, "isMatched": true } ], "not": [ { "isMatched": true, "term": "Auchan", "itemsMatched": [ "2" ], "quantityMatched": 1 }, { "isMatched": false, "term": "Cora", "itemsMatched": [], "quantityMatched": 0 } ], "itemsMatched": [ "3", "1" ], "quantityMatched": 2, "isMatched": true }, "dateRule": { "min": "2019-01-01", "max": "2019-11-01", "isMatched": true }, "priceRule": { "eligibleOnly": 15, "isMatched": false }, "signRule": { "signList": [ "Cora", "Auchan", "Carrefour" ], "isMatched": true }, "allRulesMatched": false, "totalPriceOfMatchedItems": 9.74 }
- name: required(string)
- appId: (string)
If this document has been received from AGKit (our mobile application SDK), this field allow to identify the application which have been used to send the document
- introspectionData: (object)
Introspection data that is infered from a given image, those data are useful to identify an image / receipt from its binary data
- resolution: required(object)
Size of the image
- width: required(number)
- height: required(number)
- size: (number)
Size in a human readable format (Mb or Kb)
- exif: (object)
Exif extracted from the image, possible keys available:
- cameraMake
- cameraModel
- software
- bitsPerSample
- imageWidth
- imageHeight
- imageDescription
- imageOrientation
- imageCopyright
- imageDatetime
- originalDatetime
- digitizeDatetime
- subsecondTime
- fstop
- exposureProgram
- isoSpeed
- subjectDistance
- exposureBias
- flashUsed
- flashReturnedLight
- flashMode
- meteringMode
- focalLength
- focalLength35mm
- gpsAltitude
- gpsPrecision
- lensFocalLengthMin
- lensFocalLengthMax
- lensFstopMin
- lensFstopMax
- lensMake
- lensModel
- focalPlaneXRes
- focalPlaneYRes
- gpsCoordinate
- resolution: required(object)
- data: (object)
Actual data that has been extracted from the receipt content Note: This field will be empty on the first document post response, as the process is running asynchronously, expect this field to be filled with data when the Status is set to
PROCESSED
- buyHour: (time-only)
🕐 The hour displayed on the receipt (ISO 8601 Time 'hh:mm:ss')
- buyDate: (date-only)
🗓 Date of buy for the receipt (ISO 8601 Date 2018-10-22)
- articleCount: (number)
Number of items in cart for this receipt
- total: (number)
🆙 Total amount paid by the customer (can be negative !)
- totalMax: (number)
🆕 Total value of the merchandises for this receipt, this can be different from what user paid (total field).
- payment: (array of string)
🆕 Buying mode or payment methods, can have multiple payments methods for a receipt, "UNKNOWN" if nothing was found
Example:
["CARD", "CASH", "CHEQUE", "UNKNOWN"]
- locale: (string)
Locale specified for this receipt analysis
- shop: (object)
🏬 This object represent the store / shop we found for this receipt, most of the time it will be only one data per field, but we can also send a top 3 with some significative accuracy
- city: (string)
City where the store of this buy is located
- sign: (string)
Store name or sign name / Brand of the shop
- subSign: (string)
SubSign of the shop
- phone: (string)
Phone number of the store
- address: (string)
Exact address of the store
- postalCode: (string)
Postal code for the city where we found this store
- geoLocation: (string)
Latitude and longitude for the shop, following https://tools.ietf.org/html/rfc5870 standard (example 13.4125,103.8667)
Example:
{ "city": "Toulon", "sign": "CARREFOUR", "subSign": "MARKET", "phone": "0494419879", "address": "CENTRE CIAL MAYOL", "postalCode": "83000", "geoLocation" : "48.31763410000001,1.9993057" }
- city: (string)
- items: required(array of object)
Items with products detected
Items: items
- id: required(string)
An ID unique to this list of item. Mainly used to identify this particular item in this receipt for our rule processor to indicate which item has matched a given rule.
- rawLabel: (string)
Raw line read on the receipt by OCR
- shortLabel: (string)
Detected short label from rawLabel, we remove price and other non label data from rawLabel
- quantity: (number)
Quantity of item detected in receipt
- unitPrice: (number)
A price detected for one piece of this item
- packageUnity: (string)
Package unity for item, for example Kg
- mass: (number)
The mass detected for the package, example 5 (Kg from PackageUnity)
- flags: (array of string)
Some notable characteristics detected on the product, BIO for example, or gluten free or anything special
Example:
["bio", "aop"]
- price: (number)
Total price for this item, (if found quantity > 1, we multiply to get this data, or we read it from receipt)
- product: (object)
What we understood from the item, we link item data to a clean and well organized product from our database and we put informations about it here.
- category: (string)
A fully qualified AGCategory name for this product infered by our AI algorithm, retrieve the complete list of categories here https://doc.kweeri.io/resources/list-of-product-categories.html
- categoryUid: (string)
Reference UID from Aboutgoods taxonomy
- brand: (string)
Fully qualified Brand name of product if displayed in label infered by our AI algorithm
- brandUid: (string)
Reference UID from Aboutgoods brands taxonomy of product if displayed in label infered by our AI algorithm
- brandLine: (string)
⚠️ deprecated: this field will be removed in future releases
- gtin: (string)
If present on the receipt, we extract the GTIN (EAN 13) Code
Example:
{ "brand": "PETIT NAVIRE", "brandLine": "FILETS DE THON", "category" : "tinned_fish", "categoryUid" : "4e54e68c-637f-a7d9-d509-f7e32b849f60", "gtin" : "1234567890123" }
- category: (string)
- bundle: (number)
Number of products in a pack. 16 x 125g, 16 is the bundle, 125g is the mass.
Example:
{ "id": "fa2cb", "rawLabel": "x5506 OATS QUAKER BIO", "quantity": 1, "unitPrice": 1.64, "packageUnity": "Kg", "mass": 1, "flags": [ "bio" ], "price": 1.64, "bundle": 1, "product": { "category": "food > sweet_grocery > cereals > breakfast_cereals", "categoryUid": "33f92698-284b-fd44-575a-f1e9cea9973e", "brand": "QUAKER", "brandUid": "05a5069d-fd64-b97b-ac06-101dcfc1686c" } }
- id: required(string)
- barcodes: (array of object)
🆕 1D or 2D codes found in the image after cropping the document from the rest of image
Items: items
- type: required(one of EAN-2, EAN-5, EAN-8, UPC-E, ISBN-10, UPC-A, EAN-13, ISBN-13, COMPOSITE, I2/5, DataBar, DataBar-Exp, Codabar, CODE-39, CODE-93, CODE-128, PDF417, QR-Code, UNKNOWN)
type of code detected
- data: required(string)
Data read from the code
- location: required(object)
- x: required(number)
x
location of the code in image - y: required(number)
y
location of the code in image - width: required(number)
width
of the code in image - height: required(number)
height
of the code in image
- x: required(number)
Example:
[{ "type": "CODE-128", "data": "12456789", "location": { "x": 0.0, "y": 0.0, "width": 50, "height": 20 } }]
- type: required(one of EAN-2, EAN-5, EAN-8, UPC-E, ISBN-10, UPC-A, EAN-13, ISBN-13, COMPOSITE, I2/5, DataBar, DataBar-Exp, Codabar, CODE-39, CODE-93, CODE-128, PDF417, QR-Code, UNKNOWN)
Example:
{ "shop": { "city": "Toulon", "sign": "CARREFOUR", "subSign": "MARKET", "phone": "0494419879", "address": "CENTRE CIAL MAYOL", "postalCode": "83000" }, "articleCount": 2, "total": 4.25, "totalMax": 4, "buyDate": "2016-12-07", "buyHour": "11:08:00", "items": [ { "id": "fa2cb", "rawLabel": "x5506 OATS QUAKER", "quantity": 1, "unitPrice": 1.64, "packageUnity": "Kg", "mass": 1, "price": 1.64, "bundle": 1, "product": { "category": "breakfast_cereals", "brand": "QUAKER" } }, { "id": "9d7fb", "rawLabel": "4 BTE 6X33CL COCA CO 2,61", "shortLabel": "BTE 6X33CL COCA CO", "quantity": 1, "unitPrice": 2.61, "packageUnity": "CL", "mass": 33, "bundle": 6, "price": 2.61, "product": { "category": "soda", "categoryUid": "efb24280-2dd9-423d-91d3-263fc780b6df", "brand": "COCA COLA" } } ] }
- buyHour: (time-only)
Example:
{ "uid": "89cd32b8-15e9-4e63-af5e-9e85da188fa1", "createdAt": "2019-09-20T08:19:57Z", "updatedAt": "2019-09-20T08:20:09Z", "dominantLanguage": "fr-FR", "name": "receiptTest", "campaignUid": "fc928982-3acc-4aea-bca3-e50d22e0b6ca", "userPseudoId": "8335c8d1-5ae7-440c-90d1-50543c86d9b4", "status": "PROCESSED", "processReport": "NO_ERROR", "imageUrl": "https://receipt.agkit.io/v2/documents/89cd32b8-15e9-4e63-af5e-9e85da188fa1/show", "data": { "shop": { "city": "Toulon", "sign": "CARREFOUR", "subSign": "MARKET", "phone": "0494419879", "address": "CENTRE CIAL MAYOL", "postalCode": "83000", "geoLocation": "48.31763410000001,1.9993057" }, "articleCount": 3, "total": 6.51, "totalMax": 6.26, "buyDate": "2016-12-07", "buyHour": "11:08:00", "payment": [ "CASH", "CARD" ], "barcodes": [ { "type": "CODE-128", "data": "12456789", "location": { "x": 0, "y": 0, "width": 50, "height": 20 } } ], "items": [ { "id": "fa2cb", "rawLabel": "x5506 OATS QUAKER 1,64", "quantity": 1, "unitPrice": 1.64, "packageUnity": "Kg", "mass": 1, "price": 1.64, "bundle": 1, "product": { "category": "food > sweet_grocery > cereals > breakfast_cereals", "categoryUid": "33f92698-284b-fd44-575a-f1e9cea9973e", "brand": "QUAKER", "brandUid": "05a5069d-fd64-b97b-ac06-101dcfc1686c" } }, { "id": "47267", "rawLabel": "PEPSI REGULAR 2,26", "shortLabel": "PEPSI REGULAR", "quantity": 1, "unitPrice": 2.26, "bundle": 1, "price": 2.26, "product": { "category": "drink > alcohol_free > soda", "categoryUid": "efb24280-2dd9-423d-91d3-263fc780b6df", "brand": "PEPSI", "brandUid": "822ed5c0-1d5c-0ec1-0cf9-5b62b2caecca" } }, { "id": "9d7fb", "rawLabel": "4 BTE 6X33CL COCA CO 2,61", "shortLabel": "BTE 6X33CL COCA CO", "quantity": 1, "unitPrice": 2.61, "packageUnity": "CL", "mass": 33, "bundle": 6, "price": 2.61, "product": { "category": "drink > alcohol_free > soda", "categoryUid": "efb24280-2dd9-423d-91d3-263fc780b6df", "brand": "COCA COLA > CLASSIC", "brandUid": "f2eaa047-39d8-0855-b0e3-098b2bbec0d5" } } ] }, "processedRules": { "uid": "1234", "name": "Quaker", "dateRule": { "min": "2019-01-01", "max": "2019-11-01", "isMatched": false }, "signRule": { "signList": [ "Carrefour" ], "isMatched": true }, "itemRule": { "term": "Quaker", "quantityRequired": 1, "strategy": "QUANTITY", "isMatched": true, "itemsMatched": [ "fa2cb" ], "quantityMatched": 1 }, "allRulesMatched": false, "totalPriceOfMatchedItems": 1.64 }, "anomalyReport": { "flags": [ "BARCODE_ALREADY_EXISTS", "SAME_SHOP_SAME_MOMENT", "EXISTING_PRODUCT_LIST", "HIGH_GLOBAL_CONTENT_SIMILARITY" ], "potentialDuplicateReceipts": [ { "uid": "e67c9571-47a7-42cd-8439-c94bc9d5e478", "flags": [ "SAME_SHOP_SAME_MOMENT", "EXISTING_PRODUCT_LIST", "HIGH_GLOBAL_CONTENT_SIMILARITY" ] }, { "uid": "c1b2997b-c6a1-48c2-819e-300fe61db5e9", "flags": [ "BARCODE_ALREADY_EXISTS" ] } ] }, "introspectionData": { "resolution": { "width": 2608, "height": 4632 }, "size": 3564061, "exif": { "bitsPerSample": 8, "cameraMake": "", "cameraModel": "", "digitizeDatetime": "", "exposureBias": 0, "exposureProgram": 0, "flashMode": 0, "flashReturnedLight": 0, "flashUsed": 0, "focalLength": 0, "focalLength35mm": 0, "focalPlaneXRes": 0, "focalPlaneYRes": 0, "fstop": 0, "gpsAltitude": 0, "gpsCoordinate": "0.000000,0.000000", "gpsPrecision": 0, "imageCopyright": "", "imageDatetime": "", "imageDescription": "", "imageHeight": 0, "imageOrientation": 0, "imageWidth": 0, "isoSpeed": 0, "lensFocalLengthMax": 0, "lensFocalLengthMin": 0, "lensFstopMax": 0, "lensFstopMin": 0, "lensMake": "", "lensModel": "", "meteringMode": 0, "originalDatetime": "", "software": "", "subjectDistance": 0, "subsecondTime": "" } } }
- uid: required(string)
HTTP status code 400
Filter malformed or invalid filter key
HTTP status code 403
You cannot access this resources with this token
HTTP status code 404
Body
Media type: application/json
Type: object
Properties- error: required(string)
Example:
{ "notFound" : "resource has not been found on this system" }
Secured by OAuth2.0 - Hydra
post /endpoints/{endpointId}/documents
Add document for a given endpoint
OAuth2.0 authentification required
URI Parameters
- endpointId: required(string)
Query Parameters
- name: required(string)
This field represent a string that identify this document for the client perspective. Allowing him to retrieve a document by it's own id. Id must be unique per company, the API will systematically refuse any duplicate id here for a given company
- dominantLanguage: (string)
A locale format with the following pattern {iso 639-1}-{ISO 3166-1}, this is used to specifiy on which language the system should analyse receipts, very important !
Example:
fr-FR
- userPseudoId: (string)
Client side user id that created this document image, this id is dependant of client.
Body
Media type: image/jpg
Type: file
Media type: image/png
Type: file
Media type: application/pdf
Type: file
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- uid: required(string)
Aboutgoods generated unique ID
- createdAt: required(datetime)
When this object has been registered in AG system
- updatedAt: required(datetime)
The last time this entity had been updated in AG system
- dominantLanguage: required(string)
A locale format with the following pattern
{iso 639-1}-{ISO 3166-1}
- Usage : specifiy on which language the Receipt Analyzer should treat receipts
Example:
fr-FR
- status: required(one of WAITING_FOR_DOCUMENT, WAITING_FOR_PROCESS, PROCESSING, PROCESSED, NOT_EXPLOITABLE, SUBSCRIPTION_ISSUE)
As of today we have 6 status for differents states of an image in our systems, when everything is fine PROCESSED
- processReport: required(one of NO_ERROR, BAD_QUALITY_IMAGE, NOT_ENOUGH_TEXT, MULTIPLE_RECEIPT, UNREADABLE, BAD_LOCALE, NOT_RECEIPT, ERROR_JPG, BAD_URL, NOT_ANALYZED)
Process Report represent a more detailled reason about why a receipt has not been analyzed correctly A key to let the client knows what happened during analysis, helps you understand the status
NO_ERROR
=> Everything is fine, this come with thePROCESSED
status by defaultBAD_QUALITY_IMAGE
=> We detected a too blurry image or too dark, it can also be the resolution of the imageNOT_ENOUGH_TEXT
=> Self explicit, we have a threshold for the text recognition in image, if our OCR did not found enough text to generate a satisfiable amount of data, we abandon the ProcessMULTIPLE_RECEIPT
=> We do not handle multiple receipt in one image, when we detect this case, we stop the processUNREADABLE
=> Our OCR could not determine any Text in the imageBAD_LOCALE
=> We could not find any language for the detection to operate. This means that the Language or country is currently not supported by our systemNOT_RECEIPT
=> We didn't find any receipt in the imageERROR_IMAGE_FORMAT
=> The image format is not valid (not one of jpg, pdf, png)BAD_URL
=> No image has been found at the given URL (internal error)NOT_ANALYZED
=> The document has not been analyzed for the moment, this comes with theWAITING_FOR_DOCUMENT
,WAITING_FOR_PROCESS
orPROCESSING
statuses
- anomalyReport: (object)
Result of the anomaly analysis
- flags: required(array of string)
Array of flags. List of the available flags:
ORIGINAL_RECEIPT
=> No clues detectedIDENTICAL_EXISTING_FILE
=> Same MD5 already present in company's receiptsBARCODE_ALREADY_EXISTS
=> Same barcode already presentHIGH_FILE_SIMILARITY
=> Similar phash already presentSAME_SHOP_SAME_MOMENT
=> Receipt with same shop at same buyTime already presentEXISTING_PRODUCT_LIST
=> Receipt with same product list already presentHIGH_GLOBAL_CONTENT_SIMILARITY
=> Combination of the 2 previous flagsBANNED_SOFTWARE
=> Receipt with one of the editing software of the list present in its exifs- Adobe Photoshop
- Windows Photo Editor
- paint.net
- PhotoFiltre
- PicsArt
- PaintShop
- GIMP
- TouchRetouch
- Snapseed
- PhotoStudio
- ACDSee
- PhotoScape
- Aviary
- potentialDuplicateReceipts: required(array of duplicateReceipt)
Items: duplicateReceipt
- uid: required(string)
Uid of the duplicated receipt
- flags: required(array of string)
Array of flags that were found for this duplicated document regarding the original receipt.
Example:
{ "uid": "e67c9571-47a7-42cd-8439-c94bc9d5e478", "flags": ["SAME_SHOP_SAME_MOMENT", "EXISTING_PRODUCT_LIST", "HIGH_GLOBAL_CONTENT_SIMILARITY"] }
- uid: required(string)
Example:
{ "flags": [ "BARCODE_ALREADY_EXISTS", "SAME_SHOP_SAME_MOMENT", "EXISTING_PRODUCT_LIST", "HIGH_GLOBAL_CONTENT_SIMILARITY" ], "potentialDuplicateReceipts": [ { "uid": "e67c9571-47a7-42cd-8439-c94bc9d5e478", "flags": ["SAME_SHOP_SAME_MOMENT", "EXISTING_PRODUCT_LIST", "HIGH_GLOBAL_CONTENT_SIMILARITY"] }, { "uid": "c1b2997b-c6a1-48c2-819e-300fe61db5e9", "flags": ["SAME_SHOP_SAME_MOMENT", "BARCODE_ALREADY_EXISTS"] } ] }
- flags: required(array of string)
- imageUrl: required(string)
URL for getting image from a cdn repository
- name: required(string)
Id of this document that client (aka you) had set when sending the image of document in the first place.
- Helps you to retrieve a document by it's name
- endpointUid: (string)
Endpoint id that had served this document
- campaignUid: (string)
If this document is a part of promotion campaign, id of campaign is displayed here
- userPseudoId: (string)
This ID correspond to a custom and client managed id specified by the developer of the application that had setup AGKit SDK (aka you in general).
- This can also come from an userId that you sent over this very API when sending a receipt
- processedRules: (object)
- name: required(string)
Name of the whole rule, must be unique for a given campaign
- uid: required(string)
unique uid of the rule
- priceRule: (object)
rule that defines rule on prices
- eligibleOnly: required(number)
minimum price of all matched items
- totalAmount: (number)
minimum total amount of receipt
- isMatched: required(boolean)
tells if the rule is matched in receipt
Example:
{ "eligibleOnly": 20.25, "totalAmount": 40, "isMatched": false }
- eligibleOnly: required(number)
- itemRule: required(object)
rule that defines terms to search and various conditions of search (or, and)
- term: (string)
Just a simple rule to look for this term in the receipt. Mutually exclusive with AND and TERM.
- quantityRequired: (integer)
minimum required quantity of term or clause (AND/OR) to find. Is added by Rulio by default = 1.
- strategy: (string)
strategy used to count the item for quantityRequired
Example:
QUANTITY | BUNDLE | QUANTITY_TIMES_BUNDLE
- or: (array of object)
The result of running OR Rule with itemsMatched and isMatched.
Items:
- and: (array of object)
The result of running AND Rule with itemsMatched and isMatched.
Items:
- not: (array of object)
The result of running NOT Rule with itemsMatched and isMatched.
Items:
- isMatched: required(boolean)
tells if the rule is matched in receipt
- itemsMatched: (array of string)
List of IDs of items that were matched by term. Even if the rule is false (quantityRequired is not met), can have some IDs.
- quantityMatched: (integer)
quantity of term or terms in clause (AND/OR) found (even if the quantityRequired is not met). Can be different from the number of items in itemsMatched (one product line - but bought twice)
Example:
{ "quantityRequired": 2, "strategy": "QUANTITY", "or": [ { "term": "Labeyrie", "quantityRequired": 1, "strategy": "QUANTITY", "itemsMatched": [ "3" ], "isMatched": true, "quantityMatched": 1 }, { "term": "Blini", "quantityRequired": 1, "strategy": "QUANTITY", "itemsMatched": [ "1", "2" ], "quantityMatched": 2, "isMatched": true } ], "not": [ { "isMatched": true, "term": "Auchan", "itemsMatched": [ "2" ], "quantityMatched": 1 }, { "isMatched": false, "term": "Cora", "itemsMatched": [], "quantityMatched": 0 }, { "isMatched": false, "term": "Carrefour", "itemsMatched": [], "quantityMatched": 0 } ], "itemsMatched": [ "3", "1" ], "quantityMatched": 2, "isMatched": true }
- term: (string)
- signRule: (object)
rule that defines the list of signs for a given promotion
- signList: required(array of string)
List of sign eligible for the promotion.
- isMatched: required(boolean)
tells if the rule is matched in receipt
Example:
{ "signList": [ "Auchan", "Cora" ], "isMatched": true }
- signList: required(array of string)
- dateRule: required(object)
rule that defines range of dates for a given promotion
- min: required(string)
start date of the promotion/campaign
- max: required(string)
last date of the promotion/campaign
- isMatched: required(boolean)
tells if the rule is matched in receipt
Example:
{ "min": "2019-01-01", "max": "2019-11-01", "isMatched": true }
- min: required(string)
- allRulesMatched: required(boolean)
summarizes all rules matching, true if all rules are matched
- totalPriceOfMatchedItems: required(number)
total price of items that matched ItemRule
Example:
{ "name": "Labeyrie", "uid": "123", "itemRule": { "quantityRequired": 2, "strategy": "QUANTITY", "or": [ { "term": "Labeyrie", "quantityRequired": 1, "strategy": "QUANTITY", "itemsMatched": [ "3" ], "isMatched": true, "quantityMatched": 1 }, { "term": "Blini", "quantityRequired": 1, "strategy": "QUANTITY", "itemsMatched": [ "1", "2" ], "quantityMatched": 2, "isMatched": true } ], "not": [ { "isMatched": true, "term": "Auchan", "itemsMatched": [ "2" ], "quantityMatched": 1 }, { "isMatched": false, "term": "Cora", "itemsMatched": [], "quantityMatched": 0 } ], "itemsMatched": [ "3", "1" ], "quantityMatched": 2, "isMatched": true }, "dateRule": { "min": "2019-01-01", "max": "2019-11-01", "isMatched": true }, "priceRule": { "eligibleOnly": 15, "isMatched": false }, "signRule": { "signList": [ "Cora", "Auchan", "Carrefour" ], "isMatched": true }, "allRulesMatched": false, "totalPriceOfMatchedItems": 9.74 }
- name: required(string)
- appId: (string)
If this document has been received from AGKit (our mobile application SDK), this field allow to identify the application which have been used to send the document
- introspectionData: (object)
Introspection data that is infered from a given image, those data are useful to identify an image / receipt from its binary data
- resolution: required(object)
Size of the image
- width: required(number)
- height: required(number)
- size: (number)
Size in a human readable format (Mb or Kb)
- exif: (object)
Exif extracted from the image, possible keys available:
- cameraMake
- cameraModel
- software
- bitsPerSample
- imageWidth
- imageHeight
- imageDescription
- imageOrientation
- imageCopyright
- imageDatetime
- originalDatetime
- digitizeDatetime
- subsecondTime
- fstop
- exposureProgram
- isoSpeed
- subjectDistance
- exposureBias
- flashUsed
- flashReturnedLight
- flashMode
- meteringMode
- focalLength
- focalLength35mm
- gpsAltitude
- gpsPrecision
- lensFocalLengthMin
- lensFocalLengthMax
- lensFstopMin
- lensFstopMax
- lensMake
- lensModel
- focalPlaneXRes
- focalPlaneYRes
- gpsCoordinate
- resolution: required(object)
- data: (object)
Actual data that has been extracted from the receipt content Note: This field will be empty on the first document post response, as the process is running asynchronously, expect this field to be filled with data when the Status is set to
PROCESSED
- buyHour: (time-only)
🕐 The hour displayed on the receipt (ISO 8601 Time 'hh:mm:ss')
- buyDate: (date-only)
🗓 Date of buy for the receipt (ISO 8601 Date 2018-10-22)
- articleCount: (number)
Number of items in cart for this receipt
- total: (number)
🆙 Total amount paid by the customer (can be negative !)
- totalMax: (number)
🆕 Total value of the merchandises for this receipt, this can be different from what user paid (total field).
- payment: (array of string)
🆕 Buying mode or payment methods, can have multiple payments methods for a receipt, "UNKNOWN" if nothing was found
Example:
["CARD", "CASH", "CHEQUE", "UNKNOWN"]
- locale: (string)
Locale specified for this receipt analysis
- shop: (object)
🏬 This object represent the store / shop we found for this receipt, most of the time it will be only one data per field, but we can also send a top 3 with some significative accuracy
- city: (string)
City where the store of this buy is located
- sign: (string)
Store name or sign name / Brand of the shop
- subSign: (string)
SubSign of the shop
- phone: (string)
Phone number of the store
- address: (string)
Exact address of the store
- postalCode: (string)
Postal code for the city where we found this store
- geoLocation: (string)
Latitude and longitude for the shop, following https://tools.ietf.org/html/rfc5870 standard (example 13.4125,103.8667)
Example:
{ "city": "Toulon", "sign": "CARREFOUR", "subSign": "MARKET", "phone": "0494419879", "address": "CENTRE CIAL MAYOL", "postalCode": "83000", "geoLocation" : "48.31763410000001,1.9993057" }
- city: (string)
- items: required(array of object)
Items with products detected
Items: items
- id: required(string)
An ID unique to this list of item. Mainly used to identify this particular item in this receipt for our rule processor to indicate which item has matched a given rule.
- rawLabel: (string)
Raw line read on the receipt by OCR
- shortLabel: (string)
Detected short label from rawLabel, we remove price and other non label data from rawLabel
- quantity: (number)
Quantity of item detected in receipt
- unitPrice: (number)
A price detected for one piece of this item
- packageUnity: (string)
Package unity for item, for example Kg
- mass: (number)
The mass detected for the package, example 5 (Kg from PackageUnity)
- flags: (array of string)
Some notable characteristics detected on the product, BIO for example, or gluten free or anything special
Example:
["bio", "aop"]
- price: (number)
Total price for this item, (if found quantity > 1, we multiply to get this data, or we read it from receipt)
- product: (object)
What we understood from the item, we link item data to a clean and well organized product from our database and we put informations about it here.
- category: (string)
A fully qualified AGCategory name for this product infered by our AI algorithm, retrieve the complete list of categories here https://doc.kweeri.io/resources/list-of-product-categories.html
- categoryUid: (string)
Reference UID from Aboutgoods taxonomy
- brand: (string)
Fully qualified Brand name of product if displayed in label infered by our AI algorithm
- brandUid: (string)
Reference UID from Aboutgoods brands taxonomy of product if displayed in label infered by our AI algorithm
- brandLine: (string)
⚠️ deprecated: this field will be removed in future releases
- gtin: (string)
If present on the receipt, we extract the GTIN (EAN 13) Code
Example:
{ "brand": "PETIT NAVIRE", "brandLine": "FILETS DE THON", "category" : "tinned_fish", "categoryUid" : "4e54e68c-637f-a7d9-d509-f7e32b849f60", "gtin" : "1234567890123" }
- category: (string)
- bundle: (number)
Number of products in a pack. 16 x 125g, 16 is the bundle, 125g is the mass.
Example:
{ "id": "fa2cb", "rawLabel": "x5506 OATS QUAKER BIO", "quantity": 1, "unitPrice": 1.64, "packageUnity": "Kg", "mass": 1, "flags": [ "bio" ], "price": 1.64, "bundle": 1, "product": { "category": "food > sweet_grocery > cereals > breakfast_cereals", "categoryUid": "33f92698-284b-fd44-575a-f1e9cea9973e", "brand": "QUAKER", "brandUid": "05a5069d-fd64-b97b-ac06-101dcfc1686c" } }
- id: required(string)
- barcodes: (array of object)
🆕 1D or 2D codes found in the image after cropping the document from the rest of image
Items: items
- type: required(one of EAN-2, EAN-5, EAN-8, UPC-E, ISBN-10, UPC-A, EAN-13, ISBN-13, COMPOSITE, I2/5, DataBar, DataBar-Exp, Codabar, CODE-39, CODE-93, CODE-128, PDF417, QR-Code, UNKNOWN)
type of code detected
- data: required(string)
Data read from the code
- location: required(object)
- x: required(number)
x
location of the code in image - y: required(number)
y
location of the code in image - width: required(number)
width
of the code in image - height: required(number)
height
of the code in image
- x: required(number)
Example:
[{ "type": "CODE-128", "data": "12456789", "location": { "x": 0.0, "y": 0.0, "width": 50, "height": 20 } }]
- type: required(one of EAN-2, EAN-5, EAN-8, UPC-E, ISBN-10, UPC-A, EAN-13, ISBN-13, COMPOSITE, I2/5, DataBar, DataBar-Exp, Codabar, CODE-39, CODE-93, CODE-128, PDF417, QR-Code, UNKNOWN)
Example:
{ "shop": { "city": "Toulon", "sign": "CARREFOUR", "subSign": "MARKET", "phone": "0494419879", "address": "CENTRE CIAL MAYOL", "postalCode": "83000" }, "articleCount": 2, "total": 4.25, "totalMax": 4, "buyDate": "2016-12-07", "buyHour": "11:08:00", "items": [ { "id": "fa2cb", "rawLabel": "x5506 OATS QUAKER", "quantity": 1, "unitPrice": 1.64, "packageUnity": "Kg", "mass": 1, "price": 1.64, "bundle": 1, "product": { "category": "breakfast_cereals", "brand": "QUAKER" } }, { "id": "9d7fb", "rawLabel": "4 BTE 6X33CL COCA CO 2,61", "shortLabel": "BTE 6X33CL COCA CO", "quantity": 1, "unitPrice": 2.61, "packageUnity": "CL", "mass": 33, "bundle": 6, "price": 2.61, "product": { "category": "soda", "categoryUid": "efb24280-2dd9-423d-91d3-263fc780b6df", "brand": "COCA COLA" } } ] }
- buyHour: (time-only)
Example:
{
"uid": "89cd32b8-15e9-4e63-af5e-9e85da188fa1",
"createdAt": "2019-09-20T08:19:57Z",
"updatedAt": "2019-09-20T08:20:09Z",
"dominantLanguage": "fr-FR",
"name": "receiptTest",
"campaignUid": "fc928982-3acc-4aea-bca3-e50d22e0b6ca",
"userPseudoId": "8335c8d1-5ae7-440c-90d1-50543c86d9b4",
"status": "PROCESSED",
"processReport": "NO_ERROR",
"imageUrl": "https://receipt.agkit.io/v2/documents/89cd32b8-15e9-4e63-af5e-9e85da188fa1/show",
"data": {
"shop": {
"city": "Toulon",
"sign": "CARREFOUR",
"subSign": "MARKET",
"phone": "0494419879",
"address": "CENTRE CIAL MAYOL",
"postalCode": "83000",
"geoLocation": "48.31763410000001,1.9993057"
},
"articleCount": 3,
"total": 6.51,
"totalMax": 6.26,
"buyDate": "2016-12-07",
"buyHour": "11:08:00",
"payment": [
"CASH",
"CARD"
],
"barcodes": [
{
"type": "CODE-128",
"data": "12456789",
"location": {
"x": 0,
"y": 0,
"width": 50,
"height": 20
}
}
],
"items": [
{
"id": "fa2cb",
"rawLabel": "x5506 OATS QUAKER 1,64",
"quantity": 1,
"unitPrice": 1.64,
"packageUnity": "Kg",
"mass": 1,
"price": 1.64,
"bundle": 1,
"product": {
"category": "food > sweet_grocery > cereals > breakfast_cereals",
"categoryUid": "33f92698-284b-fd44-575a-f1e9cea9973e",
"brand": "QUAKER",
"brandUid": "05a5069d-fd64-b97b-ac06-101dcfc1686c"
}
},
{
"id": "47267",
"rawLabel": "PEPSI REGULAR 2,26",
"shortLabel": "PEPSI REGULAR",
"quantity": 1,
"unitPrice": 2.26,
"bundle": 1,
"price": 2.26,
"product": {
"category": "drink > alcohol_free > soda",
"categoryUid": "efb24280-2dd9-423d-91d3-263fc780b6df",
"brand": "PEPSI",
"brandUid": "822ed5c0-1d5c-0ec1-0cf9-5b62b2caecca"
}
},
{
"id": "9d7fb",
"rawLabel": "4 BTE 6X33CL COCA CO 2,61",
"shortLabel": "BTE 6X33CL COCA CO",
"quantity": 1,
"unitPrice": 2.61,
"packageUnity": "CL",
"mass": 33,
"bundle": 6,
"price": 2.61,
"product": {
"category": "drink > alcohol_free > soda",
"categoryUid": "efb24280-2dd9-423d-91d3-263fc780b6df",
"brand": "COCA COLA > CLASSIC",
"brandUid": "f2eaa047-39d8-0855-b0e3-098b2bbec0d5"
}
}
]
},
"processedRules": {
"uid": "1234",
"name": "Quaker",
"dateRule": {
"min": "2019-01-01",
"max": "2019-11-01",
"isMatched": false
},
"signRule": {
"signList": [
"Carrefour"
],
"isMatched": true
},
"itemRule": {
"term": "Quaker",
"quantityRequired": 1,
"strategy": "QUANTITY",
"isMatched": true,
"itemsMatched": [
"fa2cb"
],
"quantityMatched": 1
},
"allRulesMatched": false,
"totalPriceOfMatchedItems": 1.64
},
"anomalyReport": {
"flags": [
"BARCODE_ALREADY_EXISTS",
"SAME_SHOP_SAME_MOMENT",
"EXISTING_PRODUCT_LIST",
"HIGH_GLOBAL_CONTENT_SIMILARITY"
],
"potentialDuplicateReceipts": [
{
"uid": "e67c9571-47a7-42cd-8439-c94bc9d5e478",
"flags": [
"SAME_SHOP_SAME_MOMENT",
"EXISTING_PRODUCT_LIST",
"HIGH_GLOBAL_CONTENT_SIMILARITY"
]
},
{
"uid": "c1b2997b-c6a1-48c2-819e-300fe61db5e9",
"flags": [
"BARCODE_ALREADY_EXISTS"
]
}
]
},
"introspectionData": {
"resolution": {
"width": 2608,
"height": 4632
},
"size": 3564061,
"exif": {
"bitsPerSample": 8,
"cameraMake": "",
"cameraModel": "",
"digitizeDatetime": "",
"exposureBias": 0,
"exposureProgram": 0,
"flashMode": 0,
"flashReturnedLight": 0,
"flashUsed": 0,
"focalLength": 0,
"focalLength35mm": 0,
"focalPlaneXRes": 0,
"focalPlaneYRes": 0,
"fstop": 0,
"gpsAltitude": 0,
"gpsCoordinate": "0.000000,0.000000",
"gpsPrecision": 0,
"imageCopyright": "",
"imageDatetime": "",
"imageDescription": "",
"imageHeight": 0,
"imageOrientation": 0,
"imageWidth": 0,
"isoSpeed": 0,
"lensFocalLengthMax": 0,
"lensFocalLengthMin": 0,
"lensFstopMax": 0,
"lensFstopMin": 0,
"lensMake": "",
"lensModel": "",
"meteringMode": 0,
"originalDatetime": "",
"software": "",
"subjectDistance": 0,
"subsecondTime": ""
}
}
}
HTTP status code 400
Body
Media type: application/json
Type: object
Properties- error: required(string)
Example:
{ "badRequest" : "You are missing some field or they are malformed" }
HTTP status code 401
Authentication with Auth0 failed
HTTP status code 402
Your quota has been exceeded
HTTP status code 404
Body
Media type: application/json
Type: object
Properties- error: required(string)
Example:
{ "notFound" : "resource has not been found on this system" }
HTTP status code 409
Document or name already exists for your company
Secured by OAuth2.0 - Hydra
/whoami
Get the list of all companies
get /whoami
Get the list of all companies
OAuth2.0 authentification required
HTTP status code 200
Body
Media type: application/json
Type: object
Properties- company: required(string)
Name of the company
- features: required(array of object)
Items: feature
- name: required(one of CSV_EXPORT, PROMOTIONS, QC, RECEIPT, SHERLOCK)
CSV_EXPORT gives access to /export routes PROMOTIONS gives access to /campaigns routes QC gives access to /check route RECEIPT gives access to receipt analysis SHERLOCK gives access to field 'anomalyReport' in data analysis response
- quota: required(integer)
Quota associated to the feature. A quota equals to -1 (default) gives unlimited access. Otherwise, quota is decremented each time the feature is used.
- name: required(one of CSV_EXPORT, PROMOTIONS, QC, RECEIPT, SHERLOCK)
- message: required(string)
HTTP status code 401
Body
Media type: application/json
Type: object
Properties- error: required(string)
Example:
{ "notFound" : "resource has not been found on this system" }