Create trip reference

POST

api

{version}

trips

{tripId}

references

Create trip reference

curl --request POST \
  --url https://integrations.alvys.com/api/p/v{version}/trips/{tripId}/references \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json-patch+json' \
  --data '
{
  "Name": "<string>",
  "Value": "<string>",
  "ReferenceId": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json-patch+json'},
  body: JSON.stringify({Name: '<string>', Value: '<string>', ReferenceId: '<string>'})
};

fetch('https://integrations.alvys.com/api/p/v{version}/trips/{tripId}/references', 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}/trips/{tripId}/references"

payload = {
    "Name": "<string>",
    "Value": "<string>",
    "ReferenceId": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json-patch+json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://integrations.alvys.com/api/p/v{version}/trips/{tripId}/references",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'Name' => '<string>',
    'Value' => '<string>',
    'ReferenceId' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json-patch+json"
  ],
]);

$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}/trips/{tripId}/references"

	payload := strings.NewReader("{\n  \"Name\": \"<string>\",\n  \"Value\": \"<string>\",\n  \"ReferenceId\": \"<string>\"\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json-patch+json")

	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}/trips/{tripId}/references")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json-patch+json")
  .body("{\n  \"Name\": \"<string>\",\n  \"Value\": \"<string>\",\n  \"ReferenceId\": \"<string>\"\n}")
  .asString();

{
  "Name": "<string>",
  "Value": "<string>",
  "Id": "<string>",
  "ReferenceId": "<string>",
  "Type": "<string>",
  "Access": "<string>",
  "Origin": "<string>"
}

{
  "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>"
}

Adds a custom reference to an existing trip. Creating a reference does not take a client If-Match header. The write persists only the target trip (not the load or sibling trips) and returns that trip’s refreshed ETag. Requires trip:update. See Updating records safely.

Path parameters

Name	Type	Required	Description
version	string	Yes	API version (for example `2.0`).
tripId	string	Yes	Trip id.

Request body

Field	Type	Required	Description
Name	string	Yes	Reference name. At most 50 characters.
Value	string	Yes	Reference value. At most 40 characters (enough for a 36-character CFDI folio UUID).
ReferenceId	string	No	Optional catalog definition id from List reference definitions.

{
  "Name": "Route",
  "Value": "West",
  "ReferenceId": "tenant-reference-id"
}

Example

curl --location 'https://integrations.alvys.com/api/p/v2.0/trips/{tripId}/references' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "Name": "Route",
    "Value": "West",
    "ReferenceId": "tenant-reference-id"
  }'

Status codes

Code	Description
201	Reference created; refreshed trip `ETag` on the response.
400	Validation failed (including name or value length).
401	Authentication failed or the token is missing.
403	The token is not authorized to update trips.
404	Trip or catalog definition was not found / not visible for trips.
409	This trip already has a value for that catalog definition — update the existing instance instead.

Free-form creates are not idempotent. Prefer Update trip reference with the returned instance id when overwriting.

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

tripId

string

required

version

string

default:2.0

required

API version (e.g., 2.0)

Example:

"2.0"

Body

Name

string

required

Reference name. Must be 50 characters or fewer. For catalog-backed writes, must match the configured definition name.

Maximum string length: 50

Value

string

required

Reference value. Must be 40 characters or fewer — enough for a 36-character CFDI folio UUID. OrderNumber and PONumber stay at the X12 30-character bound and are unchanged by this field.

Maximum string length: 40

ReferenceId

string | null

Optional tenant catalog definition id from List custom reference definitions. When set, the value is validated against that definition.

Response

Created

Name

string

required

Value

string

required

string | null

ReferenceId

string | null

Type

string | null

Access

string | null

Origin

string | null

⌘I

Create trip reference

curl --request POST \
  --url https://integrations.alvys.com/api/p/v{version}/trips/{tripId}/references \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json-patch+json' \
  --data '
{
  "Name": "<string>",
  "Value": "<string>",
  "ReferenceId": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json-patch+json'},
  body: JSON.stringify({Name: '<string>', Value: '<string>', ReferenceId: '<string>'})
};

fetch('https://integrations.alvys.com/api/p/v{version}/trips/{tripId}/references', 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}/trips/{tripId}/references"

payload = {
    "Name": "<string>",
    "Value": "<string>",
    "ReferenceId": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json-patch+json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://integrations.alvys.com/api/p/v{version}/trips/{tripId}/references",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'Name' => '<string>',
    'Value' => '<string>',
    'ReferenceId' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json-patch+json"
  ],
]);

$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}/trips/{tripId}/references"

	payload := strings.NewReader("{\n  \"Name\": \"<string>\",\n  \"Value\": \"<string>\",\n  \"ReferenceId\": \"<string>\"\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json-patch+json")

	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}/trips/{tripId}/references")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json-patch+json")
  .body("{\n  \"Name\": \"<string>\",\n  \"Value\": \"<string>\",\n  \"ReferenceId\": \"<string>\"\n}")
  .asString();

{
  "Name": "<string>",
  "Value": "<string>",
  "Id": "<string>",
  "ReferenceId": "<string>",
  "Type": "<string>",
  "Access": "<string>",
  "Origin": "<string>"
}

{
  "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>"
}

​Path parameters

​Request body

​Example

​Status codes

Authorizations

Path Parameters

Body

Response

Path parameters

Request body

Example

Status codes