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

Criar Documento de Venda

post

/api/v1/commercial_sales_documents

Authorizations

Body

apply_retention_when_paidboolean

Example: true

currency_conversion_ratenumber

Example: 1.21

currency_iso_codestring

Example: EUR

customer_address_detailstring

Example: Praceta da Liberdade n5

customer_business_namestring

Example: Ricardo Ribeiro

customer_citystring

Example: Lisboa

customer_countrystring

Example: PT

customer_postcodestring

Example: 1000-101

customer_tax_registration_numberstring

Example: 229659179

datestring

Example: 2023-01-01

document_typestring

Example: FT

due_datestring

Example: 2023-02-01

external_referencestring

Example: Referência do documento externo

finalizenumber

Example: 0

linesobject[]

Example: [{}]

notesstring

Example: Notas ao documento

operation_countrystring

Example: PT-MA

payment_mechanismstring

Example: MO

retentionnumber

Example: 7.5

retention_typestring

Example: IRS

settlement_expressionstring

Example: 7.5

vat_included_pricesboolean

Example: false

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '{{base_url}}/api/v1/commercial_sales_documents' \
  --header 'Content-Type: application/json' \
  --data '{
    "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
  }'

200

200

No body

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

Obter Todos os Documentos de Venda por Id

get

/api/v1/commercial_sales_documents/{salesDocumentId}

Authorizations

Path parameters

salesDocumentIdstringrequired

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '{{base_url}}/api/v1/commercial_sales_documents/{salesDocumentId}'

200

200

No body

Obter Todos os Documentos de Venda

Obter Todos os Documentos de Venda

Obter Todos os Documentos de Venda

get

/api/v1/commercial_sales_documents/

Authorizations

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '{{base_url}}/api/v1/commercial_sales_documents/'

200

200

No body