Documentos de venda

As rotas aqui descritas permitem gerir todos os processos relativos a documentos de venda: orçamentos, faturas-proforma, guias, faturas e notas.

Criação do documento

Cada documento é constituído por:

1. Um cabeçalho

2. Uma ou mais linhas

Após a sua 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. Finalizar o documento

Um documento finalizado já não pode ser alterado nem eliminado, apenas anulado.

1. Criação do cabeçalho

post

Body

application/json

Responses

200

OK

application/json

post

/commercial_sales_documents

HTTPcURLJavaScriptPython

POST /commercial_sales_documents HTTP/1.1
Host: /
Content-Type: application/json
Accept: */*
Content-Length: 1179

{
  "data": {
    "type": "commercial_sales_documents",
    "attributes": {
      "document_type": "FT|FS|FR",
      "date": "2023-01-01",
      "document_series_prefix": "Prefixo da série",
      "customer_tax_registration_number": "999999990",
      "customer_business_name": "Nome do cliente",
      "customer_address_detail": "Morada do cliente",
      "customer_postcode": "0000-000",
      "customer_city": "Cidade/Localidade do cliente",
      "customer_country": "PT",
      "due_date": "2023-01-01",
      "settlement_expression": "7.5",
      "payment_mechanism": "MO|CH|DC|CC|TR|CO|CS|DE|LC|MB|OU|RT|DDA",
      "vat_included_prices": false,
      "operation_country": "PT-MA",
      "currency_iso_code": "USD",
      "currency_conversion_rate": 1.21,
      "retention": 7.5,
      "retention_type": "IRS|IRC",
      "apply_retention_when_paid": true,
      "notes": "Notas ao documento",
      "external_reference": "Referência do documento externo"
    },
    "relationships": {
      "commercial_document_series": {
        "data": {
          "type": "commercial_document_series",
          "id": "1"
        }
      },
      "customer": {
        "data": {
          "type": "customers",
          "id": "1"
        }
      },
      "bank_accounts": {
        "data": {
          "type": "bank_accounts",
          "id": "1"
        }
      },
      "cash_accounts": {
        "data": {
          "type": "cash_accounts",
          "id": "1"
        }
      },
      "tax_exemption_reasons": {
        "data": {
          "type": "tax_exemption_reasons",
          "id": "1"
        }
      },
      "currency": {
        "data": {
          "type": "currencies",
          "id": "1"
        }
      }
    }
  }
}

200

OK

{
  "data": {
    "type": "commercial_sales_documents",
    "id": "1",
    "attributes": {
      "status": 1,
      "document_type": "FT|FS|FR",
      "document_no": "FT 2023/1",
      "date": "2023-01-01",
      "document_series_prefix": "Prefixo da série",
      "customer_tax_registration_number": "999999990",
      "customer_business_name": "Nome do cliente",
      "customer_address_detail": "Morada do cliente",
      "customer_postcode": "0000-000",
      "customer_city": "Cidade/Localidade do cliente",
      "customer_country": "PT",
      "due_date": "2023-01-01",
      "settlement_expression": "7.5",
      "payment_mechanism": "MO|CH|DC|CC|TR|CO|CS|DE|LC|MB|OU|RT|DDA",
      "vat_included_prices": false,
      "operation_country": "PT-MA",
      "currency_iso_code": "USD",
      "currency_conversion_rate": 1.21,
      "retention": 7.5,
      "retention_type": "IRS|IRC",
      "apply_retention_when_paid": true,
      "notes": "Notas ao documento",
      "external_reference": "Referência do documento externo"
    },
    "relationships": {
      "commercial_document_series": {
        "data": {
          "type": "commercial_document_series",
          "id": "1"
        }
      },
      "customer": {
        "data": {
          "type": "customers",
          "id": "1"
        }
      },
      "bank_accounts": {
        "data": {
          "type": "bank_accounts",
          "id": "1"
        }
      },
      "cash_accounts": {
        "data": {
          "type": "cash_accounts",
          "id": "1"
        }
      },
      "tax_exemption_reasons": {
        "data": {
          "type": "tax_exemption_reasons",
          "id": "1"
        }
      },
      "currency": {
        "data": {
          "type": "currencies",
          "id": "1"
        }
      }
    }
  }
}

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 é o token de acesso válido devolvido pelo serviço de OAuth. O payload JSON a enviar contém a seguinte informação:

{
  "data": {
    "type": "commercial_sales_documents",                             // [OBRIGATÓRIO]
    "attributes": {                                                   // [OBRIGATÓRIO] Os atributos do documento
      // Identificação do documento
      "document_type": "FT|FS|FR",                                    // [OBRIGATÓRIO] Tipo de documento. "FT": fatura, "FS": fatura simplificada, "FR": fatura-recibo.
      "date": "2023-01-01",                                           // [OPCIONAL] Data do documento; por omissão, a data do pedido.

      // [OPCIONAL] Identificação da série do documento. Por omissão, aplicam-se as regras configuradas na empresa para escolha da série.
      // Se a série for indicada, usar apenas ou o campo seguinte (o prefixo) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes.
      "document_series_prefix": "Prefixo da série",                   // [OPCIONAL] Em alternativa ao campo "document_series_id".

      // [OPCIONAL] Identificação do cliente. Por omissão, é o consumidor final (NIF "999999990").
      // Se o cliente for indicado, usar apenas ou o campo seguinte (o NIF) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes.
      "customer_tax_registration_number": "999999990",                // [OPCIONAL] NIF do cliente. se o cliente com o NIF indicado não existir, será criado automaticamente. Se o país ("customer_country") for Portugal ("PT", "PT-AC" ou "PT-MA"), 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": "Nome do cliente",                    // [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": "Morada do cliente",                 // [OPCIONAL]
      "customer_postcode": "0000-000",                                // [OPCIONAL] Código postal do cliente, no formato 0000-000.
      "customer_city": "Cidade/Localidade do cliente",                // [OPCIONAL]
      "customer_country": "PT",                                       // [OPCIONAL] País do cliente. 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; ver também a NOTA 3.

      // [OPCIONAL] Condições de pagamento
      "due_date": "2023-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.
      "settlement_expression": "7.5",                                 // [OPCIONAL] Desconto no cabeçalho, em percentagem; são suportados descontos compostos, como "3+5"
      "payment_mechanism": "MO|CH|DC|CC|TR|CO|CS|DE|LC|MB|OU|RT|DDA", // [OPCIONAL] Necessário apenas no caso das FR. Por omissão, "MO", ou o configurado no cliente, se o cliente tiver configurado um modo de pagamento. Modos 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": Multibanco, "CO": Cartão oferta, "CS": Compensação de saldos, "DE": Dinheiro eletrónico, "LC": Letra comercial, "OU": Outros, "RT": Ticket restaurante.

      // [OPCIONAL] IVA
      "vat_included_prices": false,                                   // [OPCIONAL] Os preços nas linhas são com IVA incluído? Por omissão, não (false).
      "operation_country": "PT-MA",                                   // [OPCIONAL] A região de operação para efeitos de IVA: usada apenas para as linhas de serviços. Por omissão, é a região onde a empresa está localizada. Para o regime OSS pode ainda usar-se o código ISO alpha-2 do país OSS (vd. https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2; ver também a NOTA 3.

      // [OPCIONAL] Moeda. Por omissão, "EUR".
      // Se a moeda for indicada, usar apenas ou o campos seguinte (o código ISO) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes.
      "currency_iso_code": "USD",                                     // [OPCIONAL] É o código ISO da moeda do documento (vd. https://en.wikipedia.org/wiki/ISO_4217).
      "currency_conversion_rate": 1.21,                               // [OMITIDO] se a moeda for "EUR". [OBRIGATÓRIO] nos restantes casos; é a taxa de conversão para EUR (1 EUR = n USD|...).

      // [OPCIONAL] Retenção
      "retention": 7.5,                                               // [OPCIONAL] Percentagem de retenção a aplicar sobre os serviços.
      "retention_type": "IRS|IRC",                                    // [OPCIONAL] Tipo de retenção ("IRS" ou "IRC"). Por omissão, "IRS".
      "apply_retention_when_paid": true,                              // [OPCIONAL] A retenção é feita logo no documento (false) ou apenas no recebimento (true). Por omissão, false.

      // [OPCIONAL] Outras informações
      "notes": "Notas ao documento",                                  // [OPCIONAL]
      "external_reference": "Referência do documento externo"         // [OPCIONAL]
    },
    "relationships": {                                                // [OPCIONAL] Recursos associados ao documento. Caso nenhum seja indicado, este bloco "relationships" deve ser omitido
      // [OPCIONAL] Identificação da série do documento. Por omissão, aplicam-se as regras configuradas na empresa para escolha da série.
      // Se a série for indicada, usar apenas ou o "id" nesta "relationship" ou campo "document_series_prefix" (o prefixo; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
      "commercial_document_series": {
        "data": {
          "type": "commercial_document_series",                       // [OBRIGATÓRIO]
          "id": "1"                                                   // [OBRIGATÓRIO] Identificador interno da série. Ver NOTA 1 abaixo.
        }
      },
      // [OPCIONAL] Identificação do cliente. Por omissão, é o consumidor final (NIF "999999990").
      // Se o cliente for indicado, usar apenas ou o "id" nesta "relationship" ou o campo "tax_registration_number" (o NIF; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
      "customer": {
        "data": {
          "type": "customers",                                        // [OBRIGATÓRIO]
          "id": "1"                                                   // [OBRIGATÓRIO] Identificador interno do cliente. Ver NOTA 2.
        }
      },
      // [OPCIONAL] Necessário apenas no caso das FR. 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.
      "bank_accounts": {
        "data": {
          "type": "bank_accounts",                                    // [OBRIGATÓRIO]
          "id": "1"                                                   // [OBRIGATÓRIO] Identificador interno da conta bancária da empresa. Ver NOTA 4.
        }
      },
      // [OPCIONAL] Necessário apenas no caso das FR. Conta de caixa da empresa para onde o recebimento é feito. Usado apenas quando o meio de pagamento da FR é "MO".
      "cash_accounts": {
        "data": {
          "type": "cash_accounts",                                    // [OBRIGATÓRIO]
          "id": "1"                                                   // [OBRIGATÓRIO] Identificador interno da conta de caixa da empresa. Ver NOTA 5.
        }
      },
      // Motivo de isenção de IVA. [OBRIGATÓRIO] apenas se o documento tiver pelo menos uma linha isenta de IVA. Não deve ser indicado nos restantes casos.
      "tax_exemption_reasons": {
        "data": {
          "type": "tax_exemption_reasons",                            // [OBRIGATÓRIO]
          "id": "1"                                                   // [OBRIGATÓRIO] Identificador interno do motivo de isenção do IVA. Ver NOTA 6.
        }
      },
      // [OPCIONAL] Moeda. Por omissão, "EUR".
      // Se a moeda for indicada, usar apenas ou o "id" nesta "relationship" ou o campo "currency_iso_code" (o código ISO; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
      "currency": {
        "data": {
          "type": "currencies",                                       // [OBRIGATÓRIO]
          "id": "1"                                                   // [OBRIGATÓRIO] Identificador interno da moeda. Ver NOTA 7.
        }
      }
    }
  }
}

• NOTA 1: A série associada ao documento tem já que existir, e o seu "id" interno pode ser obtido por um

GET /commercial_document_series?filter[document_type]=FT|<o tipo de documento>&filter[prefix]=2020|<o prefixo da série a usar> 

• NOTA 2: Se o cliente for identificado pelo seu "id" interno tem já que existir, e o seu "id" interno pode ser obtido por um

GET /customers?filter[tax_registration_number]=<o NIF do cliente>

• NOTA 3: 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 4: O "id" interno da conta bancária da empresa deve ser obtido por um

GET /company_bank_accounts?filter[iban]=<IBAN da conta> 
ou 
GET /company_bank_accounts?filter[name]=<nome da conta> 

• NOTA 5: O "id" interno da conta de caixa da empresa deve ser obtido por um

GET /cash_accounts?filter[name]=<nome da conta>

• NOTA 6: 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 7: O "id" interno da moeda deve ser obtido por um

GET /currencies?filter[iso_code]=USD|<o código ISO da moeda>

2. Criação da(s) linha(s)

As linhas podem referenciar três tipos de itens: produtos, serviços ou descritores (juros, imobilizado, impostos especiais...). Para cada um destes o payload é ligeiramente diferente, e cada um será descrito de seguida. Podem ainda ser criadas linhas apenas de descrição, com ou sem valor associado.

post

Body

application/json

Responses

200

OK

application/json

post

/commercial_sales_document_lines

HTTPcURLJavaScriptPython

POST /commercial_sales_document_lines HTTP/1.1
Host: /
Content-Type: application/json
Accept: */*
Content-Length: 722

