Certificates of origin: API
For companies that create applications from their own systems. Everything the API does can also be done in the web interface at uppruni.vi.is, and applications created either way appear in both.
Authentication
Any user of the system can create an API key: log in, open Settings and choose “Create key”. The key acts as that user and sees only your company’s applications. For an integration we recommend a dedicated user rather than a person’s own; the Chamber can set one up (mottaka@vi.is). Send the key in every request:
Authorization: Bearer upr_…Keep the key secret, as you would a password. If it leaks, revoke it under Settings and create a new one. Requests and responses are JSON (UTF-8) unless noted.
The flow
# 1. Create the application
curl -X POST https://uppruni.vi.is/api/v1/applications \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{
"exporter": "Example ehf.\nBorgartún 35\n105 Reykjavík\nIceland",
"consignee": "Example GmbH\nHafenstrasse 1\n20457 Hamburg\nGermany",
"country_of_origin": "IS",
"country_of_destination": "DE",
"transport": "Sea freight, Reykjavík to Hamburg",
"items": [{"description": "Frozen mackerel", "info": "1.000 cartons", "gross_weight": "24.500 kg", "invoice": "INV-1234"}],
"total_gross_weight": "24.500 kg"
}'
# → 201 {"id": 85012, "number": "APP-085012", "status": "in_progress", …}
# 2. Attach at least one supporting document (normally the invoice)
curl -X POST "https://uppruni.vi.is/api/v1/applications/85012/files?filename=INV-1234.pdf" \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/pdf" \
--data-binary @INV-1234.pdf
# 3. Submit it to the Chamber
curl -X POST https://uppruni.vi.is/api/v1/applications/85012/finalize -H "Authorization: Bearer $KEY"
# → {"status": "finalized", …}
# 4. Poll until it is processed (every few minutes is plenty)
curl https://uppruni.vi.is/api/v1/applications/85012 -H "Authorization: Bearer $KEY"
# → {"status": "accepted", "certificate": {"number": "IS-082012", …}, …}
# 5. Download the certificate
curl -o IS-082012.pdf https://uppruni.vi.is/api/v1/applications/85012/certificate.pdf -H "Authorization: Bearer $KEY"Statuses
in_progress being prepared, can be changed. finalized submitted, waiting for the Chamber. accepted certificate issued. revoked certificate withdrawn; the application can be changed and finalized again, and a new certificate with a new number is then issued. If the Chamber returns an application for correction it goes back to in_progress and returned_reason holds the explanation; correct it with PATCH and finalize again. The user also gets the usual e-mail notifications.
Endpoints
| GET | /api/v1/meThe key’s user and company, the company’s stamps and the allowed countries of origin. |
| GET | /api/v1/applicationsList applications, newest first. Query: status, since (ISO 8601, by creation time), limit (max 200, default 50). |
| POST | /api/v1/applicationsCreate an application (status in_progress). |
| GET | /api/v1/applications/{id}One application, including status, files and certificate number. |
| PATCH | /api/v1/applications/{id}Change an application that is in_progress. Only the fields sent are changed; items replaces all item lines. |
| DELETE | /api/v1/applications/{id}Delete an application that is in_progress. |
| POST | /api/v1/applications/{id}/files?filename=invoice.pdfAttach a document. The request body is the file itself (PDF, JPEG or PNG, max 4 MB). |
| POST | /api/v1/applications/{id}/files/upload-urlFiles over 4 MB (max 30 MB), step 1: send {content_type, size}; PUT the file to the returned upload_url. |
| POST | /api/v1/applications/{id}/files/completeFiles over 4 MB, step 2: send {key, filename}. |
| DELETE | /api/v1/applications/{id}/files/{fileId}Remove an attachment from an application that is in_progress. |
| POST | /api/v1/applications/{id}/finalizeSubmit the application to the Chamber for processing. |
| GET | /api/v1/applications/{id}/draft.pdfDraft of the certificate, before it is accepted. |
| GET | /api/v1/applications/{id}/certificate.pdfThe issued certificate with stamped attachments (status accepted). |
Application fields
The same fields and rules as the web form. Text fields may contain line breaks (\n).
exporterstring, required | Box 1. Name and address, lines separated by \n. |
consigneestring, required | Box 2. Name and address. |
country_of_originstring | ISO 3166 alpha-2 code. Default IS. Allowed codes are listed in /me. |
country_of_destinationstring, required | ISO 3166 alpha-2 code. |
transportstring | Box 4. Transport details. |
remarksstring | Box 5. |
itemsarray, required | At least one item line: {description, info, gross_weight, invoice}. |
items_descriptionstring | Free text for box 6, used with or instead of item lines. |
total_gross_weightstring | Total weight as it should appear, e.g. "24.500 kg". |
stamp_idinteger | Company stamp from /me. Default: the company’s default stamp. |
datestring | Date on the certificate, YYYY-MM-DD. Default today. |
originalsinteger | Number of originals. Default 1. |
priorityboolean | Expedited processing (fee applies). |
printboolean | The Chamber prints, stamps and signs by hand (fee applies). |
mail_deliveryboolean | Printed certificate sent by mail (fee applies; implies print). |
template_namestring | Saves the application as a template under this name. |
Errors
Errors use standard HTTP status codes and a JSON body. 401 missing or invalid key, 404 not found (or belongs to another company), 409 wrong status for the action, 422 invalid input, with the fields listed in details.
{"error": {"code": "validation", "message": "Invalid or missing fields.",
"details": [{"field": "consignee", "problem": "…"}]}}Good to know
To finalize, the application needs a company stamp, at least one attachment and, unless print is true, a signature on file for the key’s user. Stamps and signatures are managed in the web interface. Prices are in the price list on vi.is. Questions: mottaka@vi.is.