# 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: [#id-3.-finalizacao-do-documento](https://api-docs.toconline.pt/apis/versoes-anteriores/documentos-de-venda#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="" 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-serie](https://api-docs.toconline.pt/apis/apis-auxiliares/documentos-de-serie "mention") {% endhint %} {% hint style="info" %} Para saber como obter mais informação de como obter o id da Conta Bancária poderá consultar: [contas-bancarias](https://api-docs.toconline.pt/apis/apis-auxiliares/contas-bancarias "mention") {% 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](https://api-docs.toconline.pt/apis/apis-auxiliares/caixa-associada "mention") {% 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="" 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="" 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 %}