Documentação API
Search…
⌃K

Faturas

As faturas seguem a mesma estrutura anteriormente definida: são compostas por um cabeçalho, e linhas. Nesta nova versão, é possível criar ambos num só pedido, descrito de seguida.

Criação de cabeçalho e linhas

Os detalhes do pedido POST para a criação do cabeçalho estão descritos de seguida, em formato OpenAPI, e em cURL.
post
https://4290048310-files.gitbook.io/
/v1/commercial_sales_documents
curl -v -X POST -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' -d '<payload JSON>' '<API_URL>/v1/commercial_sales_documents'
Neste cURL, o payload JSON a enviar deverá vir no seguinte formato:
{
"document_type": "FT", // [OBRIGATÓRIO] Tipo de documento. "FT" para fatura, "FS" para fatura simplificada, "FR" para fatura-recibo, "FP" para faturas-proforma.
"date": "2020-01-01", // [OPCIONAL] Data do documento; por omissão, a data do pedido
"due_date": "2020-02-01", // [OPCIONAL] Data de vencimento; por omissão, a data do documento, ou a referente ao prazo de pagamento configurado no cliente, se o cliente tiver configurado um prazo de pagamento
"customer_tax_registration_number": "999999990", // [OPCIONAL] Por omissão, "999999990"; se o cliente com o NIF indicado não existir, será criado automaticamente. Se o país for Portugal, deve ser um NIF português válido.
"status": 0, // [OPCIONAL] Por omissão, vem a 1, finalizado. Pode ser indicado 0, para permaneçer em preparação
// [OPCIONAL] Os atributos seguintes são usados na criação do cliente, se não existir ainda
// Se o cliente já existir, são guardados no documento, mas a ficha do cliente não é actualizada
"customer_business_name": "Test customer", // [OBRIGATÓRIO] caso o cliente ainda não exista e tenha que ser criado. [OPCIONAL] nos outros casos, a não ser que exista mais do que um cliente com o NIF indicado, usando-se então o nome para o identificar
"customer_address_detail": "Rua dos testes 777A", // [OPCIONAL]
"customer_postcode": "4200-224", // [OPCIONAL]
"customer_city": "Porto", // [OPCIONAL]
"customer_country": "PT", // [OPCIONAL] Por omissão, "PT"; é o código ISO alpha-2 do país do cliente (vd. https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2; vd. também a NOTA 1 abaixo
// Fim do bloco [OPCIONAL] dos atributos de cliente
"settlement_expression": "7.5", // [OPCIONAL] Desconto no cabeçalho, em percentagem; são suportados descontos compostos, como "3+5"
"vat_included_prices": false, // [OPCIONAL] Os preços nas linhas são com IVA incluído? Por omissão, não (false)
"currency_iso_code": "USD", // [OPCIONAL] Por omissão, "EUR". É o código ISO da moeda do documento (vd. https://en.wikipedia.org/wiki/ISO_4217)
"currency_conversion_rate": 1.21, // [OPCIONAL] se a moeda for "EUR". [OBRIGATÓRIO] nos restantes casos; é a taxa de conversão para EUR (1 EUR = n USD|...)
"notes": "Notas ao documento", // [OPCIONAL]
"external_reference": "Referência do documento externo", // [OPCIONAL]
"payment_mechanism": "MO", // [OPCIONAL] Necessário apenas no caso das FR. Por omissão, "MO". Meios de pagamento aceites: "MO": Numerário, "CH": Cheque, "DC": Cartão de débito, "CC": Cartão de crédito, "TR": Transferência bancária, "DDA": Débito direto autorizado, "MB": Referências de pagamento Multibanco.
// [OPCIONAL] Recursos associados ao documento. Caso nenhum seja indicado, este bloco deve ser omitido
"document_series_id": 1, // [OBRIGATÓRIO] Vd. NOTA 2
"tax_exemption_reason_id": 2, // [OBRIGATÓRIO] Apenas se o documento tiver pelo menos uma linha isenta de IVA. Não deve ser indicado nos restantes casos. Ver NOTA 3
"bank_account_id": 3, // [OPCIONAL] Conta bancária da empresa para onde o recebimento é feito. Usado apenas quando o meio de pagamento da FR é "DC", "CC", "TR" ou "DDA", e apenas se for necessário indicar uma conta bancária específica. Ver NOTA 4
//Linhas do documento
lines: [
{
"quantity": 1, // [OBRIGATÓRIO]
"unit_price": 20, // [OPCIONAL] Por omissão é usado o PVP associado ao serviço
"item_type": "Service", // [OBRIGATÓRIO]
"item_code": "STEST", // [OBRIGATÓRIO] Já tem que existir o serviço com este código
"tax_code": "NOR", // [OPCIONAL] Por omissão é usado o tipo de IVA associado ao serviço. Os tipos de IVA suportados são "NOR" (normal), "INT" (intermédio), "RED" (reduzido), "ISE" (isento)
"description": "Descrição da linha", // [OPCIONAL] Por omissão é usada a descrição associada ao serviço
"settlement_expression": "3" // [OPCIONAL] Desconto de linha, em percentagem; são suportados descontos compostos, como "3+5"
"unit_of_measure_id": 0
}
]
}
  • NOTA 1: São também suportados dois "países" adicionais: "PT-AC" (Portugal, Açores) e "PT-MA" (Portugal, Madeira). Os países disponíveis podem ser consultados por um GET /countries, ou um em particular por um
