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.
Last updated
As rotas aqui descritas permitem gerir todos os processos relativos a documentos de venda: orçamentos, faturas-proforma, guias, faturas e notas.
Last updated
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.
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
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
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
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
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
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
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
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)).
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).
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.
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)).
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:
{
"data": {
"type": "commercial_sales_documents", // [OBRIGATÓRIO]
"id": "1", // [OBRIGATÓRIO] Identificador interno do documento (cabeçalho). Este "id" é o devolvido na resposta ao pedido de criação do cabeçalho, ver acima.
"attributes": { // [OBRIGATÓRIO] Os atributos do documento
"status": 4, // [OBRIGATÓRIO] Identificação do estado do documento. 4: documento anulado.
"voided_reason": "Motivo pelo qual se anula o documento" // [OBRIGATÓRIO]
}
}
}Após a sua anulação, o documento deixa de poder ser alterado. Esta operação é irreversível.
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.
Já deve ter um Serviço criado previamente. Pode consultar mais informação em
Já deve ter um Descritor criado previamente. Pode consultar mais informação em
Remover Linhas de Documentos de Venda
Id da Linha do Documento de Venda
131DELETE /api/commercial_sales_document_lines/{salesDocumentLineId} HTTP/1.1
Host: {{base_url}}
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
{
"meta": {
"observed": {
"lines": 5,
"scalar": 1
}
}
}Remover Documentos de Venda
66DELETE /api/commercial_sales_documents/{id} HTTP/1.1
Host: {{base_url}}
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
{
"meta": {
"observed": {
"scalar": 1
}
}
}| Atributo | Descrição | Opcional |
|---|---|---|
| document_type | Tipo de documento. "FT": fatura, "FS": fatura simplificada, "FR": fatura-recibo. | Não |
| date | Data do documento; por omissão, a data do pedido. | Sim |
| document_series_prefix | Em alternativa ao campo "document_series_id". | Sim |
| customer_tax_registration_number | NIF do cliente. se o cliente com o NIF indicado não existir, será criado automaticamente. | Sim |
| customer_business_name | Nome do cliente. | Não |
| customer_address_detail | Morada do cliente. | Sim |
| customer_postcode | Código postal do cliente, no formato 0000-000. | Sim |
| customer_city | Cidade/Localidade do cliente. | Sim |
| customer_country | País do cliente. Por omissão, "PT"; é o código ISO alpha-2 do país do cliente. | Sim |
| customer_id | No caso do cliente já existir e não pretender criar um novo. | Sim |
| due_date | Data de vencimento; por omissão, a data do documento, ou a referente ao prazo de pagamento configurado no cliente. | Sim |
| settlement_expression | Desconto no cabeçalho, em percentagem; são suportados descontos compostos, como "3+5" | Sim |
| payment_mechanism | Modos de pagamento aceites. | Sim |
| vat_included_prices | Os preços nas linhas são com IVA incluído? Por omissão, não (false). | Sim |
| operation_country | A região de operação para efeitos de IVA. | Sim |
| currency_iso_code | É o código ISO da moeda do documento. | Sim |
| currency_conversion_rate | É a taxa de conversão para EUR. | Sim |
| retention | Percentagem de retenção a aplicar sobre os serviços. | Sim |
| retention_type | Tipo de retenção ("IRS" ou "IRC"). Por omissão, "IRS". | Sim |
| apply_retention_when_paid | A retenção é feita logo no documento (false) ou apenas no recebimento (true). Por omissão, false. | Sim |
| notes | Notas ao documento. | Sim |
| external_reference | Referência do documento externo. | Sim |
POST /api/commercial_sales_documents HTTP/1.1
Host: {{base_url}}
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 468
{
"data": {
"attributes": {
"apply_retention_when_paid": true,
"currency_conversion_rate": 1.21,
"currency_iso_code": "EUR",
"customer_id": 2,
"date": "2023-01-01",
"document_type": "FT",
"due_date": "2023-02-01",
"external_reference": "Referência do documento externo",
"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
},
"type": "commercial_sales_documents"
}
}Sucesso
{
"data": {
"attributes": {
"acts_as_shipment_document": false,
"apply_retention_when_paid": true,
"base_currency_conversion_difference": null,
"base_currency_gross_total": null,
"base_currency_net_total": null,
"base_currency_other_retentions": null,
"base_currency_other_taxes_total": null,
"base_currency_pending_total": null,
"base_currency_retention_aware_gross_total": null,
"base_currency_retention_total": null,
"base_currency_settlement_total": null,
"base_currency_tax_payable": null,
"base_currency_vat_incidence_int": null,
"base_currency_vat_incidence_ise": null,
"base_currency_vat_incidence_nor": null,
"base_currency_vat_incidence_red": null,
"base_currency_vat_total_int": null,
"base_currency_vat_total_nor": null,
"base_currency_vat_total_red": null,
"cashed_vat": false,
"child_documents_ids": null,
"communication_code": null,
"communication_code_source": "webservice",
"communication_status": "unsent",
"created_at": "2024-03-05 14:24:53.318028",
"currency_amount": null,
"currency_conversion_rate": 1,
"currency_iso_code": "EUR",
"customer_address_detail": "",
"customer_business_name": "Gabriel",
"customer_city": "",
"customer_country": "PT",
"customer_postcode": "",
"customer_tax_country_region": "PT",
"customer_tax_registration_number": "123456789",
"date": "2023-01-01",
"description": null,
"document_area": "FT",
"document_hash_sum": null,
"document_no": null,
"document_series_no": null,
"document_series_prefix": "2023",
"document_type": "FT",
"due_date": "2023-02-01",
"due_days": null,
"email_readed": false,
"emailed": null,
"end_date": null,
"expected_shipment_unloading_time": null,
"expired": null,
"external_reference": "Referência do documento externo",
"fulfilled_mask": 0,
"gross_total": 0,
"hash_control": null,
"invoice_counter": null,
"is_active": null,
"is_document_to_self": false,
"is_invoice_receipt": null,
"is_receipt": null,
"is_third_party": false,
"issue_finalized": null,
"line_settlement_with_tax": 0,
"line_settlement_with_tax_unrounded": 0,
"line_settlement_without_tax": 0,
"line_settlement_without_tax_unrounded": 0,
"made_available_to": true,
"manual_registration_number": "",
"manual_registration_series": "",
"manual_registration_type": null,
"net_settlement_total": null,
"net_total": 0,
"notes": "Notas ao documento",
"operation_country": "PT-MA",
"other_retentions": 0,
"other_taxes_total": 0,
"parent_document_area": null,
"parent_document_reference": "",
"parent_document_type": null,
"parent_documents_ids": null,
"payment_mechanism": "MO",
"pending_retention_value": 0,
"pending_total": 0,
"periodicity": null,
"periodicity_type": null,
"printed": null,
"public_link": "",
"receipts_ids": null,
"reference": null,
"reference_document_type": null,
"required_mask": 0,
"retention": 7.5,
"retention_aware_gross_total": 0,
"retention_type": "IRS",
"retention_value": 0,
"retention_value_unrounded": 0,
"scheduled_description": null,
"scheduled_end_date": null,
"scheduled_interval": null,
"scheduled_invoice_id": null,
"scheduled_start_date": null,
"send_email": null,
"settlement": null,
"settlement_expression": "7.5",
"settlement_percentage": 7.5,
"settlement_total": 0,
"settlement_with_tax": 0,
"settlement_with_tax_unrounded": 0,
"settlement_without_tax": 0,
"settlement_without_tax_unrounded": 0,
"shipment_address_detail": null,
"shipment_city": null,
"shipment_country": null,
"shipment_from_address_detail": null,
"shipment_from_city": null,
"shipment_from_country": null,
"shipment_from_postcode": null,
"shipment_loading_time": null,
"shipment_postcode": null,
"sort_status": 0,
"start_date": null,
"status": 0,
"system_entry_date": null,
"tax_payable": 0,
"third_party_type": 0,
"total_pending_quantity": null,
"updated_at": "2024-03-05 14:24:53.318028",
"vat_incidence_int": 0,
"vat_incidence_int_unrounded": 0,
"vat_incidence_ise": 0,
"vat_incidence_ise_unrounded": 0,
"vat_incidence_nor": 0,
"vat_incidence_nor_unrounded": 0,
"vat_incidence_red": 0,
"vat_incidence_red_unrounded": 0,
"vat_included_prices": false,
"vat_percentage_int": null,
"vat_percentage_nor": null,
"vat_percentage_red": null,
"vat_total_int": 0,
"vat_total_int_unrounded": 0,
"vat_total_nor": 0,
"vat_total_nor_unrounded": 0,
"vat_total_red": 0,
"vat_total_red_unrounded": 0,
"vehicle_registration": null,
"voided_reason": null
},
"id": "66",
"relationships": {
"bank_accounts": {
"data": null
},
"cash_accounts": {
"data": null
},
"commercial_document_series": {
"data": {
"id": "72",
"type": "commercial_document_series"
}
},
"company": {
"data": {
"id": "800000046",
"type": "current_company"
}
},
"currency": {
"data": {
"id": "1",
"type": "currencies"
}
},
"customer": {
"data": {
"id": "2",
"type": "customers"
}
},
"lines": {
"data": []
},
"tax_exemption_reasons": {
"data": null
},
"user": {
"data": {
"id": "800000863",
"type": "current_company_users"
}
}
},
"type": "commercial_sales_documents"
},
"meta": {
"observed": {
"scalar": 1
}
}
}Adicionar Linha a Recibo de Venda
POST /api/commercial_sales_receipt_lines HTTP/1.1
Host: {{base_url}}
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 285
{
"data": {
"attributes": {
"cashed_vat_amount": null,
"gross_total": 10.69,
"net_total": 9.27,
"receipt_id": 13,
"receivable_id": 12,
"receivable_type": "Document",
"received_value": 10.69,
"retention_total": 0.72,
"settlement_amount": 0,
"settlement_percentage": 0
},
"type": "commercial_sales_receipt_lines"
}
}No content
Atualizar Linha de Documentos de Venda
PATCH /api/commercial_sales_document_lines HTTP/1.1
Host: {{base_url}}
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1182
{
"data": {
"attributes": {
"amount": 0,
"amount_with_header_settlement": 0,
"base_currency_amount": null,
"base_currency_net_amount": null,
"base_currency_net_unit_price": null,
"base_currency_settlement_with_tax": null,
"base_currency_settlement_without_tax": null,
"base_currency_tax_amount": null,
"base_currency_unit_price": null,
"created_at": "2024-03-05 14:25:28.275949",
"date": null,
"description": "Isto é uma NOVA breve descrição",
"exemption_reason": null,
"imported_quantity": null,
"item_code": "1000",
"item_id": 2,
"item_type": "Product",
"item_unit_price_includes_vat": false,
"locked": null,
"net_amount": 0,
"net_amount_with_header_settlement": 0,
"net_settlement_amount": null,
"net_tax_amount": null,
"net_unit_price": 2,
"original_document_no": null,
"pending_quantity": null,
"pending_retention_value": null,
"pending_total": null,
"quantity": null,
"retention_value": null,
"settlement_amount": null,
"settlement_expression": null,
"settlement_percentage": 0,
"settlement_with_tax": 0,
"settlement_without_tax": 0,
"tax_amount": 0,
"tax_code": "INT",
"tax_country_region": "PT",
"tax_descriptor_id": null,
"tax_percentage": 13,
"unit_price": 2,
"updated_at": "2024-03-05 14:25:28.275949"
},
"id": "131",
"type": "commercial_sales_document_lines"
}
}Sucesso
{
"data": {
"attributes": {
"amount": 2.09,
"amount_with_header_settlement": 2.26,
"base_currency_amount": null,
"base_currency_net_amount": null,
"base_currency_net_unit_price": null,
"base_currency_settlement_with_tax": null,
"base_currency_settlement_without_tax": null,
"base_currency_tax_amount": null,
"base_currency_unit_price": null,
"created_at": "2024-03-05 14:25:28.275949",
"date": null,
"description": "Isto é uma NOVA breve descrição",
"exemption_reason": null,
"imported_quantity": null,
"item_code": "1000",
"item_id": 2,
"item_type": "Product",
"item_unit_price_includes_vat": false,
"locked": null,
"net_amount": 1.85,
"net_amount_with_header_settlement": 2,
"net_settlement_amount": null,
"net_tax_amount": null,
"net_unit_price": 1.85,
"original_document_no": null,
"pending_quantity": null,
"pending_retention_value": null,
"pending_total": null,
"quantity": 1,
"retention_value": null,
"settlement_amount": null,
"settlement_expression": null,
"settlement_percentage": 0,
"settlement_with_tax": 0,
"settlement_without_tax": 0,
"tax_amount": 0.24,
"tax_code": "INT",
"tax_country_region": "PT",
"tax_descriptor_id": null,
"tax_percentage": 13,
"unit_price": 2,
"updated_at": "2024-03-05 14:43:46.935053"
},
"id": "131",
"relationships": {
"document": {
"data": {
"id": "66",
"type": "commercial_sales_documents"
}
},
"product": {
"data": null
},
"service": {
"data": null
},
"tax": {
"data": {
"id": "2",
"type": "taxes"
}
},
"tax_descriptor": {
"data": null
},
"unit_of_measure": {
"data": {
"id": "5",
"type": "units_of_measure"
}
}
},
"type": "commercial_sales_document_lines"
},
"meta": {
"observed": {
"lines": 1,
"scalar": 1
}
}
}