Create carrier invoice

POST

api

{version}

invoices

carrier-invoice

Create carrier invoice

curl --request POST \
  --url https://integrations.alvys.com/api/p/v{version}/invoices/carrier-invoice \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form File='@example-file' \
  --form 'TripId=<string>' \
  --form 'CarrierInvoiceNumber=<string>' \
  --form 'PaymentType=<string>'

const form = new FormData();
form.append('File', '<string>');
form.append('TripId', '<string>');
form.append('CarrierInvoiceNumber', '<string>');
form.append('PaymentType', '<string>');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://integrations.alvys.com/api/p/v{version}/invoices/carrier-invoice', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://integrations.alvys.com/api/p/v{version}/invoices/carrier-invoice"

files = { "File": ("example-file", open("example-file", "rb")) }
payload = {
    "TripId": "<string>",
    "CarrierInvoiceNumber": "<string>",
    "PaymentType": "<string>"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://integrations.alvys.com/api/p/v{version}/invoices/carrier-invoice",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"File\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"TripId\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"CarrierInvoiceNumber\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"PaymentType\"\r\n\r\n<string>\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://integrations.alvys.com/api/p/v{version}/invoices/carrier-invoice"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"File\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"TripId\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"CarrierInvoiceNumber\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"PaymentType\"\r\n\r\n<string>\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://integrations.alvys.com/api/p/v{version}/invoices/carrier-invoice")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"File\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"TripId\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"CarrierInvoiceNumber\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"PaymentType\"\r\n\r\n<string>\r\n-----011000010111000001101001--")
  .asString();

{
  "id": "<string>",
  "AttachmentPath": "<string>",
  "AttachmentType": "<string>",
  "ParentId": "<string>",
  "ParentType": "<string>",
  "AttachmentSize": 123,
  "UploadedAt": "2023-11-07T05:31:56Z",
  "UploadedBy": "<string>",
  "DownloadUrl": "<string>",
  "ExpiresAt": "2023-11-07T05:31:56Z"
}

{
  "Errors": {},
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

This endpoint allows factoring or payment platforms to push carrier invoices directly into Alvys and associate them with the relevant trip. The request uses multipart/form-data and must contain exactly one file.

Path Parameters

Parameter	Type	Required	Description
version	string	Yes	API version (e.g., `1.0`)

Request Body

Content-Type: multipart/form-data

Parameter	Type	Required	Description
File	binary	Yes	Carrier invoice document file
TripId	string	Yes	Identifier of the trip the invoice belongs to
CarrierInvoiceNumber	string	No	Carrier-provided invoice number
PaymentType	string	No	Payment type for the carrier invoice (e.g., `Standard Pay`, `Quick Pay`)

Example Request (cURL)

curl -X POST "{{host}}/api/p/v1/invoices/carrier-invoice" \
  -H "Authorization: Bearer $TOKEN" \
  -F "File=@carrier_invoice.pdf" \
  -F "TripId=trip_12345" \
  -F "CarrierInvoiceNumber=INV-93842" \
  -F "PaymentType=Standard Pay"

Responses

200 OK

Returns metadata for the uploaded carrier invoice attachment.

400 Bad Request

Returned when required fields are missing or the multipart request is invalid.

401 Unauthorized

Returned when authentication is missing or invalid.

403 Forbidden

Returned when access to this endpoint is not allowed.

404 Not Found

Returned when the specified TripId does not exist.

413 Content Too Large

Returned when the uploaded file exceeds the allowed size limit.

415 Unsupported Media Type

Returned when the uploaded file type is not supported.

Response Body

Field	Type	Description
id	string	Unique identifier of the uploaded document
AttachmentPath	string	File path or filename assigned during upload
AttachmentType	string	Type of the uploaded document
AttachmentSize	integer	File size in bytes
UploadedAt	string	UTC timestamp when the file was uploaded
ParentId	string	Identifier of the parent entity (TripId)
ParentType	string	Entity type the document is attached to
UploadedBy	string	Identifier of the user or system that uploaded the file
DownloadUrl	string	Temporary URL to download the uploaded file
ExpiresAt	string	Expiration timestamp for the download URL

Example Response

{
  "id": "string",
  "AttachmentPath": "string",
  "AttachmentType": "string",
  "AttachmentSize": 0,
  "UploadedAt": "2026-03-16T13:45:12.539Z",
  "ParentId": "string",
  "ParentType": "string",
  "UploadedBy": "string",
  "DownloadUrl": "string",
  "ExpiresAt": "2026-03-16T13:45:12.539Z"
}

Notes

The request must include exactly one file.
The uploaded document will be associated with the specified TripId.
This endpoint is typically used by factoring or payment platforms to submit carrier invoices programmatically.
Response schema uses the standard AttachmentResponse model.
Supports multipart/form-data upload only.

Example integration use case: Carriers upload invoices to a factoring/payment platform (e.g., EPay), which then pushes the invoice to Alvys via this endpoint so the invoice is attached to the relevant trip.

Validation Notes

PaymentType currently accepts any string value. If the provided value does not match a configured payment type, the system defaults to 30-day payment terms. Recommended improvement: The API should validate PaymentType against configured carrier payment terms and return 400 Bad Request when an invalid value is provided.

Authorizations

Authorization

string

header

required

OAuth 2.0 client-credentials access token. Obtain one from https://auth.alvys.com/oauth/token (grant_type=client_credentials, audience=https://api.alvys.com/public/), then paste it here. The playground sends it as Authorization: Bearer <token>.

Path Parameters

version

string

default:1.0

required

API version (e.g., 1.0)

Example:

"1.0"

Body

multipart/form-data

File

file

required

TripId

string

required

CarrierInvoiceNumber

string

PaymentType

string

Response

string

required

AttachmentPath

string

required

AttachmentType

string

required

ParentId

string

required

ParentType

string

required

AttachmentSize

integer<int64> | null

UploadedAt

string<date-time> | null

UploadedBy

string | null

DownloadUrl

string | null

ExpiresAt

string<date-time> | null

⌘I

Create carrier invoice

curl --request POST \
  --url https://integrations.alvys.com/api/p/v{version}/invoices/carrier-invoice \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form File='@example-file' \
  --form 'TripId=<string>' \
  --form 'CarrierInvoiceNumber=<string>' \
  --form 'PaymentType=<string>'

const form = new FormData();
form.append('File', '<string>');
form.append('TripId', '<string>');
form.append('CarrierInvoiceNumber', '<string>');
form.append('PaymentType', '<string>');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://integrations.alvys.com/api/p/v{version}/invoices/carrier-invoice', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://integrations.alvys.com/api/p/v{version}/invoices/carrier-invoice"

files = { "File": ("example-file", open("example-file", "rb")) }
payload = {
    "TripId": "<string>",
    "CarrierInvoiceNumber": "<string>",
    "PaymentType": "<string>"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://integrations.alvys.com/api/p/v{version}/invoices/carrier-invoice",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"File\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"TripId\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"CarrierInvoiceNumber\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"PaymentType\"\r\n\r\n<string>\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://integrations.alvys.com/api/p/v{version}/invoices/carrier-invoice"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"File\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"TripId\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"CarrierInvoiceNumber\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"PaymentType\"\r\n\r\n<string>\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://integrations.alvys.com/api/p/v{version}/invoices/carrier-invoice")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"File\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"TripId\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"CarrierInvoiceNumber\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"PaymentType\"\r\n\r\n<string>\r\n-----011000010111000001101001--")
  .asString();

{
  "id": "<string>",
  "AttachmentPath": "<string>",
  "AttachmentType": "<string>",
  "ParentId": "<string>",
  "ParentType": "<string>",
  "AttachmentSize": 123,
  "UploadedAt": "2023-11-07T05:31:56Z",
  "UploadedBy": "<string>",
  "DownloadUrl": "<string>",
  "ExpiresAt": "2023-11-07T05:31:56Z"
}

{
  "Errors": {},
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

​Path Parameters

​Request Body

​Example Request (cURL)

​Responses

​200 OK

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​413 Content Too Large

​415 Unsupported Media Type

​Response Body

​Example Response

​Notes

​Validation Notes

Authorizations

Path Parameters

Body

Response

Path Parameters

Request Body

Example Request (cURL)

Responses

200 OK

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

413 Content Too Large

415 Unsupported Media Type

Response Body

Example Response

Notes

Validation Notes