Guias de Transporte

Naturezas de documento (negócio): GT, GR, GA, GC, GD

IDs ilustrativos

Os valores nos exemplos JSON são ilustrativos. Resolva o id correcto com GET /gateway/document-type e faça corresponder description / keyId / invoiceType à natureza de transporte pretendida. Ver Resolução de IDs de tipo de documento.

Visão Geral

As guias de transporte são documentos de expedição fiscais criados através do mesmo endpoint que as faturas de venda:

POST /gateway/invoice/invoices

Naturezas suportadas:

Código	Natureza	Utilização típica
GT	Guia de transporte	Mercadoria em trânsito para cliente
GR	Guia de remessa	Mercadoria expedida para cliente
GA	Guia de activos próprios	Movimento interno de activos fixos
GC	Guia de consignação	Movimento de stock em consignação
GD	Guia de devoluções	Transporte de devolução

Regras principais

✅ Incluir currencyId e pelo menos uma linha em documentBodies.
✅ O movimento de stock segue a configuração do tipo de documento.
✅ Utilizar os campos de cabeçalho de transporte quando aplicável (ver abaixo).

Pagamentos

A maioria dos tipos de documento de transporte é configurada com CashierFlow = 0 (NoAction) e CheckingAccountFlow = 0 (None). Para estes tipos, o campo payments é opcional:

payments omitido (ou vazio): o motor atribui um tipo de pagamento Não-Aplicável (Id 0, mecanismo NA). Não é criada nenhuma entrada de caixa ou conta-corrente.
payments apenas com tipo: amount é opcional; quando omitido, o total do documento é aplicado automaticamente.
payments com tipo e valor: amount deve ser exactamente igual ao total do documento.

É permitida no máximo uma entrada de pagamento nestes tipos de documento.

// Sem pagamento — motor atribui tipo de pagamento N/A
{
  "serieId": 10,
  "documentTypeId": 42,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "documentBodies": [...]
}

// Com pagamento explícito (amount opcional — assume total do documento)
{
  "serieId": 10,
  "documentTypeId": 42,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "payments": [
    {
      "paymentTypeId": 3,
      "amount": 150.00
    }
  ],
  "documentBodies": [...]
}

Mecanismos de pagamento

Mecanismos aceites para o paymentTypeId fornecido: NU (Numerário), OU (Outros), CC (Cartão Crédito), CD (Cartão Débito). Tipos de pagamento com SendToCheckingAccount = true são bloqueados por esta API. Ver Referência de Erros para os códigos relevantes.

Documentos de Transporte Globais

Um tipo de documento de transporte com globalDocument = true representa uma guia global — uma única guia que cobre múltiplas entregas individuais.

Regras específicas para documentos GT globais:

NIF (entityVat) pode estar vazio — a AT não exige NIF para guias globais.
Consumidor final não é atribuído automaticamente — quando o NIF está vazio, o motor não substitui pelo identificador de consumidor final por defeito.
Local de descarga não é obrigatório — para uma guia global PT com apenas local de carga, a validação passa.

{
  "serieId": 10,
  "documentTypeId": 43,
  "entityKeyId": "GLOBAL001",
  "entityDescription": "Múltiplas Entregas",
  "currencyId": 1,
  "loadPlaceDescription": "Armazém Central;Lisboa;1000-001;PT",
  "obs": "Guia global de transporte — múltiplos destinos",
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 100.0,
      "retailPrice": 10.00,
      "taxId": 1
    }
  ]
}

nota

O documentTypeId deve corresponder a um tipo de documento configurado com globalDocument = true no seu tenant.

Validação Portugal

Para Portugal, os documentos de expedição devem satisfazer:

loadPlaceDescription é obrigatório (não vazio).
unloadPlaceDescription ou uma morada de cliente resolvível é obrigatória — excepto se o tipo de documento estiver configurado como global (globalDocument), caso em que apenas o local de carga é obrigatório.

Falha devolve o código de validação SaleDocumentRules.Transport.MissingPlaces.

Criar guia de transporte (exemplo GT)

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

