insert

Disponível na versão: 1.0+

Insere uma nova fatura.

Os campos financial_discount, salesman_commission e ainda o campo discount de cada elemento do conjunto products, caso sejam preenchidos, devem ser valores em percentagem, de 0 a 100.

O campo special_discount, caso seja preenchido, deverá ser um valor monetário.

O campo exemption_reason de cada elemento do conjunto products torna-se obrigatório caso o conjunto taxes esteja vazio, não contenha elementos cujo imposto correspondente seja do tipo IVA ou que estes tenham valor zero.

A estrutura properties de cada elemento do conjunto products é opcional. No entanto, caso o artigo em causa tenha propriedades mas não sejam enviadas neste endpoint, serão automaticamente preenchidas. Por outro lado, se for enviada pelo menos uma propriedade, as propriedades originais serão ignoradas.

O campo origin_id refere-se ao documento associado de onde este produto é originário. Caso tenha guias globais associadas ao documento, existe uma obrigação legal de declarar os artigos com origem nesse documento e deverá usar este campo. Se tentar usar um id de documento que não esteja presente nos associados, irá receber um erro.

Caso a empresa só tenha um CAE e o eac_id não for enviado, ou o que tenha sido enviado seja inválido, o eac_id será automaticamente preenchido com o único CAE existente. Caso a empresa tenha mais do que um CAE, este será mantido em branco.

O campo value de cada elemento dos conjuntos taxes existentes torna-se obrigatório caso o imposto definido por tax_id seja um imposto cujo valor seja definido por artigo.

Todos os campos *_id apenas aceitam valores válidos. Esses valores podem ser consultados nos respectivos endpoints da API. No caso dos associated_id dos elementos do conjunto associated_documents, têm de pertencer a documentos cujo tipo possa ser associado com faturas, isto é, guias de remessa.

O campo maturity_date_id é opcional, e deverá escolher um prazo de vencimento que se coadune com a data de vencimento enviada, tanto ao nível dos dias, como da descrição daquele. O prazo de vencimento é meramente apresentacional. Se não o enviar, a impressão do documento dirá "pronto pagamento", independentemente da data de vencimento.

O campo deduction_id, até agora existente no document, foi depreciado, e será removido da API futuramente. Recomenda-se que se passe a usar a deduction_id nos elementos da estrutura products. Durante esta fase de transição, se for enviado no document, será propagado a todos os elementos da estrutura products que não o tenham.

Os campos delivery_departure_country e delivery_destination_country apenas aceitam id de países válidos. Para além disso, se o país for Portugal (id 1), o código postal deve ser válido (4 dígitos, traço, 3 dígitos).

Pode enviar os campos vehicle_name e vehicle_number_plate para definir uma viatura de transporte sem a gravar na sua empresa. Se também enviar o campo vehicle_id, a viatura por este identificada será usada em vez daqueles campos.

O campo status aceita os valores 0 (por defeito, caso não seja preenchido) e 1, que correspondem, respectivamente, aos estados de rascunho e fechado. Ao inserir uma fatura com o estado fechado, os documentos associados, caso existam, serão conciliados com os valores definidos e será comunicada para a Autoridade Tributária, caso a empresa tenha essa opção activa.

Se a empresa tiver aderido ao regime de IVA de caixa, só podem ser usados document_set_id de séries criadas para esse regime. Será emitido um erro caso seja escolhida outra série.

Para criar documentos noutras moedas, os campos exchange_currency_id e exchange_rate devem ser preenchidos. O campo exchange_currency_id deverá ser preenchido com um id de moeda válido, que pode consultar no endpoint currencies/getAll. O campo exchange_rate deverá ser preenchido com o valor monetário apropriado. Pode consultar as tabelas de conversão que actualizamos todos os dias, no endpoint currencyExchange/getAll.

Se fechar o documento (status = 1) e se tiver configurado o sistema de geração de referências multibanco na empresa, pode enviar o campo generate_mb_reference = 1 para gerar uma referência multibanco para este documento, pelo seu valor total. Se a referência for gerada com sucesso, na resposta virá a estutura mb_reference devidamente preenchida.

