Transport Guides

Document natures (business): GT, GR, GA, GC, GD

Illustrative IDs

The values in the JSON examples are illustrations. Resolve the correct id with GET /gateway/document-type and match description / keyId / invoiceType to the transport nature you need. See Resolving document type IDs.

Overview

Transport guides are fiscal shipping documents created via the same endpoint as sales invoices:

POST /gateway/invoice/invoices

Supported natures:

Code	Nature	Typical use
GT	Transport guide	Goods in transit to customer
GR	Delivery note guide	Goods dispatched to customer
GA	Own fixed-assets guide	Internal movement of fixed assets
GC	Consignment guide	Consignment stock movement
GD	Return guide	Return transport

Key rules

✅ Include currencyId and at least one line in documentBodies.
✅ Stock movement follows document type configuration.
✅ Use transport header fields when applicable (see below).

Payments

Most transport document types are configured with CashierFlow = 0 (NoAction) and CheckingAccountFlow = 0 (None). For these types the payments field is optional:

payments omitted (or empty): the engine assigns a Not-Applicable payment type (Id 0, mechanism NA). No cashier or checking-account entry is created.
payments with type only: amount is optional; when omitted, the document total is applied automatically.
payments with type and amount: amount must equal the document total exactly.

At most one payment entry is allowed on these document types.

// No payment — engine assigns N/A payment type
{
  "serieId": 10,
  "documentTypeId": 42,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "documentBodies": [...]
}

// With explicit payment (amount optional — defaults to document total)
{
  "serieId": 10,
  "documentTypeId": 42,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "payments": [
    {
      "paymentTypeId": 3,
      "amount": 150.00
    }
  ],
  "documentBodies": [...]
}

Payment mechanisms

Accepted mechanisms for the supplied paymentTypeId: NU (Cash), OU (Other), CC (Credit card), CD (Debit card). Payment types with SendToCheckingAccount = true are blocked by this API. See Error Reference for the relevant codes.

Global Transport Documents

A transport document type with globalDocument = true represents a global guide — a single guide covering multiple individual deliveries.

Specific rules for global GT documents:

VAT (entityVat) may be empty — the AT does not require a NIF for global guides.
Final consumer is not automatically assigned — when NIF is empty, the engine does not replace it with the default final consumer identifier.
Unload address is not required — for a PT global guide with only a load address, validation passes.

{
  "serieId": 10,
  "documentTypeId": 43,
  "entityKeyId": "GLOBAL001",
  "entityDescription": "Multiple Deliveries",
  "currencyId": 1,
  "loadPlaceDescription": "Central Warehouse;Lisbon;1000-001;PT",
  "obs": "Global transport guide — multiple destinations",
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 100.0,
      "retailPrice": 10.00,
      "taxId": 1
    }
  ]
}

note

The documentTypeId must correspond to a document type configured with globalDocument = true in your tenant.

Portugal validation

For Portugal, shipment documents must satisfy:

loadPlaceDescription is required (non-empty).
unloadPlaceDescription or a resolvable customer address is required — unless the document type is configured as global (globalDocument), in which case unload place alone is optional.

Failure returns validation code SaleDocumentRules.Transport.MissingPlaces.

Create transport guide (GT example)

POST /gateway/invoice/invoices
Content-Type: application/json
Authorization: Bearer {token}
X-Timezone: Europe/Lisbon

{
  "serieId": 2,
  "documentTypeId": 12,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "entityDescription": "Example Client, Ltd",
  "entityAddress": "456 Customer Avenue",
  "entityPostalCode": "4000-000",
  "entityCity": "Porto",
  "entityCountry": "Portugal",
  "loadPlaceDescription": "Central Warehouse;Lisbon;1000-100;PT",
  "unloadPlaceDescription": "Customer Store;Porto;4000-000;PT",
  "loadPlaceDate": "2025-06-05T09:00:00",
  "unloadPlaceDate": "2025-06-05T14:00:00",
  "carrierDescription": "Fast Logistics Lda",
  "obs": "Shipment 2025-06-05 — Lisbon › Porto",
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "itemDescription": "Product 1",
      "quantity": 10,
      "retailPrice": 25,
      "taxId": 1,
      "secondTaxId": 0
    }
  ]
}

Minimal payload (dates and places optional)

{
  "serieId": 2,
  "documentTypeId": 12,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "loadPlaceDescription": "Central Warehouse;Lisbon;1000-100;PT",
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 5,
      "retailPrice": 10,
      "taxId": 1,
      "secondTaxId": 0
    }
  ]
}

Default load/unload dates are applied and the unload place may be resolved from the customer address.

Other transport natures

Use the same payload shape; only documentTypeId (and business obs / references) change.

GR — Delivery note guide

Often issued at dispatch, referencing the originating invoice or order:

{
  "serieId": 2,
  "documentTypeId": 13,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "loadPlaceDescription": "Central Warehouse;Lisbon;1000-100;PT",
  "unloadPlaceDescription": "Customer premises;Porto;4000-000;PT",
  "carrierDescription": "Own fleet",
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 2,
      "retailPrice": 50,
      "taxId": 1,
      "secondTaxId": 0
    }
  ]
}

GA, GC, GD

GA — movement of own fixed assets between locations.
GC — consignment / deposit stock to third party.
GD — return transport (e.g. customer return in transit).

Configure the correct documentTypeId per nature and provide load/unload data as for GT.

Characteristics

Characteristic	Value
Stock	✅ Per document type and item configuration
Fiscal document	✅ Yes
Transport fields	✅ Required (PT: load place)
Customer	✅ Required

Best practices

✅ Recommended

Always set loadPlaceDescription for Portugal.
Send X-Timezone so load/unload dates match local business time.
Resolve documentTypeId per nature (GT vs GR vs GA vs GC vs GD) with GET /gateway/document-type.

❌ Avoid

Relying on transport fields on FS, NC, or ND documents.
Leaving load place empty in Portugal.

Query transport documents

GET /gateway/invoice/invoices?documentTypeId=12&startDate=2025-01-01&endDate=2025-12-31
Authorization: Bearer {token}

Replace documentTypeId with your GT (or GR, GA, GC, GD) type id.

Common errors

Code	When
`SaleDocumentRules.Transport.MissingPlaces`	Load place missing (PT), or unload place missing and no resolvable customer address
`Payment.MultipleEntriesNotAllowed`	More than one entry in `payments`
`Payment.MechanismNotAllowed`	`paymentTypeId` uses a mechanism other than NU/OU/CC/CD
`Payment.CheckingAccount.NotSupported`	`paymentTypeId` has `SendToCheckingAccount = true`
`DocumentType.NotSupported`	Invoice nature not in the supported whitelist

See Invoice API Error Reference for the complete list.

Next steps

Invoice API Error Reference — complete error code catalogue
Usage Guide — general Invoice API information
Sales Invoices Guide — definitive fiscal documents

Last Updated: June 12, 2026

Overview​

Key rules​

Payments​

Global Transport Documents​

Portugal validation​

Create transport guide (GT example)​

Minimal payload (dates and places optional)​

Other transport natures​

GR — Delivery note guide​

GA, GC, GD​

Characteristics​

Best practices​

✅ Recommended​

❌ Avoid​

Query transport documents​

Common errors​

Next steps​