{
  "data": {
    "type": "commercial_sales_document_lines",
    "attributes": {
      "item_type": "Service|Product|TaxDescriptor",
      "item_code": "Código do serviço/produto/descritor",
      "description": "Descrição da linha",
      "unit_of_measure": "Unidade de medida",
      "quantity": 1,
      "unit_price": 9.99,
      "settlement_expression": "3",
      "tax_code": "NOR|INT|RED|ISE",
      "tax_percentage": 22,
      "tax_country_region": "PT-MA"
    },
    "relationships": {
      "document": {
        "data": {
          "type": "commercial_sales_documents",
          "id": "1"
        }
      },
      "product": {
        "data": {
          "type": "products",
          "id": "1"
        }
      },
      "service": {
        "data": {
          "type": "services",
          "id": "1"
        }
      },
      "tax_descriptor": {
        "data": {
          "type": "tax_descriptors",
          "id": "1"
        }
      },
      "unit_of_measure": {
        "data": {
          "type": "units_of_measure",
          "id": "1"
        }
      },
      "tax": {
        "data": {
          "type": "taxes",
          "id": "1"
        }
      }
    }
  }
}

200

OK

{
  "data": {
    "type": "commercial_sales_document_lines",
    "id": "1",
    "attributes": {
      "item_type": "Service|Product|TaxDescriptor",
      "item_code": "Código do serviço/produto/descritor",
      "description": "Descrição da linha",
      "unit_of_measure": "Unidade de medida",
      "quantity": 1,
      "unit_price": 9.99,
      "settlement_expression": "3",
      "tax_code": "NOR|INT|RED|ISE",
      "tax_percentage": 22,
      "tax_country_region": "PT-MA"
    },
    "relationships": {
      "document": {
        "data": {
          "type": "commercial_sales_documents",
          "id": "1"
        }
      },
      "product": {
        "data": {
          "type": "products",
          "id": "1"
        }
      },
      "service": {
        "data": {
          "type": "services",
          "id": "1"
        }
      },
      "tax_descriptor": {
        "data": {
          "type": "tax_descriptors",
          "id": "1"
        }
      },
      "unit_of_measure": {
        "data": {
          "type": "units_of_measure",
          "id": "1"
        }
      },
      "tax": {
        "data": {
          "type": "taxes",
          "id": "1"
        }
      }
    }
  }
}

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'

No pedido acima, o access_token é o token de acesso válido devolvido pelo serviço de OAuth. O payload JSON genérico a enviar contém a seguinte informação:

{
  "data": {
    "type": "commercial_sales_document_lines",                // [OBRIGATÓRIO]
    "attributes": {                                           // [OBRIGATÓRIO] Os atributos da linha do documento
      // [OPCIONAL] Identificação do item. Se nada for indicado, assume-se uma linha apenas de descrição.
      "item_type": "Service|Product|TaxDescriptor",           // [OPCIONAL] Tipo de item: "Service": serviço, "Product": produto, "TaxDescriptor": descritor. Por omissão, assume-se uma linha apenas de descrição.
      // Se o item for indicado, usar apenas ou o campo seguinte (o código) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes entre si, e consistentes com o "item_type".
      "item_code": "Código do serviço/produto/descritor",     // [OPCIONAL] Já tem que existir o produto/serviço/descritor com este código. Por omissão, é usado o item identificado pela "relationship" respectiva, se indicada. Se nada for indicado, assume-se uma linha apenas de descrição.
      "description": "Descrição da linha",                    // [OPCIONAL] Por omissão é usada a descrição associada ao item, se este for indicado. [OBRIGATÓRIO] Para uma linha apenas de descrição.

      // [OPCIONAL] Unidade de medida. Por omissão é a configurada no item (se for serviço ou produto), ou a por omissão na empresa.
      // Se a unidade de medida for indicada, usar apenas ou o campo seguinte (o código) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes entre si.
      "unit_of_measure": "Unidade de medida",                 // [OPCIONAL] Por omissão é a configurada no item, ou a por omissão na empresa.
      // Quantidades e valores. [OBRIGATÓRIO] Para linhas de descrição com valor.
      "quantity": 1,                                          // [OPCIONAL] Por omissão 1, se não for uma linha de descrição com valor. [OBRIGATÒRIO] Para uma linha de descrição com valor.
      "unit_price": 9.99,                                     // [OPCIONAL] Se for indicado um serviço ou produto. Por omissão é usado o PVP associado ao item (serviço ou produto). [OBRIGATÓRIO] Para uma linha de descritor ou de descrição com valor.
      "settlement_expression": "3",                           // [OPCIONAL] Desconto de linha, em percentagem; são suportados descontos compostos, como "3+5".

      // [OPCIONAL] IVA. Por omissão é aplicado o IVA associado ao item, ou à taxa normal, na região onde a empresa está localizada, ou — apenas para as linhas de serviços — a região de operação para efeitos de IVA, se indicada.
      // Se a taxa de IVA for indicada, usar apenas um ou mais dos três campos seguintes ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem todos os campos, então devem ser consistentes entre si.
      // [NÃO PODE SER USADO] no caso de uma linha de descrição sem valor, ou de um descritor que são suporte IVA: ou seja, um descritor referente a uma retenção (taxa SIRCA, outras retenções...)
      "tax_code": "NOR|INT|RED|ISE",                          // [OPCIONAL] Por omissão é usado o tipo de IVA associado ao item, ou "NOR" se nenhum associado. Os tipos de IVA suportados são "NOR" (normal), "INT" (intermédio), "RED" (reduzido), "ISE" (isento).
      "tax_percentage": 22,                                   // [OPCIONAL] Percentagem de IVA a usar: serve para indicar uma taxa de outra região (se o campo "tax_country_region" não for indicado) ou uma taxa antiga, já não em vigor.
      "tax_country_region": "PT-MA"                           // [OPCIONAL] Região do IVA. Por omissão (e se o campo "tax_percentage" não for indicado) aplica-se a taxa de IVA da região onde a empresa está localizada, ou — apenas para as linhas de serviços — a região de operação para efeitos de IVA, se indicada. Para o regime OSS pode ainda usar-se o código ISO alpha-2 do país OSS (vd. https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2; ver também a NOTA 3.
    },
    "relationships": {                                        // [OBRIGATÓRIO] Recursos associados à linha do documento.
      // [OBRIGATÓRIO] Identificação do documento (cabeçalho) a que esta linha pertence.
      "document": {
        "data": {
          "type": "commercial_sales_documents",               // [OBRIGATÓRIO]
          "id": "1"                                           // [OBRIGATÓRIO] Identificador interno do documento (cabeçalho). Ver NOTA 1.
        }
      },
      // [OPCIONAL] Produto associado à linha. Só deve ser indicado para as linhas de produtos.
      // Se o produto for indicado, usar apenas ou o "id" nesta "relationship" ou o campo "item_code" (o código do produto; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
      "product": {
        "data": {
          "type": "products",                                 // [OBRIGATÓRIO]
          "id": "1"                                           // [OBRIGATÓRIO] Identificador interno do produto. Ver NOTA 2.
        }
      },
      // [OPCIONAL] Serviço associado à linha. Só deve ser indicado para as linhas de serviços.
      // Se o serviço for indicado, usar apenas ou o "id" nesta "relationship" ou o campo "item_code" (o código do serviço; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
      "service": {
        "data": {
          "type": "services",                                 // [OBRIGATÓRIO]
          "id": "1"                                           // [OBRIGATÓRIO] Identificador interno do serviço. Ver NOTA 2.
        }
      },
      // [OPCIONAL] Descritor associado à linha. Só deve ser indicado para as linhas de descritores.
      // Se o descritor for indicado, usar apenas ou o "id" nesta "relationship" ou o campo "item_code" (o código do descritor; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
      "tax_descriptor": {
        "data": {
          "type": "tax_descriptors",                          // [OBRIGATÓRIO]
          "id": "1"                                           // [OBRIGATÓRIO] Identificador interno do descritor. Ver NOTA 2.
        }
      },
      // [OPCIONAL] Unidade de medida. Por omissão é a configurada no item (se for serviço ou produto), ou a por omissão na empresa.
      // Se a unidade de medida for indicada, usar apenas ou o "id" nesta "relationship" ou o campo "unit_of_measure" (o código da unidade; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
      "unit_of_measure": {
        "data": {
          "type": "units_of_measure",                         // [OBRIGATÓRIO]
          "id": "1"                                           // [OBRIGATÓRIO] Identificador interno da unidade de medida. Ver NOTA 4.
        }
      },
      // [OPCIONAL] IVA. Por omissão é aplicado o IVA associado ao item, ou à taxa normal na região onde a empresa está localizada, ou — apenas para as linhas de serviços — a região de operação para efeitos de IVA, se indicada.
      // Se a taxa de IVA for indicada, usar apenas ou o "id" nesta "relationship" ou um ou mais dos três campos "tax_code", "tax_percentage" e "tax_country_region" (o tipo, a percentagem e/ou a região do IVA; ver mais acima). Se se indicarem todos os campos, então devem ser consistentes.
      // [NÃO PODE SER USADO] no caso de uma linha de descrição sem valor, ou de um descritor que são suporte IVA: ou seja, um descritor referente a uma retenção (taxa SIRCA, outras retenções...)
      "tax": {
        "data": {
          "type": "taxes",                                    // [OBRIGATÓRIO]
          "id": "1"                                           // [OBRIGATÓRIO] Identificador interno da taxa de IVA. Ver NOTA 5.
        }
      }
    }
  }
}

