Guia de Compras

Endpoint: POST /gateway/invoice/purchases

Identificadores ilustrativos

Valores como "documentTypeId": 1 ou "entityKeyId": "F001" são ilustrações. Resolva os identificadores correctos em cada tenant (GET /gateway/document-type, catálogo de entidades, armazéns, impostos, tipos de pagamento). Ver Resolver IDs de tipo de documento.

Crie documentos de compra a fornecedor com POST /gateway/invoice/purchases. Após criar, consulte o documento com GET /gateway/invoice/invoices/{id}. Os preços de linha usam taxIncludedUnitPrice (com imposto) e netUnitPrice (sem imposto). Identifique o fornecedor com entityKeyId e/ou entityVat. O endpoint aceita apenas naturezas de compra, resolve preços a partir do catálogo do fornecedor quando necessário e actualiza dados de custo artigo/fornecedor após a emissão.

Para liquidar documentos de compra em aberto, use pagamentos a fornecedor (PF) no Guia de Recibos e Pagamentos a Fornecedores.

Visão geral

Tópico	Comportamento
Endpoint	`POST /gateway/invoice/purchases`
Corpo	Ver Cria um documento de compra. Preços de linha: `taxIncludedUnitPrice` / `netUnitPrice`.
Entidade	Fornecedor — `entityKeyId` e/ou `entityVat`; fallback de consumidor final não permitido
Tipo de documento	Tem de ser um tipo de documento de compra
Após criar	`201` + `Location` → `GET /gateway/invoice/invoices/{id}`

Naturezas suportadas (Onda A)

Apenas estas naturezas são aceites pelo endpoint actual:

Natureza	Uso típico
FTF	Factura de fornecedor
FSF	Factura simplificada de compra
FRF	Factura-recibo de compra
NEF	Encomenda a fornecedor
ORF	Orçamento / pedido de compra
FFF	Factura de compra (caminho fiscal alternativo, quando configurado)
DIF	Documento interno de compra
GRF	Guia de recepção de mercadorias
GTF	Guia de transporte (compra)
GAF	Guia de consignação / remessa (compra)
GCF	Guia de consignação global (compra)

Indisponíveis neste endpoint

São rejeitadas hoje (incluindo qualquer outra natureza fora da tabela):

NCF, NDF, GDF, NGT, FCF
VDF e qualquer outra natureza fora da tabela acima

FCF e VDF têm lógica de actualização de custos preparada no motor, mas não são emitíveis por POST /gateway/invoice/purchases nesta versão.

Uma natureza rejeitada devolve Purchase.DocumentNature.NotSupported.

Criar uma compra (FTF)

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

{
  "serieId": 1,
  "documentTypeId": 1,
  "entityKeyId": "F001",
  "entityDescription": "Fornecedor Exemplo, Lda",
  "entityVat": "502123456",
  "entityAddress": "Rua do Fornecedor, 10",
  "entityPostalCode": "1000-000",
  "entityCity": "Lisboa",
  "entityCountry": "PT",
  "paymentModeId": 1,
  "docReference": "ENC-2026-001",
  "obs": "Factura de compra FTF",
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 1230
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "ART001",
      "itemDescription": "Artigo comprado",
      "quantity": 10,
      "netUnitPrice": 8.5,
      "taxId": 1,
      "originWarehouse": 1,
      "supplierItemId": "FORN-ART001"
    }
  ]
}

Referência da API: Cria um documento de compra para um fornecedor.

Regras do fornecedor

Indique entityKeyId e/ou entityVat. Omitir ambos devolve Purchase.Supplier.Required.
Com entityKeyId, a API resolve o fornecedor pela chave. Se apenas indicar entityVat, resolve-o pelo NIF.
A entidade tem de ser um fornecedor. Entidades inválidas / que não sejam fornecedor devolvem Purchase.Supplier.Invalid.
Não há fallback de consumidor final.
O tipo de documento tem de ser de compra; caso contrário Purchase.DocumentType.Required (ou erros relacionados de tipo de documento).

Pagamentos

Os documentos de compra usam a mesma estrutura payments[] das vendas. Mecanismos permitidos nas compras:

