# Recibos Os recibos seguem a mesma estrutura anteriormente definida: São compostos por um cabeçalho, e linhas. Nesta nova versão, é possível criar ambas as componentes num só pedido, descrito de seguida. ## Criação de cabeçalhos e linhas 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/0bfv1V2XBFeKz2l1ZR2X" path="/v1/commercial\_sales\_receipts" method="post" %} [cloudware-deploy-APIv1-1.0-resolved.yaml](https://1113994710-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiTdJalKSEf3HO0XWftdu%2Fuploads%2FuXSKR4pUABzmU0tMSGJi%2Fcloudware-deploy-APIv1-1.0-resolved.yaml?alt=media\&token=1fed9dbf-2306-40dd-9114-400ccb053fd0) {% endopenapi %} {% code overflow="wrap" %} ``` curl -v -X POST -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer ' -d '' '/v1/commercial_sales_receipts' ``` {% endcode %} ```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. "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|DocumentLine", // [OBRIGATÓRIO] "Document" para receber faturas ou notas, "DocumentLine" para receber uma linha de um SI "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" } ] } ``` * 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]=RC&filter[prefix]=2020| ``` {% endcode %} * 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]= ``` * NOTA 3: O "id" interno da conta de caixa da empresa deve ser obtido por um ``` GET /cash_accounts?filter[name]=ACCOUNT_NAME ``` ### Anulação de um recibo (Caso seja preciso): 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/BO41QI441Vao0H7YUkuO" path="/v1/commercial\_sales\_receipts/{id}" method="delete" %} [api.yaml](https://1113994710-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiTdJalKSEf3HO0XWftdu%2Fuploads%2F2h8nz3uS2MI8cgmdxnVM%2Fapi.yaml?alt=media\&token=75c5b2a7-06b6-432a-a770-76f594a3f901) {% endopenapi %} {% code overflow="wrap" %} ``` curl -v -X DELETE -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer ' '/v1/commercial_sales_receipts/' ``` {% endcode %} No pedido acima, o \ corresponde ao token de acesso válido devolvido pelo serviço de OAuth * NOTA 1: O "id" interno do recibo a anular deve ser obtido por um {% code overflow="wrap" %} ``` GET /commercial_sales_receipts?filter[document_no]= ``` {% endcode %} É 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 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/BO41QI441Vao0H7YUkuO" path="/v1/commercial\_sales\_receipts/{id}" method="patch" %} [api.yaml](https://1113994710-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiTdJalKSEf3HO0XWftdu%2Fuploads%2F2h8nz3uS2MI8cgmdxnVM%2Fapi.yaml?alt=media\&token=75c5b2a7-06b6-432a-a770-76f594a3f901) {% endopenapi %} ### Adição de linhas 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. Neste, o id a enviar no path é o do recibo ao qual pretende adicionar a linha {% openapi src="/files/BO41QI441Vao0H7YUkuO" path="/v1/commercial\_sales\_receipt\_lines/{id}" method="post" %} [api.yaml](https://1113994710-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiTdJalKSEf3HO0XWftdu%2Fuploads%2F2h8nz3uS2MI8cgmdxnVM%2Fapi.yaml?alt=media\&token=75c5b2a7-06b6-432a-a770-76f594a3f901) {% endopenapi %} ### Remoção de linhas 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. {% openapi src="/files/BO41QI441Vao0H7YUkuO" path="/v1/commercial\_sales\_receipt\_lines/{id}" method="delete" %} [api.yaml](https://1113994710-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiTdJalKSEf3HO0XWftdu%2Fuploads%2F2h8nz3uS2MI8cgmdxnVM%2Fapi.yaml?alt=media\&token=75c5b2a7-06b6-432a-a770-76f594a3f901) {% endopenapi %} ### Consultar recibo 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. {% openapi src="/files/BO41QI441Vao0H7YUkuO" path="/v1/commercial\_sales\_receipts/{id}" method="get" %} [api.yaml](https://1113994710-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiTdJalKSEf3HO0XWftdu%2Fuploads%2F2h8nz3uS2MI8cgmdxnVM%2Fapi.yaml?alt=media\&token=75c5b2a7-06b6-432a-a770-76f594a3f901) {% endopenapi %} --- # 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://cloudware.gitbook.io/documentacao-api/api-v1/recibos.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.