Documentos de Venda

As rotas aqui descritas permitem gerir todos os processos relativos a documentos de venda — orçamentos, faturas-proforma, guias, faturas e notas —, incluindo a sua descarga em PDF.

Criar Documento de Venda

Criar Documento de Venda

post

Criar Documento de Venda

Required scopes

This endpoint requires the following scopes:

• : commercial

Authorizations

oauth2

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Body

application/json

apply_retention_when_paidbooleanOptionalExample: true

currency_conversion_ratenumberOptionalExample: 1.21

currency_iso_codestringOptionalExample: EUR

customer_address_detailstringOptionalExample: Praceta da Liberdade n5

customer_business_namestringOptionalExample: Ricardo Ribeiro

customer_citystringOptionalExample: Lisboa

customer_countrystringOptionalExample: PT

customer_postcodestringOptionalExample: 1000-101

customer_tax_registration_numberstringOptionalExample: 229659179

datestringOptionalExample: 2023-01-01

document_typestringOptionalExample: FT

due_datestringOptionalExample: 2023-02-01

external_referencestringOptionalExample: Referência do documento externo

finalizenumberOptionalExample: 0

linesobject[]OptionalExample: [{}]

notesstringOptionalExample: Notas ao documento

operation_countrystringOptionalExample: PT-MA

payment_mechanismstringOptionalExample: MO

retentionnumberOptionalExample: 7.5

retention_typestringOptionalExample: IRS

settlement_expressionstringOptionalExample: 7.5

vat_included_pricesbooleanOptionalExample: false

Responses

200Success

No content

post

/api/v1/commercial_sales_documents

HTTPcURLJavaScriptPython

POST /api/v1/commercial_sales_documents HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 640

{
  "apply_retention_when_paid": true,
  "currency_conversion_rate": 1.21,
  "currency_iso_code": "EUR",
  "customer_address_detail": "Praceta da Liberdade n5",
  "customer_business_name": "Ricardo Ribeiro",
  "customer_city": "Lisboa",
  "customer_country": "PT",
  "customer_postcode": "1000-101",
  "customer_tax_registration_number": "229659179",
  "date": "2023-01-01",
  "document_type": "FT",
  "due_date": "2023-02-01",
  "external_reference": "Referência do documento externo",
  "finalize": 0,
  "lines": [
    {}
  ],
  "notes": "Notas ao documento",
  "operation_country": "PT-MA",
  "payment_mechanism": "MO",
  "retention": 7.5,
  "retention_type": "IRS",
  "settlement_expression": "7.5",
  "vat_included_prices": false
}

200Success

No content

Cabeçalho Documentos de Venda

