7. Faturas

A tela de Faturas apresenta todas as faturas criadas para os clientes. Incluindo faturas avulsas (sem Subscrição) e faturas vinculadas a Subcrições.

O acesso às informações das Susbcrições também é disponibilizado na tela de Faturas, através do grid de faturas, e também através do Filtro por dados da Subscrição procurada. Onde será possível acompanhar os status das cobranças e realizar o reenvio das mesmas se necessário.

É possível realizar filtros customizados, analisar as cobranças separadas por temas e exportar todo seu conteúdo.

No menu do GRR Gestão de Receita Recorrente selecione a opção Faturas.

Nesta tela, além da tabela de informações, estão acessíveis os filtros: por período, por tipo de totais, e a tela de filtros finos através do botão Ver filtros.

Ao selecionar o botão Ver Filtros e preencher os parâmetros de pesquisa, clique em Aplicar Filtro.

Os cards de totais Total de Faturas, Total Recebido, Total a vencer, e Total vencido são filtros rápidos de Situação da Fatura, onde:

Total de Faturas: preenche a tela com as faturas ativas, ou seja, as faturas que não estão Em cancelamento ou Canceladas;

Total Recebido: preenche a tela com as faturas pagas;

Total a vencer: preenche a tela com as faturas com vencimentos para datas futuras;

Total vencido: preenche a tela com as faturas vencidas

Observação: os cards de totais se baseiam também no filtro definido na tela de filtros, exceto a definição da situação, onde cada card retornará sua própria situação de fatura conforme explicado acima.

Clique no card, Total de Faturas.

Clique no card, Total Recebido.

Clique no card, Total a Vencer.

Clique no card, Total Vencido.

Selecione o botão Exportar.

Em detalhes da fatura é possível conferir os dados de envio tais como seus status e conteúdo do plano, podendo também notificar o cliente mais de uma vez quando solicitado e obter a visão das notificações da cobrança.

Na tela de Faturas selecione o link Detalhes.

Informe um E-mail (válido) no campo E-mail Alternativo, em seguida clique em Notificar Cliente.

No campo Link de Pagamento clique na opção Abrir para acessar o meio de pagamento criado na assinatura.

Acesse a Caixa de Entrada onde está configurado o recebimento das cobranças, selecione o E-mail e clique no link para ter acesso a fatura.

Ao acionar o botão "Cancelar Fatura" o sistema irá cancelar o registro selecionado, não impactando nas cobranças das próximas faturas recorrentes.

Selecione o botão "Cancelar Fatura".

Em seguida realize o preenchimento da justificativa no quadrante "Cancelamento de Fatura" e selecione o botão "Sim".

Sistema irá disponibilizar o status "Cancelado".

Para realizar o estorno de uma fatura paga, siga o passo a passo conforme abaixo:

Na tela de Faturas, selecione o status "Pago" e clique no link "Detalhes".

Na tela da fatura a ser cancelada, clique no botão "Cancelar Fatura".

Na tela "Cancelamento de Fatura", descreva o motivo do cancelamento e clique no botão "Sim".

A fatura terá seu status alterado para "Em Cancelamento".

Após o processamento do cancelamento na adquirente, o status da fatura será alterado para "Cancelado".

Para incluir uma fatura eventual, siga o passo a passo conforme abaixo:

Introdução

Via integração, através dos endpoints:

Criação (Post)
https://api-recorrencia.totvs.app/api/v1/rac/bills

Edição (Patch)
https://api-recorrencia.totvs.app/api/v1/rac/bills/{billIntegrationId}

Vamos discorrer sobre esses itens.

Criação de fatura (POST):

A criação de uma fatura é feita através da utilização do endpoint https://api-recorrencia.totvs.app/api/v1/rac/bills, utilizando o exemplo de payload abaixo:

