PORTAL DE DOCUMENTAÇÃO
Gestão Empresarial | ERP senior X
ERP senior X > Banking > Recebimento > Pix

Cobrança Pix

O sistema ERP senior X permite gerar Pix junto aos bancos Itaú, Santander, Banco do Brasil e Bradesco. A geração do Pix é feita por ERPs que se conectam com o Banking as a Service, independentemente de estarem ou não na plataforma.

Para os ERPs que não estão na plataforma Senior X é necessário realizar o cadastro de Empresa e Filial pelas APIs Company e Branch, que estão disponíveis na página de APIs públicas da Senior no caminho erpx > Foundation (foundation).

Criar Pix para cobrança

A API pública para geração do pix é a registerPixBilling.

Veja abaixo mais detalhes sobre sua estrutura e informações sobre cada campo.

ClosedEstrutura registePixBilling
Observação

Em cobranças com vencimentos (COBV) é necessário informar os campos de Juros, Multas, Abatimentos e Descontos. Para maiores detalhes sobre como preenchê-los leia o tópico Como preencher os campos de Juros (interest), Multas (assessment), Abatimentos (rebate) e Desconto (discount)?

{
  "processId": "string",
  "receivableBank": "NOME_DO_BANCO",
  "company": {
    "id": "string",
    "code": 0
  },
  "branch": {
    "id": "string",
    "code": 0,
    "documentNumber": "string",
    "nifNumber": "string"
  },
  "receivableBankData": {
    "pixKey": "string",
    "branchNumber": 99999,
    "branchDigit": "st",
    "accountNumber": 999999999999,
    "accountDigit": "st"
  },
  "accountsReceivable": [
    {
      "accountReceivableId": "string",
      "accountReceivableNumber": "string",
      "accountReceivableType": "string",
      "customer": {
        "id": "string",
        "documentNumber": "string",
        "name": "string",
        "tradeName": "string"
      },
      "dueDate": "2023-04-14",
      "validityAfterExpiration": 9999,
      "values": {
        "original": "string",
        "interest": {
          "calculationType": "enumCalculationTypeInterest",
          "valueOrPercentage": "string"
        },
        "assessment": {
          "calculationType": "enumCalculationType",
          "valueOrPercentage": "string"
        },
        "rebate": {
          "calculationType": "enumCalculationType",
          "valueOrPercentage": "string"
        },
        "discount": {
          "calculationType": "enumCalculationTypeDiscount",
          "valueOrPercentage": "string",
          "discountFixedDate": [
            {
              "limitDate": "2023-04-14",
              "valueOrPercentage": "string"
            }
          ]
        }
      },
      "additionalPixInformations": {
        "payerRequest": "string",
        "additionalInformations": [
          {
            "name": "string",
            "value": "string"
          }
        ]
      }
    }
  ]
}

Descrição dos campos da registerPixBilling

ClosedprocessId

Identificador do processo;

É um valor para identificar a chamada que está sendo realizada. Este valor será retornado no final do processo para facilitar a identificação do registro de cobrança;

Informação obrigatória.

ClosedreceivableBank

Informar o nome do banco que deseja realizar o pix;

Bancos aceitos: Itaú (ITAU), Santander (SANTANDER), Banco do Brasil (BANCO_DO_BRASIL) e Bradesco (BRADESCO);

Informação obrigatória.

Closedcompany

Informar os dados da empresa que fará a solicitação do pix;

Informar o identificador da empresa (id) e/ou código da empresa (code);

Todos os campos são opcionais, mas pelo menos um deles deve ser enviado para geração do pix.

Closedbranch

Informar os dados da filial que fará a solicitação do pix;

Informar os campos:

  • Identificador da filial (id);
  • Código da filial (code);
  • Número do documento (CPF/CNPJ) (documentNumber) e/ou número de identificação fiscal (nifNumber).

Todos os campos são opcionais, mas pelo menos um deles deve ser enviado para geração do pix.

ClosedreceivableBankData

Informar os dados bancários de geração do pix;

