A solução QRPague utiliza as tecnologias de QRCode e API para implementar operações financeiras de saque, pagamentos e transferência entre instituições distintas, sendo elas financeiras ou não. Esta API fornece um conjunto de serviços de emissão, autorização e confirmação de operações financeiras online. O uso das APIs deve obedecer os fluxos de processo disponíveis no GitHub do projeto para cada natureza de operação (saque, transferência ou pagamento).
- Docker >= 17.12.0-ce
- docker-compose (OPCIONAL) >= 1.21.0
Para rodar o serviço você irá utilizar uma solução de contêiners através de uma imagem Docker.
Em nosso tutorial utilizaremos o docker-compose para facilitar a configuração do ambiente.
- Primeiro faça o download do projeto para sua máquina local, através do comando:
git clone https://github.com/qrpague/qrpague-server.git - Na pasta raiz do projeto, execute um dos seguintes comandos:
docker run -e MONGO_CONNECTION='mongodb://localhost:27017/qrpague' \
-e SERVER_URL='http://127.0.0.1:8080' \
-p 9999:8080 \
--name qrpague-api qrpague/qrpague-api
docker-compose up
docker-compose -f docker-compose-full.yaml up
MONGO_CONNECTION- OBRIGATÓRIA
- Conexão do MongoDB.
SERVER_URL- OBRIGATÓRIA
- URL do serviço de API.
MY_PRIVATE_KEY- OBRIGATÓRIA
- Chave privada assimétrica para assinatura e criptografia.
ERROR_MESSAGE_FILE- OPCIONAL | DEFAULT = Arquivo de template já determinado no projeto
- FilePath do arquivo de mensagens de erro.
INSTITUICOES_FILE- OPCIONAL | DEFAULT = Arquivo de template já determinado no projeto, porém você DEVE substituí-lo
- FilePath do arquivo responsável por carregar as informações das instituições autorizadas pelo QRpague.
- É DESEJÁVEL que você preencha esta variável e substitua o arquivo existente, pois este arquivo possui preenchimento padrão apenas para fins didáticos e ilustrativos.
QRPAGUE_IMAGE_URL- OPCIONAL | DEFAULT = 'https://avatars1.githubusercontent.com/u/43270555?s=460&v=4'
- URL do ícone do QRPague
PORT- OPCIONAL | DEFAULT = 8080
- Porta na qual o serviço irá subir.
NODE_PROJECT- OPCIONAL | DEFAULT = 'QRPAGUE-Service'
- Nome do micro-serviço.
LOG_LEVEL- OPCIONAL | DEFAULT = 'error' | VALUES = (trace, debug, info, warn, error, fatal)
- Level do log.
MONGOOSE_DEBUG- OPCIONAL | DEFAULT = 'false' | VALUES = (true, false)
- Booleano para ativar modo debug do MongoDB.
Na maioria dos projetos de serviços REST, as mensagens de erro não são tratadas com padronização adequada. Para fazer isso, o serviço QRPague fornece um mecanismo de padronização de mensagem de erro baseado na RFC-7807.
OBSERVAÇÕES
- O serviço do QRPague já vem com um arquivo padrão de mensagens de erro, mas você pode substituir este arquivo através da variável de ambiente
ERROR_MESSAGE_FILE. - O arquivo de mensagens de erro serve para a substituição do arquivo padrão no projeto, caso seja necessária a adaptação conforme sua preferência.
- Caso deseje substituir o arquivo, favor seguir orientação no exemplo abaixo:
O arquivo de mensagens precisa ser um arquivo YAML conforme exemplo abaixo:
OBS.: Qualquer formatação divergente ao padrão afetará a subida do serviço.
erros:
- insercao_operacao:
codigoErro: 1000
mensagemErro: Erro de inserção de operação
detalhes:
- erro_ao_salvar:
codigoDetalheErro: 1
detalheErro: A operação ${uuid} não pode ser salva
- operacao_existente:
codigoDetalheErro: 2
detalheErro: A operação ${uuid} já existe e não pode ser incluída novamente
- id_requisicao_existente:
codigoDetalheErro: 3
detalheErro: A operação com a requisição ${idRequisicao} já foi incluída
- Seu arquivo precisa iniciar com uma chave chamada
erros (array)e seus elementos filhos. - Deve existir no arquivo pelo menos um elemento filho de
erros. - Você pode dar o nome que desejar para todos os elementos filhos de erros, de acordo com sua preferência. Em nosso exemplo utilizamos
insercao_operacao. - Dentro do elemento erro
insercao_operacaovocê precisa declarar alguns atributos obrigatórios, como:codigoErro (number): Este campo representa um erro em sua forma mais genérica.mensagemErro (string): Este campo forma uma mensagem de erro genérica.detalhes (array): Cada erro pode ter um array de detalhes.- Deve existir no arquivo pelo menos um elemento filho de
detalhes. - Cada elemento filho de
detalhespode ter um nome conforme sua preferência. - No nosso exemplo os nomes são
erro_ao_salvar,operacao_existenteeid_requisicao_existente. - Os detalhes têm alguns atributos obrigatórios, como:
codigoDetalheErro (number): Este campo representa um erro em sua forma mais específica.detalheErro (string): Este campo forma uma mensagem detalhada do erro.
- Deve existir no arquivo pelo menos um elemento filho de
O serviço QRPague permite a autorização de instituições que podem operar no serviço do QRPague. Para tal efeito foi criado um arquivo de especificação das instituições no formato YAML.
OBSERVAÇÕES
- O serviço do QRPague já vem com um arquivo padrão de instituições, mas você DEVE substituir este arquivo através da variável de ambiente
INSTITUICOES_FILE. - Caso deseje substituir o arquivo, favor seguir orientação no exemplo abaixo:
O arquivo de instituições precisa ser um arquivo YAML conforme exemplo abaixo:
OBS.: Qualquer formatação divergente ao padrão afetará a subida do serviço.
instituicoes:
- sicoob:
nome: Sicoob Confederação
cnpj: 04.891.850/0001-88
chavePublica: /run/secrets/sicoob/sicoob_public.pub
- caixa_economica_federal:
nome: Caixa Econômica Federal
cnpj: 00.360.305/0001-04
chavePublica: /run/secrets/caixa/caixa_public.pub
- banco_do_brasil:
nome: Banco do Brasil
cnpj: 00.000.000/0001-91
chavePublica: /run/secrets/bb/bb_public.pub
- Seu arquivo precisa iniciar com uma chave chamada
instituicoes (array)e seus elementos filhos. - Deve existir no arquivo pelo menos um elemento filho de
instituicoes. - Você pode dar o nome que desejar para todos os elementos filhos de instituicoes, de acordo com sua preferência. Em nosso exemplo utilizamos
sicoob,caixa_economica_federalebanco_do_brasil. - Dentro de cada elemento da instituição, você precisa declarar alguns atributos obrigatórios, como:
nome (string): Este campo representa o nome da instituição.cnpj (string): Este campo representa o CNPJ da instituição.chavePublica (string): Este campo representa a o arquivo onde se encontra a chave pública da instituição.
As mensagens abaixo são tratadas e possuem semântica negocial no serviço QRPague.
- Código de Erro: 1000
- Mensagem de erro: Erro de inserção de operação
| Código de Detalhamento | Detalhe | Http Status Code |
|---|---|---|
| 1 | A operação ${uuid} não pode ser salva | 400 |
| 2 | A operação ${uuid} já existe e não pode ser incluída | 422 |
| 3 | A operação com a requisição ${idRequisicao} já foi incluída | 422 |
- Código de Erro: 2000
- Mensagem de erro: Erro de consulta de operação
| Código de Detalhamento | Detalhe | Http Status Code |
|---|---|---|
| 1 | A operação ${uuid} não existe | 400 |
| 2 | A instituição de cnpj ${cnpj} não está autorizada | 401 |
| 3 | O CNPJ não foi informado | 400 |
- Código de Erro: 6000
- Mensagem de erro: Erro de efetivação de operação
| Código de Detalhamento | Detalhe | Http Status Code |
|---|---|---|
| 1 | A operação ${uuid} não existe | 400 |
| 2 | A operação ${uuid} não pode ser efetivada/rejeitada | 422 |
- Código de Erro: 7000
- Mensagem de erro: Erro de confirmação de operação
| Código de Detalhamento | Detalhe | Http Status Code |
|---|---|---|
| 1 | A operação ${uuid} não existe | 400 |
| 2 | A operação ${uuid} não pode ser confirmada/cancelada | 422 |
- Código de Erro: 3000
- Mensagem de erro: Erro de inserção de pagamento
| Código de Detalhamento | Detalhe | Http Status Code |
|---|---|---|
| 1 | A operação ${uuidOperacao} não existe ou já foi confirmada/cancelada | 422 |
| 2 | A instituição de cnpj ${cnpj} não está autorizada | 401 |
| 3 | O pagamento ${uuid} não pode ser salvo | 400 |
| 4 | O pagamento ${uuid} já existe e não pode ser incluído novamente | 422 |
| 5 | O pagamento com a requisição ${idRequisicao} já foi incluído | 422 |
| 6 | O CNPJ não foi informado | 400 |
- Código de Erro: 4000
- Mensagem de erro: Erro de consulta de pagamento
| Código de Detalhamento | Detalhe | Http Status Code |
|---|---|---|
| 1 | O pagamento ${uuid} não existe ou não pertence ao cnpj ${cnpj} | 400 |
| 2 | A instituição de cnpj ${cnpj} não está autorizada | 401 |
| 3 | O CNPJ não foi informado | 400 |
- Código de Erro: 5000
- Mensagem de erro: Erro de confirmação de pagamento
| Código de Detalhamento | Detalhe | Http Status Code |
|---|---|---|
| 1 | O pagamento ${uuid} não existe | 400 |
| 2 | O pagamento ${uuid} já foi confirmado/cancelado | 422 |
| 3 | O CNPJ não foi informado | 400 |
| 4 | A instituição de cnpj ${cnpj} não está autorizada | 401 |
| 5 | A operação ${uuidOperacao} não existe ou já não pode ser mais utilizada | 422 |
| 6 | O pagamento não pode ser efetuado porque a operação ${uuidOperacao} não é mais válida | 400 |
| 7 | A operação ${uuidOperacao} associada já não pode ser mais utilizada | 400 |
Erros que podem ocorrer nas requisições http.
- Código de Erro: 997000
- Mensagem de erro: Erro na requisição
| Código de Detalhamento | Detalhe | Http Status Code |
|---|---|---|
| 1 | O campo '${campo}' é obrigatório | 400 |
Erros que podem ocorrer com relação ao token JWT.
- Código de Erro: 999000
- Mensagem de erro: Erro no JSON Web Token
| Código de Detalhamento | Detalhe | Http Status Code |
|---|---|---|
| 1 | O token não foi informado | 400 |
| 2 | Assinatura inválida para o token informado | 400 |
| 3 | Houve um erro na decodificação do token | 400 |
| 4 | O token está expirado | 400 |