# 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="" 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="" 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="" 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 } } } ```