Pular para o conteúdo principal

Casos de uso

A seguinte secção exemplifica algumas situações comuns na criação de documentos CIUS-PT.

Criação de documentos por envio de dados​

Condições de pagamento​

payment_terms[note]: 30 dias

Local de consumo (CPE) nas linhas do documento​

lines[0][additional_property][0][name]: CPE
lines[0][additional_property][0][value]: PT1234567890

Número de compromisso no cabeçalho do documento​

commitment_number: 2021/451

Número de compromisso nas linhas do documento​

lines[0][commitment][number]: 2021/123
lines[0][commitment][line]: 1

Número de encomenda​

references[0][document_type]: order
references[0][number]: 1234

Envio do PDF anexado (UTF-8)​

file: (binary)

Outros anexos secundários​

files[0]: (binary)
files[1]: (binary)

Nota: O PDF de representação do documento deve ser sempre enviado no campo file.

Desconto no cabeçalho do documento​

discounts_charges[0][type]: false // usar true para encargo
discounts_charges[0][reason]: desconto comercial
discounts_charges[0][percent]: 23.00
discounts_charges[0][tax_code]: NOR
discounts_charges[0][amount]: 8.13 // refere-se ao valor sem imposto (ou seja, este desconto é de 10.00 EUR após a aplicação de IVA)
discount_amount: 8.13 // refere-se ao total de descontos de cabeçalho aplicados ao documento (NÃO inclui descontos nas linhas)

Desconto ou encargo na linha do documento​

lines[0][discounts_charges][0][type]: false // usar true para encargo
lines[0][discounts_charges][0][reason]: desconto comercial // descrição textual do desconto
lines[0][discounts_charges][0][amount]: 5.00 // refere-se ao valor sem IVA a descontar na linha
lines[0][quantity]: 2.000 // quantidade de artigos na linha
lines[0][price]: 10.00000000 // preço unitário do artigo
lines[0][amount]: 15.00000000 // o total da linha do documento é afectado pelo desconto ( (10 * 2) - 5 = 15)
lines[0][taxes][0][tax_percent]: 23.000 // taxa de IVA
lines[0][taxes][0][tax_amount]: 3.45 // valor do IVA da linha (15 * 0.23)
discount_amount: 0.00 // refere-se ao total de descontos de cabeçalho aplicados ao documento (NÃO inclui descontos nas linhas)

Desconto no preço do artigo​

lines[0][price_discount][base_amount]: 10.00 // preço unitário original do artigo antes de aplicar o desconto
lines[0][price_discount][amount]: 5.00 // refere-se ao valor sem IVA a descontar no preço do artigo
lines[0][quantity]: 2.000 // quantidade de artigos na linha
lines[0][price]: 5.00000000 // preço do artigo após aplicação do desconto (10 - 5 = 5)
lines[0][amount]: 10.00000000 // o total da linha do documento é afectado pelo desconto ( (10 - 5) * 2 = 10)
lines[0][taxes][0][tax_percent]: 23.000 // taxa de IVA
lines[0][taxes][0][tax_amount]: 2.30 // valor do IVA da linha (10 * 0.23)
discount_amount: 0.00 // refere-se ao total de descontos de cabeçalho aplicados ao documento (NÃO inclui descontos nas linhas)

Retenção na fonte​

withholding_tax[0][type]: IRF // Código que identifica a retenção de IRS
withholding_tax[0][tax_amount]: 10.00 // valor da retenção
withholding_tax[0][description]: Retenção IRS
withholding_tax_amount: 10.00 // soma de todas as retenções do documento

Nota: os totais do documento não são afetados pela retenção

Isenção de IVA na linha​

lines[0][quantity]: 2.000 // quantidade
lines[0][price]: 5.00000000 // preço unitário
lines[0][amount]: 10.00000000 // total da linha sem IVA
lines[0][taxes][0][tax_percent]: 0.00 // taxa de IVA
lines[0][taxes][0][tax_amount]: 0.00 // valor do IVA da linha
lines[0][taxes][0][tax_exemption_reason_code]: M08 // código de motivo da AT
lines[0][taxes][0][tax_exemption_reason]: IVA - Autoliquidação // descritivo do motivo da AT

