Vendas

—

Este endpoint visa gerir a emissão de qualquer documento de venda: Facturas, Orçamentos, Encomendas e Guias. Os resultados retornados são os mesmos para qualquer um dos endpoints disponibilizados independentemente do tipo de documento emitido.

A emissão de documentos contabilísticos está dependente do volume de facturação do plano adquirido.

Os pedidos de criação de uma venda em estado Terminado devem ser realizados de forma síncrona para garantir que a numeração do documento, na respectiva série, é a correcta.

POST /sales/create

POST /sales/:id/update

POST /sales/:id/delete

POST /sales/:id/cancel

POST /sales/:id/duplicate

POST /sales/:id/receipt

POST /sales/:id/credit_note

POST /sales/:id/debit_note

POST /sales/:id/receipt

POST /sales/:id/download

POST /sales/:id/send_email

POST /sales/:id/send_sms

POST /sales/:id/generate_mbref

POST /sales/:id/generate_mbway

POST /sales/:id/sign

POST /sales/summary

POST /sales/find

POST /sales/list

Vendas - Criar

sale_reference_id integer

ID da venda a ser referenciada. Apenas deve ser preenchido quando o documento a ser emitido se trata de uma Nota de crédito ou Nota de débito e há uma referência a uma Factura, Factura Simplificada ou Factura Recibo.

issue_date date required

Data de emissão do documento

due_date date

Data de vencimento do documento

document_type mixed required

Tipo de documento. Pode ser enviado o ID ou o descritivo, exemplo: Factura, Factura Recibo, Factura Simplificada, Nota de Crédito, Nota de Débito, Factura Pró-forma, Orçamento, Encomenda, Consulta de Mesa, Guia de Transporte, Guia de Remessa, Guia de Consignação, Guia de Devolução, Guia de movimentação de activos próprios.

serie mixed

Série. Pode ser enviado o ID ou o descritivo, exemplo: 2021, 2021A, etc. No caso de não preenchimento será assumido a série pré-definida.

final_discount_financial double

Desconto financeiro €

final_discount_global double

Desconto global %

customer integer required

ID do cliente

vat_number string

Contribuinte do cliente. No caso de não preenchimento será assumido o valor 999999990.

address string required

Morada do cliente

city string required

Localidade do cliente

postal_code string required

Código postal do cliente

country string required

País do cliente

delivery_address_address string

Morada de entrega

delivery_address_city string

Localidade da morada de entrega

delivery_address_postal_code string

Código postal da morada de entrega

delivery_address_country string

País da morada de entrega

payment_method mixed

Forma de pagamento. Pode ser enviado o ID ou o descritivo, exemplo: Numerário, Transferência bancária, etc.

payment_condition mixed

Condição de pagamento. Pode ser enviado o ID ou o descritivo, exemplo: Pronto pagamento, 30 dias, etc.

shipping_mode mixed

Modo de expedição. Pode ser enviado o ID ou o descritivo, exemplo: Correios, Comboio, etc.

shipping_value double

Custo unitário da despesa de transporte

shipping_vat mixed

Taxa de IVA da despesa de transporte. Pode ser enviado o ID, descritivo ou a taxa, exemplo: 23, 13, etc.

price mixed

Tabela de preços utilizada. Pode ser enviado o ID ou o descritivo, exemplo: Preços público, Preços revenda, etc. No caso de não preenchimento será assumido a tabela de preços pré-definida.

currency mixed

Moeda utilizada. Pode ser enviado o ID, símbolo ou descritivo, exemplo: €, $, Euro, Dólar. No caso de não preenchimento será assumido a moeda pré-definida.

currency_exchange double

Câmbio da moeda. Caso não seja enviado será assumido 1.

vat_type string required

Tipo de IVA. Deve ser enviado um dos seguintes valores: Debitar IVA, IVA incluído, Não fazer nada.

observations string

Observações do documento

irs_retention_tax double

Taxa de retenção na fonte

vehicle mixed

Veículo utilizado. Este campo apenas deve ser utilizado quando o tipo de documento emitido se trata de uma guia. Pode ser enviado o ID, matrícula ou nome.

employee mixed

Vendedor do documento. Pode ser enviado o ID ou o email.

waybill_shipping_date datetime required if waybill

Data de início de transporte da guia.

waybill_global boolean

