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.
Criação do Documento de Venda
1. Criação do cabeçalho
Para dar início à criação de um documento comercial, começa-se pelo cabeçalho. Isto é realizado através de uma solicitação POST usando cURL, onde é necessário incluir um token de acesso (access_token
), e o conteúdo (payload JSON
) que detalha as especificações do documento, incluindo o tipo de documento (fatura, fatura simplificada, fatura-recibo), informação sobre o cliente (novo ou existente), condições de pagamento, detalhes sobre o IVA, entre outros atributos opcionais.
2. Adição de Linhas
Após a criação do cabeçalho, é possível adicionar uma ou mais linhas ao documento. Este passo permite detalhar os produtos ou serviços que estão sendo transacionados.
3. Finalização do Documento
O documento pode ser finalizado após a adição de todas as informações necessárias. Uma vez finalizado, o documento não pode ser alterado ou eliminado, apenas anulado se necessário.
Cada passo é crucial para assegurar que o documento comercial seja criado de forma precisa e conforme as necessidades do usuário. A atenção aos detalhes durante o processo de criação e finalização é fundamental para a integridade do documento.
1. Criar Cabeçalho de Documento de Venda
No pedido acima, o access_token é o token de acesso válido devolvido pelo serviço de OAuth. O payload JSON a enviar contém a seguinte informação:
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_prefix
Em alternativa ao campo "document_series_id".
Não
customer_tax_registration_number
NIF do cliente. Se o cliente com o NIF indicado não existir, será criado automaticamente.
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"; é o código ISO alpha-2 do país do cliente.
Não
customer_id
No caso do cliente já existir e não pretender criar um novo.
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
Modos de pagamento aceites.
Não
vat_included_prices
Os preços nas linhas são com IVA incluído? Por omissão, não (false).
Não
operation_country
A região de operação para efeitos de IVA.
Não
currency_iso_code
É o código ISO da moeda do documento.
Não
currency_conversion_rate
É a taxa de conversão para EUR.
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
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
2. Criação da(s) linha(s)
Após a criação do documento, é possível personalizar as linhas do mesmo para detalhar produtos, serviços, ou outros descritores específicos. As linhas podem ser configuradas para refletir várias especificidades fiscais e comerciais, incluindo a opção de adicionar linhas apenas descritivas, com ou sem valor associado.
As linhas podem referenciar três tipos de itens: produtos, serviços ou descritores (juros, imobilizado, impostos especiais...). Para cada um destes o payload é ligeiramente diferente, e cada um será descrito de seguida.
No pedido mencionado acima, o access_token
representa o token de acesso validado pelo serviço de OAuth. O payload JSON a ser enviado contém informações distintas para um produto, um serviço ou um descritor, conforme será detalhado nas etapas seguintes.ccc
2.1. Criar Linha de Documento de Venda para um Produto
document_id
ID do documento ao qual esta linha está associada.
Sim
item_type
Tipo de item: "Product" para produto.
Sim
quantity
Quantidade do item. Por omissão, 1.
Não
unit_price
Preço unitário do item. Por omissão, é usado o PVP associado ao produto.
Não
settlement_expression
Desconto de linha, em percentagem; são suportados descontos compostos, como "3+5".
Não
item_id
ID do produto.
Não
unit_of_measure_id
ID da unidade de medida. Por omissão, é a configurada no produto ou a padrão da empresa.
Não
tax_id
ID do imposto associado ao item. Por omissão, é aplicado o IVA associado ao produto ou a taxa normal da empresa.
Não
2.2. Criar Linha de Documento de Venda para um Serviço
Já deve ter um Serviço criado previamente. Pode consultar mais informação em Criar Serviços
type
Tipo de linha de documento.
Sim
document_id
ID do documento ao qual esta linha está associada.
Sim
item_type
Tipo de item: "Service" (serviço).
Sim
quantity
Quantidade do serviço.
Não
unit_price
Preço unitário do serviço.
Não
settlement_expression
Expressão de liquidação, em percentagem.
Não
item_id
ID do serviço associado à linha.
Não
unit_of_measure_id
ID da unidade de medida.
Não
tax_id
ID do imposto sobre o valor acrescentado (IVA) aplicado ao serviço.
Não
2.3. Criar Linha de Documento de Venda para um Descritor
Já deve ter um Descritor criado previamente. Pode consultar mais informação em Criar Descritores
document_id
ID do documento ao qual esta linha está associada.
Sim
item_type
Tipo de item: "Service" para serviço.
Sim
quantity
Quantidade do serviço. Por omissão, 1.
Não
unit_price
Preço unitário do serviço. Por omissão, é usado o PVP associado ao serviço.
Não
settlement_expression
Desconto de linha, em percentagem; são suportados descontos compostos, como "3+5".
Não
item_id
ID do serviço.
Não
unit_of_measure_id
ID da unidade de medida. Por omissão, é a configurada no serviço ou a padrão da empresa.
Não
tax_id
ID do imposto associado ao serviço. Por omissão, é aplicado o IVA associado ao serviço ou a taxa normal da empresa.
Não
2.5. Criar Linha de Documento de Venda para uma Descrição Sem Valor
Para o caso particular de uma linha de descrição sem valor, este payload contém a seguinte informação:
description
Descrição da linha do documento.
Sim
document_id
ID do documento ao qual a linha pertence.
Sim
3. Finalização do documento
Após todas as linhas criadas, e se não houver mais nenhuma alteração ao documento, este pode ser finalizado.
Após a finalização, a alteração ou eliminação do cabeçalho e das linhas deixa de ser possível, assim como a criação de linhas adicionais.
No pedido acima, o access_token é o token de acesso válido devolvido pelo serviço de OAuth e o id do documento é o "id" interno do documento (cabeçalho) é o devolvido no campo "id" da resposta ao seu pedido de criação (ver ponto 1. Criação do cabeçalho). O payload JSON a enviar contém a seguinte informação:
type
Tipo de documento.
Sim
id
Identificador interno do documento (cabeçalho). Este "id" é devolvido na resposta ao pedido de criação do cabeçalho.
Sim
status
Identificação do estado do documento. 1: documento finalizado.
Sim
Este pedido é equivalente ao pedido de alteração do cabeçalho do documento (ver Alteração do cabeçalho do documento). Por isso, a finalização do documento — que é a alteração do atributo "status" do cabeçalho — pode ser realizada juntamente com a alteração de outros atributos ou relações do cabeçalho, num único pedido.
Alteração do Documento de Venda
Enquanto o documento não for finalizado, tanto o seu cabeçalho como qualquer uma das suas linhas podem ser alteradas a qualquer momento. Além disso, qualquer uma das linhas pode ser eliminada (ver Eliminação de uma linha), e novas linhas criadas e adicionadas (ver 2. Criação da(s) linha(s)).
Atualizar Linha de Documento de Venda
O exemplo de payload acima deve por isso ser ajustado consoante se trate da alteração duma linha de produto, de serviço, de descritor ou de descrição. É ainda possível alterar o tipo de linha (de uma linha de serviço para uma de produto, por exemplo).
O access_token é o token de acesso válido devolvido pelo serviço de OAuth.
O id da linha é o "id" interno da linha do documento, devolvido no campo "id" da resposta ao seu pedido de criação (ver ponto 2. Criação da(s) linha(s) )
A informação que pode ser enviada no pedido de alteração da linha do documento é equivalente à que é obtida após criação ou obtenção de Documentos de Venda.
type
Tipo de linha de documento.
id
Identificador interno da linha do documento.
item_id
ID do item associado à linha.
item_code
Código do item.
description
Descrição da linha.
amount
Valor total da linha.
unit_price
Preço unitário do item.
quantity
Quantidade do item.
tax_code
Tipo de IVA aplicado.
tax_percentage
Percentagem de IVA.
tax_amount
Valor do IVA aplicado.
settlement_amount
Valor de liquidação da linha.
settlement_percentage
Percentagem de liquidação da linha.
exemption_reason
Motivo da isenção de imposto.
created_at
Data e hora de criação da linha.
updated_at
Data e hora da última atualização da linha.
tax_country_region
Região do IVA aplicado.
item_unit_price_includes_vat
Indica se o preço unitário do item inclui IVA.
net_amount
Valor líquido da linha.
net_unit_price
Preço unitário líquido do item.
net_tax_amount
Valor líquido do IVA.
date
Data associada à linha.
retention_value
Valor de retenção.
pending_total
Total pendente.
pending_retention_value
Valor de retenção pendente.
locked
Indica se a linha está bloqueada.
base_currency_amount
Valor total da linha na moeda base.
base_currency_unit_price
Preço unitário do item na moeda base.
base_currency_tax_amount
Valor do IVA na moeda base.
base_currency_net_unit_price
Preço unitário líquido do item na moeda base.
base_currency_net_amount
Valor líquido da linha na moeda base.
base_currency_settlement_without_tax
Valor de liquidação sem IVA na moeda base.
original_document_no
Número do documento original associado à linha.
net_settlement_amount
Valor líquido de liquidação.
net_amount_with_header_settlement
Valor líquido da linha com liquidação no cabeçalho.
amount_with_header_settlement
Valor total da linha com liquidação no cabeçalho.
settlement_with_tax
Valor de liquidação com IVA.
settlement_without_tax
Valor de liquidação sem IVA.
base_currency_settlement_with_tax
Valor de liquidação com IVA na moeda base.
item_type
Tipo de item: "Product" (produto), "Service" (serviço) ou "TaxDescriptor" (descritor de imposto).
pending_quantity
Quantidade pendente.
imported_quantity
Quantidade importada.
settlement_expression
Expressão de liquidação.
tax_descriptor_id
ID do descritor de imposto associado à linha.
Por favor, note que alguns atributos podem estar marcados como null
, o que significa que não foram fornecidos valores para esses atributos no JSON.
Nota 1 - O "id"
interno do documento, associado ao cabeçalho, corresponde ao "id" fornecido na resposta ao pedido de criação desse cabeçalho. Consulte a secção #id-1.-criacao-do-cabecalho para mais detalhes.
Nota 2 - O item (serviço, produto ou descritor) já deve existir, e o seu "id"
interno pode ser obtido por um
Nota 3 - Além de "PT" (Portugal Continental), são também suportadas as regiões autónomas de IVA "PT-AC" (Açores) e "PT-MA" (Madeira).
Para consultar os regimes de IVA no âmbito do OSS, é importante notar que os códigos de região correspondem aos códigos dos países. Estes códigos podem ser obtidos através do seguinte pedido:
Nota 4 - A unidade de medida deve existir previamente, e seu identificador "id"
interno pode ser obtido através de um
Nota 5 - O "id" interno da taxa de IVA deve ser obtido por um
Remover Linha de Documento de Venda
No pedido acima, o access_token é o token de acesso válido devolvido pelo serviço de OAuth e o id da linha é o "id" interno da linha do documento, devolvido no campo "id" da resposta ao seu pedido de criação (ver ponto 2. Criação da(s) linha(s)).
Anulação do documento
Após a sua finalização, o documento deixa de poder ser eliminado, podendo apenas ser anulado.
No pedido acima, o access_token é o token de acesso válido devolvido pelo serviço de OAuth e o id do documento é o "id" interno do documento (cabeçalho) é o devolvido no campo "id" da resposta ao seu pedido de criação (ver ponto 1. Criação do cabeçalho). O payload JSON a enviar contém a seguinte informação:
Após a sua anulação, o documento deixa de poder ser alterado. Esta operação é irreversível.
Remover Documento de Venda
Enquanto estiver em preparação, o documento pode ser eliminado.
Após a finalização, a sua eliminação — assim como a sua alteração — deixa de ser possível. Para saber mais consulte: 3. Finalização do documento
No pedido acima, o access_token é o token de acesso válido devolvido pelo serviço de OAuth e o id do documento é o "id" interno do documento (cabeçalho) é o devolvido no campo "id" da resposta ao seu pedido de criação (ver ponto 1. Criação do cabeçalho).
Esta operação é irreversível.
Last updated