> For the complete documentation index, see [llms.txt](https://cloudware.gitbook.io/documentacao-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cloudware.gitbook.io/documentacao-api/api-v1/recibos.md). # 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 %}