# Documentos de compra Os documentos de compra na versão v1 da API têm a mesma estrutura anteriormente descrita para a v0: são compostos por um cabeçalho e uma ou mais linhas. Nesta nova versão, é possível criar ambos num só pedido, descrito de seguida. ## Criação do documento {% openapi src="/files/0bfv1V2XBFeKz2l1ZR2X" path="/v1/commercial\_purchases\_documents" 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" %} ```bash curl -v -X POST -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer ' -d '' '/v1/commercial_purchases_documents' ``` {% endcode %} O *payload* JSON a enviar contém a seguinte informação: ```json { // Identificação do documento "document_type": "FC|DSP", // [OBRIGATÓRIO] Tipo de documento. "FC": fatura, "DSP": fatura de despesas. "date": "2023-01-01", // [OPCIONAL] Data do documento; por omissão, a data do pedido. // [OPCIONAL] Identificação da série do documento. Por omissão, aplicam-se as regras configuradas na empresa para escolha da série. // Se a série for indicada, usar apenas um dos dois campos seguintes (o "id" ou o prefixo). Se se indicarem os dois, então devem ser consistentes. "document_series_id": 1, // [OPCIONAL] Identificador interno da série. Ver NOTA 1 abaixo. "document_series_prefix": "Prefixo da série", // [OPCIONAL] Em alternativa ao campo "document_series_id". // [OPCIONAL] Identificação do fornecedor. Por omissão, é o fornecedor indiferenciado (NIF "999999990"). // Se o fornecedor for indicado, usar apenas um dos dois campos seguintes (o "id" ou o NIF). Se se indicarem os dois, então devem ser consistentes. "supplier_id": 1, // [OPCIONAL] Identificador interno do fornecedor. Ver NOTA 2. "supplier_tax_registration_number": "999999990", // [OPCIONAL] NIF do fornecedor. se o fornecedor com o NIF indicado não existir, será criado automaticamente. Se o país ("supplier_country") for Portugal ("PT", "PT-AC" ou "PT-MA"), deve ser um NIF português válido. // [OPCIONAL] Os atributos seguintes são usados na criação do fornecedor, se não existir ainda. // Se o fornecedor já existir, são guardados no documento, mas a ficha do fornecedor não é actualizada. "supplier_business_name": "Nome do fornecedor", // [OBRIGATÓRIO] caso o fornecedor ainda não exista e tenha que ser criado. [OPCIONAL] nos outros casos, a não ser que exista mais do que um fornecedor com o NIF indicado, usando-se então o nome para o identificar. "supplier_address_detail": "Morada do fornecedor", // [OPCIONAL] "supplier_postcode": "0000-000", // [OPCIONAL] Código postal do fornecedor, no formato 0000-000. "supplier_city": "Cidade/Localidade do fornecedor", // [OPCIONAL] "supplier_country": "PT", // [OPCIONAL] País do fornecedor. Por omissão, "PT"; é o código ISO alpha-2 do país do fornecedor (vd. https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2; ver também a NOTA 3. // [OPCIONAL] Condições de pagamento "due_date": "2023-02-01", // [OPCIONAL] Data de vencimento; por omissão, a data do documento, ou a referente ao prazo de pagamento configurado no fornecedor, se o fornecedor tiver configurado um prazo de pagamento. "settlement_expression": "7.5", // [OPCIONAL] Desconto no cabeçalho, em percentagem; são suportados descontos compostos, como "3+5" // [OPCIONAL] IVA "vat_included_prices": false, // [OPCIONAL] Os preços nas linhas são com IVA incluído? Por omissão, não (false). "tax_exemption_reason_id": 1, // Motivo de isenção de IVA. [OBRIGATÓRIO] apenas se o documento tiver pelo menos uma linha isenta de IVA. Não deve ser indicado nos restantes casos. Ver NOTA 4. // [OPCIONAL] Moeda. Por omissão, "EUR". // Se a moeda for indicada, usar apenas um dos dois campos seguintes (o "id" ou o código ISO). Se se indicarem os dois, então devem ser consistentes. "currency_id": 1, // [OPCIONAL] Identificador interno da moeda. Ver NOTA 5. "currency_iso_code": "USD", // [OPCIONAL] É o código ISO da moeda do documento (vd. https://en.wikipedia.org/wiki/ISO_4217). "currency_conversion_rate": 1.21, // [OMITIDO] se a moeda for "EUR". [OBRIGATÓRIO] nos restantes casos; é a taxa de conversão para EUR (1 EUR = n USD|...). // [OPCIONAL] Retenção "retention_total": 9.99, // [OPCIONAL] Valor total de retenção. "retention_type": "TD|TI|C|P|CPS|O", // [OPCIONAL] Tipo de retenção. TD: Trabalho dependente, TI: Trabalho independente, C: Capitais, P: Prediais, CPS: Comissões e Prestações de Serviços, O: Outros. Por omissão, "TD". // [OPCIONAL] Outras informações "notes": "Notas ao documento", // [OPCIONAL] "external_reference": "Referência do documento externo", // [OPCIONAL] // [OBRIGATÓRIO] Linhas do documento "lines": [ { // [OPCIONAL] Identificação do item. Se nada for indicado, assume-se uma linha apenas de descrição. "item_type": "Product|Purchases::ExpenseCategory", // [OPCIONAL] Tipo de item: "Product": produto, "Purchases::ExpenseCategory": categoria de despesas. Por omissão fica vazio (linha de descrição). // Se o item for indicado, usar apenas um dos dois campos seguintes (o "id" ou o código). Se se indicarem os dois, então devem ser consistentes entre si, e consistentes com o "item_type". "item_id": 1, // [OPCIONAL] Identificador interno do item. Ver NOTA 6. "item_code": "Código do produto/categoria de despesas", // [OPCIONAL] Já tem que existir o produto/categoria de despesas com este código. Por omissão, é usado o item identificado pelo campo "item_id". Se nada for indicado, assume-se uma linha apenas de descrição. "description": "Descrição da linha", // [OPCIONAL] Por omissão é usada a descrição associada ao item, se este for indicado. [OBRIGATÓRIO] Para uma linha apenas de descrição. // [OPCIONAL] Unidade de medida. Por omissão é a configurada no item (se for produto), ou a por omissão na empresa. // Se a unidade de medida for indicada, usar apenas um dos dois campos seguintes (o "id" ou o código). Se se indicarem os dois, então devem ser consistentes entre si. "unit_of_measure_id": 1, // [OPCIONAL] Identificador interno da unidade de medida. Ver NOTA 7. "unit_of_measure": "Unidade de medida", // [OPCIONAL] Por omissão é a configurada no item (se for produto), ou a por omissão na empresa. // Quantidades e valores. [OBRIGATÓRIO] Para linhas de descrição valorizadas. "quantity": 1, // [OPCIONAL] Por omissão 1, se não for uma linha de descrição valorizada. [OBRIGATÓRIO] Para uma linha de descrição valorizada. "unit_price": 9.99, // [OPCIONAL] Se for indicado um produto. Por omissão é usado o PVP associado ao produto. [OBRIGATÓRIO] Para uma linha de categoria de despesas ou de descrição valorizada. "settlement_expression": "3", // [OPCIONAL] Desconto de linha, em percentagem; são suportados descontos compostos, como "3+5". // [OPCIONAL] IVA. Por omissão é aplicado o IVA associado ao item, ou à taxa normal, na região onde a empresa está localizada. // Se a taxa de IVA for indicada, usar apenas ou o campo "id" ou um ou mais dos três campos seguintes. Se se indicarem todos os campos, então devem ser consistentes entre si. "tax_id": 1, // [OPCIONAL] Identificador interno da taxa de IVA. Ver NOTA 8. "tax_code": "NOR|INT|RED|ISE", // [OPCIONAL] Por omissão é usado o tipo de IVA associado ao item, ou "NOR" se nenhum associado. Os tipos de IVA suportados são "NOR" (normal), "INT" (intermédio), "RED" (reduzido), "ISE" (isento). "tax_percentage": 22, // [OPCIONAL] Percentagem de IVA a usar: serve para indicar uma taxa de outra região (se o campo "tax_country_region" não for indicado) ou uma taxa antiga, já não em vigor. "tax_country_region": "PT-MA" // [OPCIONAL] Região do IVA. Por omissão (e se o campo "tax_percentage" não for indicado) aplica-se a taxa de IVA da região onde a empresa está localizada. }, // Outras linhas, se existirem ... ] } ``` * NOTA 1: A série associada ao documento tem já que existir, e o seu "id" interno pode ser obtido por um {% code overflow="wrap" %} ``` GET /commercial_document_series?filter[document_type]=FC|&filter[prefix]=2020| ``` {% endcode %} * NOTA 2: Se o fornecedor for identificado pelo seu "id" interno tem já que existir, e o seu "id" interno pode ser obtido por um {% code overflow="wrap" %} ``` GET /suppliers?filter[tax_registration_number]= ``` {% endcode %} * NOTA 3: São também suportados dois "países" adicionais: "PT-AC" (Portugal, Açores) e "PT-MA" (Portugal, Madeira). Os países disponíveis podem ser consultados por um GET /countries, ou um em particular por um ``` GET /countries?filter[iso_alpha_2]=PT| ``` * NOTA 4: O "id" interno do motivo de isenção deve ser obtido por um {% code overflow="wrap" %} ``` GET /tax_exemption_reasons?filter[code]=M07| ``` {% endcode %} * NOTA 5: O "id" interno da moeda deve ser obtido por um {% code overflow="wrap" %} ``` GET /currencies?filter[iso_code]=USD| ``` {% endcode %} * NOTA 6: O item (produto ou categoria de despesas) tem já que existir, e o seu "id" interno pode ser obtido por um {% code overflow="wrap" %} ``` GET /products?filter[item_code]= ou GET /expense_categories?filter[accounting_number]=331| ``` {% endcode %} * NOTA 7: A unidade de medida tem já que existir, e o seu "id" interno pode ser obtido por um {% code overflow="wrap" %} ``` GET /units_of_measure?filter[unit_of_measure]=un| ``` {% endcode %} * NOTA 8: O "id" interno da taxa de IVA deve ser obtido por um {% code overflow="wrap" %} ``` GET /taxes?filter[tax_code]=NOR|&filter[tax_country_region]=PT| ou GET /taxes?filter[tax_code]=NOR|&filter[tax_country_region]=PT|&filter[tax_percentage]=22| ``` {% endcode %} ## Eliminação do documento Enquanto estiver em preparação, o documento pode ser eliminado. {% hint style="danger" %} Após a finalização, no entanto, a sua eliminação deixa de ser possível. {% endhint %} {% openapi src="/files/0bfv1V2XBFeKz2l1ZR2X" path="/v1/commercial\_purchases\_documents/{id}" method="delete" %} [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" %} ```bash curl -v -X DELETE -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer ' '/v1/commercial_purchases_documents/' ``` {% endcode %} ## Finalização do documento O documento pode ser imediatamente finalizado aquando da sua criação (ver o ponto anterior, atributo "finalize"). Mas pode ser deixado em preparação, e finalizado depois, por meio de um pedido adicional. {% openapi src="/files/0bfv1V2XBFeKz2l1ZR2X" path="/v1/commercial\_purchases\_documents/{id}/finalize" method="patch" %} [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" %} ```bash curl -v -X PATCH -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer ' -d '' '/v1/commercial_purchases_documents//finalize' ``` {% endcode %} O *payload* JSON a enviar contém a seguinte informação: ```json { "return_pdf": true // [OPCIONAL] Se materializa e devolve logo o PDF do documento (true) ou não (false). Por omissão, false. } ``` {% hint style="info" %} O documento pode continuar a ser alterado mesmo depois de finalizado, desde que ainda não tenha sido pago. {% endhint %} ## Anulação do documento Após a sua finalização, o documento deixa de poder ser eliminado, podendo apenas ser anulado. {% openapi src="/files/0bfv1V2XBFeKz2l1ZR2X" path="/v1/commercial\_purchases\_documents/{id}/void" method="patch" %} [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" %} ```bash curl -v -X PATCH -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer ' -d '' '/v1/commercial_purchases_documents//void' ``` {% endcode %} ## Alteração do documento Após a sua criação, e enquanto estiver em preparação, o documento pode ser alterado. A estrutura do *payload* é a mesma do POST de criação, incluindo cabeçalho e linhas. Os atributos enviados irão substituir os guardados no momento. Relativamente às linhas: * Para cada linha enviada com indicação do atributo "id", os atributos enviados irão substituir os guardados no momento na linha com esse mesmo "id". * Cada linha enviada sem indicação do atributo "id" será considerada uma linha nova, e será acrescentada ao documento. * Para eliminar uma linha existente, deverá usar-se a rota respectiva (ver **Eliminação de uma linha**). {% hint style="info" %} O pedido de alteração pode também incluir, e ser aproveitado para, a finalização do documento — usando o atributo "finalize" — e/ou para a sua materialização em PDF — usando o atributo "return\_pdf". {% endhint %} {% openapi src="/files/0bfv1V2XBFeKz2l1ZR2X" path="/v1/commercial\_purchases\_documents/{id}" method="patch" %} [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" %} ```bash curl -v -X PATCH -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer ' -d '' '/v1/commercial_purchases_documents/' ``` {% endcode %} ### Eliminação de uma linha {% openapi src="/files/0bfv1V2XBFeKz2l1ZR2X" path="/v1/commercial\_purchases\_documents/{id}/lines/{lineId}" method="delete" %} [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" %} ```bash curl -v -X DELETE -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer ' '/v1/commercial_purchases_documents//lines/' ``` {% endcode %} ## Consulta do documento Os documentos podem ser consultados a qualquer altura, antes ou depois de finalizados, e mesmo depois de anulados. {% openapi src="/files/0bfv1V2XBFeKz2l1ZR2X" path="/v1/commercial\_purchases\_documents/{id}" method="get" %} [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" %} ```bash curl -v -X GET -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer ' '/v1/commercial_purchases_documents/' ``` {% endcode %} --- # 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/documentos-de-compra.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.