Informar os campos:

  • Chave pix (pixKey);
  • Número da agência (branchNumber);
  • Dígito da agência (branchDigit);
  • Número da conta (accountNumber);
  • Dígito da conta (accountDigit);

Todos os campos são obrigatórios.

ClosedaccountsReceivable

Informar os dados do título para registrar a cobrança;

Informar os campos:

  • Identificador do Título (accountReceivableId);
  • Número do Título (accountReceivableNumber);
  • Tipo do Título (accountReceivableType);
  •  Identificador do Cliente (customer);
  •  Data de Vencimento (dueDate);
  •  Dias Corridos Após o Vencimento que a Cobrança Poderá ser Paga (validityAfterExpiration);
  •  Valores do Título (values);
  •  Informações Adicionais do Pix (additionalPixInformations);

Observações

O campo validityAfterExpiration e additionalPixInformations são opcionais;

O campo validityAfterExpiration só deve ser informado para cobranças com vencimento (COBV);

O campo values é obrigatório, mas é necessário informar os campos listados abaixo apenas para cobranças com vencimento (COBV):

O campo de Customer deve ser informado:

    • Identificador do cliente (id);
    • Número do documento (CPF/CNPJ) (documentNumber);
    • Nome (name) e/ou Nome fantasia (tradeName).

    Todos os campos são opcionais, mas sempre deve ser informado o Identificador do cliente (id) ou o Número do documento (CPF/CNPJ) (documentNumber);

    Se enviado o Número do documento (CPF/CNPJ) (documentNumber), deve ser informado o Nome (name);

    Se o Número do documento (CPF/CNPJ) (documentNumber) for CNPJ, deve ser informado o Nome fantasia (tradeName).

Como preencher o campo de Juros (interest), Multas (assessment), Abatimentos (rebate) e Desconto (discount)?

Para preencher o campo calculationType referente aos Juros (interest), Multas (assessment), Abatimentos (rebate) e Desconto (discount), é necessário buscar a informação correspondente conforme abaixo:

ClosedJuros (interest) - enumCalculationTypeInterest

Informe o campo Tipo de cálculo (calculationType), que será buscado do enumCalculationTypeInterest (o enumCalculationTypeInterest representa a modalidade de juros para a cobrança) e o campo Valor ou Percentual (valueOrPercentage).

enumeration enumCalculationTypeInterest {
            "Valor (dias corridos)"
            VALUE_FOR_CALENDAR_DAYS
            "Percentual ao dia (dias corridos)"
            PERCENTAGE_FOR_CALENDAR_DAYS
            "Percentual ao mês (dias corridos)"
            PERCENTAGE_FOR_CALENDAR_MONTH
            "Percentual ao ano (dias corridos)"
            PERCENTAGE_FOR_CALENDAR_YEAR
            "Valor (dias úteis)"
            VALUE_FOR_BUSINESS_DAYS
            "Percentual ao dia (dias úteis)"
            PERCENTAGE_FOR_BUSINESS_DAYS
            "Percentual ao mês (dias úteis)"
            PERCENTAGE_FOR_BUSINESS_MONTH
            "Percentual ao ano (dias úteis)"
            PERCENTAGE_FOR_BUSINESS_YEAR
        }
ClosedMultas (assessment) e Abatimentos (rebate) - enumCalculationType

Informe o campo Tipo de cálculo (calculationType), que será buscado do enumCalculationType (o enumCalculationType representa a modalidade de abatimento para a cobrança) e o campo Valor ou Percentual (valueOrPercentage).

           enumeration enumCalculationType {
            "Percentual"
            PERCENTAGE
            "Valor fixo"
            FIXED_VALUE
        }
ClosedDesconto (discount) - enumCalculationTypeDiscount

