As rotas aqui descritas permitem gerir todos os processos relativos a notas de venda, tanto a débito como a crédito.
As notas têm a mesma estrutura que os restantes documentos de venda. Na versão v1 da API têm a mesma estrutura anteriormente descrita para a v0: são compostas por um cabeçalho e uma ou mais linhas. Nesta nova versão, é possível criar ambos num só pedido, descrito de seguida.
Todos os pedidos descritos são formalmente semelhantes aos pedidos correspondentes dos restantes documentos de venda: as rotas utilizados são as mesmas, e os payloads JSON a enviar são estruturalmente semelhantes, partilhando os mesmos atributos.
Criação da nota
post
Body
document_typestringRequiredExample: FT|FS|FR
datestringOptionalExample: 2023-01-01
document_series_idintegerOptionalExample: 1
document_series_prefixstringOptionalExample: Prefixo da série
O payload JSON a enviar contém a seguinte informação:
NOTA 1: A série associada ao documento tem já que existir, e o seu "id" interno pode ser obtido por um
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
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
NOTA 4: O "id" interno da conta bancária da empresa deve ser obtido por um
NOTA 5: O "id" interno da conta de caixa da empresa deve ser obtido por um
NOTA 6: O "id" interno do motivo de isenção deve ser obtido por um
NOTA 7: O "id" interno da moeda deve ser obtido por um
NOTA 8: O item (serviço, produto ou descritor) tem já que existir, e o seu "id" interno pode ser obtido por um
NOTA 9: A unidade de medida tem já que existir, e o seu "id" interno pode ser obtido por um
NOTA 10: O "id" interno da taxa de IVA deve ser obtido por um
{
// Identificação do documento
"document_type": "NC|ND", // [OBRIGATÓRIO] Tipo de documento. "NC": nota de crédito, "ND": nota de débito.
"date": "2023-01-01", // [OPCIONAL] Data do documento; por omissão, a data do pedido.
// [OPCIONAL] Identificação da série do documento. Por omissão, aplicam-se as regras configuradas na empresa para escolha da série.
// Se a série for indicada, usar apenas um dos dois campos seguintes (o "id" ou o prefixo). Se se indicarem os dois, então devem ser consistentes.
"document_series_id": 1, // [OPCIONAL] Identificador interno da série. Ver NOTA 1 abaixo.
"document_series_prefix": "Prefixo da série", // [OPCIONAL] Em alternativa ao campo "document_series_id".
// [OPCIONAL] Identificação do cliente. Por omissão, é o consumidor final (NIF "999999990").
// Se o cliente for indicado, usar apenas um dos dois campos seguintes (o "id" ou o NIF). Se se indicarem os dois, então devem ser consistentes.
"customer_id": 1, // [OPCIONAL] Identificador interno do cliente. Ver NOTA 2.
"customer_tax_registration_number": "999999990", // [OPCIONAL] NIF do cliente. se o cliente com o NIF indicado não existir, será criado automaticamente. Se o país ("customer_country") for Portugal ("PT", "PT-AC" ou "PT-MA"), deve ser um NIF português válido.
// [OPCIONAL] Os atributos seguintes são usados na criação do cliente, se não existir ainda.
// Se o cliente já existir, são guardados no documento, mas a ficha do cliente não é actualizada.
"customer_business_name": "Nome do cliente", // [OBRIGATÓRIO] caso o cliente ainda não exista e tenha que ser criado. [OPCIONAL] nos outros casos, a não ser que exista mais do que um cliente com o NIF indicado, usando-se então o nome para o identificar.
"customer_address_detail": "Morada do cliente", // [OPCIONAL]
"customer_postcode": "0000-000", // [OPCIONAL] Código postal do cliente, no formato 0000-000.
"customer_city": "Cidade/Localidade do cliente", // [OPCIONAL]
"customer_country": "PT", // [OPCIONAL] País do cliente. Por omissão, "PT"; é o código ISO alpha-2 do país do cliente (vd. https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2; ver também a NOTA 3.
// [OPCIONAL] Condições de pagamento
"due_date": "2023-02-01", // [OPCIONAL] Data de vencimento; por omissão, a data do documento, ou a referente ao prazo de pagamento configurado no cliente, se o cliente tiver configurado um prazo de pagamento.
"settlement_expression": "7.5", // [OPCIONAL] Desconto no cabeçalho, em percentagem; são suportados descontos compostos, como "3+5"
// [OPCIONAL] IVA
"vat_included_prices": false, // [OPCIONAL] Os preços nas linhas são com IVA incluído? Por omissão, não (false).
"tax_exemption_reason_id": 1, // Motivo de isenção de IVA. [OBRIGATÓRIO] apenas se o documento tiver pelo menos uma linha isenta de IVA. Não deve ser indicado nos restantes casos. Ver NOTA 6.
"operation_country": "PT-MA", // [OPCIONAL] A região de operação para efeitos de IVA: usada apenas para as linhas de serviços. Por omissão, é a região onde a empresa está localizada. Para o regime OSS pode ainda usar-se o código ISO alpha-2 do país OSS (vd. https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2; ver também a NOTA 3.
// [OPCIONAL] Moeda. Por omissão, "EUR".
// Se a moeda for indicada, usar apenas um dos dois campos seguintes (o "id" ou o código ISO). Se se indicarem os dois, então devem ser consistentes.
"currency_id": 1, // [OPCIONAL] Identificador interno da moeda. Ver NOTA 7.
"currency_iso_code": "USD", // [OPCIONAL] É o código ISO da moeda do documento (vd. https://en.wikipedia.org/wiki/ISO_4217).
"currency_conversion_rate": 1.21, // [OMITIDO] se a moeda for "EUR". [OBRIGATÓRIO] nos restantes casos; é a taxa de conversão para EUR (1 EUR = n USD|...).
// [OBRIGATÓRIO] Identificação do documento sobre o qual a nota está a ser emitida.
// Usar apenas um dos dois campos seguintes:
// - Se se usar o identificador interno do documento ao qual a nota está associada, então esse documento terá que existir no produto, e a nota ficará a ele associada na hierarquia.
// - Se se usar o identificador externo do documento ao qual a nota está associada, então a nota não ficará associada a nenhum documento existente no produto.
"parent_documents_ids": "{1}", // [OPCIONAL] Identificador interno do documento ao qual a nota está associada.
"parent_document_reference": "FAC 2023/1", // [OPCIONAL] Identificador externo do documento ao qual a nota está associada.
// [OPCIONAL] Retenção
"retention": 7.5, // [OPCIONAL] Percentagem de retenção a aplicar sobre os serviços.
"retention_type": "IRS|IRC", // [OPCIONAL] Tipo de retenção ("IRS" ou "IRC"). Por omissão, "IRS".
"apply_retention_when_paid": true, // [OPCIONAL] A retenção é feita logo no documento (false) ou apenas no recebimento (true). Por omissão, false.
// [OPCIONAL] Outras informações
"notes": "Notas ao documento", // [OPCIONAL]
"external_reference": "Referência do documento externo", // [OPCIONAL]
// [OPCIONAL] Instruções de processamento do documento
"finalize": true, // [OPCIONAL] O documento deve ser imediatamente finalizado (true) ou deixado em preparação (false)? Por omissão, o documento é deixado em preparação.
"return_pdf": false, // [OPCIONAL] O documento deve ser imediatamente materializado (true), ou não (false)? Caso se opte pela materialização do documento, será devolvido um link para o respectivo PDF. Por omissão, o documento não é materializado.
// [OBRIGATÓRIO] Linhas do documento
"lines": [
{
// [OPCIONAL] Identificação do item. Se nada for indicado, assume-se uma linha apenas de descrição.
"item_type": "Service|Product|TaxDescriptor", // [OPCIONAL] Tipo de item: "Service": serviço, "Product": produto, "TaxDescriptor": descritor. Por omissão, "Service".
// Se o item for indicado, usar apenas um dos dois campos seguintes (o "id" ou o código). Se se indicarem os dois, então devem ser consistentes entre si, e consistentes com o "item_type".
"item_id": 1, // [OPCIONAL] Identificador interno do item. Ver NOTA 8.
"item_code": "Código do serviço/produto/descritor", // [OPCIONAL] Já tem que existir o produto/serviço/descritor com este código. Por omissão, é usado o item identificado pelo campo "item_id", se indicado. Se nada for indicado, assume-se uma linha apenas de descrição.
"description": "Descrição da linha", // [OPCIONAL] Por omissão é usada a descrição associada ao item, se este for indicado. [OBRIGATÓRIO] Para uma linha apenas de descrição.
// [OPCIONAL] Unidade de medida. Por omissão é a configurada no item (se for serviço ou produto), ou a por omissão na empresa.
// Se a unidade de medida for indicada, usar apenas um dos dois campos seguintes (o "id" ou o código). Se se indicarem os dois, então devem ser consistentes entre si.
"unit_of_measure_id": 1, // [OPCIONAL] Identificador interno da unidade de medida. Ver NOTA 9.
"unit_of_measure": "Unidade de medida", // [OPCIONAL] Por omissão é a configurada no item (se for serviço ou produto), ou a por omissão na empresa.
// Quantidades e valores. [OBRIGATÓRIO] Para linhas de descrição valorizadas.
"quantity": 1, // [OPCIONAL] Por omissão 1, se não for uma linha de descrição valorizada. [OBRIGATÓRIO] Para uma linha de descrição valorizada.
"unit_price": 9.99, // [OPCIONAL] Se for indicado um serviço ou produto. Por omissão é usado o PVP associado ao item (serviço ou produto). [OBRIGATÓRIO] Para uma linha de descritor ou de descrição valorizada.
"settlement_expression": "3", // [OPCIONAL] Desconto de linha, em percentagem; são suportados descontos compostos, como "3+5".
// [OPCIONAL] IVA. Por omissão é aplicado o IVA associado ao item, ou à taxa normal, na região onde a empresa está localizada, ou — apenas para as linhas de serviços — a região de operação para efeitos de IVA, se indicada.
// Se a taxa de IVA for indicada, usar apenas ou o campo "id" ou um ou mais dos três campos seguintes. Se se indicarem todos os campos, então devem ser consistentes entre si.
"tax_id": 1, // [OPCIONAL] Identificador interno da taxa de IVA. Ver NOTA 10.
"tax_code": "NOR|INT|RED|ISE", // [OPCIONAL] Por omissão é usado o tipo de IVA associado ao item, ou "NOR" se nenhum associado. Os tipos de IVA suportados são "NOR" (normal), "INT" (intermédio), "RED" (reduzido), "ISE" (isento).
"tax_percentage": 22, // [OPCIONAL] Percentagem de IVA a usar: serve para indicar uma taxa de outra região (se o campo "tax_country_region" não for indicado) ou uma taxa antiga, já não em vigor.
"tax_country_region": "PT-MA" // [OPCIONAL] Região do IVA. Por omissão (e se o campo "tax_percentage" não for indicado) aplica-se a taxa de IVA da região onde a empresa está localizada, ou — apenas para as linhas de serviços — a região de operação para efeitos de IVA, se indicada. Para o regime OSS pode ainda usar-se o código ISO alpha-2 do país OSS (vd. https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2; ver também a NOTA 3.
},
// Outras linhas, se existirem
...
]
}
GET /commercial_document_series?filter[document_type]=FT|<o tipo de documento>&filter[prefix]=2020|<o prefixo da série a usar>
GET /customers?filter[tax_registration_number]=<o NIF do cliente>
GET /countries?filter[iso_alpha_2]=PT|<o código do país>
GET /company_bank_accounts?filter[iban]=<IBAN da conta>
ou
GET /company_bank_accounts?filter[name]=<nome da conta>
GET /cash_accounts?filter[name]=<nome da conta>
GET /tax_exemption_reasons?filter[code]=M07|<o código legal do motivo de isenção>
GET /currencies?filter[iso_code]=USD|<o código ISO da moeda>
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>
GET /units_of_measure?filter[unit_of_measure]=un|<o código da unidade de medida>
GET /taxes?filter[tax_code]=NOR|<o tipo de IVA>&filter[tax_country_region]=PT|<a região do IVA>
ou
GET /taxes?filter[tax_code]=NOR|<o tipo de IVA>&filter[tax_country_region]=PT|<a região do IVA>&filter[tax_percentage]=22|<a percentagem IVA>