Create a Waybill

Creates a Waybill or Delivery Note according to the input parameters. After successful processing, the DocumentId and Document Number are returned in the result. If the client has valid Tax Authority credentials and has the Tax Communication feature activated and the option "Send automatically transport guides AT" checked, the document is reported to the Tax Authority and the document updated with the ATCode.

Endpoint

POST https://bo.magnifinance.com/api/v1.1/document/waybill

Request

Header

Parameter	Required	Value
Email	required	string(50) The API user with specific permission to create documents and get information about your own documents into a company. Example: api@magnifinance.com
Token	required	The token of the subscription in which the document will be generated.

note

*These parameters must be HTTP headers within the request.

Body

Parameter	Required	Description
IsToClose	required	boolean Should the document be closed (true) in which case it cannot be later changed, and a PDF and document number are generated or should the document be created as a draft (false) in which case no PDF or document number are generated. Example value: "true"
SendTo	optional	string Email address to send the document to after creation.
Client	required	object Client information object.
Waybill	required	object Waybill document information object.

Client

Parameter	Required	Description
Name	required	string(75) Client familiar name. Example value: "MagniFinance"
NIF	required	string(20) Client Tax ID. The tax id must be valid. Example value: "166737755"
Address	optional	string(200) Client address. Example value: "Av. Sidonio Pais, N 2, 2 Esq. A 1050 - 215"
City	optional	string(50) Client city. Example value: "Lisboa"
PostCode	optional	string(50) Client post code. The post code must be valid. Example value: "1050-214"
CountryCode	required	string(2) Client country. To consult the code list for each country, access the link: ISO 3166-1 alpha-2. Example value: "PT"
CountryName	optional	string Name of the country. Example value: "Portugal"
PhoneNumber	optional	string(50) Client phone number. Example value: "999999999"
LegalName	optional	string(500) Client legal name, client's name on invoices, whether not informed, 'Name' will be considered. Example value: "MagniFin lda"
Email	optional	string(255) Client email address. Example value: "info@magnifinance.com"
IBAN	optional	string(300) Client international bank account number. Example value: "PT50002700000001234567833"

Waybill

Parameter	Required	Description
Type	required	string(1) Type of the document to be created. The possible type is "W" for Waybill and "Y" for Delivery Note. Example value: "W"
Date	required	date Document date. This date must be posterior to the previously closed document date for this series. Format: yyyy-mm-dd. Example value: "2022-03-20"
Description	optional	string(300) Description to be included in the waybill. Example value: "Here you put the description"
Serie	optional	string(30) Document series (sequence) in which the document will be created. The series have a unique name per document type. If not sent, the default series for that type of document in that subscription will be used. You can view a list of series for each type of document following the path in the system: Settings -> General -> Document series. Example value: "FR"
TaxExemptionReasonCode	optional	string(3) Required if there is at least one line with 0% tax. Justifies why 0% tax was used. To access the complete list, click here. Example value: "M01"
Currency	optional	string(3) Currency to be used additionally to EUR. (ISO 4217). Example value: "BRL"
EuroRate	optional	decimal Number by which to multiply the amounts to get the alternative currency amount. Example value: "1"
Retention	optional	decimal Percentage of the document total amount that will be retained as tax with this operation. Example value: "8"
ExternalId	optional	string(50) Your identifier for this document. Used to prevent document duplication. Uniqueness is verified in combination with the client information. Example value: "test51519125"
Lines	required	(Object) List of APIInvoicingProduct This is the list of products that will appear in the document.
LoadDateTime	required	Date The date and time that the Waybill will be used. Should be equal or greater than the waybill date. Example value: "2022-06-21T08:22:54"
LoadAddress	required	(Object) All the LoadAddress data.
DestinationAddress	required	(Object) All the DestinationAddress data.
VehicleLicence	optional	string(30) The license plate of the vehicle using the waybill. Example value: "AA 16 AA"

Lines (APIInvoicingProduct)