• NOTA 1: O "id" interno do documento (cabeçalho) a que a linha pertence é o devolvido no campo "id" da resposta ao pedido de criação do cabeçalho (ver ponto 1. Criação do cabeçalho).

• NOTA 2: O item (serviço, produto ou descritor) tem já que existir, e o seu "id" interno pode ser obtido por um

GET /services?filter[item_code]=<o código do serviço>
ou
GET /products?filter[item_code]=<o código do produto> 
ou
GET /tax_descriptors?filter[notation]=<o código do descritor>

• NOTA 3: Além de "PT" (Portugal, Continente) são também suportadas as duas regiões de IVA "PT-AC" (Portugal, Açores) e "PT-MA" (Portugal, Madeira).

• Para os regimes de IVA no âmbito do OSS, os códigos de região são os mesmos que os códigos do país, podendo ser consultadas por um

GET /countries?filter[iso_alpha_2]=<o código do país OSS>

• NOTA 4: A unidade de medida tem já que existir, e o seu "id" interno pode ser obtido por um

GET /units_of_measure?filter[unit_of_measure]=un|<o código da unidade de medida>

• NOTA 5: O "id" interno da taxa de IVA deve ser obtido por um

GET /taxes?filter[tax_code]=NOR|<o tipo de IVA>&filter[tax_country_region]=PT|<a região do IVA>
ou
GET /taxes?filter[tax_code]=NOR|<o tipo de IVA>&filter[tax_country_region]=PT|<a região do IVA>&filter[tax_percentage]=22|<a percentagem IVA>

2.1. Criação de uma linha de produto

Para o caso particular de uma linha de produto, o payload contém a seguinte informação:

{
  "data": {
    "type": "commercial_sales_document_lines",                // [OBRIGATÓRIO]
    "attributes": {                                           // [OBRIGATÓRIO] Os atributos da linha do documento
      // [OBRIGATÓRIO] Identificação do produto.
      "item_type": "Product",                                 // [OBRIGATÓRIO] Tipo de item: "Product": produto.
      // Usar apenas ou o campo seguinte (o código) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes entre si.
      "item_code": "Código do produto",                       // [OPCIONAL] Já tem que existir o produto com este código. Por omissão, é usado o produto identificado pela "relationship" respectiva, se indicada.
      "description": "Descrição da linha",                    // [OPCIONAL] Por omissão é usada a descrição associada ao produto.

      // [OPCIONAL] Unidade de medida. Por omissão é a configurada no produto, ou a por omissão na empresa.
      // Se a unidade de medida for indicada, usar apenas ou o campo seguinte (o código) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes entre si.
      "unit_of_measure": "Unidade de medida",                 // [OPCIONAL] Por omissão é a configurada no produto, ou a por omissão na empresa.
      // [OPCIONAL] Quantidades e valores.
      "quantity": 1,                                          // [OPCIONAL] Por omissão 1.
      "unit_price": 9.99,                                     // [OPCIONAL] Por omissão é usado o PVP associado ao produto.
      "settlement_expression": "3",                           // [OPCIONAL] Desconto de linha, em percentagem; são suportados descontos compostos, como "3+5".

      // [OPCIONAL] IVA. Por omissão é aplicado o IVA associado ao produto, ou à taxa normal, na região onde a empresa está localizada.
      // Se a taxa de IVA for indicada, usar apenas um ou mais dos três campos seguintes ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem todos os campos, então devem ser consistentes entre si.
      "tax_code": "NOR|INT|RED|ISE",                          // [OPCIONAL] Por omissão é usado o tipo de IVA associado ao item, ou "NOR" se nenhum associado. Os tipos de IVA suportados são "NOR" (normal), "INT" (intermédio), "RED" (reduzido), "ISE" (isento).
      "tax_percentage": 22,                                   // [OPCIONAL] Percentagem de IVA a usar: serve para indicar uma taxa de outra região (se o campo "tax_country_region" não for indicado) ou uma taxa antiga, já não em vigor.
      "tax_country_region": "PT-MA"                           // [OPCIONAL] Região do IVA. Por omissão (e se o campo "tax_percentage" não for indicado) aplica-se a taxa de IVA da região onde a empresa está localizada. Para o regime OSS pode ainda usar-se o código ISO alpha-2 do país OSS (vd. https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2; ver também a NOTA 3.
    },
    "relationships": {                                        // [OBRIGATÓRIO] Recursos associados à linha do documento.
      // [OBRIGATÓRIO] Identificação do documento (cabeçalho) a que esta linha pertence.
      "document": {
        "data": {
          "type": "commercial_sales_documents",               // [OBRIGATÓRIO]
          "id": "1"                                           // [OBRIGATÓRIO] Identificador interno do documento (cabeçalho). Ver NOTA 1.
        }
      },
      // [OPCIONAL] Produto associado à linha.
      // Usar apenas ou o "id" nesta "relationship" ou o campo "item_code" (o código do produto; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
      "product": {
        "data": {
          "type": "products",                                 // [OBRIGATÓRIO]
          "id": "1"                                           // [OBRIGATÓRIO] Identificador interno do produto. Ver NOTA 2.
        }
      },
      // [OPCIONAL] Unidade de medida. Por omissão é a configurada no produto, ou a por omissão na empresa.
      // Se a unidade de medida for indicada, usar apenas ou o "id" nesta "relationship" ou o campo "unit_of_measure" (o código da unidade; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
      "unit_of_measure": {
        "data": {
          "type": "units_of_measure",                         // [OBRIGATÓRIO]
          "id": "1"                                           // [OBRIGATÓRIO] Identificador interno da unidade de medida. Ver NOTA 4.
        }
      },
      // [OPCIONAL] IVA. Por omissão é aplicado o IVA associado ao produto, ou à taxa normal na região onde a empresa está localizada.
      // Se a taxa de IVA for indicada, usar apenas ou o "id" nesta "relationship" ou um ou mais dos três campos "tax_code", "tax_percentage" e "tax_country_region" (o tipo, a percentagem e/ou a região do IVA; ver mais acima). Se se indicarem todos os campos, então devem ser consistentes.
      "tax": {
        "data": {
          "type": "taxes",                                    // [OBRIGATÓRIO]
          "id": "1"                                           // [OBRIGATÓRIO] Identificador interno da taxa de IVA. Ver NOTA 5.
        }
      }
    }
  }
}

2.2. Criação de uma linha de serviço

Para o caso particular de uma linha de serviço, este payload contém a seguinte informação:

