Skip to main content

Create a Waybill

Creates a waybill (guia de transporte) or a delivery note (guia de remessa). On success the response returns the DocumentId and, for closed documents, the DocumentNumber.

If the company has valid Tax Authority (AT) credentials, the Tax Communication feature enabled, and automatic sending of transport documents to the AT turned on, a closed waybill is communicated to the AT and the response includes the ATDocCode the AT assigned.

POST https://bo.magnifinance.com/MagniAPI/Invoicing.asmx

Sample Body​

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:inv="http://MagniAPI/Invoicing/">
<soapenv:Header/>
<soapenv:Body>
<inv:WaybillCreate>
<inv:Authentication>
<inv:Email>api@yourcompany.pt</inv:Email>
<inv:Token>your-subscription-token</inv:Token>
</inv:Authentication>
<inv:Client>
<inv:NIF>166737755</inv:NIF>
<inv:Name>MagniFinance</inv:Name>
<inv:Address>Av. Sidónio Pais, n.º 2, 2.º Esq. A</inv:Address>
<inv:City>Lisboa</inv:City>
<inv:PostCode>1050-215</inv:PostCode>
<inv:CountryCode>PT</inv:CountryCode>
</inv:Client>
<inv:Waybill>
<inv:Date>2026-10-08</inv:Date>
<inv:Description>Delivery of order 10045</inv:Description>
<inv:Type>W</inv:Type>
<inv:Lines>
<inv:APIInvoicingProduct>
<inv:Code>BOX-12</inv:Code>
<inv:Description>Box of 12 bottles</inv:Description>
<inv:UnitPrice>18.50</inv:UnitPrice>
<inv:Quantity>4</inv:Quantity>
<inv:Unit>Box</inv:Unit>
<inv:Type>P</inv:Type>
<inv:TaxValue>23</inv:TaxValue>
<inv:ProductDiscount>0</inv:ProductDiscount>
</inv:APIInvoicingProduct>
</inv:Lines>
<inv:LoadDateTime>2026-10-08T09:30:00</inv:LoadDateTime>
<inv:LoadAddress>
<inv:AddressDetail>Rua do Armazém, 10</inv:AddressDetail>
<inv:City>Lisboa</inv:City>
<inv:PostalCode>1000-001</inv:PostalCode>
<inv:CountryCode>PT</inv:CountryCode>
</inv:LoadAddress>
<inv:DestinationAddress>
<inv:AddressDetail>Av. Sidónio Pais, n.º 2, 2.º Esq. A</inv:AddressDetail>
<inv:City>Lisboa</inv:City>
<inv:PostalCode>1050-215</inv:PostalCode>
<inv:CountryCode>PT</inv:CountryCode>
</inv:DestinationAddress>
<inv:VehicleLicence>AA-16-AA</inv:VehicleLicence>
</inv:Waybill>
<inv:IsToClose>true</inv:IsToClose>
</inv:WaybillCreate>
</soapenv:Body>
</soapenv:Envelope>
tip

Leave out the optional fields you don't use. Don't send them empty: an empty number or date makes the whole request fail (see Sending values).

Request​

ParameterRequiredValue
Content-Typerequiredtext/xml; charset=utf-8
SOAPActionoptional"http://MagniAPI/Invoicing/WaybillCreate"

Body​

Authentication​

ParameterRequiredDescription
Emailrequiredstring(50) The email of an API user of your company with permission to create documents. Example: api@yourcompany.pt
Tokenrequiredstring(50) The token of the company (subscription) in which the waybill is created.

Client​

The customer (recipient of the goods). Same fields as Client in DocumentCreate: NIF, Name and CountryCode are required; Address, City, PostCode, PhoneNumber, CountryName, LegalName, Email and IBAN are optional.

Waybill​

ParameterRequiredDescription
Daterequireddate The document date, YYYY-MM-DD. It can't be earlier than the date of the last closed document in the same series. Example: "2026-10-08"
DueDateoptionaldate Not needed for waybills; you can leave it out.
Descriptionoptionalstring(300) A description printed on the document. Example: "Delivery of order 10045"
Typerequiredstring(1) W for a waybill (guia de transporte), Y for a delivery note (guia de remessa). Example: "W"
Serieoptionalstring(30) The series (numbering sequence) to use. Series names are unique per document type. If you leave it out, the company's default series for that type is used. You can see the series in MagniFinance under Settings → General → Document series. Example: "W2"
ExternalIdoptionalstring(50) Your own id for this waybill, such as your order number. It prevents duplicates: a second waybill of the same type with the same ExternalId, sent by the same API user, is refused while the first one isn't cancelled. See What is ExternalId for?. Example: "order-10045"
TaxExemptionReasonCodeoptionalstring(3) Required when at least one line has 0% VAT. Use a code from the Code column of the exemption reasons list. Example: "M01"
LinesrequiredList of APIInvoicingProduct The goods being transported. Same fields as Lines in DocumentCreate.
LoadDateTimerequireddateTime When the transport starts, YYYY-MM-DDThh:mm:ss. It can't be earlier than Date. Example: "2026-10-08T09:30:00"
LoadAddressrequiredAddress Where the goods are loaded (below).
DestinationAddressrequiredAddress Where the goods are delivered (below).
VehicleLicenceoptionalstring(30) The licence plate of the vehicle. Example: "AA-16-AA"