Isenção de IVA no desconto ou encargo de cabeçalho​

discounts_charges[0][type]: false // usar true para encargo
discounts_charges[0][reason]: desconto comercial // descritivo
discounts_charges[0][percent]: 0.00 // percentagem (isento)
discounts_charges[0][tax_code]: ISE // isento
discounts_charges[0][amount]: 10.00 // valor do desconto
discounts_charges[0][tax_exemption_reason]: M08 // código de motivo da AT
discounts_charges[0][tax_exemption_reason_code]: IVA - Autoliquidação // descritivo do motivo da AT

Envio da fatura por e-mail a um ou mais endereços​

send_by_email: 1,
customer[email]: endereco1@email.com // enviado sempre para o email especificado no cliente
additional_emails[0]: endereco2@email.com // também enviado para a lista adicional de endereços
additional_emails[1]: endereco3@email.com

Envio de código QR​

qr_code: A:500000000*B:123456789*C:PT*D:GT*E:N*F:20190720*G:GT G234CB/50987*H:GTVX4Y8B-50987*I1:0*N:0.00*O:0.00*Q:5uIg*R:9999

Criação de documentos por envio do CIUS-PT​

Note-se que a ordem dos elementos XML é relevante e afecta as validações no formato UBL. Recomenda-se a leitura do guia de modelo de dados semânticos do formato CIUS-PT aqui.

Número de compromisso no cabeçalho do documento​

<Invoice>
  ...
  <cbc:AccountingCost>2021/156</cbc:AccountingCost>
</Invoice>

Capital Social do fornecedor​

<Invoice>
  ...
  <cac:AccountingSupplierParty>
    <cac:PartyLegalEntity>
      <cbc:CompanyLegalForm>2.000.000 EUR</cbc:CompanyLegalForm>
    </cac:PartyLegalEntity>
  </cac:AccountingSupplierParty>
</Invoice>

GLN do cliente (usar o schemeID 0088)​

<Invoice>
  ...
  <cac:AccountingCustomerParty>
    <cbc:EndpointID schemeID="0088">123456789</cbc:EndpointID>
  </cac:AccountingCustomerParty>
</Invoice>

ATCUD e QRCODE​

<Invoice>
  ...
  <cac:AdditionalDocumentReference>
    <cbc:ID schemeID="ANG">AFHOFX-22</cbc:ID> <!-- Valor ATCUD -->
    <cbc:DocumentDescription>QR_CODE</cbc:DocumentDescription>
    <cac:Attachment> <!-- Texto do QRCODE, em base64 (da sequência de carateres, NÃO da imagem) -->
        <cbc:EmbeddedDocumentBinaryObject mimeCode="text/plain" filename="QR_CODE.txt">UVJDT0RF=</cbc:EmbeddedDocumentBinaryObject>
    </cac:Attachment>
  </cac:AdditionalDocumentReference>
</Invoice>

Método de pagamento​

<Invoice>
  ...
  <cac:PaymentMeans>
    <cbc:PaymentMeansCode>NU</cbc:PaymentMeansCode>
  </cac:PaymentMeans>
</Invoice>

Valores permitidos:

CódigoDescrição
CCCartão crédito
CDCartão débito
CHCheque bancário
CICrédito documentário internacional
COCheque ou cartão oferta
CSCompensação de saldos em conta corrente
DEDinheiro eletrónico (ex.: cartões de fidelidade ou pontos)
LCLetra comercial
MBReferências de pagamento para Multibanco
NUNumerário
OUOutros meios não assinalados
PRPermuta de bens
TBTransferência bancária ou débito direto autorizado
TRTítulos de compensação extrassalarial (ex.: refeição, educação, etc.)

Informações de pagamento de cartão de débito ou crédito​