{
  "data": {
    "type": "commercial_sales_document_lines",                // [OBRIGATÓRIO]
    "attributes": {                                           // [OBRIGATÓRIO] Os atributos da linha do documento
      // [OBRIGATÓRIO] Identificação do serviço.
      "item_type": "Service",                                 // [OBRIGATÓRIO] Tipo de item: "Service": serviço.
      // Usar apenas ou o campo seguinte (o código) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes entre si.
      "item_code": "Código do serviço",                       // [OPCIONAL] Já tem que existir o serviço com este código. Por omissão, é usado o serviço identificado pela "relationship" respectiva, se indicada.
      "description": "Descrição da linha",                    // [OPCIONAL] Por omissão é usada a descrição associada ao serviço.

      // [OPCIONAL] Unidade de medida. Por omissão é a configurada no serviço, ou a por omissão na empresa.
      // Se a unidade de medida for indicada, usar apenas ou o campo seguinte (o código) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes entre si.
      "unit_of_measure": "Unidade de medida",                 // [OPCIONAL] Por omissão é a configurada no serviço, ou a por omissão na empresa.
      // [OPCIONAL] Quantidades e valores.
      "quantity": 1,                                          // [OPCIONAL] Por omissão 1.
      "unit_price": 9.99,                                     // [OPCIONAL] Por omissão é usado o PVP associado ao serviço.
      "settlement_expression": "3",                           // [OPCIONAL] Desconto de linha, em percentagem; são suportados descontos compostos, como "3+5".

      // [OPCIONAL] IVA. Por omissão é aplicado o IVA associado ao serviço, ou à taxa normal, na região onde a empresa está localizada, ou a região de operação para efeitos de IVA, se indicada.
      // Se a taxa de IVA for indicada, usar apenas um ou mais dos três campos seguintes ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem todos os campos, então devem ser consistentes entre si.
      "tax_code": "NOR|INT|RED|ISE",                          // [OPCIONAL] Por omissão é usado o tipo de IVA associado ao item, ou "NOR" se nenhum associado. Os tipos de IVA suportados são "NOR" (normal), "INT" (intermédio), "RED" (reduzido), "ISE" (isento).
      "tax_percentage": 22,                                   // [OPCIONAL] Percentagem de IVA a usar: serve para indicar uma taxa de outra região (se o campo "tax_country_region" não for indicado) ou uma taxa antiga, já não em vigor.
      "tax_country_region": "PT-MA"                           // [OPCIONAL] Região do IVA. Por omissão (e se o campo "tax_percentage" não for indicado) aplica-se a taxa de IVA da região onde a empresa está localizada, ou a região de operação para efeitos de IVA, se indicada. Para o regime OSS pode ainda usar-se o código ISO alpha-2 do país OSS (vd. https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2; ver também a NOTA 3.
    },
    "relationships": {                                        // [OBRIGATÓRIO] Recursos associados à linha do documento.
      // [OBRIGATÓRIO] Identificação do documento (cabeçalho) a que esta linha pertence.
      "document": {
        "data": {
          "type": "commercial_sales_documents",               // [OBRIGATÓRIO]
          "id": "1"                                           // [OBRIGATÓRIO] Identificador interno do documento (cabeçalho). Ver NOTA 1.
        }
      },
      // [OPCIONAL] Serviço associado à linha.
      // Usar apenas ou o "id" nesta "relationship" ou o campo "item_code" (o código do serviço; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
      "service": {
        "data": {
          "type": "services",                                 // [OBRIGATÓRIO]
          "id": "1"                                           // [OBRIGATÓRIO] Identificador interno do serviço. Ver NOTA 2.
        }
      },
      // [OPCIONAL] Unidade de medida. Por omissão é a configurada no serviço, ou a por omissão na empresa.
      // Se a unidade de medida for indicada, usar apenas ou o "id" nesta "relationship" ou o campo "unit_of_measure" (o código da unidade; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
      "unit_of_measure": {
        "data": {
          "type": "units_of_measure",                         // [OBRIGATÓRIO]
          "id": "1"                                           // [OBRIGATÓRIO] Identificador interno da unidade de medida. Ver NOTA 4.
        }
      },
      // [OPCIONAL] IVA. Por omissão é aplicado o IVA associado ao serviço, ou à taxa normal na região onde a empresa está localizada, ou a região de operação para efeitos de IVA, se indicada.
      // Se a taxa de IVA for indicada, usar apenas ou o "id" nesta "relationship" ou um ou mais dos três campos "tax_code", "tax_percentage" e "tax_country_region" (o tipo, a percentagem e/ou a região do IVA; ver mais acima). Se se indicarem todos os campos, então devem ser consistentes.
      "tax": {
        "data": {
          "type": "taxes",                                    // [OBRIGATÓRIO]
          "id": "1"                                           // [OBRIGATÓRIO] Identificador interno da taxa de IVA. Ver NOTA 5.
        }
      }
    }
  }
}

2.3. Criação de uma linha de descritor

Para o caso particular de uma linha de descritor, este payload contém a seguinte informação:

{
  "data": {
    "type": "commercial_sales_document_lines",                // [OBRIGATÓRIO]
    "attributes": {                                           // [OBRIGATÓRIO] Os atributos da linha do documento
      // [OBRIGATÓRIO] Identificação do descritor.
      "item_type": "TaxDescriptor",                           // [OBRIGATÓRIO] Tipo de item: "TaxDescriptor": descritor.
      // Usar apenas ou o campo seguinte (o código) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes entre si.
      "item_code": "Código do descritor",                     // [OPCIONAL] Já tem que existir o descritor com este código. Por omissão, é usado o descritor identificado pela "relationship" respectiva, se indicada.
      "description": "Descrição da linha",                    // [OPCIONAL] Por omissão é usada a descrição associada ao descritor.

      // [OPCIONAL] Unidade de medida. Por omissão é a configurada por omissão na empresa.
      // Se a unidade de medida for indicada, usar apenas ou o campo seguinte (o código) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes entre si.
      "unit_of_measure": "Unidade de medida",                 // [OPCIONAL] Por omissão é a configurada por omissão na empresa.
      // [OBRIGATÓRIO] Quantidades e valores.
      "quantity": 1,                                          // [OPCIONAL] Por omissão 1, se não for uma linha de descrição com valor. [OBRIGATÒRIO] Para uma linha de descrição com valor.
      "unit_price": 9.99,                                     // [OBRIGATÓRIO]
      "settlement_expression": "3",                           // [OPCIONAL] Desconto de linha, em percentagem; são suportados descontos compostos, como "3+5".

      // [OPCIONAL] IVA. Por omissão é aplicado o IVA associado ao descritor, ou à taxa normal, na região onde a empresa está localizada.
      // Se a taxa de IVA for indicada, usar apenas um ou mais dos três campos seguintes ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem todos os campos, então devem ser consistentes entre si.
      // [NÃO PODE SER USADO] no caso de uma linha de descritor que são suporte IVA: ou seja, um descritor referente a uma retenção (taxa SIRCA, outras retenções...)
      "tax_code": "NOR|INT|RED|ISE",                          // [OPCIONAL] Por omissão é usado o tipo de IVA associado ao item, ou "NOR" se nenhum associado. Os tipos de IVA suportados são "NOR" (normal), "INT" (intermédio), "RED" (reduzido), "ISE" (isento).
      "tax_percentage": 22,                                   // [OPCIONAL] Percentagem de IVA a usar: serve para indicar uma taxa de outra região (se o campo "tax_country_region" não for indicado) ou uma taxa antiga, já não em vigor.
      "tax_country_region": "PT-MA"                           // [OPCIONAL] Região do IVA. Por omissão (e se o campo "tax_percentage" não for indicado) aplica-se a taxa de IVA da região onde a empresa está localizada. Para o regime OSS pode ainda usar-se o código ISO alpha-2 do país OSS (vd. https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2; ver também a NOTA 3.
    },
    "relationships": {                                        // [OBRIGATÓRIO] Recursos associados à linha do documento.
      // [OBRIGATÓRIO] Identificação do documento (cabeçalho) a que esta linha pertence.
      "document": {
        "data": {
          "type": "commercial_sales_documents",               // [OBRIGATÓRIO]
          "id": "1"                                           // [OBRIGATÓRIO] Identificador interno do documento (cabeçalho). Ver NOTA 1.
        }
      },
      // [OPCIONAL] Descritor associado à linha.
      // Usar apenas ou o "id" nesta "relationship" ou o campo "item_code" (o código do descritor; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
      "tax_descriptor": {
        "data": {
          "type": "tax_descriptors",                          // [OBRIGATÓRIO]
          "id": "1"                                           // [OBRIGATÓRIO] Identificador interno do descritor. Ver NOTA 2.
        }
      },
      // [OPCIONAL] Unidade de medida. Por omissão é a configurada por omissão na empresa.
      // Se a unidade de medida for indicada, usar apenas ou o "id" nesta "relationship" ou o campo "unit_of_measure" (o código da unidade; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
      "unit_of_measure": {
        "data": {
          "type": "units_of_measure",                         // [OBRIGATÓRIO]
          "id": "1"                                           // [OBRIGATÓRIO] Identificador interno da unidade de medida. Ver NOTA 4.
        }
      },
      // [OPCIONAL] IVA. Por omissão é aplicado o IVA associado ao descritor, ou à taxa normal na região onde a empresa está localizada.
      // Se a taxa de IVA for indicada, usar apenas ou o "id" nesta "relationship" ou um ou mais dos três campos "tax_code", "tax_percentage" e "tax_country_region" (o tipo, a percentagem e/ou a região do IVA; ver mais acima). Se se indicarem todos os campos, então devem ser consistentes.
      // [NÃO PODE SER USADO] no caso de uma linha de descritor que são suporte IVA: ou seja, um descritor referente a uma retenção (taxa SIRCA, outras retenções...)
      "tax": {
        "data": {
          "type": "taxes",                                    // [OBRIGATÓRIO]
          "id": "1"                                           // [OBRIGATÓRIO] Identificador interno da taxa de IVA. Ver NOTA 5.
        }
      }
    }
  }
}

2.4. Criação de uma linha de descrição com valor

