Visão geral da API v2
A API da Web3Card permite que os seus próprios sistemas operem o seu programa de cartões por código: usuários, verificação de identidade, as contas que abastecem os cartões, os cartões em si, transações e eventos.
A API cobre o programa de cartões. Acesso à conta, equipe, marca e domínio são cuidados no painel Business e não fazem parte dela.
A API v2 está desenhada e ainda não foi construída. Nenhuma rota está publicada. Esta página descreve o que a API é e os princípios que ela segue, e os detalhes ainda podem mudar. A referência completa, com cada rota, pedido e resposta, será publicada neste capítulo quando a primeira versão puder ser testada.
Uma API para o seu programa
A Web3Card funciona como um hub ligado a vários parceiros emissores de cartão. Um programa pode rodar em um parceiro ou em mais de um.
Você integra uma vez, com uma API. Usuários, cartões e transações têm o mesmo formato seja qual for a instituição por trás.
Nem toda função existe em todo programa. Funções como limite de gasto por cartão, ou devolver saldo do cartão para a conta, dependem do parceiro por trás do programa. A API diz quais funções o seu programa tem e responde com um erro próprio quando você chama uma que ele não tem.
Princípios do desenho
Estes são os princípios sobre os quais a API foi desenhada.
| Princípio | O que significa para a sua integração |
|---|---|
| Operações assíncronas | Um pedido que cria ou altera algo na instituição parceira, como pedir ou congelar um cartão, devolve uma operação, que você acompanha até terminar. Pedidos que não dependem do parceiro respondem na hora |
| Repetição segura | Todo pedido de escrita leva uma chave escolhida por você. Mandar o mesmo pedido duas vezes com a mesma chave nunca repete o efeito |
| Eventos assinados | A plataforma avisa o seu sistema quando algo acontece, como um cartão ficar ativo ou uma compra ser feita. Cada aviso é assinado, para você confirmar que veio da plataforma |
| O mesmo modelo em todo programa | Usuários, cartões e transações têm o mesmo formato e os mesmos estados em todos os programas |
| Dados do cartão protegidos | A plataforma não guarda número completo de cartão, código de segurança nem PIN |
O que a API vai cobrir
| Área | O que você vai fazer com ela |
|---|---|
| Usuários | Criar e consultar os usuários do seu programa |
| Verificação de identidade | Iniciar a verificação de um usuário e acompanhar o resultado |
| Produtos | Listar os produtos de cartão disponíveis no seu programa |
| Contas de saldo | Criar a conta que abastece os cartões, acompanhar o saldo, depositar e sacar |
| Cartões | Pedir, congelar, descongelar e encerrar cartões |
| Recarga e retirada | Mover saldo da conta para um cartão e de um cartão de volta para a conta |
| Limites e controles de gasto | Definir limites e restringir tipos de loja, onde o programa tiver |
| Dados do cartão | Obter os dados completos de um cartão para mostrar ao titular, por um pedido de uso único |
| Códigos de verificação | Receber o código que a loja pede em uma compra online |
| Operações | Acompanhar cada pedido que você fez até ele terminar |
| Transações | Listar compras, estornos, depósitos e recargas |
| Eventos | Receber avisos nos seus próprios sistemas |
| Simulação | Gerar compras, estornos e liquidações de teste |
A lista pode mudar antes de a referência ser publicada.
O que vem a seguir neste capítulo
- Autenticação e ambientes
- Convenções: pedidos, respostas, erros e repetição
- A referência de cada área acima
- Eventos e como conferir a assinatura
- Guias passo a passo dos fluxos mais comuns
Cada item é publicado quando puder ser testado.