<Invoice>
  ...
  <cac:PaymentMeans>
    <cbc:PaymentMeansCode>CC</cbc:PaymentMeansCode>
    <cac:CardAccount>
      <cbc:PrimaryAccountNumberID>4211456651233545687</cbc:PrimaryAccountNumberID> <!-- Número da conta -->
      <cbc:NetworkID>04256</cbc:NetworkID> <!-- Identificador da rede bancária -->
      <cbc:HolderName>João Ferreira</cbc:HolderName> <!-- Nome do titular -->
    </cac:CardAccount>
  </cac:PaymentMeans>
</Invoice>

Método de pagamento por transferência bancária​

<Invoice>
  ...
  <cac:PaymentMeans>
    <cbc:PaymentMeansCode>TB</cbc:PaymentMeansCode>
    <cac:PayeeFinancialAccount>
      <cbc:ID>PT50000700230012345667899</cbc:ID> <!-- IBAN-->
      <cbc:Name>João</cbc:Name> <!-- Nome do titular -->
      <cac:FinancialInstitutionBranch>
        <cbc:ID>NBxxxx</cbc:ID> <!--SWIFT -->
      </cac:FinancialInstitutionBranch>
    </cac:PayeeFinancialAccount>
  </cac:PaymentMeans>
</Invoice>

Método de pagamento por referência multibanco​

<Invoice>
  ...
  <cac:PaymentMeans>
    <cbc:PaymentMeansCode name="#DESCRIPTION@ATMPAYMENT#156.22#">#ENTITY@ATMPAYMENT#15652</cbc:PaymentMeansCode> <!-- Entidade e Valor -->
    <cbc:PaymentID>#REFERENCE@ATMPAYMENT#156555145#</cbc:PaymentID> <!-- Referência -->
  </cac:PaymentMeans>
</Invoice>

Segunda referência multibanco​

<Invoice>
  ...
  <cbc:Note>#ENTITY@ATMPAYMENT-001#12345#</cbc:Note> <!-- 2ª entidade -->
  <cbc:Note>#REFERENCE@ATMPAYMENT-001#012345678#</cbc:Note> <!-- 2ª referência -->
  <cbc:Note>#AMOUNT@ATMPAYMENT-001#3264.10#</cbc:Note> <!--Valor da 2ª referência -->
  <cbc:Note>#DESCRIPTION@ATMPAYMENT-001#Valor total do documento, mais valores em atraso#</cbc:Note> <!-- Descrição da 2ª referência -->
</Invoice>

Condições de pagamento:​

<Invoice>
  ...
  <PaymentTerms>
    <cbc:Note>30 dias</cbc:Note>
  </PaymentTerms>
</Invoice>

Nota textual no cabeçalho do documento​

<Invoice>
  ...
  <cbc:Note>Nota cabeçalho</cbc:Note>
</Invoice>

Nota textual nas linhas do documento​

<Invoice>
  ...
  <InvoiceLine>
    <cbc:Note>Nota linha</cbc:Note>
  </InvoiceLine>
</Invoice>

Propriedade adicional no documento​

<Invoice>
  ...
  <cbc:Note>#ADDITIONALPROPERTY#VOUCHER#123#</cbc:Note>
<Invoice>

Local de consumo (CPE) nas linhas do documento​

<cac:InvoiceLine>
  ...
  <cac:AdditionalItemProperty>
    <cbc:Name>CPE</cbc:Name>
    <cbc:Value>PT1234567890</cbc:Value>
  </cac:AdditionalItemProperty>
</cac:InvoiceLine>

Número de encomenda / número de requisição​

<Invoice>
  ...
  <cac:OrderReference>
    <cbc:ID>20159854587</cbc:ID>
  </cac:OrderReference>
</Invoice>

Número de compromisso nas linhas do documento​

<cac:InvoiceLine>
  <cbc:AccountingCost>2020/123</cbc:AccountingCost> <!-- número do compromisso da linha -->
  ...
  <cac:Item>
    <cac:AdditionalItemProperty>
      <cbc:Name>#LINEID@COMMITMENTLINEREFERENCE#</cbc:Name>
      <cbc:Value>1</cbc:Value> <!-- número da linha -->
    </cac:AdditionalItemProperty>
  </cac:Item>