Para o caso particular de uma linha de descrição com valor, este payload contém a seguinte informação:

{
  "data": {
    "type": "commercial_sales_document_lines",                // [OBRIGATÓRIO]
    "attributes": {                                           // [OBRIGATÓRIO] Os atributos da linha do documento

      "description": "Descrição da linha",                    // [OBRIGATÓRIO]

      // [OPCIONAL] Unidade de medida. Por omissão é a configurada por omissão na empresa.
      // Se a unidade de medida for indicada, usar apenas ou o campo seguinte (o código) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes entre si.
      "unit_of_measure": "Unidade de medida",                 // [OPCIONAL] Por omissão é a configurada por omissão na empresa.
      // [OBRIGATÓRIO] Quantidades e valores.
      "quantity": 1,                                          // [OBRIGATÒRIO]
      "unit_price": 9.99,                                     // [OBRIGATÒRIO]
      "settlement_expression": "3",                           // [OPCIONAL] Desconto de linha, em percentagem; são suportados descontos compostos, como "3+5".

      // [OPCIONAL] IVA. Por omissão é aplicado o IVA à taxa normal, na região onde a empresa está localizada.
      // Se a taxa de IVA for indicada, usar apenas um ou mais dos três campos seguintes ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem todos os campos, então devem ser consistentes entre si.
      "tax_code": "NOR|INT|RED|ISE",                          // [OPCIONAL] Por omissão é usado o tipo de IVA "NOR". Os tipos de IVA suportados são "NOR" (normal), "INT" (intermédio), "RED" (reduzido), "ISE" (isento).
      "tax_percentage": 22,                                   // [OPCIONAL] Percentagem de IVA a usar: serve para indicar uma taxa de outra região (se o campo "tax_country_region" não for indicado) ou uma taxa antiga, já não em vigor.
      "tax_country_region": "PT-MA"                           // [OPCIONAL] Região do IVA. Por omissão (e se o campo "tax_percentage" não for indicado) aplica-se a taxa de IVA da região onde a empresa está localizada. Para o regime OSS pode ainda usar-se o código ISO alpha-2 do país OSS (vd. https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2; ver também a NOTA 3.
    },
    "relationships": {                                        // [OBRIGATÓRIO] Recursos associados à linha do documento.
      // [OBRIGATÓRIO] Identificação do documento (cabeçalho) a que esta linha pertence.
      "document": {
        "data": {
          "type": "commercial_sales_documents",               // [OBRIGATÓRIO]
          "id": "1"                                           // [OBRIGATÓRIO] Identificador interno do documento (cabeçalho). Ver NOTA 1.
        }
      },
      // [OPCIONAL] Unidade de medida. Por omissão é a configurada por omissão na empresa.
      // Se a unidade de medida for indicada, usar apenas ou o "id" nesta "relationship" ou o campo "unit_of_measure" (o código da unidade; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
      "unit_of_measure": {
        "data": {
          "type": "units_of_measure",                         // [OBRIGATÓRIO]
          "id": "1"                                           // [OBRIGATÓRIO] Identificador interno da unidade de medida. Ver NOTA 4.
        }
      },
      // [OPCIONAL] IVA. Por omissão é aplicado o IVA à taxa normal na região onde a empresa está localizada.
      // Se a taxa de IVA for indicada, usar apenas ou o "id" nesta "relationship" ou um ou mais dos três campos "tax_code", "tax_percentage" e "tax_country_region" (o tipo, a percentagem e/ou a região do IVA; ver mais acima). Se se indicarem todos os campos, então devem ser consistentes.
      "tax": {
        "data": {
          "type": "taxes",                                    // [OBRIGATÓRIO]
          "id": "1"                                           // [OBRIGATÓRIO] Identificador interno da taxa de IVA. Ver NOTA 5.
        }
      }
    }
  }
}

2.5. Criação de uma linha de descrição sem valor

Para o caso particular de uma linha de descrição sem valor, este payload contém a seguinte informação:

{
  "data": {
    "type": "commercial_sales_document_lines",                // [OBRIGATÓRIO]
    "attributes": {                                           // [OBRIGATÓRIO] Os atributos da linha do documento
      "description": "Descrição da linha"                     // [OBRIGATÓRIO]
    },
    "relationships": {                                        // [OBRIGATÓRIO] Recursos associados à linha do documento.
      // [OBRIGATÓRIO] Identificação do documento (cabeçalho) a que esta linha pertence.
      "document": {
        "data": {
          "type": "commercial_sales_documents",               // [OBRIGATÓRIO]
          "id": "1"                                           // [OBRIGATÓRIO] Identificador interno do documento (cabeçalho). Ver NOTA 1.
        }
      }
    }
  }
}

3. Finalização do documento

Após todas as linhas criadas, e se não houver mais nenhuma alteração ao documento, este pode ser finalizado.

Após a finalização, a alteração ou eliminação do cabeçalho e das linhas deixa de ser possível, assim como a criação de linhas adicionais.

patch

Path parameters

idintegerRequired

id of the document to update or finalize

Body

application/json

Responses

200

OK

application/json

patch

/commercial_sales_documents/{id}

HTTPcURLJavaScriptPython

PATCH /commercial_sales_documents/{id} HTTP/1.1
Host: /
Content-Type: application/json
Accept: */*
Content-Length: 1199

{
  "data": {
    "type": "commercial_sales_documents",
    "id": "1",
    "attributes": {
      "status": 1,
      "document_type": "FT|FS|FR",
      "date": "2023-01-01",
      "document_series_prefix": "Prefixo da série",
      "customer_tax_registration_number": "999999990",
      "customer_business_name": "Nome do cliente",
      "customer_address_detail": "Morada do cliente",
      "customer_postcode": "0000-000",
      "customer_city": "Cidade/Localidade do cliente",
      "customer_country": "PT",
      "due_date": "2023-01-01",
      "settlement_expression": "7.5",
      "payment_mechanism": "MO|CH|DC|CC|TR|CO|CS|DE|LC|MB|OU|RT|DDA",
      "vat_included_prices": false,
      "operation_country": "PT-MA",
      "currency_iso_code": "USD",
      "currency_conversion_rate": 1.21,
      "retention": 7.5,
      "retention_type": "IRS|IRC",
      "apply_retention_when_paid": true,
      "notes": "Notas ao documento",
      "external_reference": "Referência do documento externo"
    },
    "relationships": {
      "commercial_document_series": {
        "data": {
          "type": "commercial_document_series",
          "id": "1"
        }
      },
      "customer": {
        "data": {
          "type": "customers",
          "id": "1"
        }
      },
      "bank_accounts": {
        "data": {
          "type": "bank_accounts",
          "id": "1"
        }
      },
      "cash_accounts": {
        "data": {
          "type": "cash_accounts",
          "id": "1"
        }
      },
      "tax_exemption_reasons": {
        "data": {
          "type": "tax_exemption_reasons",
          "id": "1"
        }
      },
      "currency": {
        "data": {
          "type": "currencies",
          "id": "1"
        }
      }
    }
  }
}

200

OK

{
  "data": {
    "type": "commercial_sales_documents",
    "id": "1",
    "attributes": {
      "status": 1,
      "document_type": "FT|FS|FR",
      "document_no": "FT 2023/1",
      "date": "2023-01-01",
      "document_series_prefix": "Prefixo da série",
      "customer_tax_registration_number": "999999990",
      "customer_business_name": "Nome do cliente",
      "customer_address_detail": "Morada do cliente",
      "customer_postcode": "0000-000",
      "customer_city": "Cidade/Localidade do cliente",
      "customer_country": "PT",
      "due_date": "2023-01-01",
      "settlement_expression": "7.5",
      "payment_mechanism": "MO|CH|DC|CC|TR|CO|CS|DE|LC|MB|OU|RT|DDA",
      "vat_included_prices": false,
      "operation_country": "PT-MA",
      "currency_iso_code": "USD",
      "currency_conversion_rate": 1.21,
      "retention": 7.5,
      "retention_type": "IRS|IRC",
      "apply_retention_when_paid": true,
      "notes": "Notas ao documento",
      "external_reference": "Referência do documento externo"
    },
    "relationships": {
      "commercial_document_series": {
        "data": {
          "type": "commercial_document_series",
          "id": "1"
        }
      },
      "customer": {
        "data": {
          "type": "customers",
          "id": "1"
        }
      },
      "bank_accounts": {
        "data": {
          "type": "bank_accounts",
          "id": "1"
        }
      },
      "cash_accounts": {
        "data": {
          "type": "cash_accounts",
          "id": "1"
        }
      },
      "tax_exemption_reasons": {
        "data": {
          "type": "tax_exemption_reasons",
          "id": "1"
        }
      },
      "currency": {
        "data": {
          "type": "currencies",
          "id": "1"
        }
      }
    }
  }
}

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>'

No pedido acima, o access_token é o token de acesso válido devolvido pelo serviço de OAuth e o id do documento é o "id" interno do documento (cabeçalho) é o devolvido no campo "id" da resposta ao seu pedido de criação (ver ponto 1. Criação do cabeçalho). O payload JSON a enviar contém a seguinte informação:

{
  "data": {
    "type": "commercial_sales_documents",                             // [OBRIGATÓRIO]
    "id": "1",                                                        // [OBRIGATÓRIO] Identificador interno do documento (cabeçalho). Este "id" é o devolvido na resposta ao pedido de criação do cabeçalho, ver acima.
    "attributes": {                                                   // [OBRIGATÓRIO] Os atributos do documento
      "status": 1                                                     // [OBRIGATÓRIO] Identificação do estado do documento. 1: documento finalizado.
    }
  }
}

Este pedido é equivalente ao pedido de alteração do cabeçalho do documento (ver Alteração do cabeçalho do documento). Por isso, a finalização do documento — que é a alteração do atributo "status" do cabeçalho — pode ser realizada juntamente com a alteração de outros atributos ou relações do cabeçalho, num único pedido.

Alteração do documento

Enquanto o documento não for finalizado, tanto o seu cabeçalho como qualquer uma das suas linhas podem ser alteradas a qualquer momento. Além disso, qualquer uma das linhas pode ser eliminada (ver Eliminação de uma linha), e novas linhas criadas e adicionadas (ver 2. Criação da(s) linha(s)).

Alteração do cabeçalho

patch

Path parameters

idintegerRequired

id of the document to update or finalize

Body

application/json

Responses

200

OK

application/json

patch

/commercial_sales_documents/{id}

HTTPcURLJavaScriptPython

PATCH /commercial_sales_documents/{id} HTTP/1.1
Host: /
Content-Type: application/json
Accept: */*
Content-Length: 1199