Determina se a guia se trata de uma guia global de transporte. Esta opção só pode ser utilizada se o documento a emitir se tratar de uma Guia de Transporte ou Guia de Remessa. Se activo, os campos: customer, vat_number, address, city, postal_code, country, delivery_address_address, delivery_address_city, delivery_address_postal_code, delivery_address_country, discharge_location e location_destiny deixam de ter a obrigatoriedade de preenchimento e serão sempre automaticamente preenchidos pelo Facturalusa com as informações do cliente genérico.

location_origin mixed

Local de origem. Pode ser enviado o ID ou nome do local. No caso de não preenchimento será assumido o local de origem pré-definido.

location_destiny mixed

Local de destino. Pode ser enviado o ID ou nome do local. Não será assumido nenhum valor se não for enviado nada.

cargo_location string

Localidade de carga

discharge_location string

Localidade de descarga

cargo_date datetime

Data de carga

discharge_date datetime

Data de descarga (prevista)

items json array required

Lista de artigos que constam no documento.

id mixed required

ID ou referência do artigo

details string

Descrição adicional a aparecer no documento

price double required

Preço unitário

quantity double required

Quantidade

discount double

Desconto percentual

vat mixed required

Taxa de IVA a aplicar. Pode ser enviado o ID, descritivo ou a taxa, exemplo: 23, 13, etc.

vat_exemption mixed

Isenção de IVA a aplicar. Pode ser enviado o ID ou o código, exemplo: M08, etc. No caso de não preenchimento será assumido o valor M18 - Sem isenção.

language string

Idioma a ser impresso caso o estado do documento seja Terminado. Preencher com PT ou EN. No caso de não preenchimento será assumido o idioma pré-definido.

format string

Formato a ser impresso caso o estado do documento seja Terminado. Preencher com A4, POS ou EscPOS. No caso de não preenchimento será assumido o valor definido no tipo de documento (que por norma é A4).

Os formatos A4 e POS produzem um ficheiro PDF.

O formato EscPOS produz um ficheiro TXT com os comandos da impressora em Base64.

paper_size integer

Tamanho / largura do documento em milímetros. Apenas deve ser preenchido caso o formato seja POS ou EscPOS. No caso de não preenchimento será assumido o valor definido no tipo de documento.

paper_left_margin integer

Margem à esquerda do documento. No caso de não preenchimento será assumido o valor definido no tipo de documento.

paper_right_margin integer

Margem à direita do documento. No caso de não preenchimento será assumido o valor definido no tipo de documento.

paper_top_margin integer

Margem em cima do documento. No caso de não preenchimento será assumido o valor definido no tipo de documento.

paper_bottom_margin integer

Margem em baixo do documento. No caso de não preenchimento será assumido o valor definido no tipo de documento.

force_print boolean

Determina se deve ou não gerar a impressão do documento caso o estado do mesmo seja Terminado. Se preenchido com true o documento será impresso; se preenchido com false o documento não será impresso; se não for preenchido, irá assumir o valor definido no tipo de documento.

force_send_email boolean

Determina se deve ou não enviar via email o documento para o cliente caso o estado do mesmo seja Terminado. Se preenchido com true o documento será enviado; se preenchido com false o documento não será enviado; se não for preenchido, irá assumir o valor definido no tipo de documento.

force_send_sms boolean

Determina se deve ou não enviar SMS para o cliente caso o estado do documento seja Terminado. Se preenchido com true a SMS será enviada; se preenchido com false a SMS não será enviada; se não for preenchido, irá assumir o valor definido no tipo de documento. Esta funcionalidade só funciona se tiver SMS disponíveis.

force_sign boolean

Determina se deve ou não assinar o documento caso o estado do documento seja Terminado e caso o mesmo seja impresso. Se preenchido com true o documento será assinado; se preenchido com false o documento não será assinado; se não for preenchido, irá assumir o valor definido no tipo de documento. Esta funcionalidade só funciona se tiver a Assinatura Digital activada e bem configurada.

status string required

Estado do documento. Deve ser enviado um dos seguintes valores: Rascunho ou Terminado.

Request POST /sales/create

{
    "sale_reference_id": ..
    "issue_date": ..
    "due_date": ..
    ...
    "items": 
    [
        {
            "id": ..
            "details": ..
            "price": ..
            "quantity": ..
            "discount": ..
            "vat": ..
            "vat_exemption": ..
        }
    ],
}