Ao fechar o documento, serão movimentados stocks, caso um ou mais dos seus artigos tenha gestão de stocks. Se a sua empresa tiver armazéns definidos, pode preencher o campo warehouse_id de cada artigo, para que o stock seja movimentado num armazém em concreto. Se não indicar qual o armazém, o stock será movimentado no armazém pré-definido do artigo ou, caso nenhum esteja pré-definido, no pré-definido da empresa.

Caso o artigo que está a tentar inserir seja um artigo composto, é preciso enviar a estrutura child_products de cada artigo, que corresponde aos artigos"filhos". Se não enviar esta estrutura, o artigo "pai" é adicionado ao documento como um artigo normal. É preciso ter em atenção o seguinte:

 - Os artigos "filhos" deverão estar já configurados no moloni como sendo "filhos" do artigo composto. É obrigatório que os "filhos" pertençam ao "pai", mas não é obrigatório enviar todos os "filhos" de um "pai". 

 - O campo price do artigo "pai" deverá corresponder à soma dos preços dos artigos "filhos", por exemplo, um artigo filho com um price de 1.5 e qty de 2, terá que ter um "pai" com um price de 3 e qty de 1, ou price de 1.5 e qty de 2, de forma a que os totais sejam iguais.

 - Caso o artigo "pai" tenha descontos, os mesmos deverão ser aplicados aos "filhos", e não ao "pai". Se enviar descontos diferentes para cada "filho", no artigo "pai" é calculada a percentagem de desconto correcta sobre o total. 

 - As taxes deverão ser aplicadas aos artigos "filhos", sendo que depois serão replicadas no artigo "pai".

Caso pretenda usar dados de transporte no documento, os dados referentes à morada de carga e à morada de descarga deverão ser preenchidos obrigatoriamente e deverá também ser preenchido um dos seguintes parâmetros: delivery_method_id ou vehicle_number_plate

 

Pedido

https://api.moloni.pt/v1/invoices/insert/?access_token=[current_access_token]

Parâmetros
company_id int

Obrigatório

date date

Obrigatório

expiration_date date

Obrigatório

maturity_date_id int
document_set_id int

Obrigatório

customer_id int

Obrigatório

alternate_address_id int
our_reference string
your_reference string
financial_discount float
eac_id int
salesman_id int
salesman_commission float
special_discount float
associated_documents array
associated_id int

Obrigatório

value float

Obrigatório

related_documents_notes string
products array

Obrigatório

product_id int

Obrigatório

name string

Obrigatório

summary string
qty float

Obrigatório

price float

Obrigatório

discount float
deduction_id int
order int
origin_id int
exemption_reason string
warehouse_id int
properties array
title string
value string
taxes array
tax_id int

Obrigatório

value float
order int
cumulative int
child_products array
product_id int

Obrigatório

name string

Obrigatório

summary string
qty float

Obrigatório

price float

Obrigatório

discount float
deduction_id int
order int
origin_id int
exemption_reason string
warehouse_id int
properties array
title string
value string
taxes array
tax_id int

Obrigatório

value float
order int
cumulative int
exchange_currency_id int
exchange_rate float
delivery_method_id int
delivery_datetime date
delivery_departure_address string
delivery_departure_city string
delivery_departure_zip_code string
delivery_departure_country int
delivery_destination_address string
delivery_destination_city string
delivery_destination_zip_code string
delivery_destination_country int
vehicle_id int
vehicle_name string
vehicle_number_plate string
notes string
status int
generate_mb_reference int
Nota
- O parâmetro qty tem como default 50 e o offset 0, sendo que o máximo qty é 50;
- Campos de preenchimento facultativo, significa que podem ser uma string vazia ou zero, dependendo do respectivo tipo.
Resposta
{
	valid: 1,
	document_id: int,
	mb_reference: {
		entity: string
		reference: string
		value: string
	}
}
Lista de erros possíveis
Sempre que existir um erro no preenchimento dos campos, será devolvido via JSON o objeto com os erros indexado pela ordem dos campos.
As mensagens de erro, são devolvidas sob a forma de códigos, e para perceber quais os erros disponíveis e como interpretar as mensagens recebidas, consulte esta ligação.

© 2024 Moloni

Software de faturação online

Certificado pela Autoridade Tributária N.º 2860