Recibos de Venda

Criaçã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.

1. Criar Cabeçalho do Recibo de Venda

Os detalhes do pedido POST para a criação de recibos estão descritos de seguida, em formato OpenAPI, e em cURL.

Criar Cabeçalho de Recibo de Venda

post

Criar Cabeçalho de Recibo de Venda

Authorizations
Body
Responses
200Success
post
POST /api/commercial_sales_receipts HTTP/1.1
Host: {{base_url}}
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 161

{
  "data": {
    "attributes": {
      "date": "2025-06-01",
      "document_series_id": 66,
      "gross_total": 10,
      "net_total": 20,
      "payment_mechanism": "MO"
    },
    "type": "commercial_sales_receipts"
  }
}
200Success

No content

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

Para saber como obter mais informação de como obter o id dos Documentos de Série poderá consultar: Documentos de Série

Para saber como obter mais informação de como obter o id da Conta Bancária poderá consultar: Contas Bancárias

Para saber como obter mais informação de como obter o id da Conta de Caixa Associada poderá consultar: Caixa Associada

Payload
{ 
  "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] 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.
                    
      "document_series_id": <id do documento de série>, // [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
      
      "bank_account_id": <id da conta bancária>,// [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. Vd. Nota 2

      "cash_account_id": <id da caixa> // [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. Vd. Nota3
    }

  }
}

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]=o tipo de documento> &filter[prefix]=<o prefixo da série>&filter[number]=<o numero da série>

Nota 2: O "id" interno da conta bancária da empresa deve ser obtido por um

GET /company_bank_accounts?filter[iban]= <IBAN da conta> 
ou 
GET /company_bank_accounts?filter[name]= <nome da conta> 

Nota 3: O "id" interno da conta de caixa da empresa deve ser obtido por um

GET /cash_accounts?filter[name]= <nome da conta>

2. Criar Linha do Documento de Venda:

Os detalhes do pedido POST para a criação de recibos estão descritos de seguida, em formato OpenAPI, e em cURL.

Adicionar Linha a Recibo de Venda

post

Adicionar Linha a Recibo de Venda

Authorizations
Body
Responses
200Success
post
POST /api/commercial_sales_receipt_lines HTTP/1.1
Host: {{base_url}}
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 285

{
  "data": {
    "attributes": {
      "cashed_vat_amount": null,
      "gross_total": 10.69,
      "net_total": 9.27,
      "receipt_id": 13,
      "receivable_id": 12,
      "receivable_type": "Document",
      "received_value": 10.69,
      "retention_total": 0.72,
      "settlement_amount": 0,
      "settlement_percentage": 0
    },
    "type": "commercial_sales_receipt_lines"
  }
}
200Success

No content

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

Payload
{
  "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"
      "receipt_id" : "<id do recibo>"                            // [OBRIGATÓRIO] Recibo a que esta linha pertence. 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>

3. Anular Recibo de Venda

Os detalhes do pedido POST para a criação de recibos estão descritos de seguida, em formato OpenAPI, e em cURL.

Anular Recibo de Venda

patch

Anular Recibo de Venda

Authorizations
Path parameters
salesReceiptIdstringRequired
Responses
200Success
patch
PATCH /api/v1/commercial_sales_receipts/{salesReceiptId}/void HTTP/1.1
Host: {{base_url}}
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
200Success

No content

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",
        "id": "3", //id do recibo de venda pretendido
        "attributes": {
            "deleted": true
        }
    }
}

Nota 1: O "id" interno do recibo a anular pode ser obtido por um

GET /commercial_sales_receipts?filter[document_no]=<o número do recibo, ex. RC 2020/1>

Last updated