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

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. "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

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 Retificativos

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