The other Document fields of DocumentCreate (Currency, EuroRate, Retention, DocumentReference, PurchaseOrder, Id) are accepted too, but are rarely needed on a waybill.

LoadAddress and DestinationAddress (Address)​

ParameterRequiredDescription
AddressDetailrequiredstring(100) Street and number. Example: "Rua do Armazém, 10"
Cityrequiredstring(50) The city. Example: "Lisboa"
PostalCoderequiredstring(20) The postal code. Example: "1000-001"
CountryCoderequiredstring(2) The country of this address, as an ISO 3166-1 alpha-2 code. Example: "PT"

Other Parameters​

ParameterRequiredDescription
IsToCloserequiredboolean true closes the waybill: it gets its number and PDF (and is sent to the AT, if enabled) and can no longer be changed. false saves it as a draft. Example: true

Response​

The result is in <ResponseWaybillCreate> (not <Response>); see Response Format for the fields every response has. Object holds:

ParameterDescription
DocumentIdint The id of the created waybill. Keep it to get the document later with DocumentGet. Example: 72569
DocumentNumberstring The waybill number, once it is closed. Example: "GT W2/239"
ATDocCodestring The code the Tax Authority assigned to this transport document. Only filled in when the waybill was communicated to the AT.
ErrorMessagestring Extra detail on some errors. Empty on success.

Request Sample​

Save the Sample Body as request.xml, then:

cURL​

curl https://bo.magnifinance.com/MagniAPI/Invoicing.asmx \
--header 'Content-Type: text/xml; charset=utf-8' \
--header 'SOAPAction: "http://MagniAPI/Invoicing/WaybillCreate"' \
--data-binary @request.xml

JavaScript (Node.js 18+)​

const fs = require('fs');

const body = fs.readFileSync('request.xml', 'utf8');

fetch('https://bo.magnifinance.com/MagniAPI/Invoicing.asmx', {
method: 'POST',
headers: {
'Content-Type': 'text/xml; charset=utf-8',
SOAPAction: '"http://MagniAPI/Invoicing/WaybillCreate"',
},
body,
})
.then((response) => response.text())
.then((xml) => console.log(xml))
.catch((error) => console.error(error));

Node.js (axios)​

const fs = require('fs');
const axios = require('axios');

const body = fs.readFileSync('request.xml', 'utf8');

axios
.post('https://bo.magnifinance.com/MagniAPI/Invoicing.asmx', body, {
headers: {
'Content-Type': 'text/xml; charset=utf-8',
SOAPAction: '"http://MagniAPI/Invoicing/WaybillCreate"',
},
})
.then((response) => console.log(response.data))
.catch((error) => console.error(error));

Example Response​

Success​

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<WaybillCreateResponse xmlns="http://MagniAPI/Invoicing/">
<ResponseWaybillCreate>
<RequestId>5ed21421-4b62-4043-95fa-28a73b605163</RequestId>
<Type>Success</Type>
<Object>
<DocumentId>72569</DocumentId>
<DocumentNumber>GT W2/239</DocumentNumber>
<ATDocCode><!-- code assigned by the AT --></ATDocCode>
</Object>
</ResponseWaybillCreate>
</WaybillCreateResponse>
</soap:Body>
</soap:Envelope>

Error​

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<WaybillCreateResponse xmlns="http://MagniAPI/Invoicing/">
<ResponseWaybillCreate>
<RequestId>e4d9bc16-2631-41b2-aad2-a6e56ee45ff2</RequestId>
<Type>Error</Type>
<ErrorValue>
<Value>2</Value>
<Name>ValidationError</Name>
</ErrorValue>
<ErrorHumanReadable>ValidationError</ErrorHumanReadable>
<ValidationErrors>
<ValidationError>
<Type>EmptyField</Type>
<ElementNumber>0</ElementNumber>
<Field>DocumentDetailDeliveryCountry</Field>
<Detail>Mandatory field</Detail>
</ValidationError>
</ValidationErrors>
</ResponseWaybillCreate>
</WaybillCreateResponse>
</soap:Body>
</soap:Envelope>