# Documentos de compra ### Criação de compras Tal como no caso dos recibos, as compras são constituídas por: 1. Um cabeçalho 2. Umas ou mais linhas ### 1. Criação do cabeçalho De modo a criar uma compra, deverá inicialmente criar o cabeçalho do documento. Para este efeito, deverá realizar o seguinte pedido: ``` curl -v -X POST -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer ' -d '' '/commercial_purchases_documents' ``` {% openapi src="/files/Ph0j7Hyh5VB7NivP1zhf" path="/commercial\_purchases\_documents" method="post" %} [openapi\_swagger.yml](https://1113994710-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiTdJalKSEf3HO0XWftdu%2Fuploads%2FVKja7VTBGEn3Y3110UWU%2Fopenapi_swagger.yml?alt=media\&token=9ecc7973-2b20-491a-b2ee-e9de90da70ed) {% endopenapi %} No pedido acima, o \ corresponde ao token de acesso válido devolvido pelo serviço de OAuth Caso a compra seja realizada em euros, o \ deverá vir no seguinte formato ``` { "data": { "type": "commercial_purchases_documents", "attributes": { "document_type": "FC", // Pode ser FC (fatura de compra), NCF (nota de crédito), NDF (nota de débito), DSP (fatura de despesaa) "date": "2020-05-25", // Por omissão, a data de hoje "due_date": "2020-05-25", // Por omissão, a data do documento "supplier_tax_registration_number": "888888880", // Por omissão, o fornecedor indiferenciado (999999990) // Os atributos seguintes só são necessários se o fornecedor ainda não existir e tiver que ser criado, ou se os valores forem diferentes dos da ficha "supplier_business_name": "Testes", "supplier_address_detail": "Rua dos testes 777A", "supplier_postcode": "4200-224", "supplier_city": "Porto", "supplier_country": "PT", // Por omissão, PT. Pode ainda ser PT-AC (Açores) e PT-MA (Madeira) // Indicar o atributo seguinte, com o valor true, apenas se os preços indicados nas linhas forem preços com IVA incluído "external_reference": "Texto livre, referente ao campo Vossa Ref.", // "vat_included_prices": true, // Indicar o atributo seguinte apenas se existir desconto de cabeçalho (7,5%, neste exemplo) "settlement_expression": "7.5", // Indicar o atributo seguinte apenas se existir retenção (10€, neste exemplo) "retention_total": 10 }, "relationships": { "commercial_document_series": { // Associação à série de documentos. Pode ser omitida, se for para usar a série por omissão "data": { "type": "commercial_document_series", "id": "" // Este id pode ser obtido por um GET /commercial_document_series?filter[document_type]=FC|NCF|...&filter[prefix]=2020|ou outro qualquer... } } } } } ``` Caso deseje realizar a compra numa outra moeda, o payload deverá vir no seguinte formato ``` { "data": { "type": "commercial_purchases_documents", "attributes": { "document_type": "FC", // Pode ser FC, NCF, NDF, DSP "date": "2020-05-25", // Por omissão, a data de hoje "due_date": "2020-05-25", // Por omissão, a data do documento "currency_conversion_rate": 0.813 // Obrigatório quando a moeda não é EUR. Taxa de conversão da moeda para EUR (1 EUR = x) "supplier_tax_registration_number": "888888880", // Por omissão, o fornecedor indiferenciado (999999990) // Os atributos seguintes só são necessários se o fornecedor ainda não existir e tiver que ser criado, ou se os valores forem diferentes dos da ficha "supplier_business_name": "Testes", "supplier_address_detail": "Rua dos testes 777A", "supplier_postcode": "4200-224", "supplier_city": "Porto", "supplier_country": "PT", // Por omissão, PT. Pode ainda ser PT-AC (Açores) e PT-MA (Madeira) // Indicar o atributo seguinte, com o valor true, apenas se os preços indicados nas linhas forem preços com IVA incluído "vat_included_prices": true, // Indicar o atributo seguinte apenas se existir desconto de cabeçalho (7,5%, neste exemplo) "settlement_expression": "7.5", // Indicar o atributo seguinte apenas se existir retenção (10€, neste exemplo) "retention_total": 10 }, "relationships": { "currency": { // Associação à moeda do documento. Pode ser omitida, se for um documento em EUR "data": { "type": "currencies", "id": "" // Este id pode ser obtido por um GET /currencies?filter[iso_code]=USD|... } }, "commercial_document_series": { // Associação à série de documentos. Pode ser omitida, se for para usar a série por omissão "data": { "type": "commercial_document_series", "id": "" // Este id pode ser obtido por um GET /commercial_document_series?filter[document_type]=FC|NCF|...&filter[prefix]=2020|ou outro qualquer... } } } } } ``` Após criar o cabeçalho, a resposta TEM QUE ser consultada para obtenção do identificador interno ("id") da compra criada. Este identificador será necessário para a criação de todas as linhas. ### 2. Criação de linhas Em todos os pedidos seguintes, é necessário saber qual o id do documento de compra. Este id pode ser guardado a partir da resposta (JSON) ao pedido de criação anterior, ou pode ser consultado via API. Via API, o id do documento pode ser obtido por um ``` GET /commercial_purchases_documents?filter[document_no]= ``` Se o documento ainda não estiver finalizado (fechado), ainda não tem número atribuído, e então o GET anterior não poderá ser feito. Em alternativa pode ser feito um ``` GET /commercial_purchases_documents?filter[status]=0&filter[supplier_tax_registration_number]= ``` Na resposta a este pedido, procurar o documento a que se quer adicionar as linhas De modo a inserir linhas na compra criada, deverá realizar o seguinte pedido ``` curl -v -X POST -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer ' -d '' '/commercial_purchases_document_lines' ``` {% openapi src="/files/Ph0j7Hyh5VB7NivP1zhf" path="/commercial\_purchases\_document\_lines" method="post" %} [openapi\_swagger.yml](https://1113994710-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiTdJalKSEf3HO0XWftdu%2Fuploads%2FVKja7VTBGEn3Y3110UWU%2Fopenapi_swagger.yml?alt=media\&token=9ecc7973-2b20-491a-b2ee-e9de90da70ed) {% endopenapi %} No pedido acima, o \ corresponde ao token de acesso válido devolvido pelo serviço de OAuth. O payload JSON deverá vir no seguinte formato, dependendo se se trata de um produto, ou categoria de despesa NOTA: nos documentos de despesas (tipo de documento DSP) só são aceites linhas de categorias de despesa, não de produtos #### Linha de produto ``` { "data": { "type": "commercial_purchases_document_lines", "attributes": { "quantity": 1, "unit_price": 20, "item_type": "Product", "item_code": "PTEST", // NOTA: já tem que existir o produto com este código // Indicar o atributo seguinte apenas se existir desconto de linha (3%, neste exemplo) "settlement_expression":"3" }, "relationships": { "document": { // Associação ao documento de compra "data": { "type": "commercial_purchases_documents", "id": "" } }, "tax": { "data": { "type": "taxes", "id": "1" // O id da taxa de IVA pode ser obtido por um GET /taxes?filter[tax_code]=NOR|INT|RED|ISE } } } } } ``` #### Linha de categoria de despesas ``` { "data": { "type": "commercial_purchases_document_lines", "attributes": { "quantity": 1, "unit_price": 20, "item_type": "Purchases::ExpenseCategory", "item_code": "ETEST" // NOTA: já tem que existir a categoria de despesa com este código }, "relationships": { "document": { // Associação ao documento de compra "data": { "type": "commercial_purchases_documents", "id": "" } }, "tax": { "data": { "type": "taxes", "id": "1" // O id da taxa de IVA pode ser obtido por um GET /taxes?filter[tax_code]=NOR|INT|RED|ISE } } } } } ``` ### 3. Finalização do documento De modo a finalizar o documento, deverá realizar o seguinte pedido {% openapi src="/files/Ph0j7Hyh5VB7NivP1zhf" path="/commercial\_purchases\_documents" method="patch" %} [openapi\_swagger.yml](https://1113994710-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiTdJalKSEf3HO0XWftdu%2Fuploads%2FVKja7VTBGEn3Y3110UWU%2Fopenapi_swagger.yml?alt=media\&token=9ecc7973-2b20-491a-b2ee-e9de90da70ed) {% endopenapi %} ``` curl -v -X PATCH -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer ' -d '' '/commercial_purchases_documents' ``` NOTA: o documento e as linhas podem continuar a ser alterados mesmo depois de finalizados (fechados) Neste, o payload JSON deverá ser ``` { "type": "commercial_purchases_documents", "id": "", "data": { "attributes": { "status": 1 } } } ``` ### 4. Anulação de um documento (caso seja preciso) De modo a proceder à anulação de um documento deverá realizar o mesmo pedido descrito acima, alterando o payload JSON para ``` { "data": { "type": "commercial_purchases_documents", "id": "", "attributes": { "status": 4, "voided_reason": "Texto livre com o motivo pelo qual se está a anular o documento" // Opcional, não precisa de ser indicada } } } ``` --- # 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-v0/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.