Documentos de venda
As rotas aqui descritas permitem gerir todos os processos relativos a documentos de venda: orçamentos, faturas-proforma, guias, faturas e notas.
Criação do documento
Cada documento é constituído por:
Um cabeçalho
Uma ou mais linhas
Após a sua criação, o documento fica no estado "em preparação", podendo, nesse estado, continuar a ser alterado. Para terminar definitivamente as alterações ao documento, assiná-lo e permitir a sua impressão, há depois que:
3. Finalizar o documento
Um documento finalizado já não pode ser alterado nem eliminado, apenas anulado.
1. Criação do cabeçalho
curl -v -X POST -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' -d '<payload JSON>' '<API_URL>/commercial_sales_documents'No pedido acima, o access_token é o token de acesso válido devolvido pelo serviço de OAuth. O payload JSON a enviar contém a seguinte informação:
{
"data": {
"type": "commercial_sales_documents", // [OBRIGATÓRIO]
"attributes": { // [OBRIGATÓRIO] Os atributos do documento
// Identificação do documento
"document_type": "FT|FS|FR", // [OBRIGATÓRIO] Tipo de documento. "FT": fatura, "FS": fatura simplificada, "FR": fatura-recibo.
"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 ou o campo seguinte (o prefixo) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes.
"document_series_prefix": "Prefixo da série", // [OPCIONAL] Em alternativa ao campo "document_series_id".
// [OPCIONAL] Identificação do cliente. Por omissão, é o consumidor final (NIF "999999990").
// Se o cliente for indicado, usar apenas ou o campo seguinte (o NIF) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes.
"customer_tax_registration_number": "999999990", // [OPCIONAL] NIF do cliente. se o cliente com o NIF indicado não existir, será criado automaticamente. Se o país ("customer_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 cliente, se não existir ainda.
// Se o cliente já existir, são guardados no documento, mas a ficha do cliente não é actualizada.
"customer_business_name": "Nome do cliente", // [OBRIGATÓRIO] caso o cliente ainda não exista e tenha que ser criado. [OPCIONAL] nos outros casos, a não ser que exista mais do que um cliente com o NIF indicado, usando-se então o nome para o identificar.
"customer_address_detail": "Morada do cliente", // [OPCIONAL]
"customer_postcode": "0000-000", // [OPCIONAL] Código postal do cliente, no formato 0000-000.
"customer_city": "Cidade/Localidade do cliente", // [OPCIONAL]
"customer_country": "PT", // [OPCIONAL] País do cliente. Por omissão, "PT"; é o código ISO alpha-2 do país do cliente (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 cliente, se o cliente 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"
"payment_mechanism": "MO|CH|DC|CC|TR|CO|CS|DE|LC|MB|OU|RT|DDA", // [OPCIONAL] Necessário apenas no caso das FR. Por omissão, "MO", ou o configurado no cliente, se o cliente tiver configurado um modo de pagamento. Modos 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": Multibanco, "CO": Cartão oferta, "CS": Compensação de saldos, "DE": Dinheiro eletrónico, "LC": Letra comercial, "OU": Outros, "RT": Ticket restaurante.
// [OPCIONAL] IVA
"vat_included_prices": false, // [OPCIONAL] Os preços nas linhas são com IVA incluído? Por omissão, não (false).
"operation_country": "PT-MA", // [OPCIONAL] A região de operação para efeitos de IVA: usada apenas para as linhas de serviços. Por omissão, é a região onde a empresa está localizada. Para o regime OSS pode ainda usar-se o código ISO alpha-2 do país OSS (vd. https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2; ver também a NOTA 3.
// [OPCIONAL] Moeda. Por omissão, "EUR".
// Se a moeda for indicada, usar apenas ou o campos seguinte (o código ISO) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes.
"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": 7.5, // [OPCIONAL] Percentagem de retenção a aplicar sobre os serviços.
"retention_type": "IRS|IRC", // [OPCIONAL] Tipo de retenção ("IRS" ou "IRC"). Por omissão, "IRS".
"apply_retention_when_paid": true, // [OPCIONAL] A retenção é feita logo no documento (false) ou apenas no recebimento (true). Por omissão, false.
// [OPCIONAL] Outras informações
"notes": "Notas ao documento", // [OPCIONAL]
"external_reference": "Referência do documento externo" // [OPCIONAL]
},
"relationships": { // [OPCIONAL] Recursos associados ao documento. Caso nenhum seja indicado, este bloco "relationships" deve ser omitido
// [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 ou o "id" nesta "relationship" ou campo "document_series_prefix" (o prefixo; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
"commercial_document_series": {
"data": {
"type": "commercial_document_series", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno da série. Ver NOTA 1 abaixo.
}
},
// [OPCIONAL] Identificação do cliente. Por omissão, é o consumidor final (NIF "999999990").
// Se o cliente for indicado, usar apenas ou o "id" nesta "relationship" ou o campo "tax_registration_number" (o NIF; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
"customer": {
"data": {
"type": "customers", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno do cliente. Ver NOTA 2.
}
},
// [OPCIONAL] Necessário apenas no caso das FR. Conta bancária da empresa para onde o recebimento é feito. Usado apenas quando o meio de pagamento da FR é "DC", "CC", "TR" ou "DDA", e apenas se for necessário indicar uma conta bancária específica.
"bank_accounts": {
"data": {
"type": "bank_accounts", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno da conta bancária da empresa. Ver NOTA 4.
}
},
// [OPCIONAL] Necessário apenas no caso das FR. Conta de caixa da empresa para onde o recebimento é feito. Usado apenas quando o meio de pagamento da FR é "MO".
"cash_accounts": {
"data": {
"type": "cash_accounts", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno da conta de caixa da empresa. Ver NOTA 5.
}
},
// 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.
"tax_exemption_reasons": {
"data": {
"type": "tax_exemption_reasons", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno do motivo de isenção do IVA. Ver NOTA 6.
}
},
// [OPCIONAL] Moeda. Por omissão, "EUR".
// Se a moeda for indicada, usar apenas ou o "id" nesta "relationship" ou o campo "currency_iso_code" (o código ISO; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
"currency": {
"data": {
"type": "currencies", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno da moeda. Ver NOTA 7.
}
}
}
}
}NOTA 1: A série associada ao documento tem já que existir, e o seu "id" interno pode ser obtido por um
GET /commercial_document_series?filter[document_type]=FT|<o tipo de documento>&filter[prefix]=2020|<o prefixo da série a usar> NOTA 2: Se o cliente for identificado pelo seu "id" interno tem já que existir, e o seu "id" interno pode ser obtido por um
GET /customers?filter[tax_registration_number]=<o NIF do cliente>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|<o código do país>NOTA 4: O "id" interno da conta bancária da empresa deve ser obtido por um
GET /company_bank_accounts?filter[iban]=<IBAN da conta>
ou
GET /company_bank_accounts?filter[name]=<nome da conta> NOTA 5: O "id" interno da conta de caixa da empresa deve ser obtido por um
GET /cash_accounts?filter[name]=<nome da conta>NOTA 6: O "id" interno do motivo de isenção deve ser obtido por um
GET /tax_exemption_reasons?filter[code]=M07|<o código legal do motivo de isenção> NOTA 7: O "id" interno da moeda deve ser obtido por um
GET /currencies?filter[iso_code]=USD|<o código ISO da moeda>2. Criação da(s) linha(s)
As linhas podem referenciar três tipos de itens: produtos, serviços ou descritores (juros, imobilizado, impostos especiais...). Para cada um destes o payload é ligeiramente diferente, e cada um será descrito de seguida. Podem ainda ser criadas linhas apenas de descrição, com ou sem valor associado.
curl -v -X POST -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' -d '<payload JSON>' '<API_URL>/commercial_sales_document_lines'No pedido acima, o access_token é o token de acesso válido devolvido pelo serviço de OAuth. O payload JSON genérico a enviar contém a seguinte informação:
{
"data": {
"type": "commercial_sales_document_lines", // [OBRIGATÓRIO]
"attributes": { // [OBRIGATÓRIO] Os atributos da linha do documento
// [OPCIONAL] Identificação do item. Se nada for indicado, assume-se uma linha apenas de descrição.
"item_type": "Service|Product|TaxDescriptor", // [OPCIONAL] Tipo de item: "Service": serviço, "Product": produto, "TaxDescriptor": descritor. Por omissão, assume-se uma linha apenas de descrição.
// Se o item for indicado, usar apenas ou o campo seguinte (o código) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes entre si, e consistentes com o "item_type".
"item_code": "Código do serviço/produto/descritor", // [OPCIONAL] Já tem que existir o produto/serviço/descritor com este código. Por omissão, é usado o item identificado pela "relationship" respectiva, se indicada. 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 serviço ou produto), ou a por omissão na empresa.
// Se a unidade de medida for indicada, usar apenas ou o campo seguinte (o código) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes entre si.
"unit_of_measure": "Unidade de medida", // [OPCIONAL] Por omissão é a configurada no item, ou a por omissão na empresa.
// Quantidades e valores. [OBRIGATÓRIO] Para linhas de descrição com valor.
"quantity": 1, // [OPCIONAL] Por omissão 1, se não for uma linha de descrição com valor. [OBRIGATÒRIO] Para uma linha de descrição com valor.
"unit_price": 9.99, // [OPCIONAL] Se for indicado um serviço ou produto. Por omissão é usado o PVP associado ao item (serviço ou produto). [OBRIGATÓRIO] Para uma linha de descritor ou de descrição com valor.
"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, ou — apenas para as linhas de serviços — a região de operação para efeitos de IVA, se indicada.
// Se a taxa de IVA for indicada, usar apenas um ou mais dos três campos seguintes ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem todos os campos, então devem ser consistentes entre si.
// [NÃO PODE SER USADO] no caso de uma linha de descrição sem valor, ou de um descritor que são suporte IVA: ou seja, um descritor referente a uma retenção (taxa SIRCA, outras retenções...)
"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, ou — apenas para as linhas de serviços — a região de operação para efeitos de IVA, se indicada. Para o regime OSS pode ainda usar-se o código ISO alpha-2 do país OSS (vd. https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2; ver também a NOTA 3.
},
"relationships": { // [OBRIGATÓRIO] Recursos associados à linha do documento.
// [OBRIGATÓRIO] Identificação do documento (cabeçalho) a que esta linha pertence.
"document": {
"data": {
"type": "commercial_sales_documents", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno do documento (cabeçalho). Ver NOTA 1.
}
},
// [OPCIONAL] Produto associado à linha. Só deve ser indicado para as linhas de produtos.
// Se o produto for indicado, usar apenas ou o "id" nesta "relationship" ou o campo "item_code" (o código do produto; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
"product": {
"data": {
"type": "products", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno do produto. Ver NOTA 2.
}
},
// [OPCIONAL] Serviço associado à linha. Só deve ser indicado para as linhas de serviços.
// Se o serviço for indicado, usar apenas ou o "id" nesta "relationship" ou o campo "item_code" (o código do serviço; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
"service": {
"data": {
"type": "services", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno do serviço. Ver NOTA 2.
}
},
// [OPCIONAL] Descritor associado à linha. Só deve ser indicado para as linhas de descritores.
// Se o descritor for indicado, usar apenas ou o "id" nesta "relationship" ou o campo "item_code" (o código do descritor; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
"tax_descriptor": {
"data": {
"type": "tax_descriptors", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno do descritor. Ver NOTA 2.
}
},
// [OPCIONAL] Unidade de medida. Por omissão é a configurada no item (se for serviço ou produto), ou a por omissão na empresa.
// Se a unidade de medida for indicada, usar apenas ou o "id" nesta "relationship" ou o campo "unit_of_measure" (o código da unidade; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
"unit_of_measure": {
"data": {
"type": "units_of_measure", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno da unidade de medida. Ver NOTA 4.
}
},
// [OPCIONAL] IVA. Por omissão é aplicado o IVA associado ao item, ou à taxa normal na região onde a empresa está localizada, ou — apenas para as linhas de serviços — a região de operação para efeitos de IVA, se indicada.
// Se a taxa de IVA for indicada, usar apenas ou o "id" nesta "relationship" ou um ou mais dos três campos "tax_code", "tax_percentage" e "tax_country_region" (o tipo, a percentagem e/ou a região do IVA; ver mais acima). Se se indicarem todos os campos, então devem ser consistentes.
// [NÃO PODE SER USADO] no caso de uma linha de descrição sem valor, ou de um descritor que são suporte IVA: ou seja, um descritor referente a uma retenção (taxa SIRCA, outras retenções...)
"tax": {
"data": {
"type": "taxes", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno da taxa de IVA. Ver NOTA 5.
}
}
}
}
}NOTA 1: O "id" interno do documento (cabeçalho) a que a linha pertence é o devolvido no campo "id" da resposta ao pedido de criação do cabeçalho (ver ponto 1. Criação do cabeçalho).
NOTA 2: O item (serviço, produto ou descritor) tem já que existir, e o seu "id" interno pode ser obtido por um
GET /services?filter[item_code]=<o código do serviço>
ou
GET /products?filter[item_code]=<o código do produto>
ou
GET /tax_descriptors?filter[notation]=<o código do descritor>NOTA 3: Além de "PT" (Portugal, Continente) são também suportadas as duas regiões de IVA "PT-AC" (Portugal, Açores) e "PT-MA" (Portugal, Madeira).
Para os regimes de IVA no âmbito do OSS, os códigos de região são os mesmos que os códigos do país, podendo ser consultadas por um
GET /countries?filter[iso_alpha_2]=<o código do país OSS>NOTA 4: A unidade de medida tem já que existir, e o seu "id" interno pode ser obtido por um
GET /units_of_measure?filter[unit_of_measure]=un|<o código da unidade de medida>NOTA 5: O "id" interno da taxa de IVA deve ser obtido por um
GET /taxes?filter[tax_code]=NOR|<o tipo de IVA>&filter[tax_country_region]=PT|<a região do IVA>
ou
GET /taxes?filter[tax_code]=NOR|<o tipo de IVA>&filter[tax_country_region]=PT|<a região do IVA>&filter[tax_percentage]=22|<a percentagem IVA>2.1. Criação de uma linha de produto
Para o caso particular de uma linha de produto, o payload contém a seguinte informação:
{
"data": {
"type": "commercial_sales_document_lines", // [OBRIGATÓRIO]
"attributes": { // [OBRIGATÓRIO] Os atributos da linha do documento
// [OBRIGATÓRIO] Identificação do produto.
"item_type": "Product", // [OBRIGATÓRIO] Tipo de item: "Product": produto.
// Usar apenas ou o campo seguinte (o código) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes entre si.
"item_code": "Código do produto", // [OPCIONAL] Já tem que existir o produto com este código. Por omissão, é usado o produto identificado pela "relationship" respectiva, se indicada.
"description": "Descrição da linha", // [OPCIONAL] Por omissão é usada a descrição associada ao produto.
// [OPCIONAL] Unidade de medida. Por omissão é a configurada no produto, ou a por omissão na empresa.
// Se a unidade de medida for indicada, usar apenas ou o campo seguinte (o código) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes entre si.
"unit_of_measure": "Unidade de medida", // [OPCIONAL] Por omissão é a configurada no produto, ou a por omissão na empresa.
// [OPCIONAL] Quantidades e valores.
"quantity": 1, // [OPCIONAL] Por omissão 1.
"unit_price": 9.99, // [OPCIONAL] Por omissão é usado o PVP associado ao produto.
"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 produto, ou à taxa normal, na região onde a empresa está localizada.
// Se a taxa de IVA for indicada, usar apenas um ou mais dos três campos seguintes ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem todos os campos, então devem ser consistentes entre si.
"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. Para o regime OSS pode ainda usar-se o código ISO alpha-2 do país OSS (vd. https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2; ver também a NOTA 3.
},
"relationships": { // [OBRIGATÓRIO] Recursos associados à linha do documento.
// [OBRIGATÓRIO] Identificação do documento (cabeçalho) a que esta linha pertence.
"document": {
"data": {
"type": "commercial_sales_documents", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno do documento (cabeçalho). Ver NOTA 1.
}
},
// [OPCIONAL] Produto associado à linha.
// Usar apenas ou o "id" nesta "relationship" ou o campo "item_code" (o código do produto; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
"product": {
"data": {
"type": "products", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno do produto. Ver NOTA 2.
}
},
// [OPCIONAL] Unidade de medida. Por omissão é a configurada no produto, ou a por omissão na empresa.
// Se a unidade de medida for indicada, usar apenas ou o "id" nesta "relationship" ou o campo "unit_of_measure" (o código da unidade; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
"unit_of_measure": {
"data": {
"type": "units_of_measure", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno da unidade de medida. Ver NOTA 4.
}
},
// [OPCIONAL] IVA. Por omissão é aplicado o IVA associado ao produto, ou à taxa normal na região onde a empresa está localizada.
// Se a taxa de IVA for indicada, usar apenas ou o "id" nesta "relationship" ou um ou mais dos três campos "tax_code", "tax_percentage" e "tax_country_region" (o tipo, a percentagem e/ou a região do IVA; ver mais acima). Se se indicarem todos os campos, então devem ser consistentes.
"tax": {
"data": {
"type": "taxes", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno da taxa de IVA. Ver NOTA 5.
}
}
}
}
}2.2. Criação de uma linha de serviço
Para o caso particular de uma linha de serviço, este payload contém a seguinte informação:
{
"data": {
"type": "commercial_sales_document_lines", // [OBRIGATÓRIO]
"attributes": { // [OBRIGATÓRIO] Os atributos da linha do documento
// [OBRIGATÓRIO] Identificação do serviço.
"item_type": "Service", // [OBRIGATÓRIO] Tipo de item: "Service": serviço.
// Usar apenas ou o campo seguinte (o código) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes entre si.
"item_code": "Código do serviço", // [OPCIONAL] Já tem que existir o serviço com este código. Por omissão, é usado o serviço identificado pela "relationship" respectiva, se indicada.
"description": "Descrição da linha", // [OPCIONAL] Por omissão é usada a descrição associada ao serviço.
// [OPCIONAL] Unidade de medida. Por omissão é a configurada no serviço, ou a por omissão na empresa.
// Se a unidade de medida for indicada, usar apenas ou o campo seguinte (o código) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes entre si.
"unit_of_measure": "Unidade de medida", // [OPCIONAL] Por omissão é a configurada no serviço, ou a por omissão na empresa.
// [OPCIONAL] Quantidades e valores.
"quantity": 1, // [OPCIONAL] Por omissão 1.
"unit_price": 9.99, // [OPCIONAL] Por omissão é usado o PVP associado ao serviço.
"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 serviço, ou à taxa normal, na região onde a empresa está localizada, ou a região de operação para efeitos de IVA, se indicada.
// Se a taxa de IVA for indicada, usar apenas um ou mais dos três campos seguintes ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem todos os campos, então devem ser consistentes entre si.
"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, ou a região de operação para efeitos de IVA, se indicada. Para o regime OSS pode ainda usar-se o código ISO alpha-2 do país OSS (vd. https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2; ver também a NOTA 3.
},
"relationships": { // [OBRIGATÓRIO] Recursos associados à linha do documento.
// [OBRIGATÓRIO] Identificação do documento (cabeçalho) a que esta linha pertence.
"document": {
"data": {
"type": "commercial_sales_documents", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno do documento (cabeçalho). Ver NOTA 1.
}
},
// [OPCIONAL] Serviço associado à linha.
// Usar apenas ou o "id" nesta "relationship" ou o campo "item_code" (o código do serviço; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
"service": {
"data": {
"type": "services", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno do serviço. Ver NOTA 2.
}
},
// [OPCIONAL] Unidade de medida. Por omissão é a configurada no serviço, ou a por omissão na empresa.
// Se a unidade de medida for indicada, usar apenas ou o "id" nesta "relationship" ou o campo "unit_of_measure" (o código da unidade; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
"unit_of_measure": {
"data": {
"type": "units_of_measure", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno da unidade de medida. Ver NOTA 4.
}
},
// [OPCIONAL] IVA. Por omissão é aplicado o IVA associado ao serviço, ou à taxa normal na região onde a empresa está localizada, ou a região de operação para efeitos de IVA, se indicada.
// Se a taxa de IVA for indicada, usar apenas ou o "id" nesta "relationship" ou um ou mais dos três campos "tax_code", "tax_percentage" e "tax_country_region" (o tipo, a percentagem e/ou a região do IVA; ver mais acima). Se se indicarem todos os campos, então devem ser consistentes.
"tax": {
"data": {
"type": "taxes", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno da taxa de IVA. Ver NOTA 5.
}
}
}
}
}2.3. Criação de uma linha de descritor
Para o caso particular de uma linha de descritor, este payload contém a seguinte informação:
{
"data": {
"type": "commercial_sales_document_lines", // [OBRIGATÓRIO]
"attributes": { // [OBRIGATÓRIO] Os atributos da linha do documento
// [OBRIGATÓRIO] Identificação do descritor.
"item_type": "TaxDescriptor", // [OBRIGATÓRIO] Tipo de item: "TaxDescriptor": descritor.
// Usar apenas ou o campo seguinte (o código) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes entre si.
"item_code": "Código do descritor", // [OPCIONAL] Já tem que existir o descritor com este código. Por omissão, é usado o descritor identificado pela "relationship" respectiva, se indicada.
"description": "Descrição da linha", // [OPCIONAL] Por omissão é usada a descrição associada ao descritor.
// [OPCIONAL] Unidade de medida. Por omissão é a configurada por omissão na empresa.
// Se a unidade de medida for indicada, usar apenas ou o campo seguinte (o código) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes entre si.
"unit_of_measure": "Unidade de medida", // [OPCIONAL] Por omissão é a configurada por omissão na empresa.
// [OBRIGATÓRIO] Quantidades e valores.
"quantity": 1, // [OPCIONAL] Por omissão 1, se não for uma linha de descrição com valor. [OBRIGATÒRIO] Para uma linha de descrição com valor.
"unit_price": 9.99, // [OBRIGATÓRIO]
"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 descritor, ou à taxa normal, na região onde a empresa está localizada.
// Se a taxa de IVA for indicada, usar apenas um ou mais dos três campos seguintes ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem todos os campos, então devem ser consistentes entre si.
// [NÃO PODE SER USADO] no caso de uma linha de descritor que são suporte IVA: ou seja, um descritor referente a uma retenção (taxa SIRCA, outras retenções...)
"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. Para o regime OSS pode ainda usar-se o código ISO alpha-2 do país OSS (vd. https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2; ver também a NOTA 3.
},
"relationships": { // [OBRIGATÓRIO] Recursos associados à linha do documento.
// [OBRIGATÓRIO] Identificação do documento (cabeçalho) a que esta linha pertence.
"document": {
"data": {
"type": "commercial_sales_documents", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno do documento (cabeçalho). Ver NOTA 1.
}
},
// [OPCIONAL] Descritor associado à linha.
// Usar apenas ou o "id" nesta "relationship" ou o campo "item_code" (o código do descritor; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
"tax_descriptor": {
"data": {
"type": "tax_descriptors", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno do descritor. Ver NOTA 2.
}
},
// [OPCIONAL] Unidade de medida. Por omissão é a configurada por omissão na empresa.
// Se a unidade de medida for indicada, usar apenas ou o "id" nesta "relationship" ou o campo "unit_of_measure" (o código da unidade; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
"unit_of_measure": {
"data": {
"type": "units_of_measure", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno da unidade de medida. Ver NOTA 4.
}
},
// [OPCIONAL] IVA. Por omissão é aplicado o IVA associado ao descritor, ou à taxa normal na região onde a empresa está localizada.
// Se a taxa de IVA for indicada, usar apenas ou o "id" nesta "relationship" ou um ou mais dos três campos "tax_code", "tax_percentage" e "tax_country_region" (o tipo, a percentagem e/ou a região do IVA; ver mais acima). Se se indicarem todos os campos, então devem ser consistentes.
// [NÃO PODE SER USADO] no caso de uma linha de descritor que são suporte IVA: ou seja, um descritor referente a uma retenção (taxa SIRCA, outras retenções...)
"tax": {
"data": {
"type": "taxes", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno da taxa de IVA. Ver NOTA 5.
}
}
}
}
}2.4. Criação de uma linha de descrição com valor
Para o caso particular de uma linha de descrição com valor, este payload contém a seguinte informação:
{
"data": {
"type": "commercial_sales_document_lines", // [OBRIGATÓRIO]
"attributes": { // [OBRIGATÓRIO] Os atributos da linha do documento
"description": "Descrição da linha", // [OBRIGATÓRIO]
// [OPCIONAL] Unidade de medida. Por omissão é a configurada por omissão na empresa.
// Se a unidade de medida for indicada, usar apenas ou o campo seguinte (o código) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes entre si.
"unit_of_measure": "Unidade de medida", // [OPCIONAL] Por omissão é a configurada por omissão na empresa.
// [OBRIGATÓRIO] Quantidades e valores.
"quantity": 1, // [OBRIGATÒRIO]
"unit_price": 9.99, // [OBRIGATÒRIO]
"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 à taxa normal, na região onde a empresa está localizada.
// Se a taxa de IVA for indicada, usar apenas um ou mais dos três campos seguintes ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem todos os campos, então devem ser consistentes entre si.
"tax_code": "NOR|INT|RED|ISE", // [OPCIONAL] Por omissão é usado o tipo de IVA "NOR". 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. Para o regime OSS pode ainda usar-se o código ISO alpha-2 do país OSS (vd. https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2; ver também a NOTA 3.
},
"relationships": { // [OBRIGATÓRIO] Recursos associados à linha do documento.
// [OBRIGATÓRIO] Identificação do documento (cabeçalho) a que esta linha pertence.
"document": {
"data": {
"type": "commercial_sales_documents", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno do documento (cabeçalho). Ver NOTA 1.
}
},
// [OPCIONAL] Unidade de medida. Por omissão é a configurada por omissão na empresa.
// Se a unidade de medida for indicada, usar apenas ou o "id" nesta "relationship" ou o campo "unit_of_measure" (o código da unidade; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
"unit_of_measure": {
"data": {
"type": "units_of_measure", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno da unidade de medida. Ver NOTA 4.
}
},
// [OPCIONAL] IVA. Por omissão é aplicado o IVA à taxa normal na região onde a empresa está localizada.
// Se a taxa de IVA for indicada, usar apenas ou o "id" nesta "relationship" ou um ou mais dos três campos "tax_code", "tax_percentage" e "tax_country_region" (o tipo, a percentagem e/ou a região do IVA; ver mais acima). Se se indicarem todos os campos, então devem ser consistentes.
"tax": {
"data": {
"type": "taxes", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno da taxa de IVA. Ver NOTA 5.
}
}
}
}
}2.5. Criação de uma linha de descrição sem valor
Para o caso particular de uma linha de descrição sem valor, este payload contém a seguinte informação:
{
"data": {
"type": "commercial_sales_document_lines", // [OBRIGATÓRIO]
"attributes": { // [OBRIGATÓRIO] Os atributos da linha do documento
"description": "Descrição da linha" // [OBRIGATÓRIO]
},
"relationships": { // [OBRIGATÓRIO] Recursos associados à linha do documento.
// [OBRIGATÓRIO] Identificação do documento (cabeçalho) a que esta linha pertence.
"document": {
"data": {
"type": "commercial_sales_documents", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno do documento (cabeçalho). Ver NOTA 1.
}
}
}
}
}3. Finalização do documento
Após todas as linhas criadas, e se não houver mais nenhuma alteração ao documento, este pode ser finalizado.
Após a finalização, a alteração ou eliminação do cabeçalho e das linhas deixa de ser possível, assim como a criação de linhas adicionais.
curl -v -X PATCH -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' -d '<payload JSON>' '<API_URL>/commercial_sales_documents/<id do documento>'No pedido acima, o access_token é o token de acesso válido devolvido pelo serviço de OAuth e o id do documento é o "id" interno do documento (cabeçalho) é o devolvido no campo "id" da resposta ao seu pedido de criação (ver ponto 1. Criação do cabeçalho). O payload JSON a enviar contém a seguinte informação:
{
"data": {
"type": "commercial_sales_documents", // [OBRIGATÓRIO]
"id": "1", // [OBRIGATÓRIO] Identificador interno do documento (cabeçalho). Este "id" é o devolvido na resposta ao pedido de criação do cabeçalho, ver acima.
"attributes": { // [OBRIGATÓRIO] Os atributos do documento
"status": 1 // [OBRIGATÓRIO] Identificação do estado do documento. 1: documento finalizado.
}
}
}Este pedido é equivalente ao pedido de alteração do cabeçalho do documento (ver Alteração do cabeçalho do documento). Por isso, a finalização do documento — que é a alteração do atributo "status" do cabeçalho — pode ser realizada juntamente com a alteração de outros atributos ou relações do cabeçalho, num único pedido.
Alteração do documento
Enquanto o documento não for finalizado, tanto o seu cabeçalho como qualquer uma das suas linhas podem ser alteradas a qualquer momento. Além disso, qualquer uma das linhas pode ser eliminada (ver Eliminação de uma linha), e novas linhas criadas e adicionadas (ver 2. Criação da(s) linha(s)).
Alteração do cabeçalho
curl -v -X PATCH -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' -d '<payload JSON>' '<API_URL>/commercial_sales_documents/<id do documento>'No pedido acima, o access_token é o token de acesso válido devolvido pelo serviço de OAuth e o id do documento é o "id" interno do documento (cabeçalho), devolvido no campo "id" da resposta ao seu pedido de criação (ver ponto 1. Criação do cabeçalho). O payload JSON a enviar contém a seguinte informação:
{
"data": {
"type": "commercial_sales_documents", // [OBRIGATÓRIO]
"id": "1", // [OBRIGATÓRIO] Identificador interno do documento (cabeçalho). Este "id" é o devolvido na resposta ao pedido de criação do cabeçalho, ver acima.
"attributes": { // [OBRIGATÓRIO] Os atributos do documento
"status": 1 // [OPCIONAL] Identificação do estado do documento. 1: documento finalizado.
// Identificação do documento
"document_type": "FT|FS|FR", // [OBRIGATÓRIO] Tipo de documento. "FT": fatura, "FS": fatura simplificada, "FR": fatura-recibo.
"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 ou o campo seguinte (o prefixo) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes.
"document_series_prefix": "Prefixo da série", // [OPCIONAL] Em alternativa ao campo "document_series_id".
// [OPCIONAL] Identificação do cliente. Por omissão, é o consumidor final (NIF "999999990").
// Se o cliente for indicado, usar apenas ou o campo seguinte (o NIF) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes.
"customer_tax_registration_number": "999999990", // [OPCIONAL] NIF do cliente. se o cliente com o NIF indicado não existir, será criado automaticamente. Se o país ("customer_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 cliente, se não existir ainda.
// Se o cliente já existir, são guardados no documento, mas a ficha do cliente não é actualizada.
"customer_business_name": "Nome do cliente", // [OBRIGATÓRIO] caso o cliente ainda não exista e tenha que ser criado. [OPCIONAL] nos outros casos, a não ser que exista mais do que um cliente com o NIF indicado, usando-se então o nome para o identificar.
"customer_address_detail": "Morada do cliente", // [OPCIONAL]
"customer_postcode": "0000-000", // [OPCIONAL] Código postal do cliente, no formato 0000-000.
"customer_city": "Cidade/Localidade do cliente", // [OPCIONAL]
"customer_country": "PT", // [OPCIONAL] País do cliente. Por omissão, "PT"; é o código ISO alpha-2 do país do cliente (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 cliente, se o cliente 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"
"payment_mechanism": "MO|CH|DC|CC|TR|CO|CS|DE|LC|MB|OU|RT|DDA", // [OPCIONAL] Necessário apenas no caso das FR. Por omissão, "MO", ou o configurado no cliente, se o cliente tiver configurado um modo de pagamento. Modos 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": Multibanco, "CO": Cartão oferta, "CS": Compensação de saldos, "DE": Dinheiro eletrónico, "LC": Letra comercial, "OU": Outros, "RT": Ticket restaurante.
// [OPCIONAL] IVA
"vat_included_prices": false, // [OPCIONAL] Os preços nas linhas são com IVA incluído? Por omissão, não (false).
"operation_country": "PT-MA", // [OPCIONAL] A região de operação para efeitos de IVA: usada apenas para as linhas de serviços. Por omissão, é a região onde a empresa está localizada. Para o regime OSS pode ainda usar-se o código ISO alpha-2 do país OSS (vd. https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2; ver também a NOTA 3.
// [OPCIONAL] Moeda. Por omissão, "EUR".
// Se a moeda for indicada, usar apenas ou o campos seguinte (o código ISO) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes.
"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": 7.5, // [OPCIONAL] Percentagem de retenção a aplicar sobre os serviços.
"retention_type": "IRS|IRC", // [OPCIONAL] Tipo de retenção ("IRS" ou "IRC"). Por omissão, "IRS".
"apply_retention_when_paid": true, // [OPCIONAL] A retenção é feita logo no documento (false) ou apenas no recebimento (true). Por omissão, false.
// [OPCIONAL] Outras informações
"notes": "Notas ao documento", // [OPCIONAL]
"external_reference": "Referência do documento externo" // [OPCIONAL]
},
"relationships": { // [OPCIONAL] Recursos associados ao documento. Caso nenhum seja indicado, este bloco "relationships" deve ser omitido
// [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 ou o "id" nesta "relationship" ou campo "document_series_prefix" (o prefixo; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
"commercial_document_series": {
"data": {
"type": "commercial_document_series", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno da série. Ver NOTA 1 abaixo.
}
},
// [OPCIONAL] Identificação do cliente. Por omissão, é o consumidor final (NIF "999999990").
// Se o cliente for indicado, usar apenas ou o "id" nesta "relationship" ou o campo "tax_registration_number" (o NIF; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
"customer": {
"data": {
"type": "customers", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno do cliente. Ver NOTA 2.
}
},
// [OPCIONAL] Necessário apenas no caso das FR. Conta bancária da empresa para onde o recebimento é feito. Usado apenas quando o meio de pagamento da FR é "DC", "CC", "TR" ou "DDA", e apenas se for necessário indicar uma conta bancária específica.
"bank_accounts": {
"data": {
"type": "bank_accounts", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno da conta bancária da empresa. Ver NOTA 4.
}
},
// [OPCIONAL] Necessário apenas no caso das FR. Conta de caixa da empresa para onde o recebimento é feito. Usado apenas quando o meio de pagamento da FR é "MO".
"cash_accounts": {
"data": {
"type": "cash_accounts", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno da conta de caixa da empresa. Ver NOTA 5.
}
},
// 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.
"tax_exemption_reasons": {
"data": {
"type": "tax_exemption_reasons", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno do motivo de isenção do IVA. Ver NOTA 6.
}
},
// [OPCIONAL] Moeda. Por omissão, "EUR".
// Se a moeda for indicada, usar apenas ou o "id" nesta "relationship" ou o campo "currency_iso_code" (o código ISO; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
"currency": {
"data": {
"type": "currencies", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno da moeda. Ver NOTA 7.
}
}
}
}
}A informação que pode ser enviada no pedido de alteração do cabeçalho do documento é a mesma que é enviada no pedido de criação, com a eventual adição do atributo "status" para finalizar o documento.
Alteração de uma linha
curl -v -X PATCH -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' -d '<payload JSON>' '<API_URL>/commercial_sales_document_lines/<id da linha>'No pedido acima, o access_token é o token de acesso válido devolvido pelo serviço de OAuth e o id da linha é o "id" interno da linha do documento, devolvido no campo "id" da resposta ao seu pedido de criação (ver ponto 2. Criação da(s) linha(s)). O payload JSON a enviar contém a seguinte informação:
{
"data": {
"type": "commercial_sales_document_lines", // [OBRIGATÓRIO]
"id": "1", // [OBRIGATÓRIO] Identificador interno da linha do documento. Este "id" é o devolvido na resposta ao pedido de criação da linha, ver acima.
"attributes": { // [OBRIGATÓRIO] Os atributos da linha do documento
// [OPCIONAL] Identificação do item. Se nada for indicado, assume-se uma linha apenas de descrição.
"item_type": "Service|Product|TaxDescriptor", // [OPCIONAL] Tipo de item: "Service": serviço, "Product": produto, "TaxDescriptor": descritor. Por omissão, assume-se uma linha apenas de descrição.
// Se o item for indicado, usar apenas ou o campo seguinte (o código) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes entre si, e consistentes com o "item_type".
"item_code": "Código do serviço/produto/descritor", // [OPCIONAL] Já tem que existir o produto/serviço/descritor com este código. Por omissão, é usado o item identificado pela "relationship" respectiva, se indicada. 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 serviço ou produto), ou a por omissão na empresa.
// Se a unidade de medida for indicada, usar apenas ou o campo seguinte (o código) ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem os dois, então devem ser consistentes entre si.
"unit_of_measure": "Unidade de medida", // [OPCIONAL] Por omissão é a configurada no item, ou a por omissão na empresa.
// Quantidades e valores. [OBRIGATÓRIO] Para linhas de descrição com valor.
"quantity": 1, // [OPCIONAL] Por omissão 1, se não for uma linha de descrição com valor. [OBRIGATÒRIO] Para uma linha de descrição com valor.
"unit_price": 9.99, // [OPCIONAL] Se for indicado um serviço ou produto. Por omissão é usado o PVP associado ao item (serviço ou produto). [OBRIGATÓRIO] Para uma linha de descritor ou de descrição com valor.
"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, ou — apenas para as linhas de serviços — a região de operação para efeitos de IVA, se indicada.
// Se a taxa de IVA for indicada, usar apenas um ou mais dos três campos seguintes ou o "id" na "relationship" respectiva (ver mais abaixo). Se se indicarem todos os campos, então devem ser consistentes entre si.
// [NÃO PODE SER USADO] no caso de uma linha de descrição sem valor, ou de um descritor que são suporte IVA: ou seja, um descritor referente a uma retenção (taxa SIRCA, outras retenções...)
"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, ou — apenas para as linhas de serviços — a região de operação para efeitos de IVA, se indicada. Para o regime OSS pode ainda usar-se o código ISO alpha-2 do país OSS (vd. https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2; ver também a NOTA 3.
},
"relationships": { // [OBRIGATÓRIO] Recursos associados à linha do documento.
// [OBRIGATÓRIO] Identificação do documento (cabeçalho) a que esta linha pertence.
"document": {
"data": {
"type": "commercial_sales_documents", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno do documento (cabeçalho). Ver NOTA 1.
}
},
// [OPCIONAL] Produto associado à linha. Só deve ser indicado para as linhas de produtos.
// Se o produto for indicado, usar apenas ou o "id" nesta "relationship" ou o campo "item_code" (o código do produto; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
"product": {
"data": {
"type": "products", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno do produto. Ver NOTA 2.
}
},
// [OPCIONAL] Serviço associado à linha. Só deve ser indicado para as linhas de serviços.
// Se o serviço for indicado, usar apenas ou o "id" nesta "relationship" ou o campo "item_code" (o código do serviço; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
"service": {
"data": {
"type": "services", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno do serviço. Ver NOTA 2.
}
},
// [OPCIONAL] Descritor associado à linha. Só deve ser indicado para as linhas de descritores.
// Se o descritor for indicado, usar apenas ou o "id" nesta "relationship" ou o campo "item_code" (o código do descritor; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
"tax_descriptor": {
"data": {
"type": "tax_descriptors", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno do descritor. Ver NOTA 2.
}
},
// [OPCIONAL] Unidade de medida. Por omissão é a configurada no item (se for serviço ou produto), ou a por omissão na empresa.
// Se a unidade de medida for indicada, usar apenas ou o "id" nesta "relationship" ou o campo "unit_of_measure" (o código da unidade; ver mais acima). Se se indicarem os dois, então devem ser consistentes.
"unit_of_measure": {
"data": {
"type": "units_of_measure", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno da unidade de medida. Ver NOTA 4.
}
},
// [OPCIONAL] IVA. Por omissão é aplicado o IVA associado ao item, ou à taxa normal na região onde a empresa está localizada, ou — apenas para as linhas de serviços — a região de operação para efeitos de IVA, se indicada.
// Se a taxa de IVA for indicada, usar apenas ou o "id" nesta "relationship" ou um ou mais dos três campos "tax_code", "tax_percentage" e "tax_country_region" (o tipo, a percentagem e/ou a região do IVA; ver mais acima). Se se indicarem todos os campos, então devem ser consistentes.
// [NÃO PODE SER USADO] no caso de uma linha de descrição sem valor, ou de um descritor que são suporte IVA: ou seja, um descritor referente a uma retenção (taxa SIRCA, outras retenções...)
"tax": {
"data": {
"type": "taxes", // [OBRIGATÓRIO]
"id": "1" // [OBRIGATÓRIO] Identificador interno da taxa de IVA. Ver NOTA 5.
}
}
}
}
}A informação que pode ser enviada no pedido de alteração da linha do documento é a mesma que é enviada no pedido de criação. O exemplo de payload acima deve por isso ser ajustado consoante se trate da alteração duma linha de produto, de serviço, de descritor ou de descrição. É ainda possível alterar o tipo de linha (de uma linha de serviço para uma de produto, por exemplo).
Eliminação de uma linha
curl -v -X DELETE -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' '<API_URL>/commercial_sales_document_lines/<id da linha>'No pedido acima, o access_token é o token de acesso válido devolvido pelo serviço de OAuth e o id da linha é o "id" interno da linha do documento, devolvido no campo "id" da resposta ao seu pedido de criação (ver ponto 2. Criação da(s) linha(s)).
Eliminação do documento
Enquanto estiver em preparação, o documento pode ser eliminado.
Após a finalização, no entanto, a sua eliminação — assim como a sua alteração — deixa de ser possível.
curl -v -X DELETE -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' '<API_URL>/commercial_sales_documents/<id do documento>'No pedido acima, o access_token é o token de acesso válido devolvido pelo serviço de OAuth e o id do documento é o "id" interno do documento (cabeçalho) é o devolvido no campo "id" da resposta ao seu pedido de criação (ver ponto 1. Criação do cabeçalho).
Esta operação é irreversível.
Anulação do documento
Após a sua finalização, o documento deixa de poder ser eliminado, podendo apenas ser anulado.
curl -v -X PATCH -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' -d '<payload JSON>' '<API_URL>/commercial_sales_documents/<id do documento>'No pedido acima, o access_token é o token de acesso válido devolvido pelo serviço de OAuth e o id do documento é o "id" interno do documento (cabeçalho) é o devolvido no campo "id" da resposta ao seu pedido de criação (ver ponto 1. Criação do cabeçalho). O payload JSON a enviar contém a seguinte informação:
{
"data": {
"type": "commercial_sales_documents", // [OBRIGATÓRIO]
"id": "1", // [OBRIGATÓRIO] Identificador interno do documento (cabeçalho). Este "id" é o devolvido na resposta ao pedido de criação do cabeçalho, ver acima.
"attributes": { // [OBRIGATÓRIO] Os atributos do documento
"status": 4, // [OBRIGATÓRIO] Identificação do estado do documento. 4: documento anulado.
"voided_reason": "Motivo pelo qual se anula o documento" // [OBRIGATÓRIO]
}
}
}Após a sua anulação, o documento deixa de poder ser alterado. Esta operação é irreversível.
Last updated