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

Authorizations
Body
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
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"
  }
}
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...
    }
  }
}

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

Authorizations
Body
Responses
200Success
post
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"
  }
}
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.

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

Authorizations
Path parameters
idstringRequiredExample: 41
Body
objectOptional
Responses
200
Finalizar Documentos de Compra
application/json
patch
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

Authorizations
Path parameters
idstringRequiredExample: 41
Responses
200Success
patch
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

Authorizations
Responses
200Success
delete
DELETE /api/commercial_purchases_payment_lines HTTP/1.1
Host: {{base_url}}
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
200Success

No content

Last updated