{
  "data": {
    "type": "commercial_sales_documents",
    "id": "1",
    "attributes": {
      "status": 1,
      "document_type": "FT|FS|FR",
      "date": "2023-01-01",
      "document_series_prefix": "Prefixo da série",
      "customer_tax_registration_number": "999999990",
      "customer_business_name": "Nome do cliente",
      "customer_address_detail": "Morada do cliente",
      "customer_postcode": "0000-000",
      "customer_city": "Cidade/Localidade do cliente",
      "customer_country": "PT",
      "due_date": "2023-01-01",
      "settlement_expression": "7.5",
      "payment_mechanism": "MO|CH|DC|CC|TR|CO|CS|DE|LC|MB|OU|RT|DDA",
      "vat_included_prices": false,
      "operation_country": "PT-MA",
      "currency_iso_code": "USD",
      "currency_conversion_rate": 1.21,
      "retention": 7.5,
      "retention_type": "IRS|IRC",
      "apply_retention_when_paid": true,
      "notes": "Notas ao documento",
      "external_reference": "Referência do documento externo"
    },
    "relationships": {
      "commercial_document_series": {
        "data": {
          "type": "commercial_document_series",
          "id": "1"
        }
      },
      "customer": {
        "data": {
          "type": "customers",
          "id": "1"
        }
      },
      "bank_accounts": {
        "data": {
          "type": "bank_accounts",
          "id": "1"
        }
      },
      "cash_accounts": {
        "data": {
          "type": "cash_accounts",
          "id": "1"
        }
      },
      "tax_exemption_reasons": {
        "data": {
          "type": "tax_exemption_reasons",
          "id": "1"
        }
      },
      "currency": {
        "data": {
          "type": "currencies",
          "id": "1"
        }
      }
    }
  }
}

200

OK

{
  "data": {
    "type": "commercial_sales_documents",
    "id": "1",
    "attributes": {
      "status": 1,
      "document_type": "FT|FS|FR",
      "document_no": "FT 2023/1",
      "date": "2023-01-01",
      "document_series_prefix": "Prefixo da série",
      "customer_tax_registration_number": "999999990",
      "customer_business_name": "Nome do cliente",
      "customer_address_detail": "Morada do cliente",
      "customer_postcode": "0000-000",
      "customer_city": "Cidade/Localidade do cliente",
      "customer_country": "PT",
      "due_date": "2023-01-01",
      "settlement_expression": "7.5",
      "payment_mechanism": "MO|CH|DC|CC|TR|CO|CS|DE|LC|MB|OU|RT|DDA",
      "vat_included_prices": false,
      "operation_country": "PT-MA",
      "currency_iso_code": "USD",
      "currency_conversion_rate": 1.21,
      "retention": 7.5,
      "retention_type": "IRS|IRC",
      "apply_retention_when_paid": true,
      "notes": "Notas ao documento",
      "external_reference": "Referência do documento externo"
    },
    "relationships": {
      "commercial_document_series": {
        "data": {
          "type": "commercial_document_series",
          "id": "1"
        }
      },
      "customer": {
        "data": {
          "type": "customers",
          "id": "1"
        }
      },
      "bank_accounts": {
        "data": {
          "type": "bank_accounts",
          "id": "1"
        }
      },
      "cash_accounts": {
        "data": {
          "type": "cash_accounts",
          "id": "1"
        }
      },
      "tax_exemption_reasons": {
        "data": {
          "type": "tax_exemption_reasons",
          "id": "1"
        }
      },
      "currency": {
        "data": {
          "type": "currencies",
          "id": "1"
        }
      }
    }
  }
}

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>'

No pedido acima, o access_token é o token de acesso válido devolvido pelo serviço de OAuth e o id do documento é o "id" interno do documento (cabeçalho), devolvido no campo "id" da resposta ao seu pedido de criação (ver ponto 1. Criação do cabeçalho). O payload JSON a enviar contém a seguinte informação:

{
  "data": {
    "type": "commercial_sales_documents",                             // [OBRIGATÓRIO]
    "id": "1",                                                        // [OBRIGATÓRIO] Identificador interno do documento (cabeçalho). Este "id" é o devolvido na resposta ao pedido de criação do cabeçalho, ver acima.
    "attributes": {                                                   // [OBRIGATÓRIO] Os atributos do documento
      "status": 1                                                     // [OPCIONAL] Identificação do estado do documento. 1: documento finalizado.
      // Identificação do documento
      "document_type": "FT|FS|FR",                                    // [OBRIGATÓRIO] Tipo de documento. "FT": fatura, "FS": fatura simplificada, "FR": fatura-recibo.
      "date": "2023-01-01",                                           // [OPCIONAL] Data do documento; por omissão, a data do pedido.

      // [OPCIONAL] Identificação da série do documento. Por omissão, aplicam-se as regras configuradas na empresa para escolha da série.
      // Se a série for indicada, usar apenas ou o campo seguinte (o prefixo) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes.
      "document_series_prefix": "Prefixo da série",                   // [OPCIONAL] Em alternativa ao campo "document_series_id".

      // [OPCIONAL] Identificação do cliente. Por omissão, é o consumidor final (NIF "999999990").
      // Se o cliente for indicado, usar apenas ou o campo seguinte (o NIF) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes.
      "customer_tax_registration_number": "999999990",                // [OPCIONAL] NIF do cliente. se o cliente com o NIF indicado não existir, será criado automaticamente. Se o país ("customer_country") for Portugal ("PT", "PT-AC" ou "PT-MA"), 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": "Nome do cliente",                    // [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": "Morada do cliente",                 // [OPCIONAL]
      "customer_postcode": "0000-000",                                // [OPCIONAL] Código postal do cliente, no formato 0000-000.
      "customer_city": "Cidade/Localidade do cliente",                // [OPCIONAL]
      "customer_country": "PT",                                       // [OPCIONAL] País do cliente. 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; ver também a NOTA 3.

      // [OPCIONAL] Condições de pagamento
      "due_date": "2023-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.
      "settlement_expression": "7.5",                                 // [OPCIONAL] Desconto no cabeçalho, em percentagem; são suportados descontos compostos, como "3+5"
      "payment_mechanism": "MO|CH|DC|CC|TR|CO|CS|DE|LC|MB|OU|RT|DDA", // [OPCIONAL] Necessário apenas no caso das FR. Por omissão, "MO", ou o configurado no cliente, se o cliente tiver configurado um modo de pagamento. Modos 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": Multibanco, "CO": Cartão oferta, "CS": Compensação de saldos, "DE": Dinheiro eletrónico, "LC": Letra comercial, "OU": Outros, "RT": Ticket restaurante.

      // [OPCIONAL] IVA
      "vat_included_prices": false,                                   // [OPCIONAL] Os preços nas linhas são com IVA incluído? Por omissão, não (false).
      "operation_country": "PT-MA",                                   // [OPCIONAL] A região de operação para efeitos de IVA: usada apenas para as linhas de serviços. Por omissão, é a região onde a empresa está localizada. Para o regime OSS pode ainda usar-se o código ISO alpha-2 do país OSS (vd. https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2; ver também a NOTA 3.

      // [OPCIONAL] Moeda. Por omissão, "EUR".
      // Se a moeda for indicada, usar apenas ou o campos seguinte (o código ISO) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes.
      "currency_iso_code": "USD",                                     // [OPCIONAL] É o código ISO da moeda do documento (vd. https://en.wikipedia.org/wiki/ISO_4217).
      "currency_conversion_rate": 1.21,                               // [OMITIDO] se a moeda for "EUR". [OBRIGATÓRIO] nos restantes casos; é a taxa de conversão para EUR (1 EUR = n USD|...).

      // [OPCIONAL] Retenção
      "retention": 7.5,                                               // [OPCIONAL] Percentagem de retenção a aplicar sobre os serviços.
      "retention_type": "IRS|IRC",                                    // [OPCIONAL] Tipo de retenção ("IRS" ou "IRC"). Por omissão, "IRS".
      "apply_retention_when_paid": true,                              // [OPCIONAL] A retenção é feita logo no documento (false) ou apenas no recebimento (true). Por omissão, false.

      // [OPCIONAL] Outras informações
      "notes": "Notas ao documento",                                  // [OPCIONAL]
      "external_reference": "Referência do documento externo"         // [OPCIONAL]
    },
    "relationships": {                                                // [OPCIONAL] Recursos associados ao documento. Caso nenhum seja indicado, este bloco "relationships" deve ser omitido
      // [OPCIONAL] Identificação da série do documento. Por omissão, aplicam-se as regras configuradas na empresa para escolha da série.
      // Se a série for indicada, usar apenas ou o "id" nesta "relationship" ou campo "document_series_prefix" (o prefixo; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
      "commercial_document_series": {
        "data": {
          "type": "commercial_document_series",                       // [OBRIGATÓRIO]
          "id": "1"                                                   // [OBRIGATÓRIO] Identificador interno da série. Ver NOTA 1 abaixo.
        }
      },
      // [OPCIONAL] Identificação do cliente. Por omissão, é o consumidor final (NIF "999999990").
      // Se o cliente for indicado, usar apenas ou o "id" nesta "relationship" ou o campo "tax_registration_number" (o NIF; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
      "customer": {
        "data": {
          "type": "customers",                                        // [OBRIGATÓRIO]
          "id": "1"                                                   // [OBRIGATÓRIO] Identificador interno do cliente. Ver NOTA 2.
        }
      },
      // [OPCIONAL] Necessário apenas no caso das FR. 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.
      "bank_accounts": {
        "data": {
          "type": "bank_accounts",                                    // [OBRIGATÓRIO]
          "id": "1"                                                   // [OBRIGATÓRIO] Identificador interno da conta bancária da empresa. Ver NOTA 4.
        }
      },
      // [OPCIONAL] Necessário apenas no caso das FR. Conta de caixa da empresa para onde o recebimento é feito. Usado apenas quando o meio de pagamento da FR é "MO".
      "cash_accounts": {
        "data": {
          "type": "cash_accounts",                                    // [OBRIGATÓRIO]
          "id": "1"                                                   // [OBRIGATÓRIO] Identificador interno da conta de caixa da empresa. Ver NOTA 5.
        }
      },
      // Motivo de isenção de IVA. [OBRIGATÓRIO] apenas se o documento tiver pelo menos uma linha isenta de IVA. Não deve ser indicado nos restantes casos.
      "tax_exemption_reasons": {
        "data": {
          "type": "tax_exemption_reasons",                            // [OBRIGATÓRIO]
          "id": "1"                                                   // [OBRIGATÓRIO] Identificador interno do motivo de isenção do IVA. Ver NOTA 6.
        }
      },
      // [OPCIONAL] Moeda. Por omissão, "EUR".
      // Se a moeda for indicada, usar apenas ou o "id" nesta "relationship" ou o campo "currency_iso_code" (o código ISO; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
      "currency": {
        "data": {
          "type": "currencies",                                       // [OBRIGATÓRIO]
          "id": "1"                                                   // [OBRIGATÓRIO] Identificador interno da moeda. Ver NOTA 7.
        }
      }
    }
  }
}

