Viðskiptaráð Íslands

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/me
The key’s user and company, the company’s stamps and the allowed countries of origin.
GET/api/v1/applications
List applications, newest first. Query: status, since (ISO 8601, by creation time), limit (max 200, default 50).
POST/api/v1/applications
Create 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.pdf
Attach a document. The request body is the file itself (PDF, JPEG or PNG, max 4 MB).
POST/api/v1/applications/{id}/files/upload-url
Files 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/complete
Files 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}/finalize
Submit the application to the Chamber for processing.
GET/api/v1/applications/{id}/draft.pdf
Draft of the certificate, before it is accepted.
GET/api/v1/applications/{id}/certificate.pdf
The 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).

exporter
string, required
Box 1. Name and address, lines separated by \n.
consignee
string, required
Box 2. Name and address.
country_of_origin
string
ISO 3166 alpha-2 code. Default IS. Allowed codes are listed in /me.
country_of_destination
string, required
ISO 3166 alpha-2 code.
transport
string
Box 4. Transport details.
remarks
string
Box 5.
items
array, required
At least one item line: {description, info, gross_weight, invoice}.
items_description
string
Free text for box 6, used with or instead of item lines.
total_gross_weight
string
Total weight as it should appear, e.g. "24.500 kg".
stamp_id
integer
Company stamp from /me. Default: the company’s default stamp.
date
string
Date on the certificate, YYYY-MM-DD. Default today.
originals
integer
Number of originals. Default 1.
priority
boolean
Expedited processing (fee applies).
print
boolean
The Chamber prints, stamps and signs by hand (fee applies).
mail_delivery
boolean
Printed certificate sent by mail (fee applies; implies print).
template_name
string
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.