Documentação API
Search…
⌃K

Compras

As compras seguem a mesma estrutura anteriormente definida: São compostas por um cabeçalho, e linhas. Nesta nova versão, é possível criar ambas as componentes num só pedido, descrito de seguida.

Criação de cabeçalhos e linhas

Os detalhes do pedido POST para a criação de recibos estão descritos de seguida, em formato OpenAPI, e em cURL.
post
/v1/commercial_purchases_documents
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>/v1/commercial_purchases_documents'
{
"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)
//Fim de atributos opcionais
"vat_included_prices": true, // Indicar o atributo, com o valor true, apenas se os preços indicados nas linhas forem preços com IVA incluído
"settlement_expression": "7.5", // Indicar o atributo apenas se existir desconto de cabeçalho (7,5%, neste exemplo)
"retention_total": 10, // Indicar o atributo apenas se existir retenção (10€, neste exemplo)
"currency_id": 2, // Este id pode ser obtido por um GET /currencies?filter[iso_code]=USD
"commercial_document_series_id": 3 // Associação à série de documentos. Pode ser omitida, se for para usar a série por omissão. // Este id pode ser obtido por um GET /commercial_document_series?filter[document_type]=FC|NCF|...
"lines": [
{
"quantity": 1,
"unit_price": 20,
"item_type": "Product",
"item_code": "PTEST", // NOTA: já tem que existir o produto com este código
"settlement_expression":"3" // Indicar o atributo apenas se existir desconto de linha (3%, neste exemplo)
"tax_id": 1 // O id da taxa de IVA pode ser obtido por um GET /taxes?filter[tax_code]=NOR|INT|RED|ISE
}
]
}

Finalização do documento

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

Anulação de um recibo (Caso seja preciso) :

Os detalhes do pedido POST para a criação de recibos estão descritos de seguida, em formato OpenAPI, e em cURL.
delete
/v1/commercial_purchases_documents/{id}
curl -v -X DELETE -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' '<API_URL>/commercial_purchases_documents/<id do documento>/'
  • NOTA 1: O "id" interno do recibo a anular deve ser obtido por um
GET /commercial_sales_receipts?filter[document_no]=<o número do recibo, ex. RC 2020/1>
É na linha do recibo que se indica qual o documento (FT, ou outro) que foi pago.
Se necessário, pode criar-se mais do que uma linha (e nesse caso o recibo é emitido de uma só vez para todos os documentos referenciados)

Edição do documento, após criação

O seguinte pedido pode ser realizado, após a criação do documento, e permite alterar informações sobre o documento. A estrutura do payload é a mesma do POST de criação. Neste, deverá enviar no id do pedido o id do documento a alterar. Os atributos enviados no body irão substituir os guardados no momento, e cada linha enviada dentro de lines irá substituir os dados guardados na linha com id especificado em purchase_line_id
patch
/v1/commercial_purchases_documents/{id}

Adição de linhas

Caso pretenda adicionar novas linhas ao documento, após a sua criação, pode utilizar a seguinte rota, que utiliza o mesmo payload das lines do pedido POST de criação. Neste, o id a enviar no path é o do documento ao qual pretende adicionar a linha
post
/v1/commercial_purchases_document_lines/{id}

Remoção de linhas

Do mesmo modo, caso pretenda remover linhas de um documento, pode utilizar a seguinte rota, onde apenas tem de indicar o id da linha a remover, no path.
delete
/v1/commercial_purchases_document_lines/{id}

Consultar documento

Por fim, se pretender obter informações sobre um dado documento, pode utilizar a seguinte rota, onde deverá especificar o id do documento a analisar no path.
get
/v1/commercial_purchases_documents/{id}