# Recibos de Venda

### Criar Cabeçalho Recibo de Venda <a href="#criacao-de-cabecalhos-e-linhas" id="criacao-de-cabecalhos-e-linhas"></a>

{% openapi src="/files/LrXEg3IjIacAycCz7IWE" path="/api/v1/commercial\_sales\_receipts" method="post" %}
[TOConline Open API.yaml](https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2Fgit-blob-1f7bd9dd692716d3f3f93d9c9a4f7226d78277e3%2FTOConline%20Open%20API.yaml?alt=media)
{% endopenapi %}

```json
{ 
    "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"
        }
    ]
}
```

{% hint style="info" %}
**Nota 1:** A série associada ao recibo tem já que existir, e o seu "id" interno deve ser obtido por um

{% code overflow="wrap" %}

```
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>
```

{% endcode %}
{% endhint %}

{% hint style="info" %}
**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> 
```

{% endhint %}

{% hint style="info" %}
**Nota 3:** O "id" interno da conta de caixa da empresa deve ser obtido por um

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

{% endhint %}

### Criar Linhas de Recibo de Venda <a href="#criacao-de-cabecalhos-e-linhas" id="criacao-de-cabecalhos-e-linhas"></a>

{% openapi src="/files/LrXEg3IjIacAycCz7IWE" path="/api/commercial\_sales\_receipt\_lines" method="post" %}
[TOConline Open API.yaml](https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2Fgit-blob-1f7bd9dd692716d3f3f93d9c9a4f7226d78277e3%2FTOConline%20Open%20API.yaml?alt=media)
{% endopenapi %}

### Anular Recibo de Venda <a href="#anulacao-de-um-recibo-caso-seja-preciso" id="anulacao-de-um-recibo-caso-seja-preciso"></a>

{% openapi src="/files/LrXEg3IjIacAycCz7IWE" path="/api/v1/commercial\_sales\_receipts/{salesReceiptId}/void" method="patch" %}
[TOConline Open API.yaml](https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2Fgit-blob-1f7bd9dd692716d3f3f93d9c9a4f7226d78277e3%2FTOConline%20Open%20API.yaml?alt=media)
{% endopenapi %}

No pedido acima, o \<access\_token> corresponde ao token de acesso válido devolvido pelo serviço de OAuth

{% hint style="info" %}
**Nota 1:** O "id" interno do recibo a anular deve ser obtido por um

`GET /api/commercial_sales_receipts?filter[document_no]=<o número do recibo, ex. RC 2020/1>`
{% endhint %}

É 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 <a href="#edicao-do-recibo-apos-criacao" id="edicao-do-recibo-apos-criacao"></a>

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

{% openapi src="/files/LrXEg3IjIacAycCz7IWE" path="/api/v1/commercial\_sales\_receipts/{salesReceiptId}" method="patch" %}
[TOConline Open API.yaml](https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2Fgit-blob-1f7bd9dd692716d3f3f93d9c9a4f7226d78277e3%2FTOConline%20Open%20API.yaml?alt=media)
{% endopenapi %}

#### Exemplo:

{% tabs %}
{% tab title="Payload" %}
{% code title="Exemplo de Payload " %}

```json
{
    "date": "2024-02-24",
    "document_no": "RC 2023/1",
    "document_series_id": 66,
    "payment_mechanism": "MO",
    "gross_total": 10.69,
    "net_total": 9.25,
    "third_party_type": null,
    "third_party_id": null,
    "check_number": null,
    "currency_conversion_rate": 1,
    "internal_observations": "",
    "observations": "",
    "standalone": true,
    "saft_import_id": null,
    "deleted": true,
    "manual_registration_type": null,
    "manual_registration_series": null,
    "manual_registration_number": null,
    "created_at": "2024-02-23 11:49:25.209661",
    "updated_at": "2024-02-27 11:19:15.761393",
    "id": 2,
    "cash_account_id": 2,
    "company_id": 800000046,
    "country_id": 1,
    "currency_id": 1,
    "customer_id": 57,
    "user_id": 800000863,
    "lines": [
        {
            "receipt_id": 2,
            "receivable_type": "Document",
            "receivable_id": 12,
            "received_value": 10.69,
            "settlement_percentage": 0,
            "cashed_vat_amount": null,
            "gross_total": 11.38,
            "settlement_amount": 0.0,
            "net_total": 9.25,
            "retention_total": 0.69,
            "id": 2
        }
    ]
}
```

{% endcode %}
{% endtab %}

{% tab title="Response" %}
{% code title="Exemplo de Response" %}

```json
{
    "date": "2024-02-24",
    "document_no": "RC 2023/1",
    "document_series_id": 66,
    "payment_mechanism": "MO",
    "gross_total": 10.69,
    "net_total": 9.25,
    "third_party_type": null,
    "third_party_id": null,
    "check_number": null,
    "currency_conversion_rate": 1,
    "internal_observations": "",
    "observations": "",
    "standalone": true,
    "saft_import_id": null,
    "deleted": true,
    "manual_registration_type": null,
    "manual_registration_series": null,
    "manual_registration_number": null,
    "created_at": "2024-02-23 11:49:25.209661",
    "updated_at": "2024-02-27 14:03:24.085399",
    "id": 2,
    "cash_account_id": 2,
    "company_id": 800000046,
    "country_id": 1,
    "currency_id": 1,
    "customer_id": 57,
    "user_id": 800000863,
    "lines": [
        {
            "receipt_id": 2,
            "receivable_type": "Document",
            "receivable_id": 12,
            "received_value": 10.69,
            "settlement_percentage": 0,
            "cashed_vat_amount": null,
            "gross_total": 11.38,
            "settlement_amount": 0.0,
            "net_total": 9.25,
            "retention_total": 0.69,
            "id": 2
        }
    ]
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

### Adição de Linha em Documento de Recibo de Venda <a href="#adicao-de-linhas" id="adicao-de-linhas"></a>

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.

{% openapi src="/files/LrXEg3IjIacAycCz7IWE" path="/api/commercial\_sales\_receipt\_lines" method="post" %}
[TOConline Open API.yaml](https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2Fgit-blob-1f7bd9dd692716d3f3f93d9c9a4f7226d78277e3%2FTOConline%20Open%20API.yaml?alt=media)
{% endopenapi %}

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

{% code title="Payload" %}

```json
{
  "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
    }
  }
}
```

{% endcode %}

{% hint style="info" %}
**Nota 1:** O "id" interno do documento (fatura, nota) a receber deve ser obtido por um

{% code overflow="wrap" %}

```
GET /commercial_sales_documents?filter[document_no]=<o número do documento, ex. FT 2020/1>
```

{% endcode %}
{% endhint %}

{% hint style="success" %}
É 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)
{% endhint %}

### Remover Linha do Recibo de Venda

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.

<mark style="color:red;">`DELETE`</mark> `/v1/commercial_sales_receipt_lines/{id}`

#### Path Parameters

| Name                                 | Type    | Description                      |
| ------------------------------------ | ------- | -------------------------------- |
| id<mark style="color:red;">\*</mark> | Integer | id of the receipt line to delete |

{% tabs %}
{% tab title="200: OK OK" %}

{% endtab %}
{% endtabs %}

### Obter Recibo de Venda por ID <a href="#consultar-recibo" id="consultar-recibo"></a>

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.

<mark style="color:blue;">`GET`</mark> `/v1/commercial_sales_receipts/{id}`

#### Path Parameters

| Name                                 | Type    | Description                                 |
| ------------------------------------ | ------- | ------------------------------------------- |
| id<mark style="color:red;">\*</mark> | integer | id of the receipt to get the information of |

{% tabs %}
{% tab title="200: OK OK" %}

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://api-docs.toconline.pt/apis/vendas/recibos-de-venda.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.