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

Body

document_typestringRequiredExample: FT|FS|FR

datestringOptionalExample: 2023-01-01

document_series_idintegerOptionalExample: 1

document_series_prefixstringOptionalExample: Prefixo da série

customer_idintegerOptionalExample: 1

customer_tax_registration_numberstringOptionalExample: 999999990

customer_business_namestringOptionalExample: Nome do cliente

customer_address_detailstringOptionalExample: Morada do cliente

customer_postcodestringOptionalExample: 0000-000

customer_citystringOptionalExample: Cidade/Localidade do cliente

customer_countrystringOptionalExample: PT

due_datestringOptionalExample: 2023-01-01

settlement_expressionstringOptionalExample: 7.5

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

bank_account_idintegerOptionalExample: 1

cash_account_idintegerOptionalExample: 1

vat_included_pricesbooleanOptionalExample: false

tax_exemption_reason_idintegerOptionalExample: 1

operation_countrystringOptionalExample: PT-MA

currency_idintegerOptionalExample: 1

currency_iso_codestringOptionalExample: USD

currency_conversion_ratenumberOptionalExample: 1.21

retentionnumberOptionalExample: 7.5

retention_typestringOptionalExample: IRS|IRC

apply_retention_when_paidbooleanOptionalExample: true

notesstringOptionalExample: Notas ao documento

external_referencestringOptionalExample: Referência do documento externo

finalizebooleanOptionalExample: true

return_pdfbooleanOptionalExample: true

Responses

200

application/json

post

/v1/commercial_sales_documents

POST /v1/commercial_sales_documents HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 1245

{
  "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",
  "finalize": true,
  "return_pdf": true,
  "lines": [
    {
      "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"
    }
  ]
}

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

Path parameters

idintegerRequired

id of the document to delete

Responses

200

No content

delete

/v1/commercial_sales_documents/{id}

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

200

No content

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

Path parameters

idintegerRequired

id of the document to finalize

Body

return_pdfbooleanOptionalExample: true

Responses

200

application/json

patch

/v1/commercial_sales_documents/{id}/finalize

PATCH /v1/commercial_sales_documents/{id}/finalize HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 19

{
  "return_pdf": true
}

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

Path parameters

idintegerRequired

id of the document to void

Body

voided_reasonstringRequiredExample: Texto descritivo do motivo de anulação

Responses

200

application/json

patch

/v1/commercial_sales_documents/{id}/void

PATCH /v1/commercial_sales_documents/{id}/void HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 60

{
  "voided_reason": "Texto descritivo do motivo de anulação"
}

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

Path parameters

idintegerRequired

id of the document to update

Body

idintegerOptionalExample: 1

document_typestringOptionalExample: FT|FS|FR

datestringOptionalExample: 2023-01-01

document_series_idintegerOptionalExample: 1

document_series_prefixstringOptionalExample: Prefixo da série

customer_idintegerOptionalExample: 1

customer_tax_registration_numberstringOptionalExample: 999999990

customer_business_namestringOptionalExample: Nome do cliente

customer_address_detailstringOptionalExample: Morada do cliente

customer_postcodestringOptionalExample: 0000-000

customer_citystringOptionalExample: Cidade/Localidade do cliente

customer_countrystringOptionalExample: PT

due_datestringOptionalExample: 2023-01-01

settlement_expressionstringOptionalExample: 7.5

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

bank_account_idintegerOptionalExample: 1

cash_account_idintegerOptionalExample: 1

vat_included_pricesbooleanOptionalExample: false

tax_exemption_reason_idintegerOptionalExample: 1

operation_countrystringOptionalExample: PT-MA

currency_idintegerOptionalExample: 1

currency_iso_codestringOptionalExample: USD

currency_conversion_ratenumberOptionalExample: 1.21

retentionnumberOptionalExample: 7.5

retention_typestringOptionalExample: IRS|IRC

apply_retention_when_paidbooleanOptionalExample: true

notesstringOptionalExample: Notas ao documento

external_referencestringOptionalExample: Referência do documento externo

finalizebooleanOptionalExample: true

return_pdfbooleanOptionalExample: true

Responses

200

application/json

patch

/v1/commercial_sales_documents/{id}

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

{
  "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",
  "finalize": true,
  "return_pdf": true,
  "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"
    }
  ]
}

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

Path parameters

idintegerRequired

id of the document

lineIdintegerRequired

id of the document line to delete

Responses

200

No content

delete

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

DELETE /v1/commercial_sales_documents/{id}/lines/{lineId} HTTP/1.1
Accept: */*

200

No content

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

Path parameters

idintegerRequired

id of the document of which to get the information

Responses

200

application/json

get

/v1/commercial_sales_documents/{id}

GET /v1/commercial_sales_documents/{id} HTTP/1.1
Accept: */*

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

PreviousIntrodução à API v1 NextRecibos

Last updated 2 years ago

hashtagCriação do documento

hashtagEliminação do documento

hashtagFinalização do documento

hashtagAnulação do documento

hashtagAlteração do documento

hashtagEliminação de uma linha

hashtagConsulta do documento

Criação do documento

Eliminação do documento

Finalização do documento

Anulação do documento

Alteração do documento

Eliminação de uma linha

Consulta do documento