Parameter	Required	Description
Code	required	string(60) Identifies the product. Example value: "PRODUCT CODE 123"
Description	required	string(200) Description of the product. Example value: "My Product Description"
UnitPrice	required	decimal Amount per unit. Example value: "2.45"
Quantity	required	decimal Number of units. Example value: "1"
Unit	required	string(50) Unit name. Example value: "KG"
Type	required	string(1) "S" for services, "P" for product. Once the product is created you cannot change the type. Example value: "P"
TaxValue	required	decimal Percentage of tax. Example value: "23"
ProductDiscount	required	decimal Percentage of discount. Example value: "0"
CostCenter	optional	string(50) Cost center to be used for the line. Example value: "Espanha"

LoadAddress

Parameter	Required	Description
AddressDetail	required	string(100) The address of the starting point of the waybill. Example value: "Av. Sidonio Pais, N 2, 2 Esq. A"
City	required	string(50) The city of the starting point of the waybill. Example value: "Lisboa"
PostalCode	required	string(20) The postal-code of the starting point of the waybill. Example value: "1050-215"
CountryCode	required	string(2) Client country. To consult the code list for each country, access the link: ISO 3166-1 alpha-2. Example value: "PT"

DestinationAddress

Parameter	Required	Description
AddressDetail	required	string(100) The destination address of the waybill. Example value: "Rua das madres 100"
City	required	string(50) The destination city of the waybill. Example value: "Lisboa"
PostalCode	required	string(20) The postal-code destination of the waybill. Example value: "1000-000"
CountryCode	required	string(2) Client country. To consult the code list for each country, access the link: ISO 3166-1 alpha-2. Example value: "PT"

Response

Parameter	Description
RequestId	Unique Id for the request to have a way to identify the request
Type	string Description to inform if the request was a success or error. Example value: "Success"
Object
DocumentId	int If the request is successful the Id of the document is returned for future queries. Example value: "67204"
DocumentNumber	string In case of success the number of the document is returned. Example value: "GT GT/238"
ErrorMessage	string Unprocessed error message.
ErrorValue	MagniEnum
Value	int Identifies the error with a number. To identify the types of errors in more detail, click here. Example value: "14"
Name	string Identifies the error with a token. Example value: "SaveFailed"
ErrorHumanReadable	string Text that explains the error found. Example value: "ValidationError"
ValidationErrors	List of ValidationError
Type	string Identifies the error with a token. Example value: "MustBePosteriorToMostCurrentClosedDocument"
ElementNumber	int Identifies index of the field in which validation failed. Example value: "0"
Field	string Name of the field in which validation failed. Example value: "DocumentDetailDate"
Detail	string Detailed error explanation. Example value: "A closed document already exists with a date after this with this Series. You must change series or enter a date equal or after to 2021-11-10"
IsError	boolean Whether the request failed or not. Example value: "false"
IsSuccess	boolean Whether the request succeeded or not. Example value: "true"

Sample Body

{
  "IsToClose": "",
  "SendTo": "",
  "Client": {
    "NIF": "",
    "Name": "",
    "Address": "",
    "City": "",
    "PostCode": "",
    "CountryCode": "",
    "PhoneNumber": "",
    "CountryName": "",
    "LegalName": ""
  },
  "Waybill": {
    "Type": "",
    "Serie": "",
    "Date": "",
    "DueDate": "",
    "Description": "",
    "DocumentReference": "",
    "TaxExemptionReasonCode": "",
    "Currency": "",
    "EuroRate": "",
    "Retention": "",
    "Lines": [
      {
        "Code": "",
        "Description": "",
        "UnitPrice": "",
        "Quantity": "",
        "Unit": "",
        "Type": "",
        "TaxValue": "",
        "ProductDiscount": "",
        "CostCenter": ""
      }
    ],
    "LoadDateTime": "",
    "LoadAddress": {
      "AddressDetail": "",
      "City": "",
      "PostalCode": "",
      "CountryCode": ""
    },
    "DestinationAddress": {
      "AddressDetail": "",
      "City": "",
      "PostalCode": "",
      "CountryCode": ""
    },
    "VehicleLicence": ""
  }
}

Request Samples

Below you can check some examples of the REST request in some technologies.

cURL