Response 200

{
    "status": true,
    "data": 
    {
        "id": ..
        "number": ..
        "issue_date": ..
        "due_date": ..
        "serie_id": ..
        "document_type_id": ..
        "gross_total": ..
        "total_discount": ..
        "net_total": ..
        "total_base_vat": ..
        "total_vat": ..
        "total_shipping": ..
        "total_services": ..
        "grand_total": ..
        "final_discount_financial": ..
        "final_discount_global": ..
        "final_discount_value": ..
        "customer_id": ..
        "customer_code": ..
        "customer_name": ..
        "customer_vat_number": ..
        "customer_country": ..
        "customer_city": ..
        "customer_address": ..
        "customer_postal_code": ..
        "customer_delivery_address_country": ..
        "customer_delivery_address_address": ..
        "customer_delivery_address_city": ..
        "customer_delivery_address_postal_code": ..
        "company_name": ..
        "company_vat_number": ..
        "company_country": ..
        "company_address": ..
        "company_city": ..
        "company_postal_code": ..
        "company_vat_scheme": ..
        "payment_method_id": ..
        "payment_condition_id": ..
        "shipping_mode_id": ..
        "shipping_value": ..
        "shipping_vat_id": ..
        "price_id": ..
        "currency_id": ..
        "currency_exchange": ..
        "vehicle_id": ..
        "employee_id": ..
        "waybill_shipping_date": ..
        "waybill_global": ..
        "location_origin_id": ..
        "location_origin_name": ..
        "location_origin_country": ..
        "location_origin_address": ..
        "location_origin_city": ..
        "location_origin_postal_code": ..
        "warehouse_origin_id": ..
        "warehouse_destiny_id": ..
        "location_destiny_id": ..
        "cargo_location": ..
        "discharge_location": ..
        "cargo_date": ..
        "discharge_date": ..
        "mb_entity": ..
        "mb_sub_entity": ..
        "mb_reference": ..
        "at_code": ..
        "at_message": ..
        "vat_type": ..
        "observations": ..
        "irs_retention_apply": ..
        "irs_retention_base": ..
        "irs_retention_total": ..
        "irs_retention_tax": ..
        "url_file": ..
        "file_previewed": ..
        "file_last_generated": ..
        "status": ..
        "status_last_change": ..
        "created_by": ..
        "finished_by": ..
        "canceled_by": ..
        "canceled_at": ..
        "canceled_reason": ..
        "updated_at": ..
        "created_at": ..
        "reference": [],
        "serie": [],
        "documenttype": [],
        "documenttypeserie": [],
        "paymentmethod": [],
        "paymentcondition": [],
        "shippingmode": [],
        "shippingvat": [],
        "price": [],
        "currency": [],
        "vehicle": [],
        "employee": [],
        "locationdestiny": [],
        "warehouseorigin": [],
        "warehousedestiny": [],
        "vats": [],
        "items": [],
        "createdby": [],
        "finishedby": [],
        "canceledby": [],
        "customercountry": [],
        "accountopen": [],
    }
}

Sugerimos que teste e valide a resposta completa numa plataforma de testes de API como por exemplo Postman ou Insomnia.

