Documentos de Compra

Criação de Documentos de Compra

Para a criação de compras no sistema, é necessário seguir dois passos principais: a criação do cabeçalho e a inserção de uma ou mais linhas correspondentes aos itens adquiridos.

1. Cabeçalho da Compra: O cabeçalho contém informações gerais sobre a compra, como data, fornecedor e condições de pagamento.

2. Linhas da Compra: Cada linha detalha um item específico comprado, incluindo a descrição, quantidade e preço.

3. Finalização de Documento de Compra

1. Criar Cabeçalho de Documentos de Compra

De modo a criar uma compra, deverá inicialmente criar o cabeçalho do documento. Para este efeito, deverá realizar o seguinte pedido:

Criar Linha de Documentos de Venda para um Produto

Criar Linha de Documentos de Venda para um Produto

POST{{base_url}}/api/commercial_sales_document_lines

Body

application/json

dataobject

Response

200

Sucesso / Criar Linha de Documentos de Venda para um Serviço / Criar Linha de Documentos de Venda para um Descritor / Criar Linha de Documento de Venda para uma Descrição Sem Valor

Headers

Body

application/json

dataobject

metaobject

Request

JavaScriptCurlPython

const response = await fetch('{{base_url}}/api/commercial_sales_document_lines', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "data": {
        "attributes": {
          "description": "<p>Descrição da linha</p>",
          "document_id": 66,
          "__$markdownParsed": true
        },
        "type": "commercial_sales_document_lines"
      }
    }),
});
const data = await response.json();

Response

200

{
  "data": {
    "attributes": {
      "amount": 10.13,
      "amount_with_header_settlement": 10.95,
      "base_currency_amount": null,
      "base_currency_net_amount": null,
      "base_currency_net_unit_price": null,
      "base_currency_settlement_with_tax": null,
      "base_currency_settlement_without_tax": null,
      "base_currency_tax_amount": null,
      "base_currency_unit_price": null,
      "created_at": "2024-03-05 14:25:52.160841",
      "date": null,
      "description": "Isto é uma breve descrição",
      "exemption_reason": null,
      "imported_quantity": null,
      "item_code": "1000",
      "item_id": 2,
      "item_type": "Product",
      "item_unit_price_includes_vat": false,
      "locked": null,
      "net_amount": 8.96,
      "net_amount_with_header_settlement": 9.69,
      "net_settlement_amount": null,
      "net_tax_amount": null,
      "net_unit_price": 8.9635,
      "original_document_no": null,
      "pending_quantity": 1,
      "pending_retention_value": null,
      "pending_total": null,
      "quantity": 1,
      "retention_value": null,
      "settlement_amount": 0.3,
      "settlement_expression": "3",
      "settlement_percentage": 3,
      "settlement_with_tax": 0.34,
      "settlement_without_tax": 0.3,
      "tax_amount": 1.17,
      "tax_code": "INT",
      "tax_country_region": "PT",
      "tax_descriptor_id": null,
      "tax_percentage": 13,
      "unit_price": 9.99,
      "updated_at": "2024-03-05 14:25:52.160841"
    },
    "id": "132",
    "relationships": {
      "document": {
        "data": {
          "id": "66",
          "type": "commercial_sales_documents"
        }
      },
      "product": {
        "data": null
      },
      "service": {
        "data": null
      },
      "tax": {
        "data": {
          "id": "2",
          "type": "taxes"
        }
      },
      "tax_descriptor": {
        "data": null
      },
      "unit_of_measure": {
        "data": {
          "id": "2",
          "type": "units_of_measure"
        }
      }
    },
    "type": "commercial_sales_document_lines"
  },
  "meta": {
    "observed": {
      "lines": 1,
      "scalar": 1
    }
  }
}

No pedido acima, o <access_token> corresponde ao token de acesso válido devolvido pelo serviço de OAuth

Caso a compra seja realizada em euros, o <payload JSON> deverá vir de acordo com os exemplos seguintes:

1.1 Criar Cabeçalho de Documento de Venda para uma Nova Empresa

