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 —, incluindo a sua descarga em PDF.

Os documentos de venda na versão v1 da API têm a mesma estrutura anteriormente descrita para a v0: são compostos por um cabeçalho e uma ou mais linhas. Nesta nova versão, é possível criar ambos num só pedido, descrito de seguida.

Criação do documento

POST//v1/commercial_sales_documents

Body

application/json

document_type*string

Example: "FT|FS|FR"

datestring

Example: "2023-01-01"

document_series_idinteger

Example: 1

document_series_prefixstring

Example: "Prefixo da série"

customer_idinteger

Example: 1

customer_tax_registration_numberstring

Example: "999999990"

customer_business_namestring

Example: "Nome do cliente"

customer_address_detailstring

Example: "Morada do cliente"

customer_postcodestring

Example: "0000-000"

customer_citystring

Example: "Cidade/Localidade do cliente"

customer_countrystring

Example: "PT"

due_datestring

Example: "2023-01-01"

settlement_expressionstring

Example: "7.5"

payment_mechanismstring

Example: "MO|CH|DC|CC|TR|CO|CS|DE|LC|MB|OU|RT|DDA"

bank_account_idinteger

Example: 1

cash_account_idinteger

Example: 1

vat_included_pricesboolean

Example: false

tax_exemption_reason_idinteger

Example: 1

operation_countrystring

Example: "PT-MA"

currency_idinteger

Example: 1

currency_iso_codestring

Example: "USD"

currency_conversion_ratenumber

Example: 1.21

retentionnumber

Example: 7.5

retention_typestring

Example: "IRS|IRC"

apply_retention_when_paidboolean

Example: true

notesstring

Example: "Notas ao documento"

external_referencestring

Example: "Referência do documento externo"

finalizeboolean

Example: true

return_pdfboolean

Example: true

linesarray of object

Response

200

OK

Body

application/json

idinteger

Example: 1

document_typestring

Example: "FT|FS|FR"

datestring

Example: "2023-01-01"

document_series_idinteger

Example: 1

document_series_prefixstring

Example: "Prefixo da série"

customer_idinteger

Example: 1

customer_tax_registration_numberstring

Example: "999999990"

customer_business_namestring

Example: "Nome do cliente"

customer_address_detailstring

Example: "Morada do cliente"

customer_postcodestring

Example: "0000-000"

customer_citystring

Example: "Cidade/Localidade do cliente"

customer_countrystring

Example: "PT"

due_datestring

Example: "2023-01-01"

settlement_expressionstring

Example: "7.5"

payment_mechanismstring

Example: "MO|CH|DC|CC|TR|CO|CS|DE|LC|MB|OU|RT|DDA"

bank_account_idinteger

Example: 1

cash_account_idinteger

Example: 1

vat_included_pricesboolean

Example: false

tax_exemption_reason_idinteger

Example: 1

operation_countrystring

Example: "PT-MA"

currency_idinteger

Example: 1

currency_iso_codestring

Example: "USD"

currency_conversion_ratenumber

Example: 1.21

retentionnumber

Example: 7.5

retention_typestring

Example: "IRS|IRC"

apply_retention_when_paidboolean

Example: true

notesstring

Example: "Notas ao documento"

external_referencestring

Example: "Referência do documento externo"

urlstring

Example: "https://app.cloudware.pt/path_to_file"

linesarray of object

Request

JavaScriptCurlPython

const response = await fetch('//v1/commercial_sales_documents', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "document_type": "FT|FS|FR"
    }),
});
const data = await response.json();

Response

200