{
  "organizationId": "Informar o Id da Organização", 
  "organizationIntegrationId": "Informar o Integration Id da Organização",
  "source": "Informar source",
  "reference": "Informar a referência",
  "integrationId": "Informar o Integration Id da fatura",
  "origin": "Informar origin", //Ex: Protheus
  "description": "Informar descrição",
  "customerId": "Informar Id do Cliente", //opcional no caso de enviar um novo cliente (*1)
  "customerIntegrationId": "Informar Integration Id do Cliente", //opcional no caso de enviar um novo cliente (*1)
  "currencyId": "9495d9da-33be-4634-a67e-22eced59274d", //uuid BRL
  "currencyCode": "BRL",
  "paymentMethods": [
    "1","2","3" //Ex: "1","2","3" - 1=Boleto, 2=Cartão, 3=Pix
  ],  
  "creationDate": "data",
  "totalAmount": 100.5, //decimal
  "usageTotalAmount": 200.99, //decimal
  "alwaysSaveCreditcard": true, //true ou false
  "status": "1", //1 = Created
  "items": [
    {
      "itemId": "Informar o Id do item no GRR",
      "integrationId": "Informar novo Integration Id",
      "itemIntegrationId": "Informar novo Integration Id",
      "description": "Informar descrição",
      "unitMeasurement": "Informar código",
      "billItemReference": "Informar a referência",
      "quantity": 0,
      "baseValue": 0,
      "value": 0,
      "totalAmount": 0,
      "source": "Informar source",
    }
  ],
  "provider": "2", //Ex: 0=None, 2=MaxiPago
  "dueDate": "Informar data de vencimento",
  "subscriptionId": "Informar Id da subscrição caso haja", //opcional, caso a fatura seja parte de uma subscrição (*2)
  "subscriptionIntegrationId": "Informar Integration Id da subscrição caso haja", //opcional, caso a fatura seja parte de uma subscrição (*2)
  "billingDate": "Informar a data",
  "generateCharge": true, //true ou false
  "billingRuler": { //payload BillingRuler (régua de cobrança) opcional (*3) para o caso de criação de nova regua de cobrança para esta fatura. Caso não informar este payload, a fatura será vinculada a régua de cobrança padrão
    "description": "Informar descrição",
    "sendingCharge": "0", //Ex: 0 = ExactlyDay,
    "chargeAfterDueDate": "1", //Ex: cobrança após 1 dia do vencimento
    "chargeAfterDueDateEachDay": 1, //Ex: após vencimento, cobrar a cada 1 dia(s)
    "chargeAfterDueDatePer": 120, //Ex: cobrar por um período de 120 dias
    "checkoutExpirationInDays": 0
  },
  "customer": { //payload de Customer opcional (*4)
    "code": "Informar o código",
    "reference": "Informar a referencia",
    "name": "Informar o nome",
    "typeDocument": "1", //Ex: 1=CPF, 2=CNPJ,
    "documentNumber": "CPF ou CNPJ",
    "stateRegistration": "000.000.000.000",
    "cityRegistration": "000000-0",
    "integrationId": "Informar a Integração associado",
    "status": "1", //Ex: 1=Active,
    "addresses": [
      {
        "type": "1",
        "street": "Campo Obrigatório",
        "number": "Campo Obrigatório",
        "complement": "Campo Obrigatório",
        "district": "Campo Obrigatório",
        "zipCode": "Campo Obrigatório",
        "cityName": "Campo Obrigatório",
        "stateInitials": "Campo Obrigatório",
        "stateName": "Campo Obrigatório",
        "countryName": "BR"
      }
    ],
    "emails": [
      {
        "type": "1", //Ex: 1=Personal,
        "emailAddress": "Campo Obrigatório"
      }
    ],
    "phones": [
      {
        "type": "1", //Ex: 1=Home,
        "countryCode": "Campo Obrigatório",
        "areaCode": "Campo Obrigatório",
        "number": "Campo Obrigatório",
        "extension": "2666"
      }
    ],
    "birthDate": "Informar a data",
    "organizationId": "Informar o Id da Organização",
    "organizationIntegrationId": "Informar o Integration Id da Organização"
  }
}

(*1) O Id e IntegrationId de Customer não tem necessidade de ser enviado caso o objeto de novo Customer (*4) seja enviado. Caso o objeto de novo Customer (*4) não seja enviado, é necessário enviar o Id ou IntegrationId do cliente

(*2) O Id ou IntegrationId da Subscrição só precisarão ser enviados caso a fatura vá fazer parte de uma Subscrição. Caso a fatura faça parte de uma Subscrição e não seja enviado payload da régua de cobrança (*3) a fatura será vinculada à régua de cobrança da Subscrição

(*3) O payload de régua de cobrança (Billing Ruler) é opcional para ser enviado no caso de precisar criar uma régua de cobrança personalizada para esta fatura. Se não for enviado, a fatura se vinculará a régua de cobrança padrão

(*4) O payload de Customer é opcional para o caso de criar fatura avulsa para um novo cliente

Edição da fatura (PATCH):

A edição de uma fatura é feita através da utilização do endpoint https://api-recorrencia.totvs.app/api/v1/rac/bills/{billIntegrationId}, utilizando o exemplo de payload abaixo:

[
  {
    "op": "string",
    "path": "string",
    "value": {}
  }
]

Onde:

op = operação (add ou replace)
path = caminho da propriedade ou objeto a ser atualizado
value = valor ou valores a serem atualizados

Para o caso do payload de PATCH de fatura há condições e particularidades:

Condições:

Algumas propriedades da fatura podem ser atualizadas, são:

