Referência da API
A API da Web3Card é uma API REST sobre HTTPS, com corpo de pedido e de resposta em JSON.
Esta página faz parte da referência da primeira versão da API da Web3Card, mantida aqui para consulta. A API v1 não recebe integrações novas: a API v2 a substitui, e a plataforma hoje funciona como descrito no resto deste manual.
URL base
https://api.web3card.dev/v1
Autenticação
Todos os endereços de parceiro pedem a sua chave de API como token Bearer:
Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx
As sessões do usuário final (para ações assinadas pela carteira do portador) usam o Sign-In with Ethereum por cima da chave de parceiro. Veja Autenticação.
Ambientes
| Ambiente | Prefixo da chave | Comportamento |
|---|---|---|
| Produção | w3c_live_ | Cartões de verdade, cofres na mainnet |
| Sandbox | w3c_test_ | Cartões de teste, cofres em testnet, autorizações simuladas |
Erros
Os erros usam os códigos HTTP de costume e um corpo sempre igual:
{
"error": {
"code": "insufficient_balance",
"message": "Vault balance does not cover the requested amount.",
"requestId": "req_b81f2c"
}
}
| Código | Significado |
|---|---|
400 | Corpo ou parâmetros inválidos |
401 | Chave de API ausente ou inválida |
403 | Chave válida, mas sem permissão para este recurso |
404 | Recurso não encontrado |
409 | Conflito com a situação do recurso (ex.: ativar um cartão anulado) |
429 | Limite de chamadas atingido |
5xx | Erro da plataforma; pode repetir com intervalo crescente |
Mande o requestId quando falar com o suporte sobre uma chamada específica.
Paginação
Os endereços de lista devolvem páginas com um cursor opaco:
GET /transactions?limit=50&cursor=eyJvZmZzZXQiOjUwfQ
{ "data": [ … ], "nextCursor": "eyJvZmZzZXQiOjEwMH0" }
nextCursor vem null na última página.
Idempotência
Mande o cabeçalho Idempotency-Key em todo POST que você possa repetir. Duas chamadas com a mesma chave devolvem o mesmo resultado e criam no máximo um recurso.