{
  "id": 1,
  "document_type": "FT|FS|FR",
  "date": "2023-01-01",
  "document_series_id": 1,
  "document_series_prefix": "Prefixo da série",
  "customer_id": 1,
  "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",
  "bank_account_id": 1,
  "cash_account_id": 1,
  "vat_included_prices": false,
  "tax_exemption_reason_id": 1,
  "operation_country": "PT-MA",
  "currency_id": 1,
  "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",
  "url": "https://app.cloudware.pt/path_to_file",
  "lines": [
    {
      "id": 1,
      "item_type": "Service|Product|TaxDescriptor",
      "item_id": 1,
      "item_code": "Código do serviço/produto/descritor",
      "description": "Descrição da linha",
      "unit_of_measure_id": 1,
      "unit_of_measure": "Unidade de medida",
      "quantity": 1,
      "unit_price": 9.99,
      "settlement_expression": "3",
      "tax_id": 1,
      "tax_code": "NOR|INT|RED|ISE",
      "tax_percentage": 22,
      "tax_country_region": "PT-MA"
    }
  ]
}

curl -v -X POST -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' -d '<payload JSON>' '<API_URL>/v1/commercial_sales_documents'

O payload JSON a enviar contém a seguinte informação:

{
    // 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 um dos dois campos seguintes (o "id" ou o prefixo). Se se indicarem os dois, então devem ser consistentes.
    "document_series_id": 1,                                        // [OPCIONAL] Identificador interno da série. Ver NOTA 1 abaixo.
    "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 um dos dois campos seguintes (o "id" ou o NIF). Se se indicarem os dois, então devem ser consistentes.
    "customer_id": 1,                                               // [OPCIONAL] Identificador interno do cliente. Ver NOTA 2.
    "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.
    "bank_account_id": 1,                                           // [OPCIONAL] Conta bancária da empresa para onde o recebimento é feito. Usado apenas quando o meio de pagamento da FR é "DC", "CC", "TR" ou "DDA", e apenas se for necessário indicar uma conta bancária específica. Ver NOTA 4.
    "cash_account_id": 1,                                           // [OPCIONAL] Conta de caixa da empresa para onde o recebimento é feito. Usado apenas quando o meio de pagamento da FR é "MO". Ver NOTA 5.

    // [OPCIONAL] IVA
    "vat_included_prices": false,                                   // [OPCIONAL] Os preços nas linhas são com IVA incluído? Por omissão, não (false).
    "tax_exemption_reason_id": 1,                                   // 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. Ver NOTA 6.
    "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 um dos dois campos seguintes (o "id" ou o código ISO). Se se indicarem os dois, então devem ser consistentes.
    "currency_id": 1,                                               // [OPCIONAL] Identificador interno da moeda. Ver NOTA 7.
    "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]

    // [OBRIGATÓRIO] Linhas do documento

    "lines": [
        {
            // [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ços, "Product": produtos, "TaxDescriptor": descritores. Por omissão, "Service".
            // Se o item for indicado, usar apenas um dos dois campos seguintes (o "id" ou o código). Se se indicarem os dois, então devem ser consistentes entre si, e consistentes com o "item_type".
            "item_id": 1,                                           // [OPCIONAL] Identificador interno do item. Ver NOTA 8.
            "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 pelo campo "item_id", se indicado. 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 um dos dois campos seguintes (o "id" ou o código). Se se indicarem os dois, então devem ser consistentes entre si.
            "unit_of_measure_id": 1,                                // [OPCIONAL] Identificador interno da unidade de medida. Ver NOTA 9.
            "unit_of_measure": "Unidade de medida",                 // [OPCIONAL] Por omissão é a configurada no item (se for serviço ou produto), ou a por omissão na empresa.
            // Quantidades e valores. [OBRIGATÓRIO] Para linhas de descrição valorizadas.
            "quantity": 1,                                          // [OPCIONAL] Por omissão 1, se não for uma linha de descrição valorizada. [OBRIGAtÒRIO] Para uma linha de descrição valorizada.
            "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 valorizada.
            "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 ou o campo "id" ou um ou mais dos três campos seguintes. Se se indicarem todos os campos, então devem ser consistentes entre si.
            "tax_id": 1,                                            // [OPCIONAL] Identificador interno da taxa de IVA. Ver NOTA 10.
            "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.
        },
        // Outras linhas, se existirem
        ...
    ]
}