Atributo	Descrição	Obrigatório
document_type	Tipo de documento. "FT": fatura, "FS": fatura simplificada, "FR": fatura-recibo.	Sim
date	Data do documento. Por omissão, a data do pedido.	Não
document_series_id	Identificador interno da série.	Não
document_series_prefix	Prefixo da série.	Não
customer_id	Identificador interno do cliente.	Não
customer_tax_registration_number	NIF do cliente.	Não
customer_business_name	Nome do cliente.	Sim
customer_address_detail	Morada do cliente.	Não
customer_postcode	Código postal do cliente, no formato 0000-000.	Não
customer_city	Cidade/Localidade do cliente.	Não
customer_country	País do cliente. Por omissão, "PT".	Não
due_date	Data de vencimento. Por omissão, a data do documento, ou a referente ao prazo de pagamento configurado no cliente.	Não
settlement_expression	Desconto no cabeçalho, em percentagem. São suportados descontos compostos, como "3+5".	Não
payment_mechanism	Modo de pagamento.	Não
bank_account_id	Identificador interno da conta bancária da empresa para onde o recebimento é feito.	Não
cash_account_id	Identificador interno da conta de caixa da empresa para onde o recebimento é feito.	Não
vat_included_prices	Os preços nas linhas são com IVA incluído? Por omissão, não (false).	Não
tax_exemption_reason_id	Motivo de isenção de IVA.	Não
operation_country	A região de operação para efeitos de IVA.	Não
currency_id	Identificador interno da moeda.	Não
currency_iso_code	Código ISO da moeda do documento.	Não
currency_conversion_rate	Taxa de conversão para EUR (1 EUR = n USD	Nãão
retention	Percentagem de retenção a aplicar sobre os serviços.	Não
retention_type	Tipo de retenção ("IRS" ou "IRC"). Por omissão, "IRS".	Não
apply_retention_when_paid	A retenção é feita logo no documento (false) ou apenas no recebimento (true). Por omissão, false.	Não
notes	Notas ao documento.	Não
external_reference	Referência do documento externo.	Não
lines	Lista de linhas do documento.	Sim

Linha de Documentos de Venda

Atributo	Descrição	Obrigatório
item_type	Tipo de item: "Service": serviços, "Product": produtos, "TaxDescriptor": descritores.	Sim
item_id	Identificador interno do item.	Não
item_code	Código do serviço/produto/descritor.	Não
description	Descrição da linha. Por omissão é usada a descrição associada ao item, se este for indicado.	Sim
unit_of_measure_id	Identificador interno da unidade de medida.	Não
unit_of_measure	Unidade de medida. Por omissão é a configurada no item (se for serviço ou produto).	Não
quantity	Quantidade da linha.	Sim
unit_price	Preço unitário da linha.	Sim
settlement_expression	Desconto de linha, em percentagem.	Não
tax_id	Identificador interno da taxa de IVA.	Não
tax_code	Tipo de IVA associado ao item.	Não
tax_percentage	Percentagem de IVA a usar.	Não
tax_country_region	Região do IVA.	Não

Nota 1 - A série associada ao documento tem já que existir, e o seu "id" interno pode ser obtido por um:

GET /commercial_document_series?filter[document_type]=<o tipo de documento>&filter[prefix]=<o prefixo da série a usar>

Nota 2 - Se o cliente for identificado pelo seu "id" interno tem já que existir, e o seu "id" interno pode ser obtido por um:

GET /customers?filter[tax_registration_number]=<o NIF do cliente>

Nota 3 - São também suportados dois "países" adicionais: "PT-AC" (Portugal, Açores) e "PT-MA" (Portugal, Madeira). Os países disponíveis podem ser consultados por um GET /countries, ou um em particular por um:

GET /countries?filter[iso_alpha_2]=<o código do país>

Nota 4 - O "id" interno da conta bancária da empresa deve ser obtido por um:

GET /company_bank_accounts?filter[iban]=<IBAN da conta>

ou

GET /company_bank_accounts?filter[name]=<nome da conta>

Nota 5 - O "id" interno da conta de caixa da empresa deve ser obtido por um

GET /cash_accounts?filter[name]=<nome da conta>

Nota 6 - O "id" interno do motivo de isenção deve ser obtido por um

GET /tax_exemption_reasons?filter[code]=<o código legal do motivo de isenção>

Nota 7 - O "id" interno da moeda deve ser obtido por um

GET /currencies?filter[iso_code]=<o código ISO da moeda>

Nota 8: O item (serviço, produto ou descritor) tem já que existir, e o seu "id" interno pode ser obtido por um

GET /services?filter[item_code]=<o código do serviço>

ou

GET /products?filter[item_code]=<o código do produto>

ou

GET /tax_descriptors?filter[notation]=<o código do descritor de taxa>

Nota 9: A unidade de medida tem já que existir, e o seu "id" interno pode ser obtido por um

GET /units_of_measure?filter[unit_of_measure]=un|<o código da unidade de medida>

Nota 10: O "id" interno da taxa de IVA deve ser obtido por um

GET /taxes?filter[tax_code]=<Código de Taxa> &filter[tax_country_region]=<Código da Região>

ou

GET /taxes?filter[tax_code]=<Código de Taxa> &filter[tax_country_region]=PT|<Código da Região>&filter[tax_percentage]=<a percentagem IVA>

Nota 11: Para as faturas-recibos (FR), o recibo associado é criado automaticamente quando a FR é finalizada.

Ao submenter o documento de venda fica automaticamente finalizado!

Alteração do Documento de Venda

Após a criação de um documento de venda este fica automaticamente finalizado, se pretender criar documentos sem finalizar pode consultar a versão anterior desta API:Documentos de Venda

Quando um documento é criado em um estado finalizado, torna-se impossível executar as seguintes operações em documentos de venda:

• Finalização do Documento de Venda

• Anulação do Documento de Venda

• Atualizar Documento de Venda

• Eliminação do Documento de Venda

---

Obter Documento de Venda por Id

Obter Todos os Documentos de Venda por Id

get

Obter Todos os Documentos de Venda por Id

Required scopes

This endpoint requires the following scopes:

• : commercial

Authorizations

oauth2

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Path parameters

salesDocumentIdstringRequired

Responses

200Success

No content

get

/api/v1/commercial_sales_documents/{salesDocumentId}

HTTPcURLJavaScriptPython

GET /api/v1/commercial_sales_documents/{salesDocumentId} HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

200Success

No content

Obter Todos os Documentos de Venda

Obter Todos os Documentos de Venda

get

Obter Todos os Documentos de Venda

Required scopes

This endpoint requires the following scopes:

• : commercial

Authorizations

oauth2

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Responses

200Success

No content

get

/api/v1/commercial_sales_documents/

HTTPcURLJavaScriptPython

GET /api/v1/commercial_sales_documents/ HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

200Success

No content