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

Authorizations

Body

dataobject

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '{{base_url}}/api/commercial_sales_document_lines' \
  --header 'Content-Type: application/json' \
  --data '{
    "data": {
      "attributes": {
        "description": "Descrição da linha",
        "document_id": 66
      },
      "type": "commercial_sales_document_lines"
    }
  }'

200

200

Criar Linha de Documento de Venda para uma Descrição Sem Valor

Criar Linha de Documentos de Venda para um Descritor

Criar Linha de Documentos de Venda para um Serviço

Sucesso

Criar Linha de Documento de Venda para uma Descrição Sem Valor

{
  "data": {
    "attributes": {
      "amount": null,
      "amount_with_header_settlement": null,
      "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:27:22.265972",
      "date": null,
      "description": "Descrição da linha",
      "exemption_reason": null,
      "imported_quantity": null,
      "item_code": "",
      "item_id": null,
      "item_type": "",
      "item_unit_price_includes_vat": false,
      "locked": null,
      "net_amount": null,
      "net_amount_with_header_settlement": null,
      "net_settlement_amount": null,
      "net_tax_amount": null,
      "net_unit_price": null,
      "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": null,
      "settlement_without_tax": null,
      "tax_amount": null,
      "tax_code": null,
      "tax_country_region": "PT-MA",
      "tax_descriptor_id": null,
      "tax_percentage": null,
      "unit_price": null,
      "updated_at": "2024-03-05 14:27:22.265972"
    },
    "id": "136",
    "relationships": {
      "document": {
        "data": {
          "id": "66",
          "type": "commercial_sales_documents"
        }
      },
      "product": {
        "data": null
      },
      "service": {
        "data": null
      },
      "tax": {
        "data": null
      },
      "tax_descriptor": {
        "data": null
      },
      "unit_of_measure": {
        "data": null
      }
    },
    "type": "commercial_sales_document_lines"
  },
  "meta": {
    "observed": {
      "lines": 1,
      "scalar": 0
    }
  }
}

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

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

Authorizations

Body

dataobject

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '{{base_url}}/api/commercial_purchases_payment_lines' \
  --header 'Content-Type: application/json' \
  --data '{
    "data": {
      "attributes": {
        "paid_value": 50,
        "payable_id": 2,
        "payable_type": "Purchases::Document",
        "settlement_percentage": 3
      },
      "type": "commercial_purchases_payment_lines"
    }
  }'

200

200

No body

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

Authorizations

Path parameters

idstringrequired

Example: 41

Body

object

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PATCH \
  --url '{{base_url}}/api/v1/commercial_purchases_documents/{id}/finalize' \
  --header 'Content-Type: application/json' \
  --data '{}'

200

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": "Impostos Sobre o Rendimento",
      "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"
    }
  ],
  "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
}

Finalizar Documentos de Compra

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

Authorizations

Path parameters

idstringrequired

Example: 41

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PATCH \
  --url '{{base_url}}/api/v1/commercial_purchases_documents/{id}/void'

200

200

No body

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

Authorizations

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request DELETE \
  --url '{{base_url}}/api/commercial_purchases_payment_lines'

200

200

No body