curl --location --request POST 'https://bo.magnifinance.com/api/v1.1/document/waybill' \
  --header 'email: XXX@example.com' \
  --header 'token: XXX' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "IsToClose": "true",
    "SendTo": "",
    "Client": {
      "NIF": "166737755",
      "Name": "MagniFinance",
      "Address": "Av. Sidonio Pais, N 2",
      "City": "Lisboa",
      "PostCode": "1050-215",
      "CountryCode": "PT",
      "PhoneNumber": "",
      "CountryName": "Portugal",
      "LegalName": "MagniFin lda"
    },
    "Waybill": {
      "Type": "W",
      "Serie": "",
      "Date": "2022-03-20",
      "Description": "Transport description",
      "TaxExemptionReasonCode": "",
      "Currency": "",
      "EuroRate": "",
      "Retention": "",
      "Lines": [
        {
          "Code": "PROD001",
          "Description": "Product Description",
          "UnitPrice": "10.00",
          "Quantity": "5",
          "Unit": "KG",
          "Type": "P",
          "TaxValue": "23",
          "ProductDiscount": "0",
          "CostCenter": ""
        }
      ],
      "LoadDateTime": "2022-06-21T08:22:54",
      "LoadAddress": {
        "AddressDetail": "Av. Sidonio Pais, N 2, 2 Esq. A",
        "City": "Lisboa",
        "PostalCode": "1050-215",
        "CountryCode": "PT"
      },
      "DestinationAddress": {
        "AddressDetail": "Rua das madres 100",
        "City": "Porto",
        "PostalCode": "4000-000",
        "CountryCode": "PT"
      },
      "VehicleLicence": "AA 16 AA"
    }
  }'

JavaScript (fetch)

var myHeaders = new Headers();
myHeaders.append("Host", "bo.magnifinance.com");
myHeaders.append("email", "XXX@example.com");
myHeaders.append("token", "XXX");
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({
  "IsToClose": "true",
  "SendTo": "",
  "Client": {
    "NIF": "166737755",
    "Name": "MagniFinance",
    "Address": "Av. Sidonio Pais, N 2",
    "City": "Lisboa",
    "PostCode": "1050-215",
    "CountryCode": "PT",
    "PhoneNumber": "",
    "CountryName": "Portugal",
    "LegalName": "MagniFin lda"
  },
  "Waybill": {
    "Type": "W",
    "Serie": "",
    "Date": "2022-03-20",
    "Description": "Transport description",
    "Lines": [
      {
        "Code": "PROD001",
        "Description": "Product Description",
        "UnitPrice": "10.00",
        "Quantity": "5",
        "Unit": "KG",
        "Type": "P",
        "TaxValue": "23",
        "ProductDiscount": "0"
      }
    ],
    "LoadDateTime": "2022-06-21T08:22:54",
    "LoadAddress": {
      "AddressDetail": "Av. Sidonio Pais, N 2, 2 Esq. A",
      "City": "Lisboa",
      "PostalCode": "1050-215",
      "CountryCode": "PT"
    },
    "DestinationAddress": {
      "AddressDetail": "Rua das madres 100",
      "City": "Porto",
      "PostalCode": "4000-000",
      "CountryCode": "PT"
    },
    "VehicleLicence": "AA 16 AA"
  }
});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://bo.magnifinance.com/api/v1.1/document/waybill", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Node.js (axios)

var axios = require('axios');

var data = JSON.stringify({
  "IsToClose": "true",
  "SendTo": "",
  "Client": {
    "NIF": "166737755",
    "Name": "MagniFinance",
    "Address": "Av. Sidonio Pais, N 2",
    "City": "Lisboa",
    "PostCode": "1050-215",
    "CountryCode": "PT",
    "PhoneNumber": "",
    "CountryName": "Portugal",
    "LegalName": "MagniFin lda"
  },
  "Waybill": {
    "Type": "W",
    "Serie": "",
    "Date": "2022-03-20",
    "Description": "Transport description",
    "Lines": [
      {
        "Code": "PROD001",
        "Description": "Product Description",
        "UnitPrice": "10.00",
        "Quantity": "5",
        "Unit": "KG",
        "Type": "P",
        "TaxValue": "23",
        "ProductDiscount": "0"
      }
    ],
    "LoadDateTime": "2022-06-21T08:22:54",
    "LoadAddress": {
      "AddressDetail": "Av. Sidonio Pais, N 2, 2 Esq. A",
      "City": "Lisboa",
      "PostalCode": "1050-215",
      "CountryCode": "PT"
    },
    "DestinationAddress": {
      "AddressDetail": "Rua das madres 100",
      "City": "Porto",
      "PostalCode": "4000-000",
      "CountryCode": "PT"
    },
    "VehicleLicence": "AA 16 AA"
  }
});

