Integração para Registro de Pix - inncash/inncash-docs GitHub Wiki

Integração para registro de Pix

1 – Descrição Resumida do Fluxo

  • Empresa parceira consome o serviço de geração de token no InnCash.
  • Empresa parceira envia solicitação de registro de Pix de Cobrança.
  • O InnCash retorna a Url de geração de Pix para que a empresa parceira compartilhe com seu cliente.
  • Através da Url disponibilizada o cliente da empresa parceira poderá efetuar a consulta do qrCode gerado para realizar o pagamento.
  • O InnCash verifica o pagamento do Pix e envia essa informação para o ERP da empresa parceira.

2 - Credenciais

As credenciais de acesso serão fornecidas pela Innova Connect Sistemas seguindo o modelo abaixo.

Ambiente de Homologação

Ambiente de Produção

3 - Recursos

1 - Gerar Token de Autenticação

Recurso que permite a geração de um Access Token para validar a conexão entre o sistema da empresa parceira e o InnCash. Devem ser informadas as credenciais específicas para cada ambiente.

Url : /login
Método : POST (Multipar Form)
Retorno : 201 Sucesso ou 401 Erro

Exemplo do corpo da requisão

{
"username": "pix.parceiro",
"password": "19062bb75efa12dd28744fcc9b6badc46d4ff655"
}

Exemplo de Retornos

{
  "status": 201,
  "data": {
    "message": "Token gerado com sucesso!",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
    "expiration_time": 3600
  }
}

{
   "status": 401,
   "data": {
     "message": "Usuário ou senha inválidos!",
     "token": "",
     "expiration_time": 0
}
}

{
   "status": 401,
   "data": { 
     "message": "Token inválido!",
     "token": "",
     "expiration_time": 0
}
}

2 - Gerar Registro de Cobrança Pix

Recurso que permite ao Sistema da empresa parceira gerar uma cobrança Pix através do InnCash.

Url : /cob
Método : POST (JSON)
Parâmetros no Head : token
Retorno : 201 Sucesso ou 400 Erro

Exemplo de Envio

{
  "data": {
    "credential_id": 1,
    "request_id": 123456,
    "pix_key": "[email protected]",
    "expiration_time": 0,
    "document_value": 1000.00,
    "payer": {
      "client_number": 123,
      "branch_number": "123",
      "payer_id": "24779780000188",
      "payer_type": "PJ"
    },
    "extras": [
      {
        "label": "Cliente",
        "value": "Innova Connect Sistemas"
      },
      {
        "label": "Workflow email",
        "value": "[email protected]"
      },
      {
        "label": "Email to Contact",
        "value": "[email protected]"
      }
    ]
  },
  "event": "pix_create",
  "company_id": 1
}

Exemplos de Retornos

{
  "status": 201,
  "data": {
    "id": "123456789012345",
    "message": "Pix registrado com sucesso!",
    "location": "https://inn.cash/pix/cob/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJsdW1lbi1qd3QiLCJzdWIiOjEyMzY1NzksImlhdCI6MTYxNjQzNTIzNiwiZXhwIjoxNjE2NTIxNjM2fQ.sQp4hRf02Jw-HuWA76g_Wf4KZOzrLC7BawxeTt3UnAw"
  }
}

{
  "status": 400,
  "data": {
    "id": "0",
    "message": "Instituição bancária não respondeu!",
    "location": ""
  }
}

3 - Cancelar Registro de Cobrança Pix

Permite solicitar o cancelamento da cobrança Pix,

Url : /cob/cancela
Método : PATCH (application/x-www-form-urlencoded)
Parâmetros no Query : _method
Parâmetros no URL : id
Parâmetros no Head : token
Retorno : 201 Sucesso ou 400 Erro

Exemplos de Retorno

{
  "status": 201,
  "data": {
    "message": "Cancelamento do PIX realizado!"
  }
}

{
  "status": 400,
  "data": {
    "message": "PIX já pago, não é permitido fazer o cancelamento!"
  }
}

4 - Geração de QrCode

É possivel gerar a imagem do QrCode através desse serviço.

Url : /cob/qrcode/:id
Método : GET
Parâmetros no URL : id
Parâmetros no Head : token
Retorno : 201 Sucesso ou 400 Erro

Retornará uma imagem qrCode

Descrição dos campos

Tipo Nome Descrição
String username Nome do usuário fornecedo pela Innova Connect Sistemas
String password Senha fornecida pela Innova Connect Sistemas
String message Mensagem de retorno da operação
String token Token JWT gerado no ato da autenticação
Int expiration_time Parâmetro opcional do tempo da validade do Pix, se não informado, informado um valor inválido ou o valor for igual a 0 (zero) assume o valor padrão de 86400 segundos (24 horas)
Int id Número da solicitação interna do sistema parceiro registrado na instituição financeira
Int credential_id ID informado pela Innova Connect Sistemas vinculado ao convênio bancário
Int request_id ID informado pelo cliente para controle interno
String pix_key Chave Pix do recebedor
Float document_value Valor a ser registrado na instituição bancária
String client_number Número identificador do código do cliente
String branch_number Número identificador da filial do cliente
String payer_id Número identificador Pagador (CNPJ / CPF)
String payer_type Identificador se o pagador é Pessoa Fisica ou Pessoa Jurídica
String label Informação adicional a ser impressa ou armazenada para controle de um valor (value)
String value Informação adicional vinculada a uma etiqueta (label)
String location URL onde os dados para pagamento estão disponíveis
⚠️ **GitHub.com Fallback** ⚠️