Não tem permissões para executar esta operação
Na versão demo o total não pode ultrapassar os 10.000,00€
Não preencheu todos os campos obrigatórios
O tipo de documento não existe ou não se encontra activo
O tipo de IVA não existe ou não foi introduzido
Não preencheu a série ou não existe nenhuma série pré-definida para utilizar
Não preencheu a moeda ou não existe nenhuma moeda pré-definida para utilizar
Seleccione pelo menos um artigo
Os documentos tem o limite máximo de 100 artigos
O cliente não existe
O cliente não se encontra activo
O contribuinte do cliente já foi averbado, não o pode alterar
O estado do documento não é válido
A série não se encontra atribuída no tipo de documento seleccionado
A série não se encontra activa no tipo de documento seleccionado
A série encontra-se expirada
A série não se encontra comunicada à AT no tipo de documento seleccionado. A partir de 2023 passou a ser um requisito obrigatório
O local não existe ou não se encontra activo
Não preencheu correctamente o desconto financeiro (formato aceite: 0,00 ou 0.00)
Não preencheu correctamente o desconto global (formato aceite: 0,00 ou 0.00)
O preço unitário do artigo não pode ser inferior a zero, na linha: X
Um ou mais artigos mal preenchidos, na linha: X
O artigo não existe
Não preencheu todos os campos obrigatórios nos artigos
Não preencheu correctamente o preço unitário (formato aceite: 0,00000 ou 0.00000)
Não preencheu correctamente a quantidade (formato aceite: 0,00000 ou 0.00000)
Não preencheu correctamente o desconto (formato aceite: 0,00 ou 0.00)
Quando existe isenção de IVA é obrigatório que a taxa de IVA seja zero
Quando o tipo de IVA seleccionado é «Não fazer nada» todos os artigos do documento devem ter a Taxa de IVA 0% e o respectivo motivo de isenção de IVA aplicado
A data início transporte não contêm um formato válido (ano-mês-dia horas:minutos)
É obrigatório preencher o campo da data de início de transporte nas Guias
A data e hora da guia não pode ser inferior à data e hora actual
O código postal é de preenchimento obrigatório em Portugal
O local de destino é de preenchimento obrigatório
O total não pode ser negativo ou igual a zero
Já atingiu o volume máximo de facturação ou a soma do total geral do documento actual com o valor actual da subscrição ultrapassa o limite
Não pode criar este documento sobre o contribuinte de consumidor final
Artigo 36.º alinea 15 do CIVA : É necessária a identificação e domicílio do cliente quando o valor total da factura for igual ou superior a 1000,00€
Na Factura Simplificada o total base não pode ser superior a 1000.00€ para particulares
Na Factura Simplificada o total de serviços não pode exceder 100,00€ para particulares
Na Factura Simplificada o total base não pode ser superior a 100.00€ para empresas
Formato/valor de câmbio inválido
Não preencheu correctamente a taxa de retenção de IRS (formato aceite: 0,00 ou 0.00)
Não preencheu correctamente as despesas de transporte
Não preencheu correctamente o valor da despesa de transporte (formato aceite: 0,00 ou 0.00)
A data emissão não contêm um formato válido (ano-mês-dia)
A data de vencimento não contêm um formato válido (ano-mês-dia)
A data de vencimento não pode ser inferior à data de emissão
A data de carga não contêm um formato válido (ano-mês-dia horas:minutos)
A data e hora da carga não pode ser inferior à data e hora actual
A data de descarga não contêm um formato válido (ano-mês-dia horas:minutos)
A data e hora da descarga não pode ser inferior à data e hora actual
O local de origem e o local de destino não podem ser iguais!
Despacho n.º 8632/2014: Quando acontecer uma situação de erro ou anomalia (...) devem ser encerradas as séries em utilização. A série encontra-se bloqueada
Já existe um documento do mesmo tipo e da mesma série emitido com uma data superior à data de emissão escolhida
O documento referenciado não existe
Só pode referenciar Facturas, Facturas Recibo ou Facturas Simplificadas
O cliente do documento rectificativo não pode ser diferente do documento original
A data de emissão do documento rectificativo não pode ser inferior à do documento original
Um ou mais artigos não se encontram atribuídos ao documento que está a ser rectificado
Um ou mais artigos nunca foram facturados a este cliente e está a lançar um documento rectificativo
O total geral do documento rectificativo não pode ser superior ao total geral do documento original
Os valores (quantidades, preços, descontos, taxas iva, totais) dos artigos do documento rectificativo tem de ser iguais ou inferiores aos valores do documento original
O desconto financeiro não pode ser superior à soma dos preços unitários dos artigos
As guias globais só podem ser criadas nos tipos de documento Guia de Transporte e Guia de Remessa
O país introduzido é inválido

Changelog Vendas - Actualizar

Introdução

Autenticação

Resposta e erros

SDKs e plugins

Países

Isenções IVA

Changelog

Vendas

Recibos

Clientes

Clientes - Contas em aberto

Artigos

Artigos - Stock

Artigos - Movimentos stock

Agenda - Marcações

Agenda - Indisponibilidades

Administração

Administração - Armazéns

Administração - Categorias

Administração - Colaboradores

Administração - Condições de pagamento

Administração - Formas de pagamento

Administração - Modos de expedição

Administração - Moedas

Administração - Preços

Administração - Séries

Administração - Taxas de IVA

Administração - Tipos de documento

Administração - Veículos

Administração - Unidades

Subscrição

Subscrição - Locais

Vendas

Vendas - Criar