var config = {
  method: 'post',
  url: 'https://bo.magnifinance.com/api/v1.1/document/waybill',
  headers: {
    'email': 'XXX@example.com',
    'token': 'XXX',
    'Content-Type': 'application/json'
  },
  data: data
};

axios(config)
  .then(function (response) {
    console.log(JSON.stringify(response.data));
  })
  .catch(function (error) {
    console.log(error);
  });

Python (requests)

import requests
import json

url = "https://bo.magnifinance.com/api/v1.1/document/waybill"
headers = {
    "email": "XXX@example.com",
    "token": "XXX",
    "Content-Type": "application/json"
}
payload = {
    "IsToClose": "true",
    "SendTo": "",
    "Client": {
        "NIF": "166737755",
        "Name": "MagniFinance",
        "Address": "Av. Sidonio Pais, N 2",
        "City": "Lisboa",
        "PostCode": "1050-215",
        "CountryCode": "PT",
        "PhoneNumber": "",
        "CountryName": "Portugal",
        "LegalName": "MagniFin lda"
    },
    "Waybill": {
        "Type": "W",
        "Serie": "",
        "Date": "2022-03-20",
        "Description": "Transport description",
        "Lines": [
            {
                "Code": "PROD001",
                "Description": "Product Description",
                "UnitPrice": "10.00",
                "Quantity": "5",
                "Unit": "KG",
                "Type": "P",
                "TaxValue": "23",
                "ProductDiscount": "0"
            }
        ],
        "LoadDateTime": "2022-06-21T08:22:54",
        "LoadAddress": {
            "AddressDetail": "Av. Sidonio Pais, N 2, 2 Esq. A",
            "City": "Lisboa",
            "PostalCode": "1050-215",
            "CountryCode": "PT"
        },
        "DestinationAddress": {
            "AddressDetail": "Rua das madres 100",
            "City": "Porto",
            "PostalCode": "4000-000",
            "CountryCode": "PT"
        },
        "VehicleLicence": "AA 16 AA"
    }
}

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

PHP (cURL)