A informação que pode ser enviada no pedido de alteração do cabeçalho do documento é a mesma que é enviada no pedido de criação, com a eventual adição do atributo "status" para finalizar o documento.

Alteração de uma linha

patch

Path parameters

idintegerRequired

id of the document line to update

Body

application/json

Responses

200

OK

application/json

patch

/commercial_sales_document_lines/{id}

HTTPcURLJavaScriptPython

PATCH /commercial_sales_document_lines/{id} HTTP/1.1
Host: /
Content-Type: application/json
Accept: */*
Content-Length: 664

{
  "data": {
    "type": "commercial_sales_document_lines",
    "id": "1",
    "attributes": {
      "item_type": "Service|Product|TaxDescriptor",
      "item_code": "Código do serviço/produto/descritor",
      "description": "Descrição da linha",
      "unit_of_measure": "Unidade de medida",
      "quantity": 1,
      "unit_price": 9.99,
      "settlement_expression": "3",
      "tax_code": "NOR|INT|RED|ISE",
      "tax_percentage": 22,
      "tax_country_region": "PT-MA"
    },
    "relationships": {
      "product": {
        "data": {
          "type": "products",
          "id": "1"
        }
      },
      "service": {
        "data": {
          "type": "services",
          "id": "1"
        }
      },
      "tax_descriptor": {
        "data": {
          "type": "tax_descriptors",
          "id": "1"
        }
      },
      "unit_of_measure": {
        "data": {
          "type": "units_of_measure",
          "id": "1"
        }
      },
      "tax": {
        "data": {
          "type": "taxes",
          "id": "1"
        }
      }
    }
  }
}

200

OK

{
  "data": {
    "type": "commercial_sales_document_lines",
    "id": "1",
    "attributes": {
      "item_type": "Service|Product|TaxDescriptor",
      "item_code": "Código do serviço/produto/descritor",
      "description": "Descrição da linha",
      "unit_of_measure": "Unidade de medida",
      "quantity": 1,
      "unit_price": 9.99,
      "settlement_expression": "3",
      "tax_code": "NOR|INT|RED|ISE",
      "tax_percentage": 22,
      "tax_country_region": "PT-MA"
    },
    "relationships": {
      "document": {
        "data": {
          "type": "commercial_sales_documents",
          "id": "1"
        }
      },
      "product": {
        "data": {
          "type": "products",
          "id": "1"
        }
      },
      "service": {
        "data": {
          "type": "services",
          "id": "1"
        }
      },
      "tax_descriptor": {
        "data": {
          "type": "tax_descriptors",
          "id": "1"
        }
      },
      "unit_of_measure": {
        "data": {
          "type": "units_of_measure",
          "id": "1"
        }
      },
      "tax": {
        "data": {
          "type": "taxes",
          "id": "1"
        }
      }
    }
  }
}

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_document_lines/<id da linha>'

No pedido acima, o access_token é o token de acesso válido devolvido pelo serviço de OAuth e o id da linha é o "id" interno da linha do documento, devolvido no campo "id" da resposta ao seu pedido de criação (ver ponto 2. Criação da(s) linha(s)). O payload JSON a enviar contém a seguinte informação:

{
  "data": {
    "type": "commercial_sales_document_lines",                // [OBRIGATÓRIO]
    "id": "1",                                                // [OBRIGATÓRIO] Identificador interno da linha do documento. Este "id" é o devolvido na resposta ao pedido de criação da linha, ver acima.    
    "attributes": {                                           // [OBRIGATÓRIO] Os atributos da linha do documento
      // [OPCIONAL] Identificação do item. Se nada for indicado, assume-se uma linha apenas de descrição.
      "item_type": "Service|Product|TaxDescriptor",           // [OPCIONAL] Tipo de item: "Service": serviço, "Product": produto, "TaxDescriptor": descritor. Por omissão, assume-se uma linha apenas de descrição.
      // Se o item for indicado, usar apenas ou o campo seguinte (o código) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes entre si, e consistentes com o "item_type".
      "item_code": "Código do serviço/produto/descritor",     // [OPCIONAL] Já tem que existir o produto/serviço/descritor com este código. Por omissão, é usado o item identificado pela "relationship" respectiva, se indicada. Se nada for indicado, assume-se uma linha apenas de descrição.
      "description": "Descrição da linha",                    // [OPCIONAL] Por omissão é usada a descrição associada ao item, se este for indicado. [OBRIGATÓRIO] Para uma linha apenas de descrição.

      // [OPCIONAL] Unidade de medida. Por omissão é a configurada no item (se for serviço ou produto), ou a por omissão na empresa.
      // Se a unidade de medida for indicada, usar apenas ou o campo seguinte (o código) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes entre si.
      "unit_of_measure": "Unidade de medida",                 // [OPCIONAL] Por omissão é a configurada no item, ou a por omissão na empresa.
      // Quantidades e valores. [OBRIGATÓRIO] Para linhas de descrição com valor.
      "quantity": 1,                                          // [OPCIONAL] Por omissão 1, se não for uma linha de descrição com valor. [OBRIGATÒRIO] Para uma linha de descrição com valor.
      "unit_price": 9.99,                                     // [OPCIONAL] Se for indicado um serviço ou produto. Por omissão é usado o PVP associado ao item (serviço ou produto). [OBRIGATÓRIO] Para uma linha de descritor ou de descrição com valor.
      "settlement_expression": "3",                           // [OPCIONAL] Desconto de linha, em percentagem; são suportados descontos compostos, como "3+5".

      // [OPCIONAL] IVA. Por omissão é aplicado o IVA associado ao item, ou à taxa normal, na região onde a empresa está localizada, ou — apenas para as linhas de serviços — a região de operação para efeitos de IVA, se indicada.
      // Se a taxa de IVA for indicada, usar apenas um ou mais dos três campos seguintes ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem todos os campos, então devem ser consistentes entre si.
      // [NÃO PODE SER USADO] no caso de uma linha de descrição sem valor, ou de um descritor que são suporte IVA: ou seja, um descritor referente a uma retenção (taxa SIRCA, outras retenções...)
      "tax_code": "NOR|INT|RED|ISE",                          // [OPCIONAL] Por omissão é usado o tipo de IVA associado ao item, ou "NOR" se nenhum associado. Os tipos de IVA suportados são "NOR" (normal), "INT" (intermédio), "RED" (reduzido), "ISE" (isento).
      "tax_percentage": 22,                                   // [OPCIONAL] Percentagem de IVA a usar: serve para indicar uma taxa de outra região (se o campo "tax_country_region" não for indicado) ou uma taxa antiga, já não em vigor.
      "tax_country_region": "PT-MA"                           // [OPCIONAL] Região do IVA. Por omissão (e se o campo "tax_percentage" não for indicado) aplica-se a taxa de IVA da região onde a empresa está localizada, ou — apenas para as linhas de serviços — a região de operação para efeitos de IVA, se indicada. Para o regime OSS pode ainda usar-se o código ISO alpha-2 do país OSS (vd. https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2; ver também a NOTA 3.
    },
    "relationships": {                                        // [OBRIGATÓRIO] Recursos associados à linha do documento.
      // [OBRIGATÓRIO] Identificação do documento (cabeçalho) a que esta linha pertence.
      "document": {
        "data": {
          "type": "commercial_sales_documents",               // [OBRIGATÓRIO]
          "id": "1"                                           // [OBRIGATÓRIO] Identificador interno do documento (cabeçalho). Ver NOTA 1.
        }
      },
      // [OPCIONAL] Produto associado à linha. Só deve ser indicado para as linhas de produtos.
      // Se o produto for indicado, usar apenas ou o "id" nesta "relationship" ou o campo "item_code" (o código do produto; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
      "product": {
        "data": {
          "type": "products",                                 // [OBRIGATÓRIO]
          "id": "1"                                           // [OBRIGATÓRIO] Identificador interno do produto. Ver NOTA 2.
        }
      },
      // [OPCIONAL] Serviço associado à linha. Só deve ser indicado para as linhas de serviços.
      // Se o serviço for indicado, usar apenas ou o "id" nesta "relationship" ou o campo "item_code" (o código do serviço; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
      "service": {
        "data": {
          "type": "services",                                 // [OBRIGATÓRIO]
          "id": "1"                                           // [OBRIGATÓRIO] Identificador interno do serviço. Ver NOTA 2.
        }
      },
      // [OPCIONAL] Descritor associado à linha. Só deve ser indicado para as linhas de descritores.
      // Se o descritor for indicado, usar apenas ou o "id" nesta "relationship" ou o campo "item_code" (o código do descritor; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
      "tax_descriptor": {
        "data": {
          "type": "tax_descriptors",                          // [OBRIGATÓRIO]
          "id": "1"                                           // [OBRIGATÓRIO] Identificador interno do descritor. Ver NOTA 2.
        }
      },
      // [OPCIONAL] Unidade de medida. Por omissão é a configurada no item (se for serviço ou produto), ou a por omissão na empresa.
      // Se a unidade de medida for indicada, usar apenas ou o "id" nesta "relationship" ou o campo "unit_of_measure" (o código da unidade; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
      "unit_of_measure": {
        "data": {
          "type": "units_of_measure",                         // [OBRIGATÓRIO]
          "id": "1"                                           // [OBRIGATÓRIO] Identificador interno da unidade de medida. Ver NOTA 4.
        }
      },
      // [OPCIONAL] IVA. Por omissão é aplicado o IVA associado ao item, ou à taxa normal na região onde a empresa está localizada, ou — apenas para as linhas de serviços — a região de operação para efeitos de IVA, se indicada.
      // Se a taxa de IVA for indicada, usar apenas ou o "id" nesta "relationship" ou um ou mais dos três campos "tax_code", "tax_percentage" e "tax_country_region" (o tipo, a percentagem e/ou a região do IVA; ver mais acima). Se se indicarem todos os campos, então devem ser consistentes.
      // [NÃO PODE SER USADO] no caso de uma linha de descrição sem valor, ou de um descritor que são suporte IVA: ou seja, um descritor referente a uma retenção (taxa SIRCA, outras retenções...)
      "tax": {
        "data": {
          "type": "taxes",                                    // [OBRIGATÓRIO]
          "id": "1"                                           // [OBRIGATÓRIO] Identificador interno da taxa de IVA. Ver NOTA 5.
        }
      }
    }
  }
}

A informação que pode ser enviada no pedido de alteração da linha do documento é a mesma que é enviada no pedido de criação. O exemplo de payload acima deve por isso ser ajustado consoante se trate da alteração duma linha de produto, de serviço, de descritor ou de descrição. É ainda possível alterar o tipo de linha (de uma linha de serviço para uma de produto, por exemplo).

Eliminação de uma linha

delete

Path parameters

idintegerRequired

id of the document line to delete

Responses

200

OK

No content

delete

/commercial_sales_document_lines/{id}

HTTPcURLJavaScriptPython

DELETE /commercial_sales_document_lines/{id} HTTP/1.1
Host: /
Accept: */*

