Invoice

Not authenticated— sign in to auto-fill your API key in code examples

Upload invoice

POST/v1/invoices/upload

Response200

{
  "ok": true,
  "importId": "imp_01HQXYZ",
  "mappingId": "map_01HQXYZ",
  "detectedColumns": [
    "Tracking Number",
    "Weight (kg)",
    "Zone",
    "Price HT",
    "Surcharges"
  ]
}

Response400

{
  "ok": false,
  "error": "Invalid request parameters",
  "code": "VALIDATION_ERROR",
  "details": {
    "field": "email",
    "reason": "must be a valid email address"
  }
}

Response401

{
  "ok": false,
  "error": "Authentication required",
  "code": "UNAUTHORIZED",
  "details": {}
}

Get mapping

GET/v1/invoices/mappings/:id

Confirm mapping

PUT/v1/invoices/mappings/:id/confirm

List imports

GET/v1/invoices/imports

Parameter	Required	Description
`page`integer	optional	Page number (1-based).
`limit`integer	optional	Number of items per page.
`status`enum	optional	Filter by import status.

Response200

{
  "ok": true,
  "imports": [
    {
      "id": "imp_01HQXYZ",
      "carrierId": "car_01HQXYZ",
      "carrierName": "Chronopost",
      "fileName": "invoice_march_2026.csv",
      "status": "completed",
      "totalLines": 3200,
      "errorCount": 12,
      "createdAt": "2026-03-15T10:00:00Z",
      "completedAt": "2026-03-15T10:05:32Z"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 20
}

Response401

{
  "ok": false,
  "error": "Authentication required",
  "code": "UNAUTHORIZED",
  "details": {}
}

Start processing

POST/v1/invoices/imports/start-processing

Request body

importIdstringrequired

Response200

{
  "ok": true,
  "jobId": "job_01HQXYZ"
}

Response400

{
  "ok": false,
  "error": "Invalid request parameters",
  "code": "VALIDATION_ERROR",
  "details": {
    "field": "email",
    "reason": "must be a valid email address"
  }
}

Response401

{
  "ok": false,
  "error": "Authentication required",
  "code": "UNAUTHORIZED",
  "details": {}
}

Response404

{
  "ok": false,
  "error": "Resource not found",
  "code": "NOT_FOUND",
  "details": {}
}

Import lines

GET/v1/invoices/imports/:id/lines

Import errors

GET/v1/invoices/imports/:id/errors

Reconcile

POST/v1/invoices/reconcile

Request body

importIdstringrequired

optionsobject

Response200

{
  "ok": true,
  "key": "recon_01HQXYZ"
}

Response400

{
  "ok": false,
  "error": "Invalid request parameters",
  "code": "VALIDATION_ERROR",
  "details": {
    "field": "email",
    "reason": "must be a valid email address"
  }
}

Response401

{
  "ok": false,
  "error": "Authentication required",
  "code": "UNAUTHORIZED",
  "details": {}
}

Reconcile progress

GET/v1/invoices/reconcile/progress/:key

Parameter	Required	Description
`key`string	required

Response200

{
  "ok": true,
  "progress": 67.5,
  "status": "running",
  "total": 3200,
  "processed": 2160
}

Response401

{
  "ok": false,
  "error": "Authentication required",
  "code": "UNAUTHORIZED",
  "details": {}
}

Response404

{
  "ok": false,
  "error": "Resource not found",
  "code": "NOT_FOUND",
  "details": {}
}

Simulate

POST/v1/invoices/simulate

Request body

importIdstringrequired

parametersobjectrequired

Response200

{
  "ok": true,
  "jobId": "sim_01HQXYZ"
}

Response400

{
  "ok": false,
  "error": "Invalid request parameters",
  "code": "VALIDATION_ERROR",
  "details": {
    "field": "email",
    "reason": "must be a valid email address"
  }
}

Response401

{
  "ok": false,
  "error": "Authentication required",
  "code": "UNAUTHORIZED",
  "details": {}
}

Active simulation

GET/v1/invoices/simulate/active

Response200

{
  "ok": true,
  "simulation": {
    "jobId": "sim_01HQXYZ",
    "importId": "imp_01HQXYZ",
    "status": "running",
    "progress": 45,
    "createdAt": "2026-03-31T11:00:00Z"
  }
}

Response401

{
  "ok": false,
  "error": "Authentication required",
  "code": "UNAUTHORIZED",
  "details": {}
}

Simulation result

GET/v1/invoices/simulate/result

Response200

{
  "ok": true,
  "result": {
    "jobId": "sim_01HQXYZ",
    "importId": "imp_01HQXYZ",
    "status": "completed",
    "totalLines": 3200,
    "summary": {
      "currentTotalExclTax": 42560,
      "simulatedTotalExclTax": 38750,
      "savingsExclTax": 3810,
      "savingsPercent": 8.95
    },
    "completedAt": "2026-03-31T11:12:45Z"
  }
}

Response401

{
  "ok": false,
  "error": "Authentication required",
  "code": "UNAUTHORIZED",
  "details": {}
}

Response404

{
  "ok": false,
  "error": "Resource not found",
  "code": "NOT_FOUND",
  "details": {}
}

Simulation status

GET/v1/invoices/simulate/status/:jobId

Parameter	Required	Description
`jobId`string	required

Response200

{
  "ok": true,
  "jobId": "sim_01HQXYZ",
  "status": "running",
  "progress": 45
}

Response401

{
  "ok": false,
  "error": "Authentication required",
  "code": "UNAUTHORIZED",
  "details": {}
}

Response404

{
  "ok": false,
  "error": "Resource not found",
  "code": "NOT_FOUND",
  "details": {}
}