{
  "data": {
    "type": "commercial_purchases_documents",
    "attributes": {
      "document_type": "FC", //[OBRIGATÓRIO] Pode ser FC (fatura de compra), NCF (nota de crédito), NDF (nota de débito), DSP (fatura de despesaa)
      "date": "2020-05-25", // Por omissão, a data de hoje
      "due_date": "2020-05-25", // Por omissão, a data do documento
      "currency_conversion_rate": 0.813 // Obrigatório quando a moeda não é EUR. Taxa de conversão da moeda para EUR (1 EUR = x)
      "supplier_tax_registration_number": "888888880", // Por omissão, o fornecedor indiferenciado (999999990)
      
      //**** Para uma empresa que já existe
      "company_id": 2,

      //id da moeda usada
      "currency_id" :2
      
      //id de um fornecedor
      "supplier_id": 2,
      
      // Indicar o atributo seguinte, com o valor true, apenas se os preços indicados nas linhas forem preços com IVA incluído
      "external_reference": "Texto livre, referente ao campo Vossa Ref.", //
      "vat_included_prices": true,
      // Indicar o atributo seguinte apenas se existir desconto de cabeçalho (7,5%, neste exemplo)
      "settlement_expression": "7.5",
      // Indicar o atributo seguinte apenas se existir retenção (10€, neste exemplo)
      "retention_total": 10
      
      // Associação à série de documentos. Pode ser omitida, se for para usar a série por omissão
     "commercial_document_series_id": "<id da série de documentos associada>" // Este id pode ser obtido por um GET /commercial_document_series?filter[document_type]=FC|NCF|...&filter[prefix]=2020|ou outro qualquer...
    }
  }
}

Após criar o cabeçalho, a resposta TEM QUE ser consultada para obtenção do identificador interno ("id") da compra criada. Este identificador será necessário para a criação de todas as linhas.

1.2 Criar Cabeçalho de Documento de Venda para uma Empresa Existente

{
  "data": {
    "type": "commercial_purchases_documents",
    "attributes": {
      "document_type": "FC", //[OBRIGATÓRIO] Pode ser FC (fatura de compra), NCF (nota de crédito), NDF (nota de débito), DSP (fatura de despesaa)
      "date": "2020-05-25", // Por omissão, a data de hoje
      "due_date": "2020-05-25", // Por omissão, a data do documento
      "currency_conversion_rate": 0.813 // Obrigatório quando a moeda não é EUR. Taxa de conversão da moeda para EUR (1 EUR = x)
      "supplier_tax_registration_number": "888888880", // Por omissão, o fornecedor indiferenciado (999999990)

      //**** Para uma empresa que já existe
      "company_id": 2,
      
      // Indicar o atributo seguinte, com o valor true, apenas se os preços indicados nas linhas forem preços com IVA incluído
      "external_reference": "Texto livre, referente ao campo Vossa Ref.", //
      "vat_included_prices": true,
      // Indicar o atributo seguinte apenas se existir desconto de cabeçalho (7,5%, neste exemplo)
      "settlement_expression": "7.5",
      // Indicar o atributo seguinte apenas se existir retenção (10€, neste exemplo)
      "retention_total": 10
      
      // Associação à série de documentos. Pode ser omitida, se for para usar a série por omissão
     "commercial_document_series_id": "<id da série de documentos associada>" // Este id pode ser obtido por um GET /commercial_document_series?filter[document_type]=FC|NCF|...&filter[prefix]=2020|ou outro qualquer...
    }
  }
}

2. Criar Linhas de Documentos de Compra

Em todos os pedidos seguintes, é necessário saber qual o id do documento de compra. Este id pode ser guardado a partir da resposta (JSON) ao pedido de criação anterior, ou pode ser consultado via API. Via API, o id do documento pode ser obtido por um filtro a todos os Documentos de Compra usando o número do documento (finalizado).

GET /commercial_purchases_documents?filter[document_no]=<número do documento, ex: FC 2020/1> 

Se o documento ainda não estiver finalizado (fechado), então ainda não tem número atribuído, e o GET anterior não poderá ser feito! Em alternativa pode realizado um filtro a todos os Documentos de Compra usando o estado do documento e número de registro fiscal do fornecedor.

GET /commercial_purchases_documents?filter[status]=0&filter[supplier_tax_registration_number]=<número de registro fiscal do fornecedor>

De modo a inserir linhas na compra criada, deverá realizar o seguinte pedido

Adicionar Linha a Pagamentos

Adicionar Linha a Pagamentos

POST{{base_url}}/api/commercial_purchases_payment_lines

Body

application/json

dataobject

Response

200

Request

JavaScriptCurlPython

const response = await fetch('{{base_url}}/api/commercial_purchases_payment_lines', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "data": {
        "attributes": {
          "paid_value": 50,
          "payable_id": 2,
          "payable_type": "Purchases::Document",
          "settlement_percentage": 3
        },
        "type": "commercial_purchases_payment_lines"
      }
    }),
});
const data = await response.json();