• 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]= 

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

• NOTA 8: 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 9: 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 10: 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>

Para as faturas-recibos (FR), o recibo associado é criado automaticamente quando a FR é finalizada.

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//v1/commercial_sales_documents/{id}

Path parameters

id*integer

id of the document to delete

Response

200

OK

Request

JavaScriptCurlPython

const response = await fetch('//v1/commercial_sales_documents/{id}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

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

Finalização do documento

O documento pode ser imediatamente finalizado aquando da sua criação (ver o ponto anterior, atributo "finalize"). Mas pode ser deixado em preparação, e finalizado depois, por meio de um pedido adicional.

PATCH//v1/commercial_sales_documents/{id}/finalize

Path parameters

id*integer

id of the document to finalize

Body

application/json

return_pdfboolean

Example: true

Response

200

OK

Body

application/json

idinteger

Example: 1

document_typestring

Example: "FT|FS|FR"

datestring

Example: "2023-01-01"

document_series_idinteger

Example: 1

document_series_prefixstring

Example: "Prefixo da série"

customer_idinteger

Example: 1

customer_tax_registration_numberstring

Example: "999999990"

customer_business_namestring

Example: "Nome do cliente"

customer_address_detailstring

Example: "Morada do cliente"

customer_postcodestring

Example: "0000-000"

customer_citystring

Example: "Cidade/Localidade do cliente"

customer_countrystring

Example: "PT"

due_datestring

Example: "2023-01-01"

settlement_expressionstring

Example: "7.5"

payment_mechanismstring

Example: "MO|CH|DC|CC|TR|CO|CS|DE|LC|MB|OU|RT|DDA"

bank_account_idinteger

Example: 1

cash_account_idinteger

Example: 1

vat_included_pricesboolean

Example: false

tax_exemption_reason_idinteger

Example: 1

operation_countrystring

Example: "PT-MA"

currency_idinteger

Example: 1

currency_iso_codestring

Example: "USD"

currency_conversion_ratenumber

Example: 1.21

retentionnumber

Example: 7.5

retention_typestring

Example: "IRS|IRC"

apply_retention_when_paidboolean

Example: true

notesstring

Example: "Notas ao documento"

external_referencestring

Example: "Referência do documento externo"

urlstring

Example: "https://app.cloudware.pt/path_to_file"

linesarray of object

Request

JavaScriptCurlPython

const response = await fetch('//v1/commercial_sales_documents/{id}/finalize', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

{
  "id": 1,
  "document_type": "FT|FS|FR",
  "date": "2023-01-01",
  "document_series_id": 1,
  "document_series_prefix": "Prefixo da série",
  "customer_id": 1,
  "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",
  "bank_account_id": 1,
  "cash_account_id": 1,
  "vat_included_prices": false,
  "tax_exemption_reason_id": 1,
  "operation_country": "PT-MA",
  "currency_id": 1,
  "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",
  "url": "https://app.cloudware.pt/path_to_file",
  "lines": [
    {
      "id": 1,
      "item_type": "Service|Product|TaxDescriptor",
      "item_id": 1,
      "item_code": "Código do serviço/produto/descritor",
      "description": "Descrição da linha",
      "unit_of_measure_id": 1,
      "unit_of_measure": "Unidade de medida",
      "quantity": 1,
      "unit_price": 9.99,
      "settlement_expression": "3",
      "tax_id": 1,
      "tax_code": "NOR|INT|RED|ISE",
      "tax_percentage": 22,
      "tax_country_region": "PT-MA"
    }
  ]
}

curl -v -X PATCH -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' -d '<payload JSON>' '<API_URL>/v1/commercial_sales_documents/<id do documento>/finalize'

O payload JSON a enviar contém a seguinte informação:

{
    "return_pdf": true                                              // [OPCIONAL] Se materializa e devolve logo o PDF do documento (true) ou não (false). Por omissão, false.
}

Anulação do documento

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

PATCH//v1/commercial_sales_documents/{id}/void

Path parameters

id*integer

id of the document to void

Body

application/json

voided_reason*string

Example: "Texto descritivo do motivo de anulação"

Response

200

OK

Body

application/json

idinteger

Example: 1

document_typestring

Example: "FT|FS|FR"

datestring

Example: "2023-01-01"

document_series_idinteger

Example: 1

document_series_prefixstring

Example: "Prefixo da série"

customer_idinteger

Example: 1

customer_tax_registration_numberstring

Example: "999999990"

customer_business_namestring

Example: "Nome do cliente"

customer_address_detailstring

Example: "Morada do cliente"

customer_postcodestring

Example: "0000-000"

customer_citystring

Example: "Cidade/Localidade do cliente"

customer_countrystring

Example: "PT"

due_datestring

Example: "2023-01-01"

settlement_expressionstring

Example: "7.5"

payment_mechanismstring

Example: "MO|CH|DC|CC|TR|CO|CS|DE|LC|MB|OU|RT|DDA"

bank_account_idinteger

Example: 1

cash_account_idinteger

Example: 1

vat_included_pricesboolean

Example: false

tax_exemption_reason_idinteger

Example: 1

operation_countrystring

Example: "PT-MA"

currency_idinteger

Example: 1

currency_iso_codestring

Example: "USD"

currency_conversion_ratenumber

Example: 1.21

retentionnumber

Example: 7.5

retention_typestring

Example: "IRS|IRC"

apply_retention_when_paidboolean

Example: true

notesstring

Example: "Notas ao documento"

external_referencestring

Example: "Referência do documento externo"

urlstring

Example: "https://app.cloudware.pt/path_to_file"

linesarray of object

Request

JavaScriptCurlPython

const response = await fetch('//v1/commercial_sales_documents/{id}/void', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "voided_reason": "Texto descritivo do motivo de anulação"
    }),
});
const data = await response.json();

