Documentação API
Search…
⌃K

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
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.
"commercial_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", // [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"
}
]
}
  • 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}
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}

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}

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}

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}