Pagamentos
Os pagamentos 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.
POST /commercial_purchases_payments HTTP/1.1
Host: v1
Content-Type: application/json
Accept: */*
Content-Length: 285
{
"date": "2023-01-01",
"payment_mechanism": "MO|CH|DC|CC|TR|DDA|MB|OU|...",
"document_series_id": 1,
"bank_account_id": 1,
"cash_account_id": 1,
"return_pdf": true,
"lines": [
{
"payable_type": "Purchases::Document|Purchases::DocumentLine",
"payable_id": 1,
"paid_value": 9.99,
"settlement_percentage": 5
}
]
}OK
{
"id": 1,
"date": "2023-01-01",
"payment_mechanism": "MO|CH|DC|CC|TR|DDA|MB|OU|...",
"document_series_id": 1,
"bank_account_id": 1,
"cash_account_id": 1,
"url": "https://app.cloudware.pt/path_to_file",
"lines": [
{
"id": 1,
"payable_type": "Purchases::Document|Purchases::DocumentLine",
"payable_id": 1,
"paid_value": 9.99,
"settlement_percentage": 5
}
]
}Este pedido permite criar um pagamento, e respetivas linhas, em simultâneo.
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_payments'Neste, o payload JSON deverá vir no seguinte formato
{
"date": "2017-06-01", // Data do pagamento
"payment_mechanism": "MO|CH|DC|CC|TR|DDA|MB|OU|...", // Por omissão, MO. Modo de pagamento: MO (numerário), CH (cheque), DC (cartão de débito), CC (cartão de crédito), TR (transferência), DDA (débito directo), MB (referência MB), OU (outro)
"document_series_id": 1, // Associação à série de pagamentos. 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]=PF&filter[prefix]=2020|ou outro qualquer...
"bank_account_id": 2, // SÓ NECESSÁRIO se o meio de pagamento for DC,CC,TR,CH, e se for para indicar uma conta bancária específica. Associação à conta bancária da empresa de onde o pagamento foi feito. // Este id pode ser obtido por um GET /company_bank_accounts?filter[iban]=<IBAN da conta>, ou GET /company_bank_accounts?filter[name]=<nome da conta>
"cash_account_id": 2, // SÓ NECESSÁRIO se o meio de pagamento for MO, e se for para indicar uma conta de caixa específica. Associação à conta de caixa da empresa de onde o pagamento foi feito. Este id pode ser obtido por um GET /cash_accounts?filter[name]=<nome da conta de caixa>
"lines": [
{
"payable_type": "Purchases::Document",
"payable_id": "<id do documento de compra a pagar>",
"paid_value": 50, // Valor total a pagar (não é necessário pagar a totalidade do documento, ou pode pagar-se mais do que um documento)
// Indicar o atributo seguinte apenas se existir desconto no pagamento (3%, neste exemplo)
"settlement_percentage": 3,
"commercial_purchases_document_id": 2 //id do documento de compra a pagar
}
]
}Finalização do documento
Não é necessário. Os pagamentos são sempre fechados.
Anulação de um documento (Caso seja preciso)
id of the payment line to delete
Texto descritivo do motivo de anulaçãoDELETE /v1/commercial_purchases_payments/{id} HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 60
{
"voided_reason": "Texto descritivo do motivo de anulação"
}OK
No content
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 payment_line_id
id of the payment to edit the information of
15-7-2022MO|CH|DC|CC|TR|DDA|MB|OU|...PATCH /v1/commercial_purchases_payments/{id} HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 255
{
"date": "15-7-2022",
"payment_mechanism": "MO|CH|DC|CC|TR|DDA|MB|OU|...",
"commercial_document_series_id": 1,
"bank_account_id": 1,
"cash_account_id": 1,
"lines": [
{
"payment_line_id": 1,
"payable_id": 1,
"payable_type": "text",
"paid_value": 1,
"settlement_percentage": 1
}
]
}OK
No content
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
id of the payment to add the line to
POST /v1/commercial_purchases_payment_lines/{id} HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 108
{
"lines": [
{
"payable_type": "Purchases::Document",
"payable_id": 1,
"paid_value": 1,
"settlement_percentage": "5"
}
]
}OK
No content
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.
id of the payment line to delete
DELETE /v1/commercial_purchases_payment_lines/{id} HTTP/1.1
Host:
Accept: */*
OK
No content
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.
id of the payment to get the information of
GET /v1/commercial_purchases_payments/{id} HTTP/1.1
Host:
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