Response

200

{
  "id": 1,
  "document_type": "FT|FS|FR",
  "date": "2023-01-01",
  "document_series_id": 1,
  "document_series_prefix": "Prefixo da série",
  "customer_id": 1,
  "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",
  "bank_account_id": 1,
  "cash_account_id": 1,
  "vat_included_prices": false,
  "tax_exemption_reason_id": 1,
  "operation_country": "PT-MA",
  "currency_id": 1,
  "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",
  "url": "https://app.cloudware.pt/path_to_file",
  "lines": [
    {
      "id": 1,
      "item_type": "Service|Product|TaxDescriptor",
      "item_id": 1,
      "item_code": "Código do serviço/produto/descritor",
      "description": "Descrição da linha",
      "unit_of_measure_id": 1,
      "unit_of_measure": "Unidade de medida",
      "quantity": 1,
      "unit_price": 9.99,
      "settlement_expression": "3",
      "tax_id": 1,
      "tax_code": "NOR|INT|RED|ISE",
      "tax_percentage": 22,
      "tax_country_region": "PT-MA"
    }
  ]
}

curl -v -X PATCH -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' -d '<payload JSON>' '<API_URL>/v1/commercial_sales_documents/<id do documento>/void'

Alteração do documento

Após a sua criação, e enquanto estiver em preparação, o documento pode ser alterado. A estrutura do payload é a mesma do POST de criação, incluindo cabeçalho e linhas. Os atributos enviados irão substituir os guardados no momento.

Relativamente às linhas:

• Para cada linha enviada com indicação do atributo "id", os atributos enviados irão substituir os guardados no momento na linha com esse mesmo "id".

• Cada linha enviada sem indicação do atributo "id" será considerada uma linha nova, e será acrescentada ao documento.

• Para eliminar uma linha existente, deverá usar-se a rota respectiva (ver Eliminação de uma linha).

