Compras
O atual capítulo tem como objetivo descrever as rotas da API responsáveis pela gestão de compras

Criação de compras

Tal como no caso dos recibos, as compras são constituídas por:
  1. 1.
    Um cabeçalho
  2. 2.
    Umas ou mais linhas

1. Criação do cabeçalho

De modo a criar uma compra, deverá inicialmente criar o cabeçalho do documento. Para este efeito, deverá realizar o seguinte pedido:
curl -v -X POST -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' -d '<payload JSON>' '<API_URL>/commercial_purchases_documents'
post
/commercial_purchases_documents
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 no seguinte formato
{
"data": {
"type": "commercial_purchases_documents",
"attributes": {
"document_type": "FC", // 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
"supplier_tax_registration_number": "888888880", // Por omissão, o fornecedor indiferenciado (999999990)
// Os atributos seguintes só são necessários se o fornecedor ainda não existir e tiver que ser criado, ou se os valores forem diferentes dos da ficha
"supplier_business_name": "Testes",
"supplier_address_detail": "Rua dos testes 777A",
"supplier_postcode": "4200-224",
"supplier_city": "Porto",
"supplier_country": "PT", // Por omissão, PT. Pode ainda ser PT-AC (Açores) e PT-MA (Madeira)
// Indicar o atributo seguinte, com o valor true, apenas se os preços indicados nas linhas forem preços com IVA incluído
"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
},
"relationships": {
"commercial_document_series": { // Associação à série de documentos. Pode ser omitida, se for para usar a série por omissão
"data": {
"type": "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...
}
}
}
}
}
Caso deseje realizar a compra numa outra moeda, o payload deverá vir no seguinte formato
{
"data": {
"type": "commercial_purchases_documents",
"attributes": {
"document_type": "FC", // Pode ser FC, NCF, NDF, DSP
"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)
// Os atributos seguintes só são necessários se o fornecedor ainda não existir e tiver que ser criado, ou se os valores forem diferentes dos da ficha
"supplier_business_name": "Testes",
"supplier_address_detail": "Rua dos testes 777A",
"supplier_postcode": "4200-224",
"supplier_city": "Porto",
"supplier_country": "PT", // Por omissão, PT. Pode ainda ser PT-AC (Açores) e PT-MA (Madeira)
// Indicar o atributo seguinte, com o valor true, apenas se os preços indicados nas linhas forem preços com IVA incluído
"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
},
"relationships": {
"currency": { // Associação à moeda do documento. Pode ser omitida, se for um documento em EUR
"data": {
"type": "currencies",
"id": "<id da moeda do documento>" // Este id pode ser obtido por um GET /currencies?filter[iso_code]=USD|...
}
},
"commercial_document_series": { // Associação à série de documentos. Pode ser omitida, se for para usar a série por omissão
"data": {
"type": "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.

2. Criação de linhas

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
GET /commercial_purchases_documents?filter[document_no]=<número do documento, ex: FC 2020/1>
Se o documento ainda não estiver finalizado (fechado), ainda não tem número atribuído, e então o GET anterior não poderá ser feito. Em alternativa pode ser feito um
GET /commercial_purchases_documents?filter[status]=0&filter[supplier_tax_registration_number]=
Na resposta a este pedido, procurar o documento a que se quer adicionar as linhas
De modo a inserir linhas na compra criada, deverá realizar o seguinte pedido
curl -v -X POST -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' -d '<payload JSON>' '<API_URL>/commercial_purchases_document_lines'
post
/commercial_purchases_document_lines
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
NOTA: nos documentos de despesas (tipo de documento DSP) só são aceites linhas de categorias de despesa, não de produtos

Linha de 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"
},
"relationships": {
"document": { // Associação ao documento de compra
"data": {
"type": "commercial_purchases_documents",
"id": "<id do documento>"
}
},
"tax": {
"data": {
"type": "taxes",
"id": "1" // O id da taxa de IVA pode ser obtido por um GET /taxes?filter[tax_code]=NOR|INT|RED|ISE
}
}
}
}
}

Linha de 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
},
"relationships": {
"document": { // Associação ao documento de compra
"data": {
"type": "commercial_purchases_documents",
"id": "<id do documento>"
}
},
"tax": {
"data": {
"type": "taxes",
"id": "1" // O id da taxa de IVA pode ser obtido por um GET /taxes?filter[tax_code]=NOR|INT|RED|ISE
}
}
}
}
}

3. Finalização do documento

De modo a finalizar o documento, deverá realizar o seguinte pedido
patch
/commercial_purchases_documents
curl -v -X PATCH -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' -d '<payload JSON>' '<API_URL>/commercial_purchases_documents'
NOTA: o documento e as linhas podem continuar a ser alterados mesmo depois de finalizados (fechados)
Neste, o payload JSON deverá ser
{
"type": "commercial_purchases_documents",
"id": "<id do documento>",
"data": {
"attributes": {
"status": 1
}
}
}

4. Anulação de um documento (caso seja preciso)

De modo a proceder à anulação de um documento deverá realizar o mesmo pedido descrito acima, alterando o payload JSON para
{
"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
}
}
}
Last modified 4mo ago