No pedido acima, o <access_token> corresponde ao token de acesso válido devolvido pelo serviço de OAuth. O payload JSON deverá vir no seguinte formato, dependendo se se trata de um produto, ou categoria de despesa.

Nos documentos de despesas (tipo de documento DSP), só são aceites linhas de Categorias de Despesa, não de Produtos.

2.1 Criar Linha para Produto

{
  "data": {
    "type": "commercial_purchases_document_lines",
    "attributes": {
      "quantity": 1,
      "unit_price": 20,
      "item_type": "Product",
      "item_code": "PTEST", // NOTA: já tem que existir o produto com este código
      // Indicar o atributo seguinte apenas se existir desconto de linha (3%, neste exemplo)
      "settlement_expression":"3",
      "document_id": 2, // Associação ao documento de compra
      "tax_id":1  // O id da taxa de IVA pode ser obtido por um GET /taxes?filter[tax_code]=NOR|INT|RED|ISE
    }
  }
}

2.2 Criar Linha para Categoria de Despesas

{
  "data": {
    "type": "commercial_purchases_document_lines",
    "attributes": {
      "quantity": 1,
      "unit_price": 20,
      "item_type": "Purchases::ExpenseCategory",
      "item_code": "ETEST", // NOTA: já tem que existir a categoria de despesa com este código
    
      "documet_id": 2,
      "tax_id": 2
    }
  }
}

Para mais informações acerca de Categorias de Despesa visite a página: Categorias de Despesa

3. Finalização de um Documento de Compra

Finalizar Documentos de Compra

Finalizar Documentos de Compra

PATCH{{base_url}}/api/v1/commercial_purchases_documents/{id}/finalize

Path parameters

id*string

Example: "41"

Body

application/json

object

Response

200

Finalizar Documentos de Compra

Headers

Body

application/json

acts_as_shipment_documentnullable any

apply_retention_when_paidnullable any

base_currency_gross_totalnullable any

base_currency_net_totalnullable any

base_currency_pending_totalnullable any

base_currency_retention_totalnullable any

base_currency_settlement_totalnullable any

base_currency_vat_incidence_intnullable any

base_currency_vat_incidence_isenullable any

base_currency_vat_incidence_nornullable any

base_currency_vat_incidence_rednullable any

base_currency_vat_total_intnullable any

base_currency_vat_total_nornullable any

base_currency_vat_total_rednullable any

cashed_vatnullable any

child_documents_idsnullable any

communication_codenullable any

communication_code_sourcenullable any

communication_statusnullable any

company_idnumber

Example: 800000046

created_atstring

Example: "2024-03-06 10:52:52.637757"

currency_conversion_ratenumber

Example: 1

currency_idnumber

Example: 1

currency_iso_codestring

Example: "EUR"

datestring

Example: "2024-03-06"

document_areastring

Example: "FC"

document_hash_sumnullable any

document_nostring

Example: "FC 2023/4"

document_series_idnumber

Example: 125

document_series_prefixstring

Example: "2023"

document_typestring

Example: "FC"

due_datestring

Example: "2024-03-06"

emailednullable any

external_referencestring

Example: ""

gross_totalnumber

Example: 0

hash_controlnullable any

idnumber

Example: 41

is_third_partynullable any

line_settlement_with_taxnumber

Example: 0

line_settlement_with_tax_unroundednumber

Example: 0

line_settlement_without_taxnumber

Example: 0

line_settlement_without_tax_unroundednumber

Example: 0

linesarray of object

net_totalnumber

Example: 0

notesstring

Example: ""

operation_countrynullable any

parent_document_areanullable any

parent_documents_idsnullable any

payments_idsnullable any

pending_retention_valuenumber

Example: 0

pending_totalnumber

Example: 0

printednullable any

public_linkstring

Example: ""

retentionnullable any

retention_typenullable any

retention_valuenumber

Example: 0

retention_value_unroundednumber

Example: 0

settlement_expressionnullable any

settlement_percentagenumber

Example: 0

settlement_totalnumber

Example: 0

settlement_with_taxnumber

Example: 0

settlement_with_tax_unroundednumber

Example: 0

settlement_without_taxnumber

Example: 0

settlement_without_tax_unroundednumber

Example: 0

shipment_countrynullable any

shipment_loading_address_detailnullable any

shipment_loading_citynullable any

shipment_loading_countrynullable any

shipment_loading_postcodenullable any

