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

Já tem de exisitir um Documento de Venda Finalizado

Para mais informações consulte: 3. Finalização do documento

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

HTTPcURLJavaScriptPython

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

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
    }

  }
}

Response

{
    "data": {
        "type": "commercial_sales_receipts",
        "id": "6",
        "attributes": {
            "date": "2020-06-01",
            "document_no": "RC 2023/5",
            "document_series_id": 66,
            "payment_mechanism": "MO",
            "gross_total": 0,
            "net_total": 0,
            "third_party_type": "",
            "third_party_id": null,
            "check_number": null,
            "currency_conversion_rate": 1,
            "internal_observations": null,
            "observations": null,
            "standalone": null,
            "saft_import_id": null,
            "deleted": false,
            "manual_registration_type": null,
            "manual_registration_series": null,
            "manual_registration_number": null,
            "created_at": "2024-02-26 11:31:37.827953",
            "updated_at": "2024-02-26 11:31:37.827953"
        },
        "relationships": {
            "bank_accounts": {
                "data": null
            },
            "cash_accounts": {
                "data": null
            },
            "commercial_document_series": {
                "data": {
                    "type": "commercial_document_series",
                    "id": "66"
                }
            },
            "company": {
                "data": {
                    "type": "current_company",
                    "id": "800000046"
                }
            },
            "country": {
                "data": null
            },
            "currency": {
                "data": null
            },
            "customer": {
                "data": null
            },
            "lines": {
                "data": []
            },
            "user": {
                "data": {
                    "type": "current_company_users",
                    "id": "800000863"
                }
            }
        }
    }
}

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.

Quando um documento é finalizado este vai gerar um número do documento com a estrutura [TIPO ANO/NUMERO] através deste poderá executar um filtro nos documentos de série para encontrar o seu documento.

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

HTTPcURLJavaScriptPython

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

HTTPcURLJavaScriptPython

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

Payload

{
    "data": {
        "type": "commercial_sales_receipts",
        "id": "3", //id do recibo de venda pretendido
        "attributes": {
            "deleted": true
        }
    }
}

Response

{
    "data": {
        "type": "commercial_sales_receipts",
        "id": "3",
        "attributes": {
            "date": "2020-06-01",
            "document_no": "RC 2023/2",
            "document_series_id": 66,
            "payment_mechanism": "MO",
            "gross_total": 0,
            "net_total": 0,
            "third_party_type": null,
            "third_party_id": null,
            "check_number": null,
            "currency_conversion_rate": 1,
            "internal_observations": null,
            "observations": null,
            "standalone": null,
            "saft_import_id": null,
            "deleted": true,
            "manual_registration_type": null,
            "manual_registration_series": null,
            "manual_registration_number": null,
            "created_at": "2024-02-23 15:34:36.778593",
            "updated_at": "2024-02-27 12:52:10.462666"
        },
        "relationships": {
            "bank_accounts": {
                "data": null
            },
            "cash_accounts": {
                "data": null
            },
            "commercial_document_series": {
                "data": {
                    "type": "commercial_document_series",
                    "id": "66"
                }
            },
            "company": {
                "data": {
                    "type": "current_company",
                    "id": "800000046"
                }
            },
            "country": {
                "data": null
            },
            "currency": {
                "data": null
            },
            "customer": {
                "data": null
            },
            "lines": {
                "data": []
            },
            "user": {
                "data": {
                    "type": "current_company_users",
                    "id": "800000863"
                }
            }
        }
    }
}

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>

É 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)