Documentos de Venda
Emita Facturas, Facturas-Simplificadas, Facturas-Recibo, Notas de Crédito, Encomendas a clientes e faça a gestão de contas-correntes.
API - Documentos de Venda:
Apresentamos alguns end-points onde pode gerar, consultar e editar todo o tipo de documentos de venda.
- Criar Documento de Venda
- Obter Documento de Venda
- Alterar Documento: Definir Cliente
- Alterar Documento: Definir NIF
- Alterar Documento: Preços com IVA Incluído
- Alterar Documento: Definir Desconto Global
- Alterar Documento: Definir como Doc. de Transporte
- Limpar Linhas do Documento
- Cancelar Documento de Venda
- Finalizar Documento de Venda
- Anular Documento de Venda
Nova Documento de Venda /sale/new POST
Criar um novo documento de venda.
| Parâmetros | |
|---|---|
| document_nature |
Natureza do Documento int
Pode tomar os valores:
|
| party_id |
Cliente int
Relação com o campo 'id' da tabela 'Clientes'.
O id do cliente pode ser logo fornecido na criação para assim evitar chamar posteriormente o end-point específico.
|
| party_code |
Código do Cliente int
Relação com o campo 'code' da tabela 'Clientes'. O code do cliente pode ser logo fornecido na criação para assim evitar chamar posteriormente o end-point específico.
Nota: Caso indique ambos os party_code e party_id, prevalece o código do cliente.
|
| details |
Linhas do Documento list
Deverá conter uma lista de objectos, sendo que cada objecto poderá conter os parâmetros de uma linha conforme descritos em Linhas de Documentos. Os dados para criação das linhas podem ser logo fornecidos na criação para assim evitar chamar posteriormente o end-point específico. |
| payments |
Pagamentos list
Deverá conter uma lista de objectos, sendo que cada objecto poderá conter os parâmetros de um pagamento conforme descritos em Pagamentos de Documentos. Os dados para criação dos pagamentos podem ser logo fornecidos na criação para assim evitar chamar posteriormente o end-point específico. |
| finalize |
Finalizar Documento de Imediato bool.
Se pretender finalizar de imediato um documento de pagamento imediato (ex: Factura-Recibo), deverá fornecer dados relativos ao(s) pagamento(s) no campo payments, de forma a que o somatório dos pagamentos seja igual ao valor total do documento.
Só assim o mesmo poderá ser finalizado.
Default: false |
$ curl -X POST https://www.cloudinvoice.net/v3/sale/new/
-d '{
"document_nature": 302,
"party_id": 2
}'
{
"has_document": true,
"has_last_sale": false,
"document": {
"id": 1,
"document_key": "FSI A01/-1",
"document_nature": 302,
"document_name": "Factura Simplificada",
"document_status": 1201,
"status_reason": "",
"document_date": "2020-06-20",
"document_time": "12:56:47.205",
"due_date": "2020-06-20",
"delivery_date": "",
"is_valued": true,
"is_converted": false,
"is_partial_converted": false,
"origin_document_header_id": null,
"origin_document_header": "",
"origin_document_header__document_name": "",
"emission_reason": "",
"warehouse_id": 1,
"warehouse": "Armazém 1",
"party_id": 2,
"party_code": 2,
"party_name": "Client Demo",
"party_commercial_name": "",
"party_fiscal_number": "503217239",
"salesman_id": 1,
"salesman": "Vendedor 1",
"price_line_id": 1,
"price_line": "Preço de Venda 1",
"base_currency_id": 1,
"global_discount1": 0.0,
"payment_method_id": 1,
"payment_term_id": 1,
"payment_term": "Pronto Pagamento",
"currency_id": 1,
"is_tax_included": true,
"has_withholding": false,
"line_details_count": 0,
"lines_total_quantity": 0.0,
"total_amount": 0.0,
"total_gross_amount_currency": 0.0,
"total_global_discount_currency": 0.0,
"total_line_discount_currency": 0.0,
"total_net_amount_currency": 0.0,
"total_taxes_amount_currency": 0.0,
"total_amount_currency": 0.0,
"withholding_amount_currency": 0.0,
"total_document_amount_currency": 0.0,
"total_due_amount_currency": 0.0,
"document__ask_payment_onclose": true,
"is_paid": false,
"paid_total_amount_currency": 0.0,
"can_finalize": false,
"can_communicate": false,
"can_communicate_by_webservice": false,
...
}
}
Obter Documento de Venda /sale/<id> GET
Obter informação de um documento de venda a partir do seu ID.
$ curl https://www.cloudinvoice.net/v3/sale/1/
{
"has_document": true,
"has_last_sale": false,
"document": {
"id": 1,
"document_key": "FSI A01/-1",
"document_nature": 302,
"document_name": "Factura Simplificada",
"document_status": 1201,
"status_reason": "",
"document_date": "2020-06-20",
"document_time": "12:56:47.205",
"due_date": "2020-06-20",
"delivery_date": "",
"is_valued": true,
"is_converted": false,
"is_partial_converted": false,
"origin_document_header_id": null,
"origin_document_header": "",
"origin_document_header__document_name": "",
"emission_reason": "",
"warehouse_id": 1,
"warehouse": "Armazém 1",
"party_id": 2,
"party_code": 2,
"party_name": "Client Demo",
"party_commercial_name": "",
"party_fiscal_number": "503217239",
"salesman_id": 1,
"salesman": "Vendedor 1",
"price_line_id": 1,
"price_line": "Preço de Venda 1",
"base_currency_id": 1,
"global_discount1": 0.0,
"payment_method_id": 1,
"payment_term_id": 1,
"payment_term": "Pronto Pagamento",
"currency_id": 1,
"is_tax_included": true,
"has_withholding": false,
"line_details_count": 0,
"lines_total_quantity": 0.0,
"total_amount": 0.0,
"total_gross_amount_currency": 0.0,
"total_global_discount_currency": 0.0,
"total_line_discount_currency": 0.0,
"total_net_amount_currency": 0.0,
"total_taxes_amount_currency": 0.0,
"total_amount_currency": 0.0,
"withholding_amount_currency": 0.0,
"total_document_amount_currency": 0.0,
"total_due_amount_currency": 0.0,
"document__ask_payment_onclose": true,
"is_paid": false,
"paid_total_amount_currency": 0.0,
"can_finalize": false,
"can_communicate": false,
"can_communicate_by_webservice": false,
...
}
}
Alterar Documento: Definir Cliente /sale/<id>/select-customer POST
Definir cliente a usar no documento. O cliente pode afectar valores do documento como isenção de IVA, retenção na fonte, linha de preços, desconto global, entre outros.
| Parâmetros | |
|---|---|
| party_id |
Cliente int
Relação com o campo 'id' da tabela 'Clientes'.
O id do cliente pode ser logo fornecido na criação para assim evitar chamar posteriormente o
end-point específico.
|
curl -X POST https://www.cloudinvoice.net/v3/sale/1/select-customer/
-d '{
"party_id": 1
}'
{
"has_document": true,
"has_last_sale": false,
"document": {
"id": 1,
"document_key": "FSI A01/-1",
"document_nature": 302,
"document_name": "Factura Simplificada",
"document_status": 1201,
"status_reason": "",
"party_id": 1,
"party_code": 1,
"party_name": "",
"party_commercial_name": "",
"party_fiscal_number": "999999990",
"price_line_id": 1,
"price_line": "Preço de Venda 1",
"global_discount1": 0.0,
"has_withholding": false,
...
}
}
Alterar Documento: Definir NIF /sale/<id>/set-nif POST
Definir número de identificação fiscal, aplicável quando o cliente actual é o Consumidor Final genérico.
Se existir uma ficha de cliente com o NIF que introduziu, o cliente do documento será substituído, caso contrário, será usado o cliente Consumidor Final com o NIF introduzido.
| Parâmetros | |
|---|---|
| party_fiscal_number |
Número de Identificação Fiscal string
Preenchimento Obrigatório* |
curl -X POST https://www.cloudinvoice.net/v3/sale/1/set-nif/
-d '{
"party_fiscal_number": "123456789"
}'
{
"has_document": true,
"has_last_sale": false,
"document": {
"id": 1,
"document_key": "FSI A01/-1",
"document_nature": 302,
"document_name": "Factura Simplificada",
"document_status": 1201,
"status_reason": "",
"party_id": 1,
"party_code": 1,
"party_name": "",
"party_commercial_name": "",
"party_fiscal_number": "123456789",
"price_line_id": 1,
"price_line": "Preço de Venda 1",
"global_discount1": 0.0,
"has_withholding": false,
...
}
}
Importante:
Para que este pedido surta efeito, é necessário que NÃO exista nenhuma linha no documento.
Alterar Documento: Preços com IVA Incluído /sale/<id>/set-is-tax-included POST
Alterar documento para que os valores sejam mostrados com ou sem IVA incluído.
| Parâmetros | |
|---|---|
| is_tax_included |
Preço Unit c/IVA bool
Default: false |
curl -X POST https://www.cloudinvoice.net/v3/sale/1/set-is-tax-included/
-d '{
"is_tax_included": false
}'
{
"has_document": true,
"has_last_sale": false,
"document": {
"id": 1,
"document_key": "FSI A01/-1",
"document_nature": 302,
"document_name": "Factura Simplificada",
"document_status": 1201,
"is_valued": true,
"is_tax_included": false,
"line_details_count": 0,
"lines_total_quantity": 0.0,
"total_amount": 0.0,
"can_finalize": false,
...
}
}
Alterar Documento: Definir Desconto Global /sale/<id>/set-global-discount1 POST
Alterar desconto global aplicado ao documento.
| Parâmetros | |
|---|---|
| global_discount1 |
Desconto Global decimal
Valores: entre 0 e 100 |
curl -X POST https://www.cloudinvoice.net/v3/sale/1/set-global-discount1/
-d '{
"global_discount1": 20.0
}'
{
"has_document": true,
"has_details": true,
"document": {
"id": 1,
"document_key": "FSI A01/-1",
"document_nature": 302,
"document_name": "Factura Simplificada",
"document_status": 1201,
"is_valued": true,
"is_tax_included": true,
"line_details_count": 1,
"lines_total_quantity": 1.0,
"global_discount1": 20.0,
"total_amount": 123.0,
"total_gross_amount_currency": 123.0,
"total_global_discount_currency": 20.0,
"total_line_discount_currency": 0.0,
"total_net_amount_currency": 80.0,
"total_taxes_amount_currency": 18.4,
"total_amount_currency": 98.4,
"total_document_amount_currency": 98.4,
"total_due_amount_currency": 98.4,
"can_finalize": true,
...
},
"details": [
{
"id": 1,
"line_number": 1,
"line_subitem": 0,
"code": "PROD1",
"short_description": "Produto Standard 1",
"base_qty": 1.0,
"base_qty_unit": "1.000 UNI",
"measure_unit_id": 1,
"measure_unit__code": "UNI",
"line_unit_value": 123.0,
"line_discount1": 0.0,
"line_discount2": 0.0,
"use_serial_number": false,
"has_lots": false,
"lot_number": "",
"gross_unit_price_currency": 123.0,
"total_net_amount_currency": 80.0,
"total_amount_currency": 98.4,
...
}
]
}
Alterar Documento: Definir como Doc. de Transporte /sale/<id>/transport POST
Alguns Documentos de Venda, como Facturas ou Facturas-Recibo entre outros, podem ser usadas como Documento de Transporte, poupando assim a emissão de uma Guia específica para o efeito.
| Parâmetros | |
|---|---|
| is_transport_document |
Documento de Transporte bool
Indica se o Documento é considerado Documento de Transporte. Se este campo não estiver com valor true,
nenhum dos outros campos relacionados será considerado.
No caso de, apenas este campo ser submetido com valor |
| load_date |
Data de Carga datetime
Quando submetido, este campo deverá conter uma data futura ou não será considerado. Formato: YYYY-MM-DD hh:mm:ss |
| ship_from_street1 | Morada de Carga string |
| ship_from_street2 | Morada de Carga Linha 2 string |
| ship_from_zip_code | Código Postal (Origem) string |
| ship_from_zip_locale | Localidade (Origem) string |
| ship_from_city | Cidade (Origem) string |
| ship_from_country |
País de Partida int
Relação com o campo 'id' da tabela 'Países'. |
| vehicle_plate | Matrícula da Viatura string |
| unload_date |
Data de Descarga datetime
Quando submetido, este campo deverá conter uma data futura ou não será considerado. Formato: YYYY-MM-DD hh:mm:ss |
| ship_to_street1 | Morada de Descarga string |
| ship_to_street2 | Morada de Descarga Linha 2 string |
| ship_to_zip_code | Código Postal (Destino) string |
| ship_to_zip_locale | Localidade (Destino) string |
| ship_to_city | Cidade (Destino) string |
| ship_to_country |
País de Destino int
Relação com o campo 'id' da tabela 'Países'. |
curl -X POST https://www.cloudinvoice.net/v3/sale/1/transport/
-d '{
"is_transport_document": true,
"load_date": "2020-05-20 08:00",
"unload_date": "2020-05-20 08:30",
"ship_to_street1": "Avenida Principal, nº 22",
"ship_to_zip_code": "8800-000",
"ship_to_zip_locale": "Tavira",
}'
{
"has_document": true,
"has_details": true,
"document": {
"id": 1,
"document_key": "FSI A01/-1",
"document_nature": 302,
"document_name": "Factura Simplificada",
"document_status": 1201,
"is_valued": true,
"is_tax_included": true,
"line_details_count": 1,
"lines_total_quantity": 1.0,
"is_transport_document": true,
"load_shipment_id": 1,
"load_shipment": "Nossas instalações",
"ship_from_warehouse_id": 1,
"ship_from_warehouse": "Armazém 1",
"ship_from_country_id": 1,
"ship_from_country": "Portugal",
"load_date_tz": "2020-05-20 08:00",
"ship_from_street1": "Av. Dr. Mateus Teixeira de Azevedo, Lote 3 R/C Esq.",
"ship_from_street2": "",
"ship_from_zip_code": "8800-379",
"ship_from_zip_locale": "TVR",
"vehicle_plate": "",
"unload_shipment_id": null,
"unload_shipment": "",
"ship_to_party_address_id": null,
"ship_to_party_address": "",
"ship_to_country_id": 1,
"ship_to_country": "Portugal",
"unload_date_tz": "2020-05-20 08:30",
"ship_to_street1": "Avenida Principal, nº 22",
"ship_to_street2": "",
"ship_to_zip_code": "8800-000",
"ship_to_zip_locale": "Tavira",
...
},
"details": [
...
]
}
Limpar Linhas do Documento /sale/<id>/delete-all POST
Apagar todas as linhas do documento.
$ curl -X POST https://www.cloudinvoice.net/v3/sale/1/delete-all/
{
"has_document": true,
"has_last_sale": false,
"document": {
"id": 1,
"document_key": "FSI A01/-1",
"document_nature": 302,
"document_name": "Factura Simplificada",
"document_status": 1201,
"status_reason": "",
"document_date": "2020-06-20",
"document_time": "12:56:47.205",
"due_date": "2020-06-20",
"delivery_date": "",
"is_valued": true,
"is_converted": false,
"is_partial_converted": false,
"origin_document_header_id": null,
"origin_document_header": "",
"origin_document_header__document_name": "",
"emission_reason": "",
"warehouse_id": 1,
"warehouse": "Armazém 1",
"party_id": 2,
"party_code": 2,
"party_name": "Client Demo",
"party_commercial_name": "",
"party_fiscal_number": "503217239",
"salesman_id": 1,
"salesman": "Vendedor 1",
"price_line_id": 1,
"price_line": "Preço de Venda 1",
"base_currency_id": 1,
"global_discount1": 0.0,
"payment_method_id": 1,
"payment_term_id": 1,
"payment_term": "Pronto Pagamento",
"currency_id": 1,
"is_tax_included": true,
"has_withholding": false,
"line_details_count": 0,
"lines_total_quantity": 0.0,
"total_amount": 0.0,
"total_gross_amount_currency": 0.0,
"total_global_discount_currency": 0.0,
"total_line_discount_currency": 0.0,
"total_net_amount_currency": 0.0,
"total_taxes_amount_currency": 0.0,
"total_amount_currency": 0.0,
"withholding_amount_currency": 0.0,
"total_document_amount_currency": 0.0,
"total_due_amount_currency": 0.0,
"document__ask_payment_onclose": true,
"is_paid": false,
"paid_total_amount_currency": 0.0,
"can_finalize": false,
"can_communicate": false,
"can_communicate_by_webservice": false,
...
}
}
Cancelar Documento de Venda /sale/<id>/cancel POST
Cancelar um documento de venda. Ao ser cancelado, um documento é completamente apagado do sistema, sendo irrecuperável.
Um documento apenas pode ser cancelado até ao momento em que é finalizado. Após a finalização, terá de usar a anulação.
$ curl -X POST https://www.cloudinvoice.net/v3/sale/1/cancel/
{
"id": 1
}
Informação:
Os exemplos dados referem-se a documentos de venda, mas existem end-points com funcionamento análogo para outros documentos:
- /receipt/<id>/cancel - recibos;
Finalizar Documento de Venda /sale/<id>/finalize POST
Finalizar documento de venda.
Documentos de venda, por norma, requerem a existência de
linhas para poderem ser finalizados com sucesso.
No caso de documentos de pagamento imediato (ex: Factura-Recibo), terão de existir também
pagamentos da totalidade do documento.
$ curl -X POST https://www.cloudinvoice.net/v3/sale/1/finalize/
{
"instance": {
"id": 1,
"document_key": "FSI A01/1",
"document_name": "Factura Simplificada",
"party_id": 2,
"party_name": "Client Demo",
"document_status": 1202
}
}
Informação:
Documentos assinados (ex: Facturas) após a finalização passam a ter valor legal.
Após a finalização, esta não poderá ser revertida e o conteúdo do documento não poderá mais ser alterado. A única acção passível de ser aplicada a documentos finalizados capaz de os afectar é a anulação.
Anular Documento de Venda /sale/<id>/annul POST
Anular documento de venda.
Importante:
A anulação de um documento não poderá ser revertida em circunstância alguma.
| Parâmetros | |
|---|---|
| status_reason |
Motivo da Anulação
decimal
Preenchimento Obrigatório* |
Informação:
Os exemplos dados referem-se a documentos de venda, mas existem end-points com funcionamento análogo para outros documentos:
- /receipt/<id>/annul - recibos;
curl -X POST https://www.cloudinvoice.net/v3/sale/1/annul/
-d '{
"status_reason": "Por uma boa razão!"
}'
{
"has_document": true,
"has_details": true,
"document": {
"id": 1,
"document_key": "FSI A01/1",
"document_nature": 302,
"document_name": "Factura Simplificada",
"document_status": 1203,
"status_reason": "Por uma boa razão!",
"is_valued": true,
"is_tax_included": true,
...
},
...
}