Base de Conhecimento de Gestão Comercial de Saneamento

Essa página está em modo somente de leitura. Você pode visualizar a fonte, mas não alterá-la. Informe-se com o administrador do Wiki, caso você ache que isso está incorreto.
[[:treinamentos|{{:treinamentos:api.png?nolink&90  }}]]

----

====== API Pagamento ======

<columns> Documentação do funcionamento da API Pagamento construída para trabalhar com todos os Sistemas Comerciais suportados pela Consenso.

Este documento é direcionado para empresas administradoras de serviços de pagamento por cartão que necessitem integrar o GSAN com seu portfólio de serviços financeiros.

A API possui o recurso de segurança através de token, facilitando a habilitação e desabilitação de novos parceiros. Utiliza arquitetura REST em suas APIs. </columns>


===== Fluxo de Pagamento por Cartão =====

<columns> A seguir o fluxo completo do pagamento descrevendo os processos de autorização, pagamento do compromisso pela credenciada, resposta de autorização e baixa do pagamento pelo movimento arrecadador, até a baixa definitiva no GSAN. </columns>

\\
<WRAP center round box 100%>
{{ :integracoes:imagem_documentacao_api_pagamentos.png?1000 |}}
</WRAP>
\\

===== Autenticação =====

<columns> Os endpoints que nescessitem autenticação serão informados abaixo. Os mesmos precisarão ter as seguintes chaves, **client_secret** e **client_id**, no cabeçalho HTTP, a chave em questão deve ser solicitada para o ambiente sandbox alvo da homologação:

</columns>

  * **client_id**: CREDENCIADA
  * **client_secret**: <HASH 256b>


==== ENDPOINT CONSULTAR DÉBITOS ====

