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//v1/commercial_sales_receipts

Body

application/json

datestring

Example: "2023-01-01"

payment_mechanismstring

Example: "MO|CH|DC|..."

document_series_idinteger

Example: 1

bank_account_idinteger

Example: 1

cash_account_idinteger

Example: 1

return_pdfboolean

Example: true

linesarray of new-receipt-line (object)

Response

200

OK

Body

application/json

idinteger

Example: 1

datestring

Example: "2023-01-01"

payment_mechanismstring

Example: "MO|CH|DC|..."

document_series_idinteger

Example: 1

bank_account_idinteger

Example: 1

cash_account_idinteger

Example: 1

urlstring

Example: "https://app.cloudware.pt/path_to_file"

linesarray of existing-receipt-line (object)

Request

JavaScriptCurlPython

const response = await fetch('//v1/commercial_sales_receipts', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

{
  "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_NAME

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_sales_receipts/{id}

Path parameters

id*integer

id of the receipt line to delete

Response

200

OK

Request

JavaScriptCurlPython

const response = await fetch('/v1/commercial_sales_receipts/{id}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

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

PATCH/v1/commercial_sales_receipts/{id}

Path parameters

id*integer

id of the receipt to edit the information of

Body

application/json

datestring

Example: "15-07-2022"

payment_mechanismstring

Example: "MO|CH|DC|..."

commercial_document_series_id*integer

bank_account_id*integer

cash_account_id*integer

linesarray of object

Response

200

OK

Request

JavaScriptCurlPython

const response = await fetch('/v1/commercial_sales_receipts/{id}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "bank_account_id": 0,
      "cash_account_id": 0,
      "commercial_document_series_id": 0
    }),
});
const data = await response.json();

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

POST/v1/commercial_sales_receipt_lines/{id}

Path parameters

id*integer

id of the receipt to add the line to

Body

application/json

linesarray of object

Response

200

OK

Request

JavaScriptCurlPython

const response = await fetch('/v1/commercial_sales_receipt_lines/{id}', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

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.

DELETE/v1/commercial_sales_receipt_lines/{id}

Path parameters

id*integer

id of the receipt line to delete

Response

200

OK

Request

JavaScriptCurlPython

const response = await fetch('/v1/commercial_sales_receipt_lines/{id}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

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.

GET/v1/commercial_sales_receipts/{id}

Path parameters

id*integer

id of the receipt to get the information of

Response

200

OK

Body

application/json

dataobject

Request

JavaScriptCurlPython

const response = await fetch('/v1/commercial_sales_receipts/{id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "data": {
    "id": 0,
    "attributes": {
      "date": "text",
      "document_no": "text",
      "document_series_id": 0,
      "payment_mechanism": "text",
      "gross_total": 0,
      "net_total": 0,
      "third_party_type": "text",
      "third_party_id": 0,
      "check_number": false,
      "currency_conversion_rate": 0,
      "internal_observations": "text",
      "observations": "text",
      "standalone": false,
      "deleted": false
    },
    "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": 0
        }
      }
    }
  }
}