shipment_loading_timenullable any

shipment_unloading_address_detailnullable any

shipment_unloading_citynullable any

shipment_unloading_countrynullable any

shipment_unloading_postcodenullable any

shipment_unloading_timenullable any

statusnumber

Example: 1

supplier_address_detailstring

Example: ""

supplier_business_namestring

Example: "Fornecedor Indiferenciado"

supplier_citystring

Example: ""

supplier_countrystring

Example: "PT"

supplier_idnumber

Example: 9

supplier_postcodestring

Example: ""

supplier_tax_country_regionstring

Example: "PT"

supplier_tax_registration_numberstring

Example: "999999990"

system_entry_datestring

Example: "2024-03-06 11:06:17.132657"

tax_payablenumber

Example: 0

third_party_typenullable any

total_pending_quantitynullable any

updated_atstring

Example: "2024-03-06 11:06:17.132657"

user_idnumber

Example: 800000863

vat_incidence_intnumber

Example: 0

vat_incidence_int_unroundednumber

Example: 0

vat_incidence_isenumber

Example: 0

vat_incidence_ise_unroundednumber

Example: 0

vat_incidence_nornumber

Example: 0

vat_incidence_nor_unroundednumber

Example: 0

vat_incidence_rednumber

Example: 0

vat_incidence_red_unroundednumber

Example: 0

vat_included_pricesboolean

Example: false

vat_percentage_intnullable any

vat_percentage_nornumber

Example: 23

vat_percentage_rednullable any

vat_total_intnumber

Example: 0

vat_total_int_unroundednumber

Example: 0

vat_total_nornumber

Example: 0

vat_total_nor_unroundednumber

Example: 0

vat_total_rednumber

Example: 0

vat_total_red_unroundednumber

Example: 0

vehicle_registrationnullable any

voided_reasonnullable any

Request

JavaScriptCurlPython

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

Response

200