Informe o campo Tipo de cálculo (calculationType), que será buscado do enumCalculationTypeDiscount (o enumCalculationTypeDiscount representa a modalidade de desconto para a cobrança), Valor ou Percentual (valueOrPercentage) e o campo Descontos definidos de acordo com a data estabelecida (discountFixedDate).

           enumeration enumCalculationTypeDiscount {
            "Valor fixo até a(s) data(s) informada(s)"
            FIXED_VALUE_UNTIL_LIMIT_DATE
            "Percentual até a data informada"
            PERCENTAGE_UNTIL_LIMIT_DATE
            "Valor por antecipação dia corrido"
            VALUE_FOR_ADVANCE_CALENDAR_DAY
            "Valor por antecipação dia útil"
            VALUE_FOR_ADVANCE_BUSINESS_DAY
            "Percentual por antecipação dia corrido"
            PERCENTAGE_FOR_ADVANCE_CALENDAR_DAY
            "Percentual por antecipação dia útil"
            PERCENTAGE_FOR_ADVANCE_BUSINESS_DAY
        }

Processo de geração do Pix

Após o banking receber a requisição para geração do pix pela API registerPixBilling, o sistema segue os processos demonstrados nos fluxos a seguir:

ClosedPremissas
  • A API registerPixBilling só pode ser chamada em lote de no máximo 100 títulos por payload;
  • O mesmo título não pode ser enviado para geração ou cancelamento do pix;
  • Não é possível alterar um Pix gerado. É possível apenas cancelar e depois gerar novamente;
  • Os retornos de confirmação do Pix pago são realizados um por vez.
ClosedFluxo do processo banking - Geração do Pix

  1. Identifica se o cliente do título já está cadastrado. Caso não esteja, é realizado o cadastro do cliente;
  2. A requisição é enviada para o parceiro bancário. O parceiro bancário é responsável por enviar para o banco a solicitação de Pix;
  3. Após o banco gerar o Pix, devolve para o banking e entrega para o solicitante;
  4. Após pago, o Pix é identificado como pago pelo banco e entregue para o solicitante.
ClosedFluxo do pagamento do Pix

Bancos aceitos para cada serviço

Banco Serviço COB ou COBV
Itaú Pix copia e cola e Pix QRCode COBV
Santander Pix copia e cola e Pix QRCode COB
Bradesco Pix copia e cola e Pix QRCode COBV
Banco do Brasil Pix copia e cola e Pix QRCode COB

Parceiros bancários

Parceiro Serviço
eSales Cobrança Pix

Consultar status da criação das cobranças Pix

Ao cadastrar uma cobrança Pix por meio de um parceiro, pode ocorrer uma indisponibilidade temporária no sistema entre a solicitação de criação e o retorno da resposta pelo parceiro. Nessas situações, é possível consultar o status dos títulos criados para assegurar o acompanhamento das transações.

A API pública para consulta do Pix é a getStatusPixBilling. Veja abaixo os detalhes:

ClosedEstrutura da getStatusPixBilling 
"Query de listagem do status dos títulos de cobrança PIX
### Resources
- res://senior.com.br/erpx_bnk_cob/register_pix/queries/getStatusPixBilling"
public query getStatusPixBilling {
    in {
        "Filtro"				
        filter : recFilterGetStatusPixBilling?
        "Controle de paginação e ordenação"
        pageRequest : recPageRequest
    }

    out {
        "Dados da cobrança Pix"
        pixBillingData : recPixBillingData*
    }
    
    responses {
        400 : "Requisição inválida, parâmetros obrigatórios não informados ou campo informado incorretamente"
        403 : "Permissão negada"
        404 : "Registro não encontrado"
    }
}

recFilterGetStatusPixBilling

  • Filtro de status dos títulos de cobrança Pix;
  • Se o filtro incluir IDs de títulos e um intervalo de datas, a consulta prioriza os IDs, desconsiderando as datas informadas;
  • Caso o ID não seja informado, é obrigatório fornecer uma data inicial e uma data final. A data inicial não pode ser futura, e o intervalo entre as datas deve ser de, no máximo, 7 dias corridos.
  • O filtro aceita apenas IDs, apenas datas ou uma combinação de IDs e datas.
ClosedRecords e Enumerations 
"Record do filtro de status dos títulos de cobrança Pix"
record recFilterGetStatusPixBilling{
    "Lista de Identificadores dos títulos"
    billingId : string?*
    "Data de envio inicial"
    startDate : date?
    "Data de envio final"
    endDate : date?        
}

