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

post

Criar Linha de Documentos de Venda para um Produto

Required scopes

This endpoint requires the following scopes:

• : commercial

Authorizations

oauth2

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Body

application/json

Responses

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

application/json

post

/api/commercial_sales_document_lines

HTTPcURLJavaScriptPython

POST /api/commercial_sales_document_lines HTTP/1.1
Host: {{base_url}}
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 120

{
  "data": {
    "attributes": {
      "description": "Descrição da linha",
      "document_id": 66
    },
    "type": "commercial_sales_document_lines"
  }
}

Criar Linha de Documento de Venda para uma Descrição Sem ValorCriar Linha de Documentos de Venda para um DescritorCriar Linha de Documentos de Venda para um ProdutoCriar Linha de Documentos de Venda para um Serviço

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

{
  "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
    }
  }
}

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

post

Adicionar Linha a Pagamentos

Required scopes

This endpoint requires the following scopes:

• : commercial

Authorizations

oauth2

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Body

application/json

Responses

200Success

No content

post

/api/commercial_purchases_payment_lines

HTTPcURLJavaScriptPython

POST /api/commercial_purchases_payment_lines HTTP/1.1
Host: {{base_url}}
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 163

{
  "data": {
    "attributes": {
      "paid_value": 50,
      "payable_id": 2,
      "payable_type": "Purchases::Document",
      "settlement_percentage": 3
    },
    "type": "commercial_purchases_payment_lines"
  }
}

Adicionar Linha a PagamentosCriar Linhas de Pagamento

200Success

No content

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

patch

Finalizar Documentos de Compra

Required scopes

This endpoint requires the following scopes:

• : commercial

Authorizations

oauth2

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Path parameters

idstringRequiredExample: 41

Body

application/json

objectOptional

Responses

200

Finalizar Documentos de Compra

application/json

patch

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

HTTPcURLJavaScriptPython

PATCH /api/v1/commercial_purchases_documents/{id}/finalize HTTP/1.1
Host: {{base_url}}
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 2

{}

200

Finalizar Documentos de Compra

{
  "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
}

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

patch

Anular Documentos de Compra

Required scopes

This endpoint requires the following scopes:

• : commercial

Authorizations

oauth2

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Path parameters

idstringRequiredExample: 41

Responses

200Success

No content

patch

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

HTTPcURLJavaScriptPython

PATCH /api/v1/commercial_purchases_documents/{id}/void HTTP/1.1
Host: {{base_url}}
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

200Success

No content

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

delete

Remover Linhas de Pagamento

Required scopes

This endpoint requires the following scopes:

• : commercial

Authorizations

oauth2

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Responses

200Success

No content

delete

/api/commercial_purchases_payment_lines

HTTPcURLJavaScriptPython

DELETE /api/commercial_purchases_payment_lines HTTP/1.1
Host: {{base_url}}
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

200Success

No content