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>
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
Header
| Parameter | Required | Value |
|---|---|---|
| Content-Type | required | text/xml; charset=utf-8 |
| SOAPAction | optional | "http://MagniAPI/Invoicing/WaybillCreate" |
Body
Authentication
| Parameter | Required | Description |
|---|---|---|
| required | string(50) The email of an API user of your company with permission to create documents. Example: api@yourcompany.pt | |
| Token | required | string(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
| Parameter | Required | Description |
|---|---|---|
| Date | required | date 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" |
| DueDate | optional | date Not needed for waybills; you can leave it out. |
| Description | optional | string(300) A description printed on the document. Example: "Delivery of order 10045" |
| Type | required | string(1) W for a waybill (guia de transporte), Y for a delivery note (guia de remessa). Example: "W" |
| Serie | optional | string(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" |
| ExternalId | optional | string(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" |
| TaxExemptionReasonCode | optional | string(3) Required when at least one line has 0% VAT. Use a code from the Code column of the exemption reasons list. Example: "M01" |
| Lines | required | List of APIInvoicingProduct The goods being transported. Same fields as Lines in DocumentCreate. |
| LoadDateTime | required | dateTime When the transport starts, YYYY-MM-DDThh:mm:ss. It can't be earlier than Date. Example: "2026-10-08T09:30:00" |
| LoadAddress | required | Address Where the goods are loaded (below). |
| DestinationAddress | required | Address Where the goods are delivered (below). |
| VehicleLicence | optional | string(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)
| Parameter | Required | Description |
|---|---|---|
| AddressDetail | required | string(100) Street and number. Example: "Rua do Armazém, 10" |
| City | required | string(50) The city. Example: "Lisboa" |
| PostalCode | required | string(20) The postal code. Example: "1000-001" |
| CountryCode | required | string(2) The country of this address, as an ISO 3166-1 alpha-2 code. Example: "PT" |
Other Parameters
| Parameter | Required | Description |
|---|---|---|
| IsToClose | required | boolean 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:
| Parameter | Description |
|---|---|
| DocumentId | int The id of the created waybill. Keep it to get the document later with DocumentGet. Example: 72569 |
| DocumentNumber | string The waybill number, once it is closed. Example: "GT W2/239" |
| ATDocCode | string The code the Tax Authority assigned to this transport document. Only filled in when the waybill was communicated to the AT. |
| ErrorMessage | string 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>