"Record de dados da cobrança Pix"
record recPixBillingData {    
    "Identificador do título"
    accountReceivableId : string
    "Situação da geração do PIX"
    situation : enumSituacaoCobrancaItem 
    "Data de criação do PIX"
    creationDate : date?
    "Lista de erros na geração do PIX"
    errors : recError?*
    "PIX Copia e Cola gerado pelo banco"
    pixCopyAndPaste : string?
    "Pix QRCode"
    pixQRCode : string?
    "Valor recebido"
    valueReceived : money
    "Valor original"
    originalValue : money
    "Valor de abatimento"
    rebateValue : money
    "Valor de multa"
    assessmentValue : money
    "Valor de desconto"
    discountValue : money
    "Valor de juros"
    interestValue : money
    "Data/Hora do Recebimento"
    payDate : dateTime
    "Informação do pagador"
    payerInformation : string?
    "Identificador único do pagamento"
    endToEndId : string        	
}

"Record com informações de erro pix"
record recError {
    "Mensagem de erro"
    message : string
    "Campo do erro"
    field : string?
}

"Record para paginação e ordenação"
record recPageRequest {
    "Página atual"
    offset : integer
    "Total de registros da página"
    size : integer
    "Campos da ordenação dos registros a serem pesquisados"
    orderBy : recFieldsOrderBy?*
}

"Define o registro com os dados dos campos à serem ordenados"
record recFieldsOrderBy {
    "Nome do campo a ser ordenado"
    field : string
    "Tipo de ordenação do campo (ASC / DESC)"
    order : enumTypeOrder
}

"Enumeração para o tipo de ordenação"
enumeration enumTypeOrder {
    "Tipo de ordenação - Crescente"
    ASC
    "Tipo de ordenação - Decrescente"
    DESC
}
ClosedCURL de exemplo getStatusPixBilling 
curl --location 'https://cloud-leaf.senior.com.br/t/senior.com.br/bridge/1.0/rest/erpx_bnk_cob/register_pix/queries/getStatusPixBilling' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer AWyp9hVkJXtfG5nmyjnmMZnwQSg8hvbE' \
--data '{
    "filter": {
        "billingId": ["1f5602cb-25c5-4da6-9864-a8c366103803"],
        "startDate": "2024-06-12",
        "endDate": "2024-06-16"
    },
    "pageRequest": {
        "offset": "0",
        "size": "10"
    }
}'

Cancelar o Pix

Caso seja necessário, é possível fazer o cancelamento do Pix através da API cancelPixBilling.

ClosedEstrutura cancelPixBilling 
{
    "processId": faa72901-3701-479b-8d57-c3e5343e98eb,
    "accountsReceivableId": [
        "e2f257b0-2011-4af1-98e9-e146846121a1"
    ]
}

Descrição dos campos da cancelPixBilling

ClosedprocessId

Identificador do processo;

É um valor para identificar a chamada que está sendo realizada.

Informação obrigatória.

ClosedaccountsReceivableId

Informar os títulos que deseja cancelar.

Processo de cancelamento do Pix

Após o banking receber a requisição para o cancelamento do pix pela API cancelPixBilling, o sistema segue os processos demonstrados no fluxos a seguir:

ClosedPremissas
  • A API cancelPixBilling só pode ser chamada em lote de no máximo 100 títulos por payload;
  • O mesmo título não pode ser enviado para geração ou cancelamento do pix;
  • Não é possível alterar um Pix gerado. É possível apenas cancelar e depois gerar novamente;
ClosedFluxo do cancelamento do Pix

Este artigo ajudou você?

Base de Conhecimento

Portal de Exigências Legais

Contrato de Licenciamento de Software e Prestação de Serviços

Documentação em outros idiomas:

English

Español

Senior Store

Universidade Corporativa

Fórum de Produtos

Trabalhe conosco

Blog

Todos os direitos de cópias reservadas para Senior Sistemas S.A.

A reprodução não autorizada desta publicação, no todo ou em parte, constitui violação dos direitos autorais (Lei 9.610/98).

Ainda com dúvidas?

Fale com a SARA!

Ver site completo