Recibos
O atual capítulo tem como objetivo descrever as rotas da API responsáveis pela gestão de recibos
Cada recibo é constituído por:
- 1.Um cabeçalho
- 2.Uma ou mais linhas
O recibo não possui um estado "em preparação".
Um recibo pode ser (3.) anulado.
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
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>/commercial_sales_receipts'
No pedido acima, o <access_token> corresponde ao token de acesso válido devolvido pelo serviço de OAuth, e o <payload JSON> deverá ter o seguinte formato
{
"data": {
"type": "commercial_sales_receipts", // [OBRIGATÓRIO]
"attributes": {
"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.
},
"relationships": { // [OPCIONAL] Recursos associados ao recibo. Caso nenhum seja indicado, este bloco "relationships" deve ser omitido
"commercial_document_series": { // [OPCIONAL] 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
"data": {
"type": "commercial_document_series", // [OBRIGATÓRIO]
"id": "<id da série de recibos associada>" // [OBRIGATÓRIO] Vd. NOTA 1
}
},
"bank_accounts": { // [OPCIONAL] 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.
"data": {
"type": "bank_accounts", // [OBRIGATÓRIO]
"id": "<id da conta bancária>" // [OBRIGATÓRIO] Vd. NOTA 2
}
},
"cash_accounts": { // [OPCIONAL] 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.
"data": {
"type": "cash_accounts", // [OBRIGATÓRIO]
"id": "<id da conta de caixa associada>" // [OBRIGATÓRIO] Vd. NOTA 3// Este id pode ser obtido por um GET /cash_accounts?filter[name]=<nome da conta de caixa>
}
}
}
}
}
Após criar o cabeçalho, a resposta TEM QUE ser consultada para obtenção do identificador interno ("id") do recibo criado. Este identificador será necessário para a criação de todas as linhas.
- 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]=
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_receipt_lines
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>/commercial_sales_receipt_lines'
No pedido acima, o <access_token> corresponde ao token de acesso válido devolvido pelo serviço de OAuth, e o <payload JSON> deverá ter o seguinte formato
{
"data": {
"type": "commercial_sales_receipt_lines", // [OBRIGATÓRIO]
"attributes": {
"receivable_type": "Document", // [OBRIGATÓRIO]
"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"
},
"relationships": { // [OBRIGATÓRIO]
"receipt": { // [OBRIGATÓRIO] Recibo a que esta linha pertence
"data": {
"type": "commercial_sales_receipts", // [OBRIGATÓRIO]
"id": "<id do recibo>" // [OBRIGATÓRIO] Este "id" é o devolvido na resposta ao pedido de criação do cabeçalho, ver acima
}
}
}
}
}
- NOTA 1: O "id" interno do documento (fatura, nota) a receber deve ser obtido por um
GET /commercial_sales_documents?filter[document_no]=<o número do documento, ex. FT 2020/1>
Os detalhes do pedido POST para a criação de recibos estão descritos de seguida, em formato OpenAPI, e em cURL.
patch
/commercial_sales_receipts
curl -v -X PATCH -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' -d '<payload JSON>' '<API_URL>/commercial_sales_receipts/'
No pedido acima, o <access_token> corresponde ao token de acesso válido devolvido pelo serviço de OAuth, e o <payload JSON> deverá ter o seguinte formato
{
"data": {
"type": "commercial_sales_receipts", // [OBRIGATÓRIO]
"id": "<id do recibo>", // [OBRIGATÓRIO] Vd. NOTA 1
"attributes": {
"deleted": true // [OBRIGATÓRIO]
}
}
}
- 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)
Last modified 1mo ago