Notas de liquidação de venda

As rotas aqui descritas permitem gerir todos os processos relativos a notas de liquidação de venda, tanto a débito como a crédito.

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

Todos os pedidos descritos são formalmente semelhantes aos pedidos correspondentes dos restantes documentos de venda: as rotas utilizados são as mesmas, e os payloads JSON a enviar são estruturalmente semelhantes, partilhando os mesmos atributos.

Criação da nota de liquidação

POSThttps://api-cwb.cldware.com/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('https://api-cwb.cldware.com/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": "NLC|NLD",                                     // [OBRIGATÓRIO] Tipo de documento. "NLC": nota de liquidação a crédito; "NLD": nota de liquidação a débito.
  "date": "2023-01-01",                                           // [OPCIONAL] Data do documento; por omissão, a data do pedido.

  // [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 1.
  "customer_tax_registration_number": "999999990",                // [OPCIONAL] NIF do cliente. O cliente com o NIF indicado deverá já existir. Se for um cliente português ("PT", "PT-AC" ou "PT-MA"), deve ser um NIF português válido.

  // [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 2.
  "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] Identificação do documento sobre o qual a nota está a ser emitida. Por omissão, a nota não ficará associada a nenhum documento.
  "parent_documents_ids": "{1}",                                  // [OPCIONAL] Identificador interno do documento ao qual a nota está associada.

  // [OPCIONAL] Outras informações
  "notes": "Notas ao documento",                                  // [OPCIONAL]

  // [OPCIONAL] Instruções de processamento do documento 
  "finalize": true,                                               // [OPCIONAL] O documento deve ser imediatamente finalizado (true) ou deixado em preparação (false)? Por omissão, o documento é deixado em preparação.
  "return_pdf": false,                                            // [OPCIONAL] O documento deve ser imediatamente materializado (true), ou não (false)? Caso se opte pela materialização do documento, será devolvido um link para o respectivo PDF. Por omissão, o documento não é materializado.

  // [OBRIGATÓRIO] Linhas do documento

  "lines": [
      {
          "description": "Descrição da linha",                    // [OBRIGATÓRIO] A descrição do valor a liquidar.
          "amount": 100.50                                        // [OBRIGATÓRIO] O valor a liquidar.
      },
      // Outras linhas, se existirem
      ...
  ]
}

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

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

Eliminação da nota de liquidação

Ver Eliminação do documento.

Finalização da nota de liquidação

Ver Finalização do documento.

Anulação da nota de liquidação

Ver Anulação do documento.

Alteração da nota de liquidação

Ver Alteração do documento.

Eliminação de uma linha

Ver Eliminação de uma linha.

Consulta da nota de liquidação

Ver Consulta do documento.