Recibos
Os recibos seguem a mesma estrutura anteriormente definida: São compostos 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.
2023-01-01MO|CH|DC|...111trueOK
12023-01-01MO|CH|DC|...111https://app.cloudware.pt/path_to_filePOST /v1/commercial_sales_receipts HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 259
{
"date": "2023-01-01",
"payment_mechanism": "MO|CH|DC|...",
"document_series_id": 1,
"bank_account_id": 1,
"cash_account_id": 1,
"return_pdf": true,
"lines": [
{
"receivable_type": "Document|DocumentLine",
"receivable_id": 1,
"received_value": 9.99,
"settlement_percentage": "5"
}
]
}OK
{
"id": 1,
"date": "2023-01-01",
"payment_mechanism": "MO|CH|DC|...",
"document_series_id": 1,
"bank_account_id": 1,
"cash_account_id": 1,
"url": "https://app.cloudware.pt/path_to_file",
"lines": [
{
"id": 1,
"receivable_type": "Document|DocumentLine",
"receivable_id": 1,
"received_value": 9.99,
"settlement_percentage": 5
}
]
}NOTA 1: A série associada ao recibo tem já que existir, e o seu "id" interno deve ser obtido por um
NOTA 2: O "id" interno da conta bancária da empresa deve ser obtido por um
NOTA 3: O "id" interno da conta de caixa da empresa deve ser obtido por um
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.
id of the receipt line to delete
OK
No content
DELETE /v1/commercial_sales_receipts/{id} HTTP/1.1
Accept: */*
OK
No content
No pedido acima, o <access_token> corresponde ao token de acesso válido devolvido pelo serviço de OAuth
NOTA 1: O "id" interno do recibo a anular deve ser obtido por um
É 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 recibo, após criação
O seguinte pedido pode ser realizado, após a criação do recibo, e permite alterar informações sobre o mesmo. A estrutura do payload é a mesma do POST de criação. Neste, deverá enviar no id do pedido o id do recibo 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 receipt_line_id
id of the receipt to edit the information of
15-07-2022MO|CH|DC|...OK
No content
PATCH /v1/commercial_sales_receipts/{id} HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 256
{
"date": "15-07-2022",
"payment_mechanism": "MO|CH|DC|...",
"commercial_document_series_id": 1,
"bank_account_id": 1,
"cash_account_id": 1,
"lines": [
{
"receipt_line_id": 1,
"receivable_type": "Document",
"receivable_id": 1,
"received_value": 1,
"settlement_percentage": "5"
}
]
}OK
No content
Adição de linhas
Caso pretenda adicionar novas linhas ao recibo, 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 recibo ao qual pretende adicionar a linha
id of the receipt to add the line to
OK
No content
POST /v1/commercial_sales_receipt_lines/{id} HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 107
{
"lines": [
{
"receivable_type": "Document",
"receivable_id": 1,
"received_value": 1,
"settlement_percentage": "5"
}
]
}OK
No content
Remoção de linhas
Do mesmo modo, caso pretenda remover linhas de um recibo, pode utilizar a seguinte rota, onde apenas tem de indicar o id da linha a remover, no path.
id of the receipt line to delete
OK
No content
DELETE /v1/commercial_sales_receipt_lines/{id} HTTP/1.1
Accept: */*
OK
No content
Consultar recibo
Por fim, se pretender obter informações sobre um dado recibo pode utilizar a seguinte rota, onde deverá especificar o id do documento a analisar no path.
id of the receipt to get the information of
OK
GET /v1/commercial_sales_receipts/{id} HTTP/1.1
Accept: */*
OK
{
"data": {
"id": 1,
"attributes": {
"date": "text",
"document_no": "text",
"document_series_id": 1,
"payment_mechanism": "text",
"gross_total": 1,
"net_total": 1,
"third_party_type": "text",
"third_party_id": 1,
"check_number": true,
"currency_conversion_rate": 1,
"internal_observations": "text",
"observations": "text",
"standalone": true,
"deleted": true
},
"relationships": {
"bank_accounts": {
"data": {
"resource": "bank_accounts"
}
},
"cash_accounts": {
"data": {
"resource": "cash_accounts"
}
},
"company": {
"data": {
"resource": "current_company"
}
},
"commercial_document_series": {
"data": {
"resource": "commercial_document_series"
}
},
"country": {
"data": {
"resource": "countries"
}
},
"supplier": {
"data": {
"table": "payments",
"resource": "suppliers"
}
},
"employee": {
"data": {
"table": "payments",
"resource": "current_company_users"
}
},
"currency": {
"data": {
"resource": "currencies"
}
},
"user": {
"data": {
"resource": "current_company_users"
}
},
"lines": {
"data": {
"type": "commercial_purchases_payment_lines",
"id": 1
}
}
}
}
}Last updated