Documentos Retificativos

As rotas aqui descritas permitem gerir todos os processos relativos a documentos rectificativos — notas de crédito e notas de debito—, incluindo a sua descarga em PDF.

Criar Documento Retificativo

Criar Documento de Venda

Criar Documento de Venda

POST{{base_url}}/api/v1/commercial_sales_documents

Body

application/json

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

linesarray of object

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

Response

200

Request

JavaScriptCurlPython

const response = await fetch('{{base_url}}/api/v1/commercial_sales_documents', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "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
    }),
});
const data = await response.json();

Cabeçalho Documentos de Venda

Atributo	Descrição	Obrigatório
document_type	Tipo de documento. "NC": Nota de Crédito, "ND": Nota de Débito.	Sim
parent_documents_ids	Identificador interno do documento ao qual o documento retificativo está associado.	Não (mas é recomendado)
parent_document_reference	Identificador externo do documento ao qual o documento retificativo está associado.	Não (mas é recomendado)
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 Documentos Retificativos por Id

Obter Todos os Documentos de Venda por Id

Obter Todos os Documentos de Venda por Id

GET{{base_url}}/api/v1/commercial_sales_documents/{salesDocumentId}

Path parameters

salesDocumentId*string

Response

200

Request

JavaScriptCurlPython

const response = await fetch('{{base_url}}/api/v1/commercial_sales_documents/{salesDocumentId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Obter Todos os Documentos Retificativos

Obter Todos os Documentos de Venda

Obter Todos os Documentos de Venda

GET{{base_url}}/api/v1/commercial_sales_documents/

Response

200

Request

JavaScriptCurlPython

const response = await fetch('{{base_url}}/api/v1/commercial_sales_documents/', {
    method: 'GET',
    headers: {},
});
const data = await response.json();