[[:treinamentos|{{:treinamentos:api.png?nolink&90 }}]] ---- ====== API Pagamento ====== 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 plataforma REST com simples, utilizando JSON como protocolo padrão. ===== Fluxo de Pagamento por Cartão ===== 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. \\ {{ :integracoes:imagem_documentacao_api_pagamentos.png?1000 |}} \\ ===== Autenticação ===== 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 foi gerada para o ambiente de testes: * **client_id**: CREDENCIADA * **client_secret**: ==== 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: {documento:"21469517000102"} OU {matricula:"99999"} Resposta: { 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" } ] } ==== 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: { matricula:"452812" } Resposta: { 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" } ]} ==== 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: { matricula:777985, debitos: [ { id: "C#74481982" },{ id: "G#472527" } ] } Resposta: { matricula: 777985, debitos: [ { id: "E#17029415", codigoBarras: "826400000012251700412975001191624012702941514151", valorDebito: 125.17 }] } ==== 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: { matricula:777985, debitos: [ { id: "C#74481982" },{ id: "G#472527" } ] } Resposta: { matricula: 777985, valorDesconto: 25.17 } ==== 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: { identificacaoTransacao: "5462158456512", tipoCartao: "creditoAVista", debitos: [ { id: "C#78422196", autenticacao: "JHAJl765765765" }, { id: "G#408204", autenticacao: "6565163516516574654361351351351354531" } ] } { identificacaoTransacao: "5462158456512", tipoCartao: "debito", debitos: [ { id: "C#78422196", autenticacao: "JHAJl765765765" }, { id: "G#408204", autenticacao: "6565163516516574654361351351351354531" } ] } { identificacaoTransacao: "5462158456512", tipoCartao: "creditoParcelado", debitos: [ { id: "E#408204", autenticacao: "6565163516516574654361351351351354531" } ] } Resposta: {status: "OK"} ==== 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: { identificacaoTransacao: "5462158456512", status: "chargeback", debitos: [ { id: "C#78422196", autenticacao: "JHAJl765765765" }, { id: "G#408204", autenticacao: "6565163516516574654361351351351354531" } ] } Resposta: {status: "OK"} ==== 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: { url: "https://example.com/?param=fsdfsdf5454f35s4df5sd4f", erro: false } **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: { url: "https://example.com/?param=fsdfsdf5454f35s4df5sd4f" } ==== FLUXO DE ERRO PADRÃO ==== Dicionário de código de erros em anexo. Resposta: {erro: { cod: 3, msg: "EMPRESA NAO CADASTRADA" }} 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** 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. ==== 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 \\ > **9 – PIX 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 banking) \\ >> c – Internet/mobile sem fatura/guia de arrecadação \\ >> d – 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 \\ >> g – Casas lotéricas sem fatura/guia de arrecadação \\ >> h – Cartão/Multibanco sem fatura/guia de arrecadação \\ >> i – PIX sem fatura/guia de arrecadação \\ 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~~