200

OK

No content

curl -v -X DELETE -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' '<API_URL>/commercial_sales_document_lines/<id da linha>'

No pedido acima, o access_token é o token de acesso válido devolvido pelo serviço de OAuth e o id da linha é o "id" interno da linha do documento, devolvido no campo "id" da resposta ao seu pedido de criação (ver ponto 2. Criação da(s) linha(s)).

Eliminação do documento

Enquanto estiver em preparação, o documento pode ser eliminado.

Após a finalização, no entanto, a sua eliminação — assim como a sua alteração — deixa de ser possível.

delete

Path parameters

idintegerRequired

id of the document to delete

Responses

200

OK

No content

delete

/commercial_sales_documents/{id}

HTTPcURLJavaScriptPython

DELETE /commercial_sales_documents/{id} HTTP/1.1
Host: /
Accept: */*

200

OK

No content

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

No pedido acima, o access_token é o token de acesso válido devolvido pelo serviço de OAuth e o id do documento é o "id" interno do documento (cabeçalho) é o devolvido no campo "id" da resposta ao seu pedido de criação (ver ponto 1. Criação do cabeçalho).

Esta operação é irreversível.

Anulação do documento

Após a sua finalização, o documento deixa de poder ser eliminado, podendo apenas ser anulado.

patch

Path parameters

idintegerRequired

id of the document to update or finalize

Body

application/json

Responses

200

OK

application/json

patch

/commercial_sales_documents/{id}

HTTPcURLJavaScriptPython

PATCH /commercial_sales_documents/{id} HTTP/1.1
Host: /
Content-Type: application/json
Accept: */*
Content-Length: 1199

{
  "data": {
    "type": "commercial_sales_documents",
    "id": "1",
    "attributes": {
      "status": 1,
      "document_type": "FT|FS|FR",
      "date": "2023-01-01",
      "document_series_prefix": "Prefixo da série",
      "customer_tax_registration_number": "999999990",
      "customer_business_name": "Nome do cliente",
      "customer_address_detail": "Morada do cliente",
      "customer_postcode": "0000-000",
      "customer_city": "Cidade/Localidade do cliente",
      "customer_country": "PT",
      "due_date": "2023-01-01",
      "settlement_expression": "7.5",
      "payment_mechanism": "MO|CH|DC|CC|TR|CO|CS|DE|LC|MB|OU|RT|DDA",
      "vat_included_prices": false,
      "operation_country": "PT-MA",
      "currency_iso_code": "USD",
      "currency_conversion_rate": 1.21,
      "retention": 7.5,
      "retention_type": "IRS|IRC",
      "apply_retention_when_paid": true,
      "notes": "Notas ao documento",
      "external_reference": "Referência do documento externo"
    },
    "relationships": {
      "commercial_document_series": {
        "data": {
          "type": "commercial_document_series",
          "id": "1"
        }
      },
      "customer": {
        "data": {
          "type": "customers",
          "id": "1"
        }
      },
      "bank_accounts": {
        "data": {
          "type": "bank_accounts",
          "id": "1"
        }
      },
      "cash_accounts": {
        "data": {
          "type": "cash_accounts",
          "id": "1"
        }
      },
      "tax_exemption_reasons": {
        "data": {
          "type": "tax_exemption_reasons",
          "id": "1"
        }
      },
      "currency": {
        "data": {
          "type": "currencies",
          "id": "1"
        }
      }
    }
  }
}

200

OK

{
  "data": {
    "type": "commercial_sales_documents",
    "id": "1",
    "attributes": {
      "status": 1,
      "document_type": "FT|FS|FR",
      "document_no": "FT 2023/1",
      "date": "2023-01-01",
      "document_series_prefix": "Prefixo da série",
      "customer_tax_registration_number": "999999990",
      "customer_business_name": "Nome do cliente",
      "customer_address_detail": "Morada do cliente",
      "customer_postcode": "0000-000",
      "customer_city": "Cidade/Localidade do cliente",
      "customer_country": "PT",
      "due_date": "2023-01-01",
      "settlement_expression": "7.5",
      "payment_mechanism": "MO|CH|DC|CC|TR|CO|CS|DE|LC|MB|OU|RT|DDA",
      "vat_included_prices": false,
      "operation_country": "PT-MA",
      "currency_iso_code": "USD",
      "currency_conversion_rate": 1.21,
      "retention": 7.5,
      "retention_type": "IRS|IRC",
      "apply_retention_when_paid": true,
      "notes": "Notas ao documento",
      "external_reference": "Referência do documento externo"
    },
    "relationships": {
      "commercial_document_series": {
        "data": {
          "type": "commercial_document_series",
          "id": "1"
        }
      },
      "customer": {
        "data": {
          "type": "customers",
          "id": "1"
        }
      },
      "bank_accounts": {
        "data": {
          "type": "bank_accounts",
          "id": "1"
        }
      },
      "cash_accounts": {
        "data": {
          "type": "cash_accounts",
          "id": "1"
        }
      },
      "tax_exemption_reasons": {
        "data": {
          "type": "tax_exemption_reasons",
          "id": "1"
        }
      },
      "currency": {
        "data": {
          "type": "currencies",
          "id": "1"
        }
      }
    }
  }
}

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>'

No pedido acima, o access_token é o token de acesso válido devolvido pelo serviço de OAuth e o id do documento é o "id" interno do documento (cabeçalho) é o devolvido no campo "id" da resposta ao seu pedido de criação (ver ponto 1. Criação do cabeçalho). O payload JSON a enviar contém a seguinte informação:

{
  "data": {
    "type": "commercial_sales_documents",                             // [OBRIGATÓRIO]
    "id": "1",                                                        // [OBRIGATÓRIO] Identificador interno do documento (cabeçalho). Este "id" é o devolvido na resposta ao pedido de criação do cabeçalho, ver acima.
    "attributes": {                                                   // [OBRIGATÓRIO] Os atributos do documento
      "status": 4,                                                    // [OBRIGATÓRIO] Identificação do estado do documento. 4: documento anulado.
      "voided_reason": "Motivo pelo qual se anula o documento"        // [OBRIGATÓRIO]
    }
  }
}

Após a sua anulação, o documento deixa de poder ser alterado. Esta operação é irreversível.