{
  "acts_as_shipment_document": null,
  "apply_retention_when_paid": null,
  "base_currency_gross_total": null,
  "base_currency_net_total": null,
  "base_currency_pending_total": null,
  "base_currency_retention_total": null,
  "base_currency_settlement_total": null,
  "base_currency_vat_incidence_int": null,
  "base_currency_vat_incidence_ise": null,
  "base_currency_vat_incidence_nor": null,
  "base_currency_vat_incidence_red": null,
  "base_currency_vat_total_int": null,
  "base_currency_vat_total_nor": null,
  "base_currency_vat_total_red": null,
  "cashed_vat": null,
  "child_documents_ids": null,
  "communication_code": null,
  "communication_code_source": null,
  "communication_status": null,
  "company_id": 800000046,
  "created_at": "2024-03-06 10:52:52.637757",
  "currency_conversion_rate": 1,
  "currency_id": 1,
  "currency_iso_code": "EUR",
  "date": "2024-03-06",
  "document_area": "FC",
  "document_hash_sum": null,
  "document_no": "FC 2023/4",
  "document_series_id": 125,
  "document_series_prefix": "2023",
  "document_type": "FC",
  "due_date": "2024-03-06",
  "emailed": null,
  "external_reference": "",
  "gross_total": 0,
  "hash_control": null,
  "id": 41,
  "is_third_party": null,
  "line_settlement_with_tax": 0,
  "line_settlement_with_tax_unrounded": 0,
  "line_settlement_without_tax": 0,
  "line_settlement_without_tax_unrounded": 0,
  "lines": [
    {
      "amount": 0,
      "amount_with_header_settlement": 0,
      "base_currency_amount": null,
      "base_currency_net_amount": null,
      "base_currency_net_unit_price": null,
      "base_currency_settlement_with_tax": null,
      "base_currency_settlement_without_tax": null,
      "base_currency_tax_amount": null,
      "base_currency_unit_price": null,
      "created_at": "2024-03-06 11:05:50.019855",
      "date": null,
      "description": "<p>Impostos Sobre o Rendimento</p>",
      "document_id": 41,
      "expense_category_id": 2,
      "id": 41,
      "imported_quantity": null,
      "item_code": "241",
      "item_id": 2,
      "item_type": "Purchases::ExpenseCategory",
      "item_unit_price_includes_vat": false,
      "net_amount": 0,
      "net_amount_with_header_settlement": 0,
      "net_unit_price": 0,
      "original_document_no": null,
      "pending_quantity": null,
      "pending_retention_value": null,
      "pending_total": null,
      "quantity": null,
      "retention_value": null,
      "settlement_amount": null,
      "settlement_expression": null,
      "settlement_percentage": 0,
      "settlement_with_tax": 0,
      "settlement_without_tax": 0,
      "tax_amount": 0,
      "tax_code": "NOR",
      "tax_country_region": "PT",
      "tax_id": 1,
      "tax_percentage": 23,
      "unit_of_measure_id": 2,
      "unit_price": 0,
      "updated_at": "2024-03-06 11:05:50.019855",
      "__$markdownParsed": true
    }
  ],
  "net_total": 0,
  "notes": "",
  "operation_country": null,
  "parent_document_area": null,
  "parent_documents_ids": null,
  "payments_ids": null,
  "pending_retention_value": 0,
  "pending_total": 0,
  "printed": null,
  "public_link": "",
  "retention": null,
  "retention_type": null,
  "retention_value": 0,
  "retention_value_unrounded": 0,
  "settlement_expression": null,
  "settlement_percentage": 0,
  "settlement_total": 0,
  "settlement_with_tax": 0,
  "settlement_with_tax_unrounded": 0,
  "settlement_without_tax": 0,
  "settlement_without_tax_unrounded": 0,
  "shipment_country": null,
  "shipment_loading_address_detail": null,
  "shipment_loading_city": null,
  "shipment_loading_country": null,
  "shipment_loading_postcode": null,
  "shipment_loading_time": null,
  "shipment_unloading_address_detail": null,
  "shipment_unloading_city": null,
  "shipment_unloading_country": null,
  "shipment_unloading_postcode": null,
  "shipment_unloading_time": null,
  "status": 1,
  "supplier_address_detail": "",
  "supplier_business_name": "Fornecedor Indiferenciado",
  "supplier_city": "",
  "supplier_country": "PT",
  "supplier_id": 9,
  "supplier_postcode": "",
  "supplier_tax_country_region": "PT",
  "supplier_tax_registration_number": "999999990",
  "system_entry_date": "2024-03-06 11:06:17.132657",
  "tax_payable": 0,
  "third_party_type": null,
  "total_pending_quantity": null,
  "updated_at": "2024-03-06 11:06:17.132657",
  "user_id": 800000863,
  "vat_incidence_int": 0,
  "vat_incidence_int_unrounded": 0,
  "vat_incidence_ise": 0,
  "vat_incidence_ise_unrounded": 0,
  "vat_incidence_nor": 0,
  "vat_incidence_nor_unrounded": 0,
  "vat_incidence_red": 0,
  "vat_incidence_red_unrounded": 0,
  "vat_included_prices": false,
  "vat_percentage_int": null,
  "vat_percentage_nor": 23,
  "vat_percentage_red": null,
  "vat_total_int": 0,
  "vat_total_int_unrounded": 0,
  "vat_total_nor": 0,
  "vat_total_nor_unrounded": 0,
  "vat_total_red": 0,
  "vat_total_red_unrounded": 0,
  "vehicle_registration": null,
  "voided_reason": null
}

Payload

{
  "type": "commercial_purchases_documents",
  "id": "<id do documento>",
  "data": {
    "attributes": {
      "status": 1
    }
  }
}

NOTA: o documento e as linhas podem continuar a ser alterados mesmo depois de finalizados (fechados)

Alteração de Documento de Compra

Anulação do Documento de Compra

Anular Documentos de Compra

Anular Documentos de Compra

PATCH{{base_url}}/api/v1/commercial_purchases_documents/{id}/void

Path parameters

id*string

Example: "41"

Response

200

Request

JavaScriptCurlPython

const response = await fetch('{{base_url}}/api/v1/commercial_purchases_documents/{id}/void', {
    method: 'PATCH',
    headers: {},
});
const data = await response.json();

Payload

{
  "data": {
    "type": "commercial_purchases_documents",
    "id": "<id do documento>",
    "attributes": {
      "status": 4,
      "voided_reason": "Texto livre com o motivo pelo qual se está a anular o documento" // Opcional, não precisa de ser indicada
    }
  }
}

Obter Todos os Documentos de Compra Finalizados

Endpoint

{{base_url}}/api/commercial_purchases_documents?filter[status]=1

---

Linhas de Documento de Compra

Remover Linha de Documento

Remover Linhas de Pagamento

Remover Linhas de Pagamento

DELETE{{base_url}}/api/commercial_purchases_payment_lines

Response

200

Request

JavaScriptCurlPython

const response = await fetch('{{base_url}}/api/commercial_purchases_payment_lines', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();