O pedido de alteração pode também incluir, e ser aproveitado para, a finalização do documento — usando o atributo "finalize" — e/ou para a sua materialização em PDF — usando o atributo "return_pdf".

PATCH//v1/commercial_sales_documents/{id}

Path parameters

id*integer

id of the document to update

Body

application/json

idinteger

Example: 1

document_typestring

Example: "FT|FS|FR"

datestring

Example: "2023-01-01"

document_series_idinteger

Example: 1

document_series_prefixstring

Example: "Prefixo da série"

customer_idinteger

Example: 1

customer_tax_registration_numberstring

Example: "999999990"

customer_business_namestring

Example: "Nome do cliente"

customer_address_detailstring

Example: "Morada do cliente"

customer_postcodestring

Example: "0000-000"

customer_citystring

Example: "Cidade/Localidade do cliente"

customer_countrystring

Example: "PT"

due_datestring

Example: "2023-01-01"

settlement_expressionstring

Example: "7.5"

payment_mechanismstring

Example: "MO|CH|DC|CC|TR|CO|CS|DE|LC|MB|OU|RT|DDA"

bank_account_idinteger

Example: 1

cash_account_idinteger

Example: 1

vat_included_pricesboolean

Example: false

tax_exemption_reason_idinteger

Example: 1

operation_countrystring

Example: "PT-MA"

currency_idinteger

Example: 1

currency_iso_codestring

Example: "USD"

currency_conversion_ratenumber

Example: 1.21

retentionnumber

Example: 7.5

retention_typestring

Example: "IRS|IRC"

apply_retention_when_paidboolean

Example: true

notesstring

Example: "Notas ao documento"

external_referencestring

Example: "Referência do documento externo"

finalizeboolean

Example: true

return_pdfboolean

Example: true

linesarray of object

Response

200

OK

Body

application/json

idinteger

Example: 1

document_typestring

Example: "FT|FS|FR"

datestring

Example: "2023-01-01"

document_series_idinteger

Example: 1

document_series_prefixstring

Example: "Prefixo da série"

customer_idinteger

Example: 1

customer_tax_registration_numberstring

Example: "999999990"

customer_business_namestring

Example: "Nome do cliente"

customer_address_detailstring

Example: "Morada do cliente"

customer_postcodestring

Example: "0000-000"

customer_citystring

Example: "Cidade/Localidade do cliente"

customer_countrystring

Example: "PT"

due_datestring

Example: "2023-01-01"

settlement_expressionstring

Example: "7.5"

payment_mechanismstring

Example: "MO|CH|DC|CC|TR|CO|CS|DE|LC|MB|OU|RT|DDA"

bank_account_idinteger

Example: 1

cash_account_idinteger

Example: 1

vat_included_pricesboolean

Example: false

tax_exemption_reason_idinteger

Example: 1

operation_countrystring

Example: "PT-MA"

currency_idinteger

Example: 1

currency_iso_codestring

Example: "USD"

currency_conversion_ratenumber

Example: 1.21

retentionnumber

Example: 7.5

retention_typestring

Example: "IRS|IRC"

apply_retention_when_paidboolean

Example: true

notesstring

Example: "Notas ao documento"

external_referencestring

Example: "Referência do documento externo"

urlstring

Example: "https://app.cloudware.pt/path_to_file"

linesarray of object

Request

JavaScriptCurlPython

