Documentação API
Search…
⌃K

Faturas

As rotas definidas no presente capítulo permitem gerir toda a informação relativa a faturas. Desde criação a edição e remoção. No final da documentação é detalhado o envio por e-mail e download em PDF

Geração de faturas

Cada documento é constituído por:
  1. 1.
    Um cabeçalho
  2. 2.
    Uma ou mais linhas
Após a criação, o documento fica no estado "em preparação", podendo, nesse estado, continuar a ser alterado. Para terminar definitivamente as alterações ao documento, assiná-lo e permitir a sua impressão, há depois que:
3. Finalizá-lo.
Um documento finalizado já não pode ser alterado nem apagado, apenas anulado

1 - criação do cabecalho

Os detalhes do pedido POST para a criação do cabeçalho estão descritos de seguida, em formato OpenAPI, e em cURL.
post
/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>/commercial_sales_documents'
No pedido acima, o <access_token> corresponde ao token de acesso válido devolvido pelo serviço de OAuth, e o <payload JSON> deverá ter o seguinte formato
{
"data": {
"type": "commercial_sales_documents", // [OBRIGATÓRIO]
"attributes": {
"document_type": "FT", // [OBRIGATÓRIO] Tipo de documento. "FT" para fatura, "FS" para fatura simplificada, "FR" para fatura-recibo
"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.
// [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
"operation_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
"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] Preenche campo Vossa Ref
"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.
},
"relationships": { // [OPCIONAL] Recursos associados ao documento. Caso nenhum seja indicado, este bloco "relationships" deve ser omitido
"commercial_document_series": { // [OPCIONAL] Série de documentos associada. Não precisa de ser indicada; por omissão o documento é criado na série por omissão associada ao tipo de documento. Vd. NOTA 2
"data": {
"type": "commercial_document_series", // [OBRIGATÓRIO]
"id": "<id da série de documentos associada>" // [OBRIGATÓRIO] Vd. NOTA 2
}
},
"tax_exemption_reasons": { // [OBRIGATÓRIO] Apenas se o documento tiver pelo menos uma linha isenta de IVA. Não deve ser indicado nos restantes casos.
"data": {
"type": "tax_exemption_reasons", // [OBRIGATÓRIO]
"id": "<id do motivo de isenção de IVA>" // [OBRIGATÓRIO] Vd. NOTA 3
}
},
"bank_accounts": { // [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.
"data": {
"type": "bank_accounts", // [OBRIGATÓRIO]
"id": "<id da conta bancária>" // [OBRIGATÓRIO] Vd. NOTA 4
}
}
}
}
}
  • 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.

2 - Criação da(s) linha(s) do documento

As linhas podem referenciar três tipos de itens: produtos, serviços ou descritores (Juros, Imobilizado, Impostos Especiais...). Para cada um destes deverá ser enviado um payload diferente, descritos de seguida. Podem ainda ser criadas linhas apenas de descrição, sem valor associado
Os detalhes do pedido POST para a criação do cabeçalho estão descritos de seguida, em formato OpenAPI, e em cURL.
post
/commercial_sales_document_lines
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>/commercial_sales_document_lines'
Neste pedido, o payload JSON deverá vir no seguinte formato:
Produto
{
"data": {
"type": "commercial_sales_document_lines", // [OBRIGATÓRIO]
"attributes": {
"quantity": 1, // [OBRIGATÓRIO]
"unit_price": 20, // [OPCIONAL] Por omissão é usado o PVP associado do produto
"item_type": "Product", // [OBRIGATÓRIO]
"item_code": "PTEST", // [OBRIGATÓRIO] Vd. Nota 2 - Já tem que existir o produto com este código
"tax_code": "NOR", // [OPCIONAL] Por omissão é usado o tipo de IVA associado ao produto. 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 produto
"settlement_expression": "3" // [OPCIONAL] Desconto de linha, em percentagem; são suportados descontos compostos, como "3+5"
},
"relationships": { // [OBRIGATÓRIO]
"document": { // [OBRIGATÓRIO] Documento a que esta linha pertence
"data": {
"type": "commercial_sales_documents", // [OBRIGATÓRIO]
"id": "<id do documento>" // [OBRIGATÓRIO] Este "id" é o devolvido na resposta ao pedido de criação do cabeçalho, ver acima
}
},
"unit_of_measure": { // [OPCIONAL] Unidade de medida em que se expressa a quantidade. Por omissão, "un".
"data": {
"type": "units_of_measure", // [OBRIGATÓRIO]
"id": "<id da unidade de medida>" // [OBRIGATÓRIO] Vd. NOTA 1
}
}
}
}
}
Serviço
{
"data": {
"type": "commercial_sales_document_lines", // [OBRIGATÓRIO]
"attributes": {
"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] Vd. Nota 2 - 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"
},
"relationships": { // [OBRIGATÓRIO]
"document": { // [OBRIGATÓRIO] Documento a que esta linha pertence
"data": {
"type": "commercial_sales_documents", // [OBRIGATÓRIO]
"id": "<id do documento>" // [OBRIGATÓRIO] Este "id" é o devolvido na resposta ao pedido de criação do cabeçalho, ver acima
}
},
"unit_of_measure": { // [OPCIONAL] Unidade de medida em que se expressa a quantidade. Por omissão, "un".
"data": {
"type": "units_of_measure", // [OBRIGATÓRIO]
"id": "<id da unidade de medida>" // [OBRIGATÓRIO] Vd. NOTA 1
}
}
}
}
}
  • NOTA 1: O "id" interno da unidade de medida deve ser obtido por um GET /units_of_measure?filter[unit_of_measure]=<a designação da unidade>
  • NOTA 2: A informação do item, seja um serviço, seja um produto, poderá ser obtida por um GET a /services
Descrição
{
"data": {
"type": "commercial_sales_document_lines", // [OBRIGATÓRIO]
"attributes": {
"description": "Descrição da linha", // [OBRIGATÓRIO]
},
"relationships": { // [OBRIGATÓRIO]
"document": { // [OBRIGATÓRIO] Documento a que esta linha pertence
"data": {
"type": "commercial_sales_documents", // [OBRIGATÓRIO]
"id": "<id do documento>" // [OBRIGATÓRIO] Este "id" é o devolvido na resposta ao pedido de criação do cabeçalho, ver acima
}
}
}
}
}

3 - 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
/commercial_sales_documents
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>/commercial_sales_documents/<id do documento>'
Neste, o payload JSON a enviar deverá ser do formato:
{
"data": {
"type": "commercial_sales_documents", // [OBRIGATÓRIO]
"id": "<id do documento>", // [OBRIGATÓRIO] Este "id" é o devolvido na resposta ao pedido de criação do cabeçalho, ver acima
"attributes": {
"status": 1 // [OBRIGATÓRIO]
}
}
}

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

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>/commercial_sales_documents/<id do documento>'
Neste, o payload JSON deverá ser do seguinte formato
{
"data": {
"type": "commercial_sales_documents", // [OBRIGATÓRIO]
"id": "<id do documento>", // [OBRIGATÓRIO] Vd. NOTA 1
"attributes": {
"status": 4, // [OBRIGATÓRIO]
"voided_reason": "Texto livre com o motivo pelo qual se está a anular o documento" // [OBRIGATÓRIO]
}
}
}