Usar [[:integracoes:api-pagamento#endpoint_notificar_pagamentos|FLUXO DE ERRO PADRÃO]]

POST(autenticar): [[HTTPS://ENDPOINTALVO:PORTA/gsan/api/debitos|]]

JSON de consulta:

<code javascript>
 {documento:"21469517000102"}


</code>

OU

<code javascript>
 {matricula:"99999"}
</code>

OU
<code javascript>
{
   matricula:"99999",
   documento:"21469517000102"
}
</code>

<code>

Resposta:

</code>

<code javascript>
{
   matricula: 99999,
   nome: "EMPRESA DE EXEMPLO",
   documento: "21469517000102",
   debitos:    [
      {
         id: "C#76108553",
         tipoDebito: "CONTA",
         valorOriginal: 3109.00,
         valorDebito: 3199.35,
         valorAcrescimos: 90.35,
         validadeDebito: "20180513",
         referencia: "04/2018",
         descricao: "REFERENCIA 04/2018"
      },
      {
         id: "G#527414",
         tipoDebito: "GUIA",
         valorOriginal: 32.5,
         valorAcrescimos: 0.00,
         valorDebito: 32.5,
         validadeDebito: "20181129",
         referencia: "04/2018",
         descricao: "CADASTRO LIG AGUA MED IND"
      },
      {
         id: "D#72478737",
         tipoDebito: "DEBITO A COBRAR",
         valorOriginal: 1.98,
         valorAcrescimos: 0.00,
         valorDebito: 1.98,
         referencia: "04/2018",
         descricao: "MULTA P/IMPONTUALIDADE PRESTACAO:0/1"
      }
   ]
}


</code>

==== ENDPOINT PESQUISAR DÉBITOS PARA EMISSÃO DE EXTRATO ====

Usar [[:integracoes:api-pagamento#endpoint_notificar_pagamentos|FLUXO DE ERRO PADRÃO]]

  * POST (autenticar): [[HTTPS://ENDPOINTALVO:PORTA/gsan/api/pagamentos/extrato/debitos|]]

JSON de consulta:

<code javascript>
{
   matricula:"452812"
}
</code>
OU
<code javascript>
{
   matricula:"452812",
   documento:"03998285663"
}
</code>

Resposta:

<code javascript>
{
 matricula:"452812",
 debitos: [
      {
      id: "C#7454122",
      tipoDebito: "CONTA",
      valorOriginal: 34.67,
      valorAcrescimos: 10.48,
      valorDebito: 45.15,
      validadeDebito: "17/01/2018",
      descricao: "MATRICULA: 452812 REFERENCIA: 01/2018"
   },
      {
      id: "G#472527",
      tipoDebito: "GUIA",
      valorOriginal: 80,
      valorAcrescimos: 0,
      valorDebito: 80,
      validadeDebito: "03/11/2017",
      descricao: "ENTRADA PARCELAMENTO      PRESTACAO:1 / 1"
   }
]}


</code>

==== ENDPOINT EMITIR EXTRATO ====

Usar [[:integracoes:api-pagamento#endpoint_notificar_pagamentos|FLUXO DE ERRO PADRÃO]]

  * POST(autenticar): [[HTTPS://ENDPOINTALVO:PORTA/gsan/api/pagamentos/extrato/emitir|]]

O débito gerado neste endpoint deve ser notificado no ENDPOINT NOTIFICAR PAGAMENTOS. Não devem ser notificados os débitos retornados no ENDPOINT PESQUISAR DÉBITOS PARA EMISSÃO DE EXTRATO.

JSON de consulta:

<code javascript>
{
   matricula:777985,
   debitos: [
            {
         id: "C#74481982"
      },{
         id: "G#472527"
      }
   ]
}


</code>

Resposta:

<code javascript>
{
   matricula: 777985,
   debitos: [   {
      id: "E#17029415",
      codigoBarras: "826400000012251700412975001191624012702941514151",
      valorDebito: 125.17
   }]
}


</code>

==== ENDPOINT DESCONTO EXTRATO ====

Usar [[:integracoes:api-pagamento#endpoint_notificar_pagamentos|FLUXO DE ERRO PADRÃO]]

  * POST(autenticar): [[HTTPS://ENDPOINTALVO:PORTA/gsan/api/pagamentos/extrato/desconto|]]

Esse endpoint não gera débito. Apenas retorna a matrícula e o valor de desconto com base nos débitos passados jo JSON de entrada.

JSON de consulta:

<code javascript>
{
   matricula:777985,
   debitos: [
            {
         id: "C#74481982"
      },{
         id: "G#472527"
      }
   ]
}


</code>

Resposta:

<code javascript>
{
   matricula: 777985,
   valorDesconto: 25.17
}


</code>

==== ENDPOINT NOTIFICAR PAGAMENTOS ====

Usar [[:integracoes:api-pagamento#endpoint_notificar_pagamentos|FLUXO DE ERRO PADRÃO]]

POST(autenticar): [[HTTPS://ENDPOINTALVO:PORTA/gsan/api/pagamentos/notificarPagamento|]]

JSON de Consulta:

<code javascript>
{
   identificacaoTransacao: "5462158456512",
   tipoCartao: "creditoAVista",
   debitos:    [
            {
         id: "C#78422196",
     autenticacao: "JHAJl765765765"
      },
            {
         id: "G#408204",
     autenticacao: "6565163516516574654361351351351354531"
      }
   ]
}


</code>

<code javascript>
{
   identificacaoTransacao: "5462158456512",
   tipoCartao: "debito",
   debitos:    [
            {
         id: "C#78422196",
     autenticacao: "JHAJl765765765"
      },
            {
         id: "G#408204",
     autenticacao: "6565163516516574654361351351351354531"
      }
   ]
}


</code>

<code javascript>
{
   identificacaoTransacao: "5462158456512",
   tipoCartao: "creditoParcelado",
   debitos:    [
            {
         id: "E#408204",
     autenticacao: "6565163516516574654361351351351354531"
      }
   ]
}


</code>

Resposta:

<code javascript>
{status: "OK"}


</code>

==== ENDPOINT NOTIFICAR CANCELAMENTO DE PAGAMENTO ====

Usar [[:integracoes:api-pagamento#endpoint_notificar_pagamentos|FLUXO DE ERRO PADRÃO]]

POST(autenticar): [[HTTPS://ENDPOINTALVO:PORTA/gsan/api/pagamentos/notificarPagamento|]]

JSON de Consulta:

<code javascript>
{
   identificacaoTransacao: "5462158456512",
   status: "chargeback",
   debitos:    [
            {
         id: "C#78422196",
     autenticacao: "JHAJl765765765"
      },
            {
         id: "G#408204",
     autenticacao: "6565163516516574654361351351351354531"
      }
   ]
}


</code>

Resposta:

<code javascript>
{status: "OK"}


</code>

==== ENDPOINT OBTER URL CHECKOUT ====

POST: [[HTTPS://ENDPOINTALVO:PORTA/gsan/api/pagamentos/obterUrlCheckoutEmpresaPagamento|]]

Parâmetros de Consulta:

  * credenciada = identificacao da credenciada
  * codBarra = código de barras do documento
  * doc = cpf/cnpj do cliente
  * nome = Nome do cliente
  * id = identificação do débito fornecido pela API de emitir débito.

JSON Resposta:

<code javascript>
{
  url: "https://example.com/?param=fsdfsdf5454f35s4df5sd4f",
  erro: false
}


</code>

**Obs.:**  Este endpoint realiza um POST para o endpoint(com o token para acessar este endpoint) disponibilizado pela EMPRESA CREDENCIADA, passando como parâmetros:

  * codigoBarras = código de barras do documento
  * matricula = matrícula do imóvel **[Opcional]**
  * documento = cpf/cnpj do cliente **[Opcional]**
  * nome = Nome do cliente **[Opcional]**
  * id = identificação do débito fornecido pela API de emitir débito. **[Opcional]**

JSON Resposta:

<code javascript>
{
  url: "https://example.com/?param=fsdfsdf5454f35s4df5sd4f"
}


</code>

==== FLUXO DE ERRO PADRÃO ====

Dicionário de código de erros em anexo.

Resposta:

<code javascript>
{erro: {
   cod: 3,
   msg: "EMPRESA NAO CADASTRADA"
}}


</code>

Tabela de Erros:

^Codigo^Erro|
|0|NÃO TRATADO|
|1|client_id obrigatório|
|2|client_secret obrigatório|
|3|EMPRESA NAO CADASTRADA|
|4|chave inválida|
|100|variável documento inexistente|
|101|variável debitos inexistente|
|102|variável debitos vazia|
|103|variável nsu ou identificacaoTransacao inexistente|
|104|cliente inexistente|
|105|documento inválido|
|106|documento obrigatório|
|107|documento cadastrado para vários clientes na base|
|108|identidicador do débito com formato inválido|
|109|invoice_number vazio|
|110|id do débito pago vazio|
|111|autenticacao do débito pago vazia|
|112|ID do débito inexistente na base|
|113|status inexistente|
|114|matricula inexistente|
|115|imóvel não cadastrado|
|116|extrato não permitido para imóvel|
|117|variável credenciada inexistente|
|118|matrícula obrigatória|
|119|matrícula inválida|
|120|pagamento inexistente|
|121|Este imóvel não tem perfil|
|122|Já existe pagamento para documento|

----

===== Apêndice 1 - Layout Arquivo de Remessa de Arrecadação =====

**“Layout” Padrão de Arrecadação/Recebimento com Utilização do Código de Barras**<columns> Para as empresas que possuem serviço de VAN é necessário respeitar o layou abaixo, conforme Febraban V.04, para transmitir o movimento com o arquivo com os devidos pagamentos, o layout abaixo precisa ser respeitado, ver [[:postgres:arrecadacao:uc0262|UC0262]] para mais detalhes. </columns>

==== Distribuir Registro Código A (CABEÇALHO DO ARQUIVO) ====

|DESCRIÇÃO DO REGISTRO **A - HEADER** OBRIGATÓRIO EM TODOS OS ARQUIVOS|||||
|POSIÇÕES||||
|CAMPOS|DE|ATÉ|FORMATO|CONTEÚDO|
|A. 01|1|1|CHAR(1)|Código do registro = A|
|A. 02|2|2|NUM(1)|Código de Remessa|
|A. 03|3|22|CHAR(20)|Código do Convênio|
|A. 04|23|42|CHAR(20)|Nome da Empresa|
|A. 05|43|45|NUM(3)|Código do Banco|
|A. 06|46|65|CHAR(20)|Nome do Banco|
|A. 07|66|73|NUM(08)|Data da geração do arquivo (AAAAMMDD)|
|A. 08|74|79|NUM(06)|Número sequencial do arquivo (NSA)|
|A. 09|80|81|NUM(02 )|Versão do layout|
|A. 10|82|98|CHAR(17)|Tipo de Movimento|
|A.11|99|150|CHAR(52)|Reservado para o futuro (em branco)|

**DESCRIÇÃO DOS CAMPOS DO REGISTRO “A”**

A.01 - Código do registro = “A” \\ A.02 - Código de Remessa \\ > 2 - RETORNO - Enviado pelo Banco para a Empresa/Órgão \\ A.03 - Código do Convênio \\ > Definido pelo banco \\ A.04 - Nome da Empresa/Órgão \\ A.05 - Código do Banco \\ > Código do Banco na câmara de compensação \\ A.06 - Nome do Banco \\ A.07 - Data da geração do arquivo (AAAAMMDD ) \\ A.08 - Número seqüencial do arquivo ( NSA ) \\ > Este número deverá evoluir de 1 em 1 para cada arquivo gerado \\ A.09 - Versão do lay - out \\ > legada = versão 03 \\ > atual = versão 04 \\ > nova = versão 05 - disponível a partir de 01.08.2016. \\ A.10 – Identificação do serviço \\ > Deverá conter “CÓDIGO DE BARRAS” \\ A.11 – Reservado para o futuro (filler)

----

==== Distribuir Registro Código G ====

|DESCRIÇÃO DO REGISTRO **G - RETORNO DAS ARRECADAÇÕES IDENTIFICADAS** **COM CÓDIGO DE BARRAS** |||||
|POSIÇÕES||||
|CAMPOS|DE|ATÉ|FORMATO|CONTEÚDO|
|G.01|1|1|CHAR(1)|Código do registro = G|
|G.02|2|21|CHAR(20)|Identificação da agência/conta/dígito creditada|
|G.03|22|29|NUM(08)|Data de pagamento (AAAAMMDD)|
|G.04|30|37|NUM(08)|Data prevista para o crédito (AAAAMMDD)|
|**G. 05** |**38** |**81** |**CHAR(44)** |**Código de Barras** |
|G.06|82|93|NUM(12,2)|Valor recebido|
|G.07|94|100|NUM(7,2)|Valor da tarifa|
|G.08|101|108|NUM(8)|NSR - Número Sequencial de Registro|
|G.09|109|116|CHAR(8)|Código da agência arrecadadora|
|G.10|117|117|CHAR(1)|Forma de arrecadação/captura|
|G.11|118|140|CHAR(23)|Número de autenticação caixa ou código de transação|
|G.12|141|141|NUM(1)|Forma de Pagamento, se a forma de pagamento for nula alterar para valor 1|
|G.13|142|150|CHAR(9)|Reservado para o futuro|

**DESCRIÇÃO DOS CAMPOS DO REGISTRO “G”**

G.01 - Código do registro = “G” \\ G.02 - Identificação da empresa/órgão no banco/agência/conta/dígito creditada \\ G.03 - Data do pagamento no formato Ano/Mês /Dia \\ G.04 - Data do crédito no formato Ano/Mês/Dia \\ G.05 - Informações do Código de Barras \\ G.06 - Valor efetivamente recebido \\ G.07 - Valor da tarifa referente a cada comprovante arrecadado (será informado desde que acordado entre as partes) \\ G.08 - Uso do Banco - Identificação do registro dentro do arquivo gerado \\ G.09 – Código da agência arrecadadora \\ G.10 – Forma de arrecadação/captura (canais de recebimento) \\ > 1 – Guichê de Caixa com fatura/guia de arrecadação \\ > 2 – Arrecadação Eletrônica com fatura/guia de arrecadação (terminais de auto - atendimento, \\ ATM, home/office banking) \\ > 3 – Internet com fatura/guia de arrecadação \\ > 4 – Outros meios com fatura/guia de arrecadação \\ > 5 – Casas lotéricas/correspondentes bancários com fatura/guia de arrecadação \\ > 6 – Telefone com fatura/guia de arrecadação \\ >> a – Guichê de Caixa sem fatura/guia de arrecadação \\ >> b – Arrecadação Eletrônica sem fatura/guia de arrecadação (terminais de auto - atendimento, ATM, home/office banking) \\ >> c – Internet sem fatura/guia de arrecadação \\ >> d – Casas lotéricas/correspondentes bancários sem fatura/guia de arrecadação \\ >> e – Telefone sem fatura/guia de arrecadação \\ >> f – Outros meios sem fatura/guia de arrecadação \\ > 7 – Casas lotéricas com fatura/guia de arrecadação \\ > 8 - Cartão/Multibanco com fatura/guia de arrecadação \\ > <color red>**9 – PIX com fatura/guia de arrecadação**</color> \\ >> <color red>a – Guichê de Caixa sem fatura/guia de arrecadação</color> \\ >> <color red>b – Arrecadação Eletrônica sem fatura/guia de arrecadação (terminais de auto - atendimento, ATM, home banking)</color> \\ >> <color red>c – Internet/mobile sem fatura/guia de arrecadação</color> \\ >> <color red>d – Correspondentes bancários sem fatura/guia de arrecadação</color> \\ >> <color red>e – Telefone sem fatura/guia de arrecadação</color> \\ >> <color red>f – Outros meios sem fatura/guia de arrecadação</color> \\ >> <color red>g – Casas lotéricas sem fatura/guia de arrecadação</color> \\ >> <color red>h – Cartão/Multibanco sem fatura/guia de arrecadação</color> \\ >> <color red>i – PIX sem fatura/guia de arrecadação</color> \\ G.11 – Número de autenticação caixa ou código de transação (será informado desde que acordado entre as partes). \\ G.12 – Forma de Pagamento \\ > 1 – Dinheiro \\ > 2 – Cheque \\ > 3 – Não identificado \\ G.13 – Reservado para o futuro

----

==== Distribuir Registro Código Z (TRAILLER) ====

Distribuir os campos do registro do arquivo de movimento de arrecadadores de acordo com o formato abaixo:

|DESCRIÇÃO DO REGISTRO **Z - TRAILLER** OBRIGATÓRIO EM TODOS OS ARQUIVOS|||||
|POSIÇÕES||||
|CAMPOS|DE|ATÉ|FORMATO|CONTEÚDO|
|Z. 01|1|1|CHAR(1)|Código do Registro = Z|
|Z. 02|2|7|NUM(06)|Total de registros do arquivo|
|Z. 03|8|24|NUM(17,2)|Valor total recebido dos registros do arquivo|
|Z. 04|25|150|CHAR(126)|Reservado para o futuro (brancos)|

~~NOSIDEBAR~~