Create load reference

POST

api

{version}

loads

{loadNumber}

references

Create load reference

curl --request POST \
  --url https://integrations.alvys.com/api/p/v{version}/loads/{loadNumber}/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}/loads/{loadNumber}/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}/loads/{loadNumber}/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}/loads/{loadNumber}/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}/loads/{loadNumber}/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}/loads/{loadNumber}/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>"
}

{
  "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 a load that already exists. Creating a reference does not take an If-Match header; the server retries bounded concurrency conflicts internally. The response includes a refreshed load ETag you can carry into a later update. Requires load:update. See Updating records safely for how create and update differ on this surface.

Path parameters

Name	Type	Required	Description
version	string	Yes	API version (for example `2.0`).
loadNumber	string	Yes	Business load number of the load.

Request body

Field	Type	Required	Description
Name	string	Yes	Reference name. At most 50 characters. For catalog-backed writes, must match the configured definition name.
Value	string	Yes	Reference value. At most 40 characters (enough for a 36-character CFDI folio UUID). `OrderNumber` / `PONumber` stay at X12 30.
ReferenceId	string	No	Optional catalog definition id from List reference definitions.

{
  "Name": "Customer PO",
  "Value": "PO-123",
  "ReferenceId": "tenant-reference-id"
}

Example

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

Status codes

Code	Description
201	Reference created; body is the reference; `ETag` header is the refreshed load validator.
400	Validation failed (including name or value length).
401	Authentication failed or the token is missing.
403	The token is not authorized to update loads.
404	No load was found for the load number, or the catalog definition is not visible for loads.
409	This load already has a value for that catalog definition — update the existing instance instead.

Free-form creates (no ReferenceId) are not idempotent. Do not automatically replay a POST unless you have confirmed the first request did not commit. Use Update load reference with the returned instance id to overwrite.

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

loadNumber

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

Name

string

required

Value

string

required

string | null

ReferenceId

string | null

Type

string | null

Access

string | null

Origin

string | null

⌘I

Create load reference

curl --request POST \
  --url https://integrations.alvys.com/api/p/v{version}/loads/{loadNumber}/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}/loads/{loadNumber}/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}/loads/{loadNumber}/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}/loads/{loadNumber}/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}/loads/{loadNumber}/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}/loads/{loadNumber}/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>"
}

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