PaymentMethods  (propriedade - array de strings)
DueDate (propriedade)
BillingDate (propriedade)
TotalAmount (propriedade)
UsageTotalAmount (propriedade)
Items (lista)
- Id
- IntegrationId
- ItemId
- ItemIntegrationId
- Description
- UnitMeasurement
- BillItemReference
- Quantity
- BaseValue
- Value
- TotalAmount
- Source
BillingRuler
- Description
- SendingCharge (0=ExactlyDay, 1=OneDayBeforeDueDate, 2=TwoDayBeforeDueDate, 3=ThreeDayBeforeDueDate, 4=FourDayBeforeDueDate, 5=FiveDayBeforeDueDate, 6=SixDayBeforeDueDate, 7=SevenDayBeforeDueDate, 8=EightDayBeforeDueDate, 9=NineDayBeforeDueDate, 10=TenDayBeforeDueDate)
- ChargeAfterDueDate (0=ExactlyDay, 1=OneDayAfterDueDate, 2=TwoDayAfterDueDate, 3=ThreeDayAfterDueDate, 4=FourDayAfterDueDate, 5=FiveDayAfterDueDate, 6=SixDayAfterDueDate, 7=SevenDayAfterDueDate, 8=EightDayAfterDueDate, 9=NineDayAfterDueDate, 10=TenDayAfterDueDate)
- ChargeAfterDueDateEachDay
- ChargeAfterDueDatePer
- CheckoutExpirationInDays
Customer
- Id
- IntegrationId
- Code
- Reference
- Name
- TypeDocument (1=NaturalPerson, 2=LegalPerson)
- DocumentNumber
- StateRegistration
- CityRegistration
- Status (1=Ativo, 2=Inativo)
- BirthDate
- Addresses (lista)
-- Type (1=Home, 2=Business, 3=Billing)
-- Street
-- Number
-- Complement
-- District
-- ZipCode
-- CityName
-- StateInitials
-- StateName
-- CountryName
-- IsActive
- Emails (lista)
-- Type (1=Personal, 2=Work, 3=Home, 4=Business, 5=Billing)
-- EmailAddress
-- IsActive
- Phones (lista)
-- Type (1=Home, 2=Business, 3=CellPhone)
-- CountryCode
-- AreaCode
-- Number
-- Extension
-- IsActive
- IsActive (true ou false)

Particularidades (para o envio do Patch):

1. Para as operações de inclusão, seré enviado "op":"add", e para operações de alteração, será anviado "op":"replace".
2. O "path" do payload deve iniciar, como sintaxe, com a "/", e deve-se seguir separando por "/" até chegar na propriedade desejada.
   1. Se a propriedade desejeda for uma lista, como Emails por exemplo, ao preencher até o item Emails ("/Customer/Emails") e ao final deverá incluir "/-", pois isso informará à fatura que trata-se de uma inclusão de item em lista. Ficando o "path" /Customer/Emails/-
   2. Nesse caso, informar no "value" as propriedades do payload (lista) em questão, conforme definidas acima, e exemplificado abaixo.
   3. Nesse caso, a inclusão de um item numa lista, não afetará os itens já existentes na mesma lista
3. É possível efetuar a atualização por completo de uma lista, com a "op" replace
   1. Nesse caso, de "op":"replace" com a lista completa para atualizar, não enviar a "/-" ao final, ja que esta é usada para "op" add. Por exemplo, para lista de emails, enviar, "path":"/Customer/Emails"
   2. Enviar a lista completa de emails; nesse caso, o email removido na nova lista, será desvinculado do cliente, e um email adicionado, será criado e vinculado, atualizando a lista de emails por completo
   3. Esquema válido para todas as listas
4. O "value" do payload pode ser enviado como valor unico ou valores de propriedades, a depender do que está definido no "path".

Veja exemplos:

Alterar data de vencimento:

{
    "op":"replace",
    "path":"/DueDate",
    "value":"2025-01-18"
}

Alterar nome do cliente

{
    "op":"replace",
    "path":"/Customer/Name",
    "value":"Nome Atualizado Do Cliente"
}

Incluir um email para o cliente desta fatura:

{
    "op":"add",
    "path":"/Customer/Emails/-",
    "value":
    {
        "type": "1",
        "emailAddress": "novoemail@dominio.com.br",
        "isActive": true
    }
}

Também é possível adicionar uma Régua de Cobrança para a fatura em questão, através do exemplo:

{
    "op":"add",
    "path":"/BillingRuler",
    "value":
    {
        "description": "Regua de cobranca personalizada",
        "chargeAfterDueDateEachDay": 5,
        "chargeAfterDueDatePer" : 5
    }
}

Todas as faturas eventuais criadas estarão disponíveis para visualização e acompanhamento do Menu Faturas.

Aqui constam os retornos para verificação de criação de Fatura e retornos.

O processo de acompanhamento de criação da Fatura, até obter o retorno seu pagamento (incluindo as notificações para o Protheus) é o mesmo, quando uma Fatura é criada para:

1. Cliente existente
2. Novo cliente
3. Fatura de Subscrição

Ao criar a Fatura, o cliente receberá um email informando-o sobre a Fatura aguardando pagamento.

Ao mesmo tempo, o Protheus receberá a notificação referente a esta nova Fatura com status Aguardando Pagamento (BillAwaitingPayment).

Após pagamento, o Protheus receberá a notificação de Fatura Paga (BillPaid).

Assim como o cliente receberá um email atualizando-o sobre a confirmação do pagamento