{
  "serieId": 2,
  "documentTypeId": 12,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "entityDescription": "Cliente Exemplo, Lda",
  "entityAddress": "Av. Cliente 456",
  "entityPostalCode": "4000-000",
  "entityCity": "Porto",
  "entityCountry": "Portugal",
  "loadPlaceDescription": "Armazém Central;Lisboa;1000-100;PT",
  "unloadPlaceDescription": "Loja Cliente;Porto;4000-000;PT",
  "loadPlaceDate": "2025-06-05T09:00:00",
  "unloadPlaceDate": "2025-06-05T14:00:00",
  "carrierDescription": "Transportes Rápidos Lda",
  "obs": "Expedição ref. 2025-06-05 — Lisboa › Porto",
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "itemDescription": "Produto 1",
      "quantity": 10,
      "retailPrice": 25,
      "taxId": 1,
      "secondTaxId": 0
    }
  ]
}

Payload mínimo (datas e locais opcionais)

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

As datas de carga/descarga por omissão são aplicadas e o local de descarga pode ser resolvido a partir da morada do cliente.

Outras naturezas de transporte

Use a mesma estrutura de payload; apenas documentTypeId (e obs / referências de negócio) mudam.

GR — Guia de remessa

Emitida no momento da expedição, referenciando a fatura ou encomenda de origem:

{
  "serieId": 2,
  "documentTypeId": 13,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "loadPlaceDescription": "Armazém Central;Lisboa;1000-100;PT",
  "unloadPlaceDescription": "Instalações do cliente;Porto;4000-000;PT",
  "carrierDescription": "Frota própria",
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 2,
      "retailPrice": 50,
      "taxId": 1,
      "secondTaxId": 0
    }
  ]
}

GA, GC, GD

GA — movimento de activos fixos próprios entre locais.
GC — stock em consignação / depósito a terceiros.
GD — transporte de devolução (ex.: devolução de cliente em trânsito).

Configure o documentTypeId correcto por natureza e forneça dados de carga/descarga como para GT.

Características

Característica	Valor
Stock	✅ Conforme configuração do tipo de documento e artigo
Documento fiscal	✅ Sim
Campos de transporte	✅ Obrigatórios (PT: local de carga)
Cliente	✅ Obrigatório

Boas práticas

✅ Recomendado

Definir sempre loadPlaceDescription para Portugal.
Enviar X-Timezone para que as datas de carga/descarga correspondam à hora local do negócio.
Resolver documentTypeId por natureza (GT vs GR vs GA vs GC vs GD) com GET /gateway/document-type.

❌ Evitar

Depender de campos de transporte em documentos FS, NC ou ND.
Deixar o local de carga vazio em Portugal.

Consultar documentos de transporte

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

Substitua documentTypeId pelo id do seu tipo GT (ou GR, GA, GC, GD).

Erros comuns

Código	Quando
`SaleDocumentRules.Transport.MissingPlaces`	Local de carga em falta (PT), ou local de descarga em falta e sem morada de cliente resolvível
`Payment.MultipleEntriesNotAllowed`	Mais de uma entrada em `payments`
`Payment.MechanismNotAllowed`	`paymentTypeId` usa mecanismo diferente de NU/OU/CC/CD
`Payment.CheckingAccount.NotSupported`	`paymentTypeId` tem `SendToCheckingAccount = true`
`DocumentType.NotSupported`	Natureza de facturação não está na lista de suporte

Ver Referência de Erros da API de Facturação para a lista completa.

Próximos passos

Referência de Erros da API de Facturação — catálogo completo de códigos de erro
Guia de Utilização — informação geral da API de Facturação
Guia de Faturas — documentos fiscais definitivos

Última actualização: 12 de junho de 2026

Visão Geral​

Regras principais​

Pagamentos​

Documentos de Transporte Globais​

Validação Portugal​

Criar guia de transporte (exemplo GT)​

Payload mínimo (datas e locais opcionais)​

Outras naturezas de transporte​

GR — Guia de remessa​

GA, GC, GD​

Características​

Boas práticas​

✅ Recomendado​

❌ Evitar​

Consultar documentos de transporte​

Erros comuns​

Próximos passos​