# 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 {% hint style="warning" %} Já tem de exisitir um **Documento de Venda Finalizado** Para mais informações consulte: [/pages/V4u6SqQjKMutBhwBvGkr#id-3.-finalizacao-do-documento](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/pages/V4u6SqQjKMutBhwBvGkr#id-3.-finalizacao-do-documento "mention") {% endhint %} Os detalhes do pedido POST para a criação de recibos estão descritos de seguida, em formato OpenAPI, e em cURL. {% openapi src="/files/LrXEg3IjIacAycCz7IWE" path="/api/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%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media\&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7) {% endopenapi %} {% code overflow="wrap" %} ```bash curl -v -X POST -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer ' -d '' '/commercial_sales_receipts' ``` {% endcode %} No pedido acima, o \ corresponde ao token de acesso válido devolvido pelo serviço de OAuth, e o \ deverá ter o seguinte formato {% hint style="info" %} Para saber como obter mais informação de como obter o id dos Documentos de Série poderá consultar: [Documentos de Série](/apis/apis-auxiliares/documentos-de-serie.md) {% endhint %} {% hint style="info" %} Para saber como obter mais informação de como obter o id da Conta Bancária poderá consultar: [Contas Bancárias](/apis/apis-auxiliares/contas-bancarias.md) {% endhint %} {% hint style="info" %} Para saber como obter mais informação de como obter o id da Conta de Caixa Associada poderá consultar: [Caixa Associada](/apis/apis-auxiliares/caixa-associada.md) {% endhint %} {% tabs %} {% tab title="Payload" %} {% code title="Payload" %} ```json { "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": , // [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": ,// [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": // [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 } } } ``` {% endcode %} {% endtab %} {% tab title="Response" %} ```json { "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" } } } } } ``` {% endtab %} {% endtabs %} {% hint style="warning" %} 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. {% endhint %} {% hint style="warning" %} 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. {% endhint %} {% 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]=&filter[number]= ``` {% 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]= ou GET /company_bank_accounts?filter[name]= ``` {% 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]= ``` {% endhint %} ### 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. {% 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%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media\&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7) {% endopenapi %} {% code overflow="wrap" %} ```bash curl -v -X POST -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer ' -d '' '/commercial_sales_receipt_lines' ``` {% endcode %} No pedido acima, o \ corresponde ao token de acesso válido devolvido pelo serviço de OAuth, e o \ 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": "", // [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" : "" // [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]= ``` {% endcode %} {% endhint %} ### 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. {% 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%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media\&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7) {% endopenapi %} {% code overflow="wrap" %} ```bash curl -v -X PATCH -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer ' -d '' '/commercial_sales_receipts/' ``` {% endcode %} No pedido acima, o \ corresponde ao token de acesso válido devolvido pelo serviço de OAuth, e o \ deverá ter o seguinte formato {% tabs %} {% tab title="Payload" %} ```json { "data": { "type": "commercial_sales_receipts", "id": "3", //id do recibo de venda pretendido "attributes": { "deleted": true } } } ``` {% endtab %} {% tab title="Response" %} ```json { "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" } } } } } ``` {% endtab %} {% endtabs %} {% hint style="info" %} **Nota 1:** O "id" interno do recibo a anular pode ser obtido por um {% code overflow="wrap" %} ``` GET /commercial_sales_receipts?filter[document_no]= ``` {% 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 %} --- # 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/versoes-anteriores/vendas/recibos-de-venda.md?ask= ``` 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.