GET /countries?filter[iso_alpha_2]=PT|<o código do país>
  • NOTA 2: A série associada ao documento tem já que existir, e o seu "id" interno deve ser obtido por um
GET /commercial_document_series?filter[document_type]=FT|...&filter[prefix]=2020|<o prefixo da série a usar>...
  • NOTA 3: O "id" interno do motivo de isenção deve ser obtido por um
GET /tax_exemption_reasons?filter[code]=M07|<o código legal do motivo de isenção>...
  • NOTA 4: O "id" interno da conta bancária da empresa deve ser obtido por um
GET /company_bank_accounts?filter[iban]=,
ou
GET /company_bank_accounts?filter[name]=
  • NOTA 5: Para as faturas-recibos (FR), o recibo associado é criado automaticamente quando a FR é finalizada.

Finalização do documento, após todas as linhas terem sido criadas:

O documento e as linhas não podem mais ser alterados depois de finalizados (fechados)
Os detalhes do pedido POST para a criação do cabeçalho estão descritos de seguida, em formato OpenAPI, e em cURL.
patch
/v1/commercial_sales_documents/{id}/finalize
curl -v -X PATCH -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' -d '<payload JSON>' '<API_URL>/v1/commercial_sales_documents/<id do documento>'
Neste, o payload JSON a enviar deverá ser do formato:
{
"return_pdf": true
}
Este argumento único deverá ser sempre fornecido. Se estiver definido como true, o PDF do documento será gerado, e o link para o aceder será retribuido.

Anulação de um documento (Caso seja preciso)

delete
/v1/commercial_sales_documents/{id}
curl -v -X DELETE -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' '<API_URL>/v1/commercial_sales_documents/<id do documento>'

Edição do documento, após criação

O seguinte pedido pode ser realizado, após a criação do documento, e permite alterar informações sobre o documento. A estrutura do payload é a mesma do POST de criação. Neste, deverá enviar no id do pedido o id do documento a alterar. Os atributos enviados no body irão substituir os guardados no momento, e cada linha enviada dentro de lines irá substituir os dados guardados na linha com id especificado em sales_line_id
patch
/v1/commercial_sales_documents/{id}

Adição de linhas

Caso pretenda adicionar novas linhas ao documento, após a sua criação, pode utilizar a seguinte rota, que utiliza o mesmo payload das lines do pedido POST de criação. Neste, o id a enviar no path é o do documento ao qual pretende adicionar a linha
post
/v1/commercial_sales_document_lines/{id}

Remoção de linhas

Do mesmo modo, caso pretenda remover linhas de um documento, pode utilizar a seguinte rota, onde apenas tem de indicar o id da linha a remover, no path.
delete
/v1/commercial_sales_document_lines/{id}

Consultar documento

Por fim, se pretender obter informações sobre um dado documento, pode utilizar a seguinte rota, onde deverá especificar o id do documento a analisar no path.
get
/v1/commercial_sales_documents/{id}