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.
POST /commercial_sales_receipts HTTP/1.1
Host: v1
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
}
]
}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_sales_receipts'{
"date": "2020-06-01", // [OPCIONAL] Data do recibo; por omissão, a data do pedido
"payment_mechanism": "MO", // [OPCIONAL] Por omissão, "MO". Meios de pagamento aceites: "MO": Numerário, "CH": Cheque, "DC": Cartão de débito, "CC": Cartão de crédito, "TR": Transferência bancária, "DDA": Débito direto autorizado, "MB": Referências de pagamento Multibanco.
// [OPCIONAL] Recursos associados ao recibo. Caso nenhum seja indicado, os restantes devem atributos devem ser omitidos. Caso contrário, todos os atributos devem ser preenchidos.
"document_series_id": 1, // [OBRIGATÓRIO] Série de recibos associada. Não precisa de ser indicada; por omissão o recibo é criado na série por omissão associada ao tipo de documento. Vd. NOTA 1
"bank_account_id": 2, // [OBRIGATÓRIO] Conta bancária da empresa para onde o recebimento é feito. Usado apenas quando o meio de pagamento é "DC", "CC", "TR" ou "DDA", e apenas se for necessário indicar uma conta bancária específica. Vd. NOTA 2
"cash_account_id": 3, // [OBRIGATÓRIO] Conta de caixa da empresa para onde o recebimento é feito. Usado apenas quando o meio de pagamento é "MO", e apenas se for necessário indicar uma conta de caixa específica. Vd. NOTA 3
"lines": [
{
"receivable_type": "Document|DocumentLine", // [OBRIGATÓRIO] "Document" para receber faturas ou notas, "DocumentLine" para receber uma linha de um SI
"receivable_id": "<id do documento a liquidar>", // [OBRIGATÓRIO] Vd. NOTA 1
"received_value": 50, // [OBRIGATÓRIO] Valor total a receber (não é necessário receber a totalidade do documento, pode fazer-se um recebimento parcial)
"settlement_percentage": "3" // [OPCIONAL] Desconto de pagamento, em percentagem; são suportados descontos compostos, como "3+5"
}
]
}NOTA 1: A série associada ao recibo tem já que existir, e o seu "id" interno deve ser obtido por um
GET /commercial_document_series?filter[document_type]=RC&filter[prefix]=2020|<o prefixo da série a usar>NOTA 2: O "id" interno da conta bancária da empresa deve ser obtido por um
GET /company_bank_accounts?filter[iban]=
ou
GET /company_bank_accounts?filter[name]=NOTA 3: O "id" interno da conta de caixa da empresa deve ser obtido por um
GET /cash_accounts?filter[name]=ACCOUNT_NAMEAnulaçã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
DELETE /v1/commercial_sales_receipts/{id} HTTP/1.1
Host:
Accept: */*
OK
No content
curl -v -X DELETE -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' '<API_URL>/v1/commercial_sales_receipts/<id do recibo>'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
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 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|...PATCH /v1/commercial_sales_receipts/{id} HTTP/1.1
Host:
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
POST /v1/commercial_sales_receipt_lines/{id} HTTP/1.1
Host:
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
DELETE /v1/commercial_sales_receipt_lines/{id} HTTP/1.1
Host:
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
GET /v1/commercial_sales_receipts/{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