Documentos de compra

As rotas aqui descritas permitem gerir todos os processos relativos a documentos de compra: notas de encomenda, faturas-proforma, guias, faturas, despesas e notas.

Criação de compras

Tal como no caso dos recibos, as compras são constituídas por:

1. Um cabeçalho

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

Body

application/json

Responses

200

OK

application/json

post

/commercial_purchases_documents

HTTPcURLJavaScriptPython

POST /commercial_purchases_documents HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 551

{
  "data": {
    "type": "commercial_purchases_documents",
    "attributes": {
      "public_link": "text"
    },
    "relationships": {
      "company": {
        "data": {
          "resource": "current_company"
        }
      },
      "supplier": {
        "data": {
          "resource": "suppliers"
        }
      },
      "currency": {
        "data": {
          "resource": "currencies"
        }
      },
      "commercial_document_series": {
        "data": {
          "resource": "commercial_document_series"
        }
      },
      "tax_exemption_reasons": {
        "data": {
          "resource": "tax_exemption_reasons"
        }
      },
      "user": {
        "data": {
          "resource": "current_company_users"
        }
      },
      "lines": {
        "data": {
          "table": "purchases_document_lines",
          "resource": "commercial_purchases_document_lines"
        }
      }
    }
  }
}

200

OK

{
  "data": {
    "type": "commercial_purchases_documents",
    "id": null,
    "attributes": {
      "public_link": "text"
    },
    "relationships": {
      "company": {
        "data": {
          "resource": "current_company"
        }
      },
      "supplier": {
        "data": {
          "resource": "suppliers"
        }
      },
      "currency": {
        "data": {
          "resource": "currencies"
        }
      },
      "commercial_document_series": {
        "data": {
          "resource": "commercial_document_series"
        }
      },
      "tax_exemption_reasons": {
        "data": {
          "resource": "tax_exemption_reasons"
        }
      },
      "user": {
        "data": {
          "resource": "current_company_users"
        }
      },
      "lines": {
        "data": {
          "table": "purchases_document_lines",
          "resource": "commercial_purchases_document_lines"
        }
      }
    }
  }
}

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

Body

application/json

Responses

200

OK

application/json

post

/commercial_purchases_document_lines

HTTPcURLJavaScriptPython

POST /commercial_purchases_document_lines HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 552

{
  "data": {
    "type": "commercial_purchases_document_lines",
    "attributes": {
      "id": 1,
      "line_type:": "text",
      "document_id": 1,
      "item_type": "text",
      "item_id": 1,
      "item_code": "text"
    },
    "relationships": {
      "document": {
        "data": {
          "resource": "commercial_purchases_documents"
        }
      },
      "unit_of_measure": {
        "data": {
          "resource": "units_of_measure"
        }
      },
      "tax": {
        "data": {
          "table": "purchases_document_lines",
          "resource": "taxes"
        }
      },
      "product": {
        "data": {
          "table": "purchases_document_lines",
          "resource": "products"
        }
      },
      "expense_category": {
        "data": {
          "table": "purchases_document_lines",
          "resource": "expense_categories"
        }
      }
    }
  }
}

200

OK

{
  "data": {
    "type": "commercial_purchases_document_lines",
    "id": null,
    "attributes": {
      "id": 1,
      "line_type:": "text",
      "document_id": 1,
      "item_type": "text",
      "item_id": 1,
      "item_code": "text"
    },
    "relationships": {
      "document": {
        "data": {
          "resource": "commercial_purchases_documents"
        }
      },
      "unit_of_measure": {
        "data": {
          "resource": "units_of_measure"
        }
      },
      "tax": {
        "data": {
          "table": "purchases_document_lines",
          "resource": "taxes"
        }
      },
      "product": {
        "data": {
          "table": "purchases_document_lines",
          "resource": "products"
        }
      },
      "expense_category": {
        "data": {
          "table": "purchases_document_lines",
          "resource": "expense_categories"
        }
      }
    }
  }
}

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

Body

application/json

Responses

200

OK

application/json

patch

/commercial_purchases_documents

HTTPcURLJavaScriptPython

PATCH /commercial_purchases_documents HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 563

{
  "data": {
    "type": "commercial_purchases_documents",
    "attributes": {
      "public_link": "text"
    },
    "relationships": {
      "company": {
        "data": {
          "resource": "current_company"
        }
      },
      "supplier": {
        "data": {
          "resource": "suppliers"
        }
      },
      "currency": {
        "data": {
          "resource": "currencies"
        }
      },
      "commercial_document_series": {
        "data": {
          "resource": "commercial_document_series"
        }
      },
      "tax_exemption_reasons": {
        "data": {
          "resource": "tax_exemption_reasons"
        }
      },
      "user": {
        "data": {
          "resource": "current_company_users"
        }
      },
      "lines": {
        "data": {
          "table": "purchases_document_lines",
          "resource": "commercial_purchases_document_lines"
        }
      }
    },
    "id": "text"
  }
}

200

OK

{
  "data": {
    "type": "commercial_purchases_documents",
    "id": null,
    "attributes": {
      "public_link": "text"
    },
    "relationships": {
      "company": {
        "data": {
          "resource": "current_company"
        }
      },
      "supplier": {
        "data": {
          "resource": "suppliers"
        }
      },
      "currency": {
        "data": {
          "resource": "currencies"
        }
      },
      "commercial_document_series": {
        "data": {
          "resource": "commercial_document_series"
        }
      },
      "tax_exemption_reasons": {
        "data": {
          "resource": "tax_exemption_reasons"
        }
      },
      "user": {
        "data": {
          "resource": "current_company_users"
        }
      },
      "lines": {
        "data": {
          "table": "purchases_document_lines",
          "resource": "commercial_purchases_document_lines"
        }
      }
    }
  }
}

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