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.
POST /sales |
PUT /sales/:id |
DELETE /sales/:id |
PUT /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 |
PUT /sales/:id/generate_mbref |
PUT /sales/:id/generate_mbway |
PUT /sales/:id/sign |
POST /sales/summary |
POST /sales/find |
Vendas - Criar
—sales/:id/download.
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.
Data de emissão do documento
Data de vencimento do documento
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,
Caução,
Guia de Transporte,
Guia de Remessa,
Guia de Consignação,
Guia de Devolução,
Guia de movimentação de activos próprios.
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.
Desconto financeiro €
Desconto global %
ID ou código do cliente
Contribuinte do cliente. No caso de não preenchimento será assumido o valor 999999990.
Morada do cliente. No caso de não preenchimento será assumido o valor Desconhecido.
Localidade do cliente. No caso de não preenchimento será assumido o valor Desconhecido.
Código postal do cliente. No caso de não preenchimento será assumido o valor Desconhecido.
País do cliente. No caso de não preenchimento será assumido o valor Portugal.
Morada de entrega
Localidade da morada de entrega
Código postal da morada de entrega
País da morada de entrega
Forma de pagamento. Pode ser enviado o ID ou o descritivo, exemplo: Numerário, Transferência bancária, etc.
Condição de pagamento. Pode ser enviado o ID ou o descritivo, exemplo: Pronto pagamento, 30 dias, etc.
Modo de expedição. Pode ser enviado o ID ou o descritivo, exemplo: Correios, Comboio, etc.
Custo unitário da despesa de transporte
Taxa de IVA da despesa de transporte. Pode ser enviado o ID, descritivo ou a taxa, exemplo: 23, 13, etc.
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.
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.
Câmbio da moeda. Caso não seja enviado será assumido 1.
Tipo de IVA. Deve ser enviado um dos seguintes valores: Debitar IVA, IVA incluído, Não fazer nada.
Observações do documento
Identificador único do documento numa plataforma externa, utilizado para garantir a idempotência das operações. Se já existir uma venda com a mesma referência, será devolvida a venda existente em vez de ser criada uma nova.
Taxa de retenção na fonte
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.
Vendedor do documento. Pode ser enviado o ID ou o email.
Data de início de transporte da guia.
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.
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.
Local de destino. Pode ser enviado o ID ou nome do local. Não será assumido nenhum valor se não for enviado nada.
Localidade de carga
Localidade de descarga
Data de carga
Data de descarga (prevista)
Lista de artigos que constam no documento.
ID ou referência do artigo
Descrição adicional a aparecer no documento
Preço unitário
Quantidade
Desconto percentual
Taxa de IVA a aplicar. Pode ser enviado o ID, descritivo ou a taxa, exemplo: 23, 13, etc.
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.
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.
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.
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.
Margem à esquerda do documento. No caso de não preenchimento será assumido o valor definido no tipo de documento.
Margem à direita do documento. No caso de não preenchimento será assumido o valor definido no tipo de documento.
Margem em cima do documento. No caso de não preenchimento será assumido o valor definido no tipo de documento.
Margem em baixo do documento. No caso de não preenchimento será assumido o valor definido no tipo de documento.
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.
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.
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.
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.
URL que o Facturalusa deve notificar quando uma Factura, Factura Pró-forma, Orçamento ou
Encomenda é paga.
Estado do documento. Deve ser enviado um dos seguintes valores: Rascunho ou Terminado.
{
"id": integer,
"sale_reference_id": integer,
"number": integer,
"issue_date": string,
"due_date": string,
"serie_id": integer,
"document_type_id": integer,
"document_full_number": string,
"gross_total": decimal,
"total_discount": decimal,
"net_total": decimal,
"total_base_vat": decimal,
"total_vat": decimal,
"total_shipping": decimal,
"grand_total": decimal,
"grand_total_with_currency_exchange": decimal,
"final_discount_financial": decimal,
"final_discount_global": decimal,
"final_discount_global_value": decimal,
"customer_id": integer,
"customer_code": string,
"customer_name": string,
"customer_vat_number": string,
"customer_country": string,
"customer_city": string,
"customer_address": string,
"customer_postal_code": string,
"customer_delivery_address_country": string,
"customer_delivery_address_address": string,
"customer_delivery_address_city": string,
"customer_delivery_address_postal_code": string,
"company_name": string,
"company_vat_number": string,
"company_country": string,
"company_address": string,
"company_city": string,
"company_postal_code": string,
"payment_method_id": integer,
"payment_condition_id": integer,
"shipping_mode_id": integer,
"shipping_value": decimal,
"shipping_vat_id": integer,
"price_id": integer,
"currency_id": integer,
"currency_exchange": decimal,
"vat_type": string,
"observations": string,
"external_reference": string,
"irs_retention_apply": boolean,
"irs_retention_base": decimal,
"irs_retention_total": decimal,
"irs_retention_tax": decimal,
"url_file": string,
"file_previewed": boolean,
"file_language": string,
"file_format": string,
"email_sent": boolean,
"sms_sent": boolean,
"status": string,
"vehicle_id": integer,
"employee_id": integer,
"waybill_shipping_date": string,
"waybill_global": boolean,
"at_code": string,
"at_message": string,
"at_success": boolean,
"mb_entity": string,
"mb_sub_entity": string,
"mb_reference": string,
"cargo_location": string,
"discharge_location": string,
"cargo_date": string,
"discharge_date": string,
"signed": boolean,
"signed_id": integer,
"sign_attempt": integer,
"sign_error": string,
"created_by": integer,
"finished_by": integer,
"finished_at": string,
"canceled_by": integer,
"canceled_at": string,
"canceled_reason": string,
"updated_at": string,
"created_at": string,
"reference": {
"id": integer,
"number": integer,
"issue_date": string,
"due_date": string,
"serie_id": integer,
"document_type_id": integer,
"document_full_number": string,
"serie": {
"id": integer,
"description": string
},
"documenttype": {
"id": integer,
"description": string,
"saft_initials": string,
"type": string
}
},
"origin": {
"id": integer,
"number": integer,
"issue_date": string,
"due_date": string,
"serie_id": integer,
"document_type_id": integer,
"document_full_number": string,
"serie": {
"id": integer,
"description": string
},
"documenttype": {
"id": integer,
"description": string,
"saft_initials": string,
"type": string
}
},
"serie": {
"id": integer,
"description": string,
"valid_until": string
},
"documenttype": {
"id": integer,
"description": string,
"saft_initials": string,
"type": string,
"print_report": string,
"print_report_width": integer,
"print_pages_number": boolean,
"print_automatic": boolean,
"print_margin_top": integer,
"print_margin_right": integer,
"print_margin_left": integer,
"print_margin_bottom": integer,
"stock_check_negative": boolean,
"stock_check_minimum": boolean,
"send_email_automatic": boolean,
"send_sms_automatic": boolean,
"sign_document_automatic": boolean,
"active": boolean,
"updated_at": string,
"created_at": string
},
"documenttypeserie": {
"id": integer,
"document_type_id": integer,
"serie_id": integer,
"document_number": integer,
"atcud": string
},
"customer": {
"id": integer,
"code": string,
"name": string,
"vat_number": string,
"country": string,
"address": string,
"city": string,
"postal_code": string,
"email": string,
"telephone": string,
"mobile": string,
"currency_id": integer,
"payment_method_id": integer,
"payment_condition_id": integer,
"shipping_mode_id": integer,
"price_id": integer,
"employee_id": integer,
"type": string,
"vat_exemption_id": integer,
"vat_type": string,
"irs_retention_tax": decimal,
"observations": string,
"other_contacts": string,
"other_emails": string,
"code_blocked": boolean,
"vat_number_blocked": boolean,
"name_blocked": boolean,
"receive_sms": boolean,
"receive_emails": boolean,
"language": string,
"active": boolean,
"updated_at": string,
"created_at": string
},
"customercountry": {
"id": integer,
"name": string,
"code_iso_one": string
},
"paymentmethod": {
"id": integer,
"description": string,
"description_english": string
},
"paymentcondition": {
"id": integer,
"description": string,
"description_english": string,
"days": integer
},
"shippingmode": {
"id": integer,
"description": string,
"description_english": string
},
"shippingvat": {
"id": integer,
"description": string,
"type": string,
"tax": decimal
},
"price": {
"id": integer,
"description": string
},
"currency": {
"id": integer,
"description": string,
"symbol": string,
"code_iso": string
},
"vehicle": {
"id": integer,
"name": string,
"license_plate": string
},
"employee": {
"id": integer,
"name": string,
"email": string
},
"locationdestiny": {
"id": integer,
"name": string,
"country": string,
"address": string,
"city": string,
"postal_code": string
},
"warehouseorigin": {
"id": integer,
"description": string
},
"warehousedestiny": {
"id": integer,
"description": string
},
"items": [
{
"id": integer,
"item_id": integer,
"item_details": string,
"unit_price": decimal,
"quantity": decimal,
"discount": decimal,
"gross_total": decimal,
"net_total": decimal,
"total_base_vat": decimal,
"total_vat": decimal,
"total_discount": decimal,
"grand_total": decimal,
"vat_id": integer,
"unit_id": integer,
"vat_exemption_id": integer,
"item": {
"id": integer,
"reference": string,
"description": string,
"details": string,
"details_show_print": boolean,
"type": string,
"cost_price": decimal,
"observations": string,
"reference_blocked": boolean,
"description_blocked": boolean,
"active": boolean,
"updated_at": string,
"created_at": string,
"stock": decimal
},
"unit": {
"id": integer,
"description": string,
"symbol": string
},
"vat": {
"id": integer,
"description": string,
"type": string,
"tax": decimal,
"saft_region": string
},
"vatexemption": {
"id": integer,
"code": string,
"description": string
}
}
],
"vats": [
{
"vat_id": integer,
"total_base_vat": decimal,
"total_vat": decimal,
"vat": {
"id": integer,
"description": string,
"type": string,
"tax": decimal,
"saft_region": string
}
}
],
"createdby": {
"id": integer,
"name": string,
"firstname": string,
"lastname": string,
"email": string
},
"finishedby": {
"id": integer,
"name": string,
"firstname": string,
"lastname": string,
"email": string
},
"canceledby": {
"id": integer,
"name": string,
"firstname": string,
"lastname": string,
"email": string
},
"accountopen": {
"id": integer,
"sale_id": integer,
"debit": decimal,
"credit": decimal,
"balance": decimal
}
}Sugerimos que teste e valide a resposta completa numa plataforma de testes de API como por exemplo Postman ou Insomnia.
- Introduza pelo menos um artigo
- Os documentos tem o limite máximo de 100 artigos
- O contribuinte do cliente já foi averbado, não o pode alterar
- 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 preço unitário do artigo não pode ser inferior a zero, na linha: X
- Quando existe isenção de IVA é obrigatório que a taxa de IVA seja zero
- No tipo de IVA «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
- É obrigatório preencher o campo da data de início de transporte nas Guias
- AO campo data início transporte deverá conter uma data posterior à actual
- O total não pode ser negativo ou igual a zero
- Atingiu ou vai atingir o limite máximo de facturação para o plano adquirido
- 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
- O local de origem e o local de destino não podem ser iguais
- Já existe um documento do mesmo tipo e da mesma série emitido com uma data superior à data de emissão escolhida
- 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