Código	Descrição	`paymentBankDetail`
`NU`	Numerário	Não permitido
`OU`	Outros	Não permitido
`CC`	Cartão de crédito	Não permitido
`CD`	Cartão de débito	Não permitido
`CS`	Crédito / conta de fornecedor	Não permitido
`TB`	Transferência bancária	Obrigatório (`accountNumber`)
`CH`	Cheque	Obrigatório (`checkSequenceNumber`)

Transferência e cheque exigem payments[].paymentBankDetail — ver Detalhe bancário do pagamento.

Pagamentos opcionais (documentos de trabalho / guias)

Quando o tipo de documento tem ambos CashierFlow e CheckingAccountFlow inactivos (zero), payments pode ser omitido — típico em documentos de trabalho e em muitas guias (por exemplo NEF, ORF, GRF, GTF, GAF, GCF, conforme a configuração). A caixa não é obrigatória nesse caso.

Prioridade de preço de linha

Para linhas de compra, a resolução do custo unitário segue esta ordem:

Preço explícito no corpo (netUnitPrice / taxIncludedUnitPrice, conforme aplicável)
Preço do catálogo do fornecedor para o par fornecedor + artigo
Custo do artigo na ficha do item

Se o artigo estiver configurado com custo fixo, o preço do catálogo do fornecedor é ignorado na resolução de custo (prevalece o custo fixo do artigo).

`supplierItemId` (opcional)

Cada linha pode incluir supplierItemId — a referência do artigo no catálogo do fornecedor.

Quando omitido, a API resolve a referência a partir do catálogo do fornecedor para o artigo.
Quando enviado, identifica / actualiza a linha correspondente do catálogo do fornecedor.

Após a emissão: sincronização do catálogo do fornecedor

Após uma criação com sucesso, nas compras suportadas a API actualiza o catálogo do fornecedor:

Cria ou actualiza linhas de catálogo elegíveis
Exclui linhas especiais (informativas / especiais sem stock, conforme configuração)
Deduplica por fornecedor + artigo (+ referência do fornecedor, quando aplicável)

Se a sincronização falhar depois de o documento ser criado, a API pode devolver Purchase.ItemSync.Failed.

Histórico de custos e preço líquido de compra global

Histórico de custos

Para linhas elegíveis com quantidade não nula e custo diferente do valor anterior, a API regista histórico de custos, incluindo artigos com custo fixo.

Preço líquido de compra global

Entre as naturezas actualmente aceites por este endpoint, apenas FTF, FRF e FSF podem actualizar o preço líquido de compra global do artigo. As actualizações respeitam:

Descontos de linha / cabeçalho
Custo fixo do artigo
Quantidade e total líquido
Compras posteriores que não devem ser sobrescritas incorrectamente

De novo: FCF e VDF ficam preparados para actualização de custos numa versão posterior, mas não são emitíveis aqui ainda.

Erros comuns

Código	Significado
`Purchase.DocumentType.Required`	O tipo de documento não é de compra / tipo de compra obrigatório
`Purchase.DocumentNature.NotSupported`	Natureza fora do conjunto suportado (Onda A)
`Purchase.Supplier.Required`	Faltam `entityKeyId` e `entityVat`
`Purchase.Supplier.Invalid`	A entidade não é um fornecedor válido (ex.: consumidor final)
`Purchase.ItemSync.Failed`	Falhou a sincronização do catálogo do fornecedor / custos após a criação

Lista completa: Referência de erros da Invoice API.

Recursos relacionados

API — Cria um documento de compra para um fornecedor
Guia de Faturas de Venda
Guia de utilização — campos partilhados e detalhe bancário
Recibos e Pagamentos a Fornecedores — liquidar compras com PF
Referência de erros

Última actualização: 8 de setembro de 2026

Visão geral​

Naturezas suportadas (Onda A)​

Indisponíveis neste endpoint​

Criar uma compra (FTF)​

Regras do fornecedor​

Pagamentos​

Pagamentos opcionais (documentos de trabalho / guias)​

Prioridade de preço de linha​

supplierItemId (opcional)​

Após a emissão: sincronização do catálogo do fornecedor​

Histórico de custos e preço líquido de compra global​

Histórico de custos​

Preço líquido de compra global​

Erros comuns​

Recursos relacionados​