<?php
$url = "https://bo.magnifinance.com/api/v1.1/document/waybill";
$headers = [
    "email: XXX@example.com",
    "token: XXX",
    "Content-Type: application/json"
];
$payload = json_encode([
    "IsToClose" => "true",
    "SendTo" => "",
    "Client" => [
        "NIF" => "166737755",
        "Name" => "MagniFinance",
        "Address" => "Av. Sidonio Pais, N 2",
        "City" => "Lisboa",
        "PostCode" => "1050-215",
        "CountryCode" => "PT",
        "PhoneNumber" => "",
        "CountryName" => "Portugal",
        "LegalName" => "MagniFin lda"
    ],
    "Waybill" => [
        "Type" => "W",
        "Serie" => "",
        "Date" => "2022-03-20",
        "Description" => "Transport description",
        "Lines" => [
            [
                "Code" => "PROD001",
                "Description" => "Product Description",
                "UnitPrice" => "10.00",
                "Quantity" => "5",
                "Unit" => "KG",
                "Type" => "P",
                "TaxValue" => "23",
                "ProductDiscount" => "0"
            ]
        ],
        "LoadDateTime" => "2022-06-21T08:22:54",
        "LoadAddress" => [
            "AddressDetail" => "Av. Sidonio Pais, N 2, 2 Esq. A",
            "City" => "Lisboa",
            "PostalCode" => "1050-215",
            "CountryCode" => "PT"
        ],
        "DestinationAddress" => [
            "AddressDetail" => "Rua das madres 100",
            "City" => "Porto",
            "PostalCode" => "4000-000",
            "CountryCode" => "PT"
        ],
        "VehicleLicence" => "AA 16 AA"
    ]
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

C# (HttpClient)

using System.Net.Http;
using System.Text;
using System.Text.Json;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("email", "XXX@example.com");
client.DefaultRequestHeaders.Add("token", "XXX");

var payload = new {
    IsToClose = "true",
    SendTo = "",
    Client = new {
        NIF = "166737755",
        Name = "MagniFinance",
        Address = "Av. Sidonio Pais, N 2",
        City = "Lisboa",
        PostCode = "1050-215",
        CountryCode = "PT",
        PhoneNumber = "",
        CountryName = "Portugal",
        LegalName = "MagniFin lda"
    },
    Waybill = new {
        Type = "W",
        Serie = "",
        Date = "2022-03-20",
        Description = "Transport description",
        Lines = new[] {
            new {
                Code = "PROD001",
                Description = "Product Description",
                UnitPrice = "10.00",
                Quantity = "5",
                Unit = "KG",
                Type = "P",
                TaxValue = "23",
                ProductDiscount = "0"
            }
        },
        LoadDateTime = "2022-06-21T08:22:54",
        LoadAddress = new {
            AddressDetail = "Av. Sidonio Pais, N 2, 2 Esq. A",
            City = "Lisboa",
            PostalCode = "1050-215",
            CountryCode = "PT"
        },
        DestinationAddress = new {
            AddressDetail = "Rua das madres 100",
            City = "Porto",
            PostalCode = "4000-000",
            CountryCode = "PT"
        },
        VehicleLicence = "AA 16 AA"
    }
};

var content = new StringContent(
    JsonSerializer.Serialize(payload),
    Encoding.UTF8,
    "application/json"
);

var response = await client.PostAsync(
    "https://bo.magnifinance.com/api/v1.1/document/waybill",
    content
);

var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

Java (HttpClient)

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

HttpClient client = HttpClient.newHttpClient();

String payload = """
    {
        "IsToClose": "true",
        "SendTo": "",
        "Client": {
            "NIF": "166737755",
            "Name": "MagniFinance",
            "Address": "Av. Sidonio Pais, N 2",
            "City": "Lisboa",
            "PostCode": "1050-215",
            "CountryCode": "PT",
            "PhoneNumber": "",
            "CountryName": "Portugal",
            "LegalName": "MagniFin lda"
        },
        "Waybill": {
            "Type": "W",
            "Serie": "",
            "Date": "2022-03-20",
            "Description": "Transport description",
            "Lines": [
                {
                    "Code": "PROD001",
                    "Description": "Product Description",
                    "UnitPrice": "10.00",
                    "Quantity": "5",
                    "Unit": "KG",
                    "Type": "P",
                    "TaxValue": "23",
                    "ProductDiscount": "0"
                }
            ],
            "LoadDateTime": "2022-06-21T08:22:54",
            "LoadAddress": {
                "AddressDetail": "Av. Sidonio Pais, N 2, 2 Esq. A",
                "City": "Lisboa",
                "PostalCode": "1050-215",
                "CountryCode": "PT"
            },
            "DestinationAddress": {
                "AddressDetail": "Rua das madres 100",
                "City": "Porto",
                "PostalCode": "4000-000",
                "CountryCode": "PT"
            },
            "VehicleLicence": "AA 16 AA"
        }
    }
    """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://bo.magnifinance.com/api/v1.1/document/waybill"))
    .header("email", "XXX@example.com")
    .header("token", "XXX")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(payload))
    .build();

HttpResponse<String> response = client.send(request,
    HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

Example Response

Success

{
  "RequestId": "98c3bc62-911d-4f14-a5f4-d610c66e8b8b",
  "Object": {
    "DocumentId": 67195,
    "ErrorMessage": null
  },
  "Type": 0,
  "ErrorValue": null,
  "ErrorHumanReadable": null,
  "ValidationErrors": null,
  "IsSuccess": true,
  "IsError": false
}

Error

{
  "RequestId": "2661fa10-c92d-4015-bef0-30f5e94e3c88",
  "Object": null,
  "Type": 1,
  "ErrorValue": {
    "Value": 2,
    "Name": "ValidationError"
  },
  "ErrorHumanReadable": "ValidationError",
  "ValidationErrors": [
    {
      "Type": "InvalidTaxId",
      "ElementNumber": 0,
      "Field": "CompanyTaxId",
      "Detail": "Invalid Tax Id"
    }
  ],
  "IsSuccess": false,
  "IsError": true
}

info

The ATCode is the code returned by the Portuguese Tax Authority (AT) that must accompany the transported goods. If Tax Communication is enabled and configured, the document will automatically be reported to AT.

Document Types

• W - Waybill (Guia de Transporte)
• Y - Delivery Note (Guia de Remessa)