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