</cac:InvoiceLine>

PDF anexado​

Nota: o conteúdo deve estar codificado em base64

<Invoice>
  ...
  <cac:AdditionalDocumentReference>
    <cbc:ID>1</cbc:ID>
    <cbc:DocumentDescription>INVOICE_REPRESENTATION</cbc:DocumentDescription>
    <cac:Attachment>
      <cbc:EmbeddedDocumentBinaryObject mimeCode="application/pdf" filename="document">JVBERi0xLjUNCiW1tbW1DQoxIDAgb2JqDQo8PC9UeXBlL0NhdGFsb2cvUGIvTGF==
      </cbc:EmbeddedDocumentBinaryObject>
    </cac:Attachment>
  </cac:AdditionalDocumentReference>
</Invoice>

Ver exemplo

Múltiplos PDFs anexados​

<Invoice>
  ...
  <cac:AdditionalDocumentReference>
    <cbc:ID>1</cbc:ID> <!-- O anexo principal deve ter a descrição INVOICE_REPRESENTATION', ou 'CREDITNOTE_REPRESENTATION' -->
    <cbc:DocumentDescription>INVOICE_REPRESENTATION</cbc:DocumentDescription>
    <cac:Attachment>
      <cbc:EmbeddedDocumentBinaryObject mimeCode="application/pdf" filename="document.pdf">JVBERi0xLjUNCiW1tbW1DQoxIDAgb2JqDQo8PC9UeXBlL0NhdGFsb2cvUGIvTGF==
      </cbc:EmbeddedDocumentBinaryObject>
    </cac:Attachment>
  </cac:AdditionalDocumentReference>

  <cac:AdditionalDocumentReference>
    <cbc:ID>2</cbc:ID> <!-- Os anexos secundários (como a nota de encomenda, guias de pagamento, etc.) devem ter a descrição 'ATTACHMENT'. É possível incluir vários ATTACHMENTs num documento. -->
    <cbc:DocumentDescription>ATTACHMENT</cbc:DocumentDescription>
    <cac:Attachment>
      <cbc:EmbeddedDocumentBinaryObject mimeCode="application/pdf" filename="document2.pdf">jUNCiW1tbW1DQoJVBERi0xLjUNCiW1tbW1DQo8PC9UeXBlL0NhUGIvTGF==
      </cbc:EmbeddedDocumentBinaryObject>
    </cac:Attachment>
  </cac:AdditionalDocumentReference>
</Invoice>

Outros anexos (QR Code, etc.)​

Nota: o conteúdo deve estar codificado em base64

<Invoice>
  ...
  <cac:AdditionalDocumentReference>
    <cbc:ID>2</cbc:ID>
    <cbc:DocumentDescription>ATTACHMENT</cbc:DocumentDescription> <!-- usar QR_CODE para o código QR -->
    <cac:Attachment>
      <cbc:EmbeddedDocumentBinaryObject mimeCode="application/txt" filename="document">JVBERi0xLjUNCiW1tbW1DQoxIDAgb2JqDQo8PC9UeXBlL0NhdGFsb2cvUGIvTGF==
      </cbc:EmbeddedDocumentBinaryObject>
    </cac:Attachment>
  </cac:AdditionalDocumentReference>
</Invoice>

Desconto ou encargo no cabeçalho do documento​

Ver exemplo

Desconto ou encargo na linha do documento​

Ver exemplo

Desconto ou encargo no preço do artigo​

Ver exemplo

Retenção na fonte​

Ver exemplo

Isenção de IVA na linha do documento​

Ver exemplo

Isenção de IVA no desconto de cabeçalho do documento​

Ver exemplo

Múltiplas isenções no documento​

Ver exemplo

Vários descontos na linha​

Ver exemplo

Consultar lista completa de casos de uso CIUS-PT pela eSPap.