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

JavaScriptCurl

const response = await fetch('/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

{
  "data": {
    "attributes": {
      "amount": 10.13,
      "amount_with_header_settlement": 10.95,
      "created_at": "2024-03-05 14:25:52.160841",
      "description": "Isto é uma breve descrição",
      "item_code": "1000",
      "item_id": 2,
      "item_type": "Product",
      "item_unit_price_includes_vat": false,
      "net_amount": 8.96,
      "net_amount_with_header_settlement": 9.69,
      "net_unit_price": 8.9635,
      "pending_quantity": 1,
      "quantity": 1,
      "retention_value": 0,
      "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": 0,
      "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": {},
      "service": {},
      "tax": {
        "data": {
          "id": "2",
          "type": "taxes"
        }
      },
      "tax_descriptor": {},
      "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/api/commercial_purchases_payment_lines

Body

application/json

dataobject

Response

200

Request

JavaScriptCurl

const response = await fetch('/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/api/v1/commercial_purchases_documents/{id}/finalize

Path parameters

id*string

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

created_atstring

currency_conversion_ratenumber

currency_idnumber

currency_iso_codestring

datestring

document_areastring

document_hash_sumnullable any

document_nostring

document_series_idnumber

document_series_prefixstring

document_typestring

due_datestring

emailednullable any

external_referencestring

gross_totalnumber

hash_controlnullable any

idnumber

is_third_partynullable any

line_settlement_with_taxnumber

line_settlement_with_tax_unroundednumber

line_settlement_without_taxnumber

line_settlement_without_tax_unroundednumber

linesarray of object

net_totalnumber

notesstring

operation_countrynullable any

parent_document_areanullable any

parent_documents_idsnullable any

payments_idsnullable any

pending_retention_valuenumber

pending_totalnumber

printednullable any

public_linkstring

retentionnullable any

retention_typenullable any

retention_valuenumber

retention_value_unroundednumber

settlement_expressionnullable any

settlement_percentagenumber

settlement_totalnumber

settlement_with_taxnumber

settlement_with_tax_unroundednumber

settlement_without_taxnumber

settlement_without_tax_unroundednumber

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

supplier_address_detailstring

supplier_business_namestring

supplier_citystring

supplier_countrystring

supplier_idnumber

supplier_postcodestring

supplier_tax_country_regionstring

supplier_tax_registration_numberstring

system_entry_datestring

tax_payablenumber

third_party_typenullable any

total_pending_quantitynullable any

updated_atstring

user_idnumber

vat_incidence_intnumber

vat_incidence_int_unroundednumber

vat_incidence_isenumber

vat_incidence_ise_unroundednumber

vat_incidence_nornumber

vat_incidence_nor_unroundednumber

vat_incidence_rednumber

vat_incidence_red_unroundednumber

vat_included_pricesboolean

vat_percentage_intnullable any

vat_percentage_nornumber

vat_percentage_rednullable any

vat_total_intnumber

vat_total_int_unroundednumber

vat_total_nornumber

vat_total_nor_unroundednumber

vat_total_rednumber

vat_total_red_unroundednumber

vehicle_registrationnullable any

voided_reasonnullable any

Request

JavaScriptCurl

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

Response

{
  "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_no": "FC 2023/4",
  "document_series_id": 125,
  "document_series_prefix": "2023",
  "document_type": "FC",
  "due_date": "2024-03-06",
  "external_reference": "text",
  "gross_total": 0,
  "id": 41,
  "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": "text",
  "pending_retention_value": 0,
  "pending_total": 0,
  "public_link": "text",
  "retention_value": 0,
  "retention_value_unrounded": 0,
  "settlement_percentage": 0,
  "settlement_total": 0,
  "settlement_with_tax": 0,
  "settlement_with_tax_unrounded": 0,
  "settlement_without_tax": 0,
  "settlement_without_tax_unrounded": 0,
  "status": 1,
  "supplier_address_detail": "text",
  "supplier_business_name": "Fornecedor Indiferenciado",
  "supplier_city": "text",
  "supplier_country": "PT",
  "supplier_id": 9,
  "supplier_postcode": "text",
  "supplier_tax_country_region": "PT",
  "supplier_tax_registration_number": "999999990",
  "system_entry_date": "2024-03-06 11:06:17.132657",
  "tax_payable": 0,
  "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_nor": 23,
  "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
}

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/api/v1/commercial_purchases_documents/{id}/void

Path parameters

id*string

Response

200

Request

JavaScriptCurl

const response = await fetch('/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/api/commercial_purchases_payment_lines

Response

200

Request

JavaScriptCurl

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