const response = await fetch('//v1/commercial_sales_documents/{id}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

{
  "id": 1,
  "document_type": "FT|FS|FR",
  "date": "2023-01-01",
  "document_series_id": 1,
  "document_series_prefix": "Prefixo da série",
  "customer_id": 1,
  "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",
  "bank_account_id": 1,
  "cash_account_id": 1,
  "vat_included_prices": false,
  "tax_exemption_reason_id": 1,
  "operation_country": "PT-MA",
  "currency_id": 1,
  "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",
  "url": "https://app.cloudware.pt/path_to_file",
  "lines": [
    {
      "id": 1,
      "item_type": "Service|Product|TaxDescriptor",
      "item_id": 1,
      "item_code": "Código do serviço/produto/descritor",
      "description": "Descrição da linha",
      "unit_of_measure_id": 1,
      "unit_of_measure": "Unidade de medida",
      "quantity": 1,
      "unit_price": 9.99,
      "settlement_expression": "3",
      "tax_id": 1,
      "tax_code": "NOR|INT|RED|ISE",
      "tax_percentage": 22,
      "tax_country_region": "PT-MA"
    }
  ]
}

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

Eliminação de uma linha

DELETE//v1/commercial_sales_documents/{id}/lines/{lineId}

Path parameters

id*integer

id of the document

lineId*integer

id of the document line to delete

Response

200

OK

Request

JavaScriptCurlPython

const response = await fetch('//v1/commercial_sales_documents/{id}/lines/{lineId}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

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

Consulta do documento

Os documentos podem ser consultados a qualquer altura, antes ou depois de finalizados, e mesmo depois de anulados.

GET//v1/commercial_sales_documents/{id}

Path parameters

id*integer

id of the document of which to get the information

Response

200

OK

Body

application/json

idinteger

Example: 1

document_typestring

Example: "FT|FS|FR"

datestring

Example: "2023-01-01"

document_series_idinteger

Example: 1

document_series_prefixstring

Example: "Prefixo da série"

customer_idinteger

Example: 1

customer_tax_registration_numberstring

Example: "999999990"

customer_business_namestring

Example: "Nome do cliente"

customer_address_detailstring

Example: "Morada do cliente"

customer_postcodestring

Example: "0000-000"

customer_citystring

Example: "Cidade/Localidade do cliente"

customer_countrystring

Example: "PT"

due_datestring

Example: "2023-01-01"

settlement_expressionstring

Example: "7.5"

payment_mechanismstring

Example: "MO|CH|DC|CC|TR|CO|CS|DE|LC|MB|OU|RT|DDA"

bank_account_idinteger

Example: 1

cash_account_idinteger

Example: 1

vat_included_pricesboolean

Example: false

tax_exemption_reason_idinteger

Example: 1

operation_countrystring

Example: "PT-MA"

currency_idinteger

Example: 1

currency_iso_codestring

Example: "USD"

currency_conversion_ratenumber

Example: 1.21

retentionnumber

Example: 7.5

retention_typestring

Example: "IRS|IRC"

apply_retention_when_paidboolean

Example: true

notesstring

Example: "Notas ao documento"

external_referencestring

Example: "Referência do documento externo"

urlstring

Example: "https://app.cloudware.pt/path_to_file"

linesarray of object

Request

JavaScriptCurlPython

const response = await fetch('//v1/commercial_sales_documents/{id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "id": 1,
  "document_type": "FT|FS|FR",
  "date": "2023-01-01",
  "document_series_id": 1,
  "document_series_prefix": "Prefixo da série",
  "customer_id": 1,
  "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",
  "bank_account_id": 1,
  "cash_account_id": 1,
  "vat_included_prices": false,
  "tax_exemption_reason_id": 1,
  "operation_country": "PT-MA",
  "currency_id": 1,
  "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",
  "url": "https://app.cloudware.pt/path_to_file",
  "lines": [
    {
      "id": 1,
      "item_type": "Service|Product|TaxDescriptor",
      "item_id": 1,
      "item_code": "Código do serviço/produto/descritor",
      "description": "Descrição da linha",
      "unit_of_measure_id": 1,
      "unit_of_measure": "Unidade de medida",
      "quantity": 1,
      "unit_price": 9.99,
      "settlement_expression": "3",
      "tax_id": 1,
      "tax_code": "NOR|INT|RED|ISE",
      "tax_percentage": 22,
      "tax_country_region": "PT-MA"
    }
  ]
}

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