Notas de liquidação de compra

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

As notas de liquidação têm a mesma estrutura que os restantes documentos de compra. 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 compra: 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

post

Body

application/json

document_typestringRequiredExample: FC|DSP

datestringOptionalExample: 2023-01-01

document_series_idintegerOptionalExample: 1

document_series_prefixstringOptionalExample: Prefixo da série

supplier_idintegerOptionalExample: 1

supplier_tax_registration_numberstringOptionalExample: 999999990

supplier_business_namestringOptionalExample: Nome do fornecedor

supplier_address_detailstringOptionalExample: Morada do fornecedor

supplier_postcodestringOptionalExample: 0000-000

supplier_citystringOptionalExample: Cidade/Localidade do fornecedor

supplier_countrystringOptionalExample: PT

due_datestringOptionalExample: 2023-02-01

settlement_expressionstringOptionalExample: 7.5

vat_included_pricesbooleanOptionalExample: false

tax_exemption_reason_idintegerOptionalExample: 1

currency_idintegerOptionalExample: 1

currency_iso_codestringOptionalExample: USD

currency_conversion_ratenumberOptionalExample: 1.21

retention_totalnumberOptionalExample: 9.99

retention_typestringOptionalExample: TD|TI|C|P|CPS|O

notesstringOptionalExample: Notas ao documento

external_referencestringOptionalExample: Referência do documento externo

finalizebooleanOptionalExample: true

return_pdfbooleanOptionalExample: true

Responses

200

OK

application/json

idintegerOptionalExample: 1

document_typestringOptionalExample: FC|DSP

datestringOptionalExample: 2023-01-01

document_series_idintegerOptionalExample: 1

document_series_prefixstringOptionalExample: Prefixo da série

supplier_idintegerOptionalExample: 1

supplier_tax_registration_numberstringOptionalExample: 999999990

supplier_business_namestringOptionalExample: Nome do fornecedor

supplier_address_detailstringOptionalExample: Morada do fornecedor

supplier_postcodestringOptionalExample: 0000-000

supplier_citystringOptionalExample: Cidade/Localidade do fornecedor

supplier_countrystringOptionalExample: PT

due_datestringOptionalExample: 2023-02-01

settlement_expressionstringOptionalExample: 7.5

vat_included_pricesbooleanOptionalExample: false

tax_exemption_reason_idintegerOptionalExample: 1

currency_idintegerOptionalExample: 1

currency_iso_codestringOptionalExample: USD

currency_conversion_ratenumberOptionalExample: 1.21

retention_totalnumberOptionalExample: 9.99

retention_typestringOptionalExample: TD|TI|C|P|CPS|O

notesstringOptionalExample: Notas ao documento

external_referencestringOptionalExample: Referência do documento externo

urlstringOptionalExample: https://app.cloudware.pt/path_to_file

post

/v1/commercial_purchases_documents

HTTPcURLJavaScriptPython

POST /v1/commercial_purchases_documents HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 1112

{
  "document_type": "FC|DSP",
  "date": "2023-01-01",
  "document_series_id": 1,
  "document_series_prefix": "Prefixo da série",
  "supplier_id": 1,
  "supplier_tax_registration_number": "999999990",
  "supplier_business_name": "Nome do fornecedor",
  "supplier_address_detail": "Morada do fornecedor",
  "supplier_postcode": "0000-000",
  "supplier_city": "Cidade/Localidade do fornecedor",
  "supplier_country": "PT",
  "due_date": "2023-02-01",
  "settlement_expression": "7.5",
  "vat_included_prices": false,
  "tax_exemption_reason_id": 1,
  "currency_id": 1,
  "currency_iso_code": "USD",
  "currency_conversion_rate": 1.21,
  "retention_total": 9.99,
  "retention_type": "TD|TI|C|P|CPS|O",
  "notes": "Notas ao documento",
  "external_reference": "Referência do documento externo",
  "finalize": true,
  "return_pdf": true,
  "lines": [
    {
      "item_type": "Product|Purchases::ExpenseCategory",
      "item_id": 1,
      "item_code": "Código do produto/categoria de despesas",
      "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"
    }
  ]
}

200

OK

{
  "id": 1,
  "document_type": "FC|DSP",
  "date": "2023-01-01",
  "document_series_id": 1,
  "document_series_prefix": "Prefixo da série",
  "supplier_id": 1,
  "supplier_tax_registration_number": "999999990",
  "supplier_business_name": "Nome do fornecedor",
  "supplier_address_detail": "Morada do fornecedor",
  "supplier_postcode": "0000-000",
  "supplier_city": "Cidade/Localidade do fornecedor",
  "supplier_country": "PT",
  "due_date": "2023-02-01",
  "settlement_expression": "7.5",
  "vat_included_prices": false,
  "tax_exemption_reason_id": 1,
  "currency_id": 1,
  "currency_iso_code": "USD",
  "currency_conversion_rate": 1.21,
  "retention_total": 9.99,
  "retention_type": "TD|TI|C|P|CPS|O",
  "notes": "Notas ao documento",
  "external_reference": "Referência do documento externo",
  "url": "https://app.cloudware.pt/path_to_file",
  "lines": [
    {
      "id": 1,
      "item_type": "Product|Purchases::ExpenseCategory",
      "item_id": 1,
      "item_code": "Código do produto/categoria de despesas",
      "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_purchases_documents'

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

{
  // Identificação do documento
  "document_type": "NLCF|NLDF",                                   // [OBRIGATÓRIO] Tipo de documento. "NLCF": nota de liquidação a crédito; "NLDF": 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 fornecedor. Por omissão, é o fornecedor indiferenciado (NIF "999999990").
  // Se o fornecedor for indicado, usar apenas um dos dois campos seguintes (o "id" ou o NIF). Se se indicarem os dois, então devem ser consistentes.
  "supplier_id": 1,                                               // [OPCIONAL] Identificador interno do fornecedor. Ver NOTA 1.
  "supplier_tax_registration_number": "999999990",                // [OPCIONAL] NIF do fornecedor. O fornecedor com o NIF indicado deverá já existir Se for um fornecedor 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 fornecedor for identificado pelo seu "id" interno tem já que existir, e o seu "id" interno pode ser obtido por um

GET /suppliers?filter[tax_registration_number]=<o NIF do fornecedor>

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