Sobre recargas nacionais
A API de Recargas Nacionais disponibiliza aos seus usuários a possibilidade de realizar recargas de telefonia e conteúdos digitais listados abaixo:
Recargas de Telefonia disponíveis
Algar (Móvel e Fixo)
Claro (Móvel)
Correios
Embratel
Sercomtel Fixo
Tim
Vivo (Móvel e Fixo)
Recargas de Conteúdo Digital disponíveis
Claro TV
Google Play
League of Legends
Oi TV
PSN Store
SKY TV
Spotify
STEAM
Uber
Xbox Live
Pré requisitos para implementação:
-
Possuir uma chave API da Celcoin, para mais informações acessar esse link
-
Ter familiaridade com APIs Rest usando o protocolo OAuth 2.0.
-
Ter o produto/solução contratada, caso queira usar a funcionalidade em ambiente produtivo, por favor entre em contato com a nossa equipe comercial através do e-mail [email protected]. Para dúvidas técnicas, basta entrar em contato com o suporte através do link.
O que você irá aprender nesse artigo:
- Consultar Operadoras
- Consultar valores operacionais
- Realizar efetivação de uma recarga
- Confirmar a transação de uma recarga
- Medida de prevenção quando ocorrer uma intermitência na API da Celcoin
A Celcoin disponibiliza suas APIs para facilitar as conexões com os provedores. Assim, processa as transações e traz o retorno sobre seu andamento, desta forma um caso de uso seria:
Caso de uso:
Como fintech, quero disponibilizar para os meus usuários a possibilidade de realizar recargas de celular, jogos, transporte, ou tv, onde ele precisa selecionar a operadora e valor que deseja contratar, digitar os dados necessários e aprovar aquisição.
Com objetivo de exibir como pode ser a jornada de Recarga para um usuário, criamos essa apresentação que simula o processo como todo:
Consultar Operadoras
Em primeiro lugar é preciso se autenticar na API da Celcoin, caso tenha dúvida em como realizar esse processo indicamos a leitura do artigo Obtendo suas credenciais.
Com o access_token retornado da chamada acima é possível realizar uma consulta na API Retorna a lista de operadoras, essa chamada irá retornar todos os provedores disponíveis para recargas na Celcoin.
Recomendamos que essa requisição não seja realizada em toda execução do fluxo de integração, basta você realizá- la uma vez ao dia e armazenar os providerId (Identificadores dos provedores) em sua base de dados, desta forma, você sempre terá eles atualizados para realizar as recargas de seus usuários e não precisará executar essa requisição diversas vezes.
Para essa requisição é necessário informar na querystring a propriedade type(tipo) que pode ser preenchido com:
0 para TODOS
1 para PIN
2 para ONLINEE a propriedade category(categoria) da recarga poderá ser informada como:
0 para TODOS
1 para TELEFONE
2 para JOGOS
3 para TV
4 para TRANSPORTE
5 para CONTEÚDO DIGITAL
Modelo de request:
curl --location --request GET 'https://sandbox.openfinance.celcoin.dev/v5/transactions/topups/providers?stateCode=13&type=0&category=0' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw ''
Modelo de retorno:
{
"providers": [
{
"category": 2,
"name": "Blizzard",
"providerId": 2139,
"RegionaisnameProvider": [],
"TipoRecarganameProvider": 1,
"maxValue": 0.0,
"minValue": 0.0
},
{
"category": 2,
"name": "Boa Compra",
"providerId": 2107,
"RegionaisnameProvider": [],
"TipoRecarganameProvider": 1,
"maxValue": 0.0,
"minValue": 0.0
}
]
}
Estrutura de dados response:
Campo | Tipo | Descrição |
---|---|---|
name | String(50) | Define o nome do produto/serviço |
providerID | int | Código do serviço |
tipoRecarganameProvider | String(1) | Retorna o tipo da operação: 1 para PIN (Retorna o PIN no comprovante que será utilizado pelo usuário no provedor do serviço) 2 para ONLINE (Recarga convencional, realizada a partir das informações passadas na requisição) |
maxValue | Double | Valor máximo permitido para pagamento do título |
minValue | Double | Valor mínimo permitido para pagamento do título |
Consultar valores operacionais
Uma vez que é apresentado para o usuários as possibilidades de provedores, ele selecionando uma para realizar a recarga, nesse momento deve ser realizado a chamada Consulta valores operacionais para uma operadora ou provedor, onde será apresentado os valores disponíveis para aquela recarga na provedora, com esses valores pode ser apresentado para o usuário escolher qual tipo de recarga ele deseja realizar.
Recomendamos que essa requisição sempre seja realizada no processo, pois esses valores podem ser alterados pelas operadoras.
Modelo de request:
curl --location --request GET 'https://sandbox.openfinance.celcoin.dev/v5/transactions/topups/provider-values?stateCode=11&providerId=2125' \
--header 'Content-Type: application/json' \
--header 'Authorization: {access_token}' \
--data-raw ''
Modelo de retorno:
{
"value": [
{
"properties": null,
"code": 0,
"cost": 0.0,
"detail": "",
"productName": "R$ 85,99 - Xbox Live 3 meses",
"checkSum": -18913591,
"dueProduct": 0,
"valueBonus": 0.0,
"maxValue": 85.99,
"minValue": 85.99
},
{
"properties": null,
"code": 0,
"cost": 0.0,
"detail": "",
"productName": "R$ 171,98 - Xbox Live 6 meses",
"checkSum": -2147483640,
"dueProduct": 0,
"valueBonus": 0.0,
"maxValue": 171.89,
"minValue": 171.98
},
{
"properties": null,
"code": 0,
"cost": 0.0,
"detail": "",
"productName": "R$ 199,00 - Xbox Live 12 meses",
"checkSum": -18913591,
"dueProduct": 0,
"valueBonus": 0.0,
"maxValue": 199.0,
"minValue": 199.0
}
],
"externalNsuQuery": null,
"errorCode": "000",
"message": "SUCESSO",
"status": 0
}
Estrutura de dados response:
Campo | Tipo | Descrição |
---|---|---|
productName | String(50) | Retorna as operações válidas (Sugerimos o espelhamento deste campo para o usuario) |
valueBonus | String(16) | Bônus para valor |
maxValue | Double | Valor máximo permitido para pagamento do título |
minValue | Double | Valor mínimo permitido para pagamento do título |
A operadora Steam efetua o desconto da tarifa para recargas. O valor desse desconto é variável e depende do montante recarregado, conforme detalhado abaixo:
Valor cobrado Valor em Créditos R$10,80 R$10,00 R$21,00 R$20,00 R$32,00 R$30,00 R$53,00 R$50,00 R$105,00 R$100,00 R$160,00 R$150,00 R$210,00 R$200,00
Reserva saldo para realizar recarga
Em seguida deve ser realizada a requisição Reserva saldo para realizar recarga, onde será validado se existe saldo em sua conta Celcoin e se é possível realizar a requisição.
Modelo de request:
curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/v5/transactions/topups' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
"externalTerminal": "1123123123",
"externalNsu": 1234,
"topupData": {
"value": 85.99
},
"cpfCnpj": "65419636069",
"signerCode": "1234567",
"providerId": 2125,
"phone": {
"stateCode": 11,
"countryCode": 55,
"number": 994114386
}
}'
A propriedade signerCode, deve ser populada com o cpf do assinante quando recargas de Tv, ou telefone quando de celular.
Para recargas de conteúdo digital, que não possuem um vínculo a um número de telefone, o objeto phone deve ser preenchido utilizando o seguinte número default: 55 11 999999999 .
Modelo de retorno:
{
"NSUnameProvider": 0,
"authentication": 5878,
"authenticationAPI": null,
"receipt": {
"receiptData": "",
"receiptformatted": " AMBIENTE DE HOMOLOGACAO\r\n PROTOCOLO 0002751870\r\n1 11/03/2022 09:24\r\nTERM 228005 AGENTE 228005 AUTE 05878\r\n----------------------------------------\r\nAUTO 806689 \r\n<VIA1>\r\nESTE CUPOM NAO TEM VALOR FISCAL\r\n</VIA1>PRODUTO: R$ 85,99 - XBOX LIVE 3 MESES\r\n<VIA1>VALOR: R$ 85,99\r\nPIN: 6365-4427-6400-1327\r\nSERIE: 00000000\r\nTELEFONE: 11 994114386\r\n\r\n COMO RESGATAR O CODIGO XBOX:\r\n VISITE XBOX.COM/REDEEMCODE\r\nDIGITE O CODIGO DESTE RECIBO E COMECE A \r\n USAR!\r\n \r\n APOS O USO, INUTILIZE ESTE CUPOM\r\nIS2B - INTEGRATED SOLUTIONS TO BUSINESS\r\n \r\n \r\n \r\n \r\n</VIA1>----------------------------------------\r\n\r\n"
},
"settleDate": "2022-03-11T00:00:00",
"createDate": "2022-03-11T09:24:38",
"transactionId": 9172370,
"Urlreceipt": null,
"errorCode": "000",
"message": null,
"status": 0
}
Perceba que será apresentado o comprovante do pagamento para exibir ao usuário final.
No campo "receiptformatted" a api retorna todas as orientações necessárias para que o usuário realize o resgate da recarga na plataforma solicitada. O PIN é a chave individual de cada recarga, utilizada para concluir o resgate na plataforma. Veja mais orientações em Termos de Uso.
Recomendamos que seja armazenada a propriedade transactionId (Id da transação), pois ela será utilizada para confirmar o pagamento e executar a recarga.
Importante
Não disponibilize o PIN antes de Confirmar o Pagamento. Caso ocorra algum problema a Celcoin não irá se responsabilizar por possíveis prejuízos.
Nesta etapa o PIN é retornado na requisição, conforme response abaixo, porém ele só pode ser disponibilizado ao usuário final na etapa de Confirmação da Recarga.
Importante lembrar, para Recargas de Conteúdo Digital ao solicitar esse tipo de Recarga, já é disponibilizado o PIN, com isso não existe a possibilidade de Cancelamento.
"receipt": { "receiptData": "", "receiptformatted": " AMBIENTE DE HOMOLOGACAO\r\n PROTOCOLO 0002751870\r\n1 11/03/2022 09:24\r\nTERM 228005 AGENTE 228005 AUTE 05878\r\n----------------------------------------\r\nAUTO 806689 \r\n<VIA1>\r\nESTE CUPOM NAO TEM VALOR FISCAL\r\n</VIA1>PRODUTO: R$ 85,99 - XBOX LIVE 3 MESES\r\n<VIA1>VALOR: R$ 85,99\r\nPIN: 6365-4427-6400-1327\r\nSERIE: 00000000\r\nTELEFONE: 11 994114386\r\n\r\n COMO RESGATAR O CODIGO XBOX:\r\n VISITE XBOX.COM/REDEEMCODE\r\nDIGITE O CODIGO DESTE RECIBO E COMECE A \r\n USAR!\r\n \r\n APOS O USO, INUTILIZE ESTE CUPOM\r\nIS2B - INTEGRATED SOLUTIONS TO BUSINESS\r\n \r\n \r\n \r\n \r\n</VIA1>----------------------------------------\r\n\r\n" }
Confirmar a transação de uma recarga
Para finalizar de fato a recarga, deve ser realizada a chamada Confirmar a transação de uma recarga, informando o transactionId, onde a Celcoin irá se comunicar com o provedor e executar a recarga.
Modelo de request:
curl --location --request PUT 'https://sandbox.openfinance.celcoin.dev/v5/transactions/topups/9173139/capture' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
"externalNSU": 1234,
"externalTerminal": "1123123123"
}
'
Modelo de retorno:
{
"errorCode": "000",
"message": "SUCESSO",
"status": 0
}
Caso essa confirmação não seja executada em até 30 minutos, a Celcoin devolve o dinheiro que seria utilizado para a recarga para sua conta bolsão de forma automática, exceto para a Recargas de Conteúdo Digital.
Para Recargas de Conteúdo Digital não é preciso confirmar, pois a partir do momento que você solicita a Reserva de Saldo na etapa anterior, ela já é CONFIRMADA AUTOMATICAMENTE e o PIN disponibilizado, sem possibilidade de Cancelamento.
Medida de prevenção quando ocorrer uma intermitência na api da Celcoin
Consultar informações de uma recarga
Basicamente uma vez que ocorrer uma intermitência ao tentar realizar a chamada API Confirmar a transação de uma recarga ou seja, nossa API retornou que ocorreu um erro inesperado, deve ser realizado um GET na API Consultar informações de uma recarga, passando um dos parâmetros abaixo;
- transactionId (Id único gerado pela Celcoin para a transação)
- externalNSU (Identificador da transação do sistema se integrando a Celcoin)
- externalTerminal (Terminal de identificação externa do sistema integrando a Celcoin)
- operationDate (Data da operação)
Onde será retornado o status da transação, podendo ser pendente, ou sucesso.
No caso de sucesso, deve ser retornado ao usuário final que o pagamento ocorreu como esperado, agora se o status estiver pendente, deve ser realizado novamente a chamada de Confirmar a transação de uma recarga, para que a liquidação ocorra com sucesso.
Modelo de request:
curl --location --request GET 'https://sandbox.openfinance.celcoin.dev/v5/transactions/status-consult?transactionId=9087426' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw ''
Modelo de retorno:
{
"transaction": {
"authentication": 6088,
"errorCode": "000",
"createDate": "2021-06-24T17:48:08",
"message": "SUCESSO",
"externalNSU": 1234,
"transactionId": "7097995",
"status": 0,
"externalTerminal": "11122233344"
},
"erroCode": "000",
"message": "SUCESSO",
"status": "0"
}
Configurar o envio de arquivos de movimentação via SFTP
Disponibilizamos também uma funcionalidade que envia arquivos para um SFTP com as movimentações que ocorreram no dia.
Caso o envio do arquivo das movimentações do dia seja feito via SFTP, compartilhamos abaixo o layout do arquivo de retorno de movimentação e recusa. O envio do arquivo será em d+1, no período da 1:00 ás 03:00 AM. A configuração deverá ser solicitada junto ao suporte.
O arquivo de movimentação contempla todas as recargas solicitadas na API em d-1.
Movimentação:
MOVIMENTACAO_ID + 9(4) – ID DO CLIENTE INTERNO + _NSA + (9(6) – NOTA DE DÉBITO) + _DATA +
AAAAMMDD – DATA CONTABIL DA NOTA DE DÉBITO
Exemplo:
MOVIMENTACAO_ID0002_NSA001494_DATA20160901
Header
Nome do campo | Descrição | Obrigatório | Tamanho | Pos. Inicial | Pos. Final | Tipo |
---|---|---|---|---|---|---|
IF-COD-CORP | Código da Corporação (Será o código do cliente estabelecido pela Celcoin) | Sim | 4 | 1 | 4 | 9(4) |
IF-NUM-LOTE | Número Lote (Número de sequência do arquivo iniciando com 00001) | Sim | 5 | 5 | 9 | 9(5) |
IF-DATA-LOTE | Data (AAAAMMDD) (Data do dia que está sendo enviado o arquivo) | Sim | 8 | 10 | 17 | 9(8) |
IF-COD-ARQUIVO | Zeros | Sim | 2 | 18 | 19 | 9(2) |
IF-TIPO-REGISTRO | “HDR” – Movimentação | Sim | 3 | 20 | 22 | X(3) |
IF-NUM-CONTA | Zeros | Sim | 19 | 23 | 41 | 9(19) |
IF-TIPO-MOVTO | “MONETARIO” | Sim | 9 | 42 | 50 | X(09) |
FILLER | Brancos | Sim | 244 | 51 | 294 | x(244) |
IF-SEQ | Sequencial que indica o número do registro dentro do arquivo. O header deverá ser montado com o sequencial 000001. (Número do registro dentro do arquivo) | Sim | 6 | 295 | 300 | 9(6) |
Body
Se Código Transação = 10 (RECARGA)
Nome do campo | Descrição | Obrigatório | Tamanho | Pos. Inicial | Pos. Final | Tipo |
---|---|---|---|---|---|---|
IF-COD-CORP | Código da Corporação (Será o código do cliente estabelecido pela Celcoin) | Sim | 4 | 1 | 4 | 9(4) |
IF-NUM-LOTE | Número Lote (Número de sequencial do arquivo iniciando com 00001) | Sim | 5 | 5 | 9 | 9(5) |
IF-DATA-LOTE | Data (AAAAMMDD) (Data do dia que está sendo enviado o arquivo) | Sim | 8 | 10 | 17 | 9(8) |
IF-COD-ARQUIVO | Zeros | Sim | 2 | 18 | 19 | 9(2) |
IF-TIPO-REGISTRO | “MOV” – Movimentação “LIQ” – Liquidação “REC” – Recusa “PRC” – Parcial | Sim | 3 | 20 | 22 | X(3) |
IF-VALOR-TRANS | Valor da Transação | Sim | 12 | 23 | 34 | 9(9)v99 |
IF-COD-TRANS | Código da transação (Será o código estabelecido pela Celcoin). (ver Tabela 1) | Sim | 3 | 35 | 37 | 9(3) |
IF-DATA-TRANS | Data da transação (AAAAMMDD) | Sim | 8 | 38 | 45 | 9(8) |
IF-HORA-TRANS | Hora da transação (HHMMSS) | Sim | 6 | 46 | 51 | 9(6) |
IF-DESCRIÇÃO | Descrição da transação | Sim | 40 | 52 | 91 | X(40) |
IF-COD-AUTORIZ. | O protocolo gerado pelo TodaConta | Sim | 10 | 92 | 101 | 9(10) |
IF-NUM-SEQ-USUARIO | Número da Sequencial da transação do usuário | Sim | 10 | 102 | 111 | 9(10) |
IF-NUM- TERMINALEXTERNO | Número do Terminal Externo | Não | 50 | 112 | 161 | X(50) |
IF-NUM-SEQ-EXTERNO | Número da Sequencial Externo | Não | 20 | 162 | 181 | 9(20) |
IF-COD-PAGTO | Número da Forma de Pagamento (ver Tabela 2) | Não | 2 | 182 | 183 | 9(2) |
IF-NUM-CARTÃO | Número do cartão que efetuou a transação | Não | 19 | 184 | 202 | 9(19) |
IF-QTDE-PARCELAS | Quantidade de parcelas | Não | 2 | 203 | 204 | 9(2) |
IF-NSU_AUTORIZADORA | NSU da Autorização online do Pagamento com cartão | Não | 10 | 205 | 214 | 9(10) |
IF-LD | Linha Digitável | Não | 48 | 215 | 262 | 9(48) |
FILLER | Brancos | Sim | 32 | 263 | 294 | X(32) |
IF-SEQ | Sequencial que indica o número do registro dentro do arquivo. O header deverá ser montado com o sequencial 000001. (Número do registro dentro do arquivo) | Sim | 6 | 295 | 300 | 9(6) |
Trailer
Nome do campo | Descrição | Obrigatório | Tamanho | Pos. Inicial | Pos. Final | Tipo |
---|---|---|---|---|---|---|
IF-COD-CORP | Código da Corporação (Será o código do cliente estabelecido pela Celcoin) | Sim | 4 | 1 | 4 | 9(4) |
IF-NUM-LOTE | Número Lote (Número de sequencial do arquivo iniciando com 00001) | Sim | 5 | 5 | 9 | 9(5) |
IF-DATA-LOTE | Data (AAAAMMDD) (Data do dia que está sendo enviado o arquivo) | Sim | 8 | 10 | 17 | 9(8) |
IF-COD-ARQUIVO | Zeros | Sim | 2 | 18 | 19 | 9(2) |
IF-TIPO- REGISTRO | “TLR” - Trailer | Sim | 3 | 20 | 22 | X(3) |
IF-NUMCONTA | Zeros | Sim | 19 | 23 | 41 | 9(19) |
IF-NUM-REGS | Total de registros no arquivo (a soma de todos os registros incluindo o Header e o Trailler) | Sim | 5 | 42 | 46 | 9(05) |
IF-VALORTOTAL | Valor total de todas as transações em REAL | Sim | 13 | 47 | 59 | 9(11)v99 |
FILLER | Brancos | Sim | 235 | 60 | 294 | x(235) |
IF-SEQ | Sequencial que indica o número do registro dentro do arquivo. O header deverá ser montado com o sequencial 000001 (Número do registro dentro do arquivo) | Sim | 6 | 295 | 300 | 9(6) |
Updated 2 months ago