Introdução à API

Entre em contato com a Equipe de Suporte para criar uma Conta da API e se tornar nosso parceiro.

Autorização

Nesse estágio, presumimos que você seja um parceiro do Bonder e nossa Equipe de Suporte tenha fornecido o nome de Utilizador, a senha e o nome do cliente API.
  • Comando auth
  • Solicitação POST
curl -k -X POST \
-H "Content-Type : application/json" \
-H "Accept : application/json" \
-d '{
  "username" : "USERNAME",
  "password" : "PASSWORD",
  "client" : "API_CLIENT_NAME",
  "rpt" : "10000"
}' \
"https:// {{API_URL}} /auth" \
Parâmetros de autorização
Parâmetro
Tipo
Descrição
username
string
nome de Utilizador API
password
string
senha API
client
string
nome do cliente API
rpt
integer
número de solicitações por token (RPT – Requests Per Token) rpt<1000, 100000>
Sucesso HTTP/1.1 200 OK
{
  "success" : true,
  "errors" : [],
  "result" : {
    "token" : "access_token",
    "expire" : "1614446080"
  }
}
Resposta
Parâmetro
Tipo
Descrição
token
string
seu token
expire
integer
registro de data e hora da data de validade do token expire=time()+3600
As variáveis expire e rpt estão em disputa. Aquele que atingir o valor alvo primeiro desativará o token.
Fracasso HTTP/1.1 200 OK
{
  "success" : false,
  "errors" : [erro-de-código],
  "result" : {}
}
erro-de-código
Erro
Descrição
INVALID_CREDENTIALS_ERROR
Senha inválida, e-mail inválido ou a Conta foi excluída ou não existe
SERVER_OFFLINE_ERROR
O servidor está offline devido a trabalhos de manutenção pendentes.
Possível atualização de software
  • Sugestões: tente novamente em 45 a 60 minutos
AUTH_SERVICE_OFFLINE_ERROR
O serviço de autenticação está temporariamente indisponível para todos os Utilizadores.
Possível atualização de software
  • Sugestões: tente novamente em 45 a 60 minutos
API_SERVICE_OFFLINE_ERROR
O serviço API está temporariamente indisponível.
Possível atualização de software
  • Sugestões: tente novamente em 45 a 60 minutos
ACCOUNT_INACTIVE_ERROR
A Conta API está suspensa ou deve ser excluída
  • Sugestões: entre em contato com a Equipe de Suporte
INTERNAL_SERVER_ERROR
Erro do servidor interno
  • Sugestões: tente novamente
DATABASE_ERROR
Erro de conexão com o banco de dados
  • Sugestões: tente novamente

Estrutura de dados

Antes de passarmos para outros comandos, explicaremos a estrutura de dados usada pelo Bonder.

Tipos de dados

tipos de dados
Tipo
Descrição
multilíngue
devem ser salvos separadamente em cada idioma
não traduzível
são armazenados em uma tabela separada e adicionados ao Cartão de Visita em cada idioma
Por exemplo: Se você alterar um valor não traduzível, como email ou mobile, todas as versões de idioma do Cartão de Visita serão atualizadas.

Modos de Cartão de Visita

Devido ao fato que seu cliente pode não ser uma pessoa física, mas uma empresa, por exemplo, Serviços-odontológicos-totalmente-não-assustadores, criamos a variável de nível superior - displayName. Se !empty(displayName), o Cartão de Visita funcionará no modo comercial e as variáveis de name lastname position serão omitidas ao gerar o Cartão de Visita (no entanto, o servidor ainda manterá os valores).
modos de Cartão de Visita
Modo
Condição
comercial
if (!empty(displayName)) {
 businessMode = TRUE
}
pessoal
if (empty(displayName)) {
 businessMode = FALSE
}
Na versão em inglês, a variável displayName possui um valor atribuído para que o servidor mantenha os dados; no entanto, o name lastname position será ignorada ao gerar o Cartão de Visita. "en" : {
  "displayName" : "Non-scary-dental-services",
  "name" : "John",
  "lastname" : Kowalski",
  "position" : "CEO"
},
Na versão polonesa, o nome de Jan Kowalski (na posição de Presidente) será exibido. "pl" : {
  "displayName" : "",
  "name" : "Jan",
  "lastname" : "Kowalski",
  "position" : "Prezes"
},
A versão russa não estará disponível para download, apesar de armazenar uma parte dos dados no servidor. "ru" : {
  "displayName" : "",
  "name" : "",
  "lastname" : "Ковалский",
  "position" : "Директор"
}

Variáveis

Cada variável precisa ser validada preliminarmente antes de enviá-la ao servidor. Se o valor da variável enviada não estiver alinhado com a expressão regular atribuída a ela, o servidor a atribuirá com null e, apesar disso, enviará a resposta positiva success=true sobre o salvamento de dados.
Variáveis
Nome
Tipo
Multilíngue
Descrição
name
string
nome
  • necessário para gerar o Cartão de Visita no modo pessoal
  • salvo e ignorado no modo comercial
  • /^[a-zA-Z0-9]{2,25}$/
lastname
string
sobrenome
  • salvo e ignorado no modo comercial
  • salvo e ignorado no modo comercial
  • /^[a-zA-Z0-9]{32,128}$/
displayName
string
nome exibido
  • necessário para gerar o Cartão de Visita no modo comercial
  • /^[a-zA-Z0-9]{32,128}$/
company
string
nome da empresa
  • /^[a-zA-Z0-9]{32,128}$/
position
string
posição
  • salvo e ignorado no modo comercial
  • /^[a-zA-Z0-9]{32,128}$/
keywords
string
palavras-chave que melhor descrevem uma determinada pessoa ou empresa
  • vírgula como separador
  • /^[a-zA-Z0-9]{1,150}$/
thumbnail
string
foto ou logo do utilizador exibido em um dispositivo móvel
  • imagem codificada em base64
  • tamanho fixo 300px x 300px
  • tamanho máximo do ficheiro 50kB
phoneA
string
número de telefone
  • zeros à esquerda e caracteres não numéricos serão cortados
  • o cliente deve fornecer o código do país
  • deve-se adicionar "+" no começo
  • /^[a-zA-Z0-9]{32,128}$/
phoneB
string
como acima
mobileA
string
número de celular
  • zeros à esquerda e caracteres não numéricos serão cortados
  • o cliente deve fornecer o código do país
  • deve-se adicionar "+" no começo
  • /^[a-zA-Z0-9]{32,128}$/
mobileB
string
como acima
skypeA
string
nome de utilizador do skype
  • /^[a-zA-Z0-9]{32,128}$/
skypeB
string
como acima
faxA
string
número de fax
  • zeros à esquerda e caracteres não numéricos serão cortados
  • o cliente deve fornecer o código do país
  • deve-se adicionar "+" no começo
  • /^[a-zA-Z0-9]{32,128}$/
faxB
string
como acima
emailA
string
e-mail
emailB
string
como acima
webA
string
URL
  • /^[a-zA-Z0-9]{32,128}$/
webB
string
como acima
webC
string
como acima
addrStreet
string
endereço - rua
  • /^[a-zA-Z0-9]{32,128}$/
addrCity
string
endereço - cidade
  • /^[a-zA-Z0-9]{32,128}$/
addrState
string
endereço - província / estado
  • /^[a-zA-Z0-9]{32,128}$/
addrZip
string
endereço - código postal
  • /^[a-zA-Z0-9]{32,128}$/
addrCountry
string
endereço - país
  • /^[a-zA-Z0-9]{32,128}$/

parâmetros

Parâmetros
Variável
Tipo
Descrição
langStatus
integer
0 = off, 1 = on
Ativar / desativar a versão do idioma sem excluir dados
  • default = 0
usePhoto
integer
0 = off, 1 = on
Ativar / desativar a foto sem excluí-la
  • default = 1
cardStatus
integer
0 = off, 1 = on
Ativar / desativar o Cartão de Visita sem excluí-lo
  • default = 1

Suporte de línguas

O Bonder permite que seus Utilizadores criem Cartões de Visita em mais de 60 idiomas e essa funcionalidade importante também está disponível para Utilizadores API. Para sua conveniência, preparamos repositórios com códigos de idioma traduzidos suportados pelo Bonder, que você pode usar ao criar seu próprio aplicativo. Usamos a variável lang para gerenciar versões de idiomas. Você o usará para adicionar, editar e excluir versões de idiomas.
  • Comando repositories
  • Solicitação GET
curl -k -X GET \
-H "X-Auth-Key : {{access_token}}" \
-H "X-Auth-Email : {{username}}" \
-H "Content-Type : application/json" \
-H "Accept : application/json" \
"https:// {{API_URL}} /repositories \
Sucesso HTTP/1.1 200 OK
{
  "success": true,
  "errors" : [],
  "result" : {
    "langList" : [local, lang]
  }
}
langList
valor
Tipo
Descrição
lang
string
código de idioma compatível com ISO 639-1:2002
local
string
lista de nomes de idiomas locais, por exemplo: en => English, ru => Русский
Exemplo de resposta O servidor retorna a lista de recursos disponíveis: local, inglês, russo, polonês, chinês HTTP/1.1 200 OK
{
  "success": true,
  "errors" : [],
  "result" : {
    "langList" : ["local", "en", "ru", "pl", "zh"]
  }
}
Use os valores de langList para baixar os recursos necessários. A resposta sempre estará na forma da chave : valor.

Baixe a lista de nomes de idiomas locais

  • Comando repositories
  • Solicitação GET
curl -k -X GET \
-H "X-Auth-Key : {{access_token}}" \
-H "X-Auth-Email : {{username}}" \
-H "Content-Type : application/json" \
-H "Accept : application/json" \
"https:// {{API_URL}} /repositories/local" \
Sucesso HTTP/1.1 200 OK
{
  "success": true,
  "errors" : [],
  "result" : {
    "pl" : "Polski",
    "en" : "English",
    "ru" : "Русский",
    ...,
    "chave" : "valor"
 }
}

Baixar nomes de idiomas traduzidos

  • Comando repositories
  • Solicitação GET
Altere a consulta acima, de acordo com o exemplo abaixo: "https:// {{API_URL}} /repositories/ru" \
"https:// {{API_URL}} /repositories/en" \
Se não tivermos um recurso que você procura em nossos repositórios, informe a Equipe de Suporte sobre isso. Vamos preencher as lacunas o mais rápido possível. Se você não puder esperar por nossa resposta, sugerimos fazer o download dos códigos de idioma disponíveis e preparar suas próprias traduções.
Fracasso HTTP/1.1 200OK
{
  "success" : false,
  "errors" : [erro-de-código],
  "result" : {}
}
erro-de-código
Erro
Descrição
INVALID_CREDENTIALS_ERROR
Senha ou e-mail inválido ou token inválido
  • Sugestões: repetir autenticação
RESOURCE_NOT_FOUND_ERROR
O recurso que você está procurando não existe
  • Sugestões: verifique a consulta
outros
consulte CÓDIGO-DE-ERRO na seção Autorização

Criando um novo Perfil

  • Comando users
  • Solicitação post
curl -k -X POST \
-H "X-Auth-Key : {{access_token}}" \
-H "X-Auth-Email : {{username}}" \
-H "Accept : application/json" \
"https:// {{API_URL}} /users" \
Sucesso HTTP/1.1 200 OK
{
  "success": true,
  "errors" : [],
  "result" : {
    "cardId" : string,
    "cardQrc" : string,
    "cardAddr" : string (url)
  }
}
RESULTADOS DA BUSCA
Variável
Tipo
Descrição
cardId
string
identificador de Cartão de Visita de um Perfil criado
  • diferencia maiúsculas e minúsculas
  • /^[a-zA-Z0-9]{32,128}$/
cardAddr
string
endereço de um Cartão de Visita criado
cardQrc
string
o código QR do endereço do Cartão de Visita codificado em base64
As variáveis cardId cardQrc cardAddr devem ser armazenadas localmente no seu servidor e atribuídas a um determinado Perfil. A variável cardId é necessária para a comunicação correta com a API.
Fracasso HTTP/1.1 200 OK
{
  "success" : false,
  "errors" : [erro-de-código],
  "result" : {}
}
erro-de-código
Erro
Descrição
INVALID_CREDENTIALS_ERROR
Senha ou e-mail inválido ou token inválido
  • Sugestões: repetir autenticação
PROFILE_LIMIT_REACHED_ERROR
Limite de Perfil atingido
  • Sugestões: entre em contato com a Equipe de Suporte para alterar as Configurações da Conta
outros
consulte CÓDIGO-DE-ERRO na seção Autorização

Salvamento de dados

  • Nós não usamos consultas fixas. Envie apenas os dados que precisam ser atualizados.
  • Use o comando PUT para criar um novo Perfil.
  • Adicione um idioma usando as teclas lang na seção translatable.
  • Se um cliente não quiser especificar uma versão do idioma, defina llang=un, que significa universal.
  • Modifique até cinco idiomas em uma consulta (atualização, adição). Versões de idiomas acima de 5 serão ignoradas.
  • Comando users
  • Solicitação put
curl -k -X PUT \
-H "X-Auth-Key : {{access_token}}" \
-H "X-Auth-Email : {{username}}" \
-H "Content-Type : application/json" \
-H "Accept : application/json" \
-d ' {
Quando cardStatus=0, o Cartão de Visita será desativado e não será possível baixá-lo.   "settings" : {
    "cardStatus" : "0",
    "usePhoto" : "1"
  },
  "translatable" : {
Use langStatus para ativar e desativar idiomas.     "pl" : {
      "name" : "John",
      "lastname" : "Connor",
      "position" : "Dyrektor Zarządzający"
    },
Ao adicionar um novo idioma, define-se langStatus=0 por padrão. Você pode ignorar essa configuração atribuindo langStatus=1 ao adicionar um idioma.     "en" : {
      "name" : "John",
      "lastname" : "Connor",
      "position" : "Managing Director",
      "displayName" : "The Great John Connor",
      "keywords" : "steel, steel pipe, tubular products"
    },
Apesar definir langStatus=1, um determinado idioma não estará pronto para download até que a condição (name!=null && lastname!=null) || displayName!=null seja atendida.     "es" : {
      "langStatus" : "1",
      "name" : "John",
      "position" : "Director Ejecutivo"
    },
    "pt" : {
      "langStatus" : "1",
      "name" : "John",
      "lastname" : "Connor",
    },
    "ru" : {
      "langStatus" : "1",
      "name" : "",
      "lastname" : "Коннор",
    },
    "zh" : {
      "position" : "首席执行官"
    }
  },
  "non-translatable" : {
    "thumbnail" : "base64_encoded_image",
    "mobileA" : "123456789",
    "emailB" : "[email protected]"
  }
} ' \
"https:// {{API_URL}} /users/{{card_id}} \
Sucesso HTTP/1.1 200 OK
{
  "success": true,
  "errors" : [erro-de-código],
  "result" : {}
}
Apesar de retornar success=true, o servidor pode relatar um erro se você adicionar uma foto de perfil à sua consulta.
erro-de-código
Erro
Descrição
THUMBNAIL_REJECTED_ERROR
Os dados foram salvos, no entanto, a imagem enviada foi rejeitada pelo servidor
  • Sugestões: valide seu gerador de imagens
Fracasso HTTP/1.1 200 OK
{
  "success" : false,
  "errors" : [erro-de-código],
  "result" : {}
}
erro-de-código
Erro
Descrição
INVALID_CREDENTIALS_ERROR
Senha ou e-mail inválido ou token inválido
  • Sugestões: repetir autenticação
CARD_ID_NOT_FOUND_ERROR
O Cartão de Visita cardId não existe ou você não possui autorizações para modificar este recurso
  • Sugestões: verifique a consulta
outros
consulte CÓDIGO-DE-ERRO na seção Autorização

Modificando configurações

Parâmetros
Parâmetro
Tipo
Descrição
status
string
<enable, disable>

Alteração do status do Cartão de Visita

  • Comando users
  • Solicitação put
curl -k -X PUT \
-H "X-Auth-Key : {{access_token}}" \
-H "X-Auth-Email : {{username}}" \
-H "Content-Type : application/json" \
-H "Accept : application/json" \
https:// {{API_URL}} /users/{{card_id}}/cardStatus/{{status}}

Alteração do status da foto

  • Comando users
  • Solicitação put
curl -k -X PUT \
-H "X-Auth-Key : {{access_token}}" \
-H "X-Auth-Email : {{username}}" \
-H "Content-Type : application/json" \
-H "Accept : application/json" \
https:// {{API_URL}} /users/{{card_id}}/usePhoto/{{status}}

Alteração do status do idioma

  • Comando users
  • Solicitação put
curl -k -X PUT \
-H "X-Auth-Key : {{access_token}}" \
-H "X-Auth-Email : {{username}}" \
-H "Content-Type : application/json" \
-H "Accept : application/json" \
https:// {{API_URL}} /users/{{card_id}}/langStatus/{{lang}}/{{status}}
Sucesso HTTP/1.1 200 OK
{
  "success" : true,
  "errors" : [],
  "result" : {}
}
Fracasso HTTP/1.1 200 OK
{
  "success" : false,
  "errors" : [erro-de-código],
  "result" : {}
}
erro-de-código
Erro
Descrição
todos
consulte CÓDIGO-DE-ERRO na seção Salvamento de dados

Baixando dados

  • Comando users
  • Solicitação get
curl -k -X GET \
-H "X-Auth-Key : {{access_token}}" \
-H "X-Auth-Email : {{username}}" \
-H "Content-Type : application/json" \
-H "Accept : application/json" \
"https:// {{API_URL}} /users/{{card_id}}" \
Sucesso HTTP/1.1 200 OK
{
"success": true,
"errors" : [],
"result" : {
  "translatable" : {
    "lang" : {
      "langStatus" : "1",
      "chave" : "valor"
    },
    "lang" : {
      "langStatus" : "0",
      "chave" : "valor"
    }
  },
  "non-translatable" : {
    "thumbnail" : "base64_encoded_image",
    "chave" : "valor"
  },
  "settings" : {
    "cardStatus" : "1",
    "usePhoto" : "1",
    "cardQrc" : "base64_encoded_image",
    "cardAddr" : "URL",
    "usePhoto" : "1"
  }
}
Fracasso HTTP/1.1 200 OK
{
  "success" : false,
  "errors" : [erro-de-código],
  "result" : {}
}
erro-de-código
Erro
Descrição
INVALID_CREDENTIALS_ERROR
Senha ou e-mail inválido ou token inválido
  • Sugestões: repetir autenticação
CARD_ID_NOT_FOUND_ERROR
O Cartão de Visita cardId não existe ou você não possui autorizações para modificar este recurso
  • Sugestões: verifique a consulta
outros
consulte CÓDIGO-DE-ERRO na seção Autorização

Exclusão de dados

Exclusão de idioma

  • Comando users
  • Solicitação delete
curl -k -X DELETE \
-H "X-Auth-Key : {{access_token}}" \
-H "X-Auth-Email : {{username}}" \
-H "Content-Type : application/json" \
-H "Accept : application/json" \
"https:// {{API_URL}} /users/{{card_id}}/{{lang}}" \

Exclusão de Perfil

  • Comando users
  • Solicitação delete
curl -k -X DELETE \
-H "X-Auth-Key : {{access_token}}" \
-H "X-Auth-Email : {{username}}" \
-H "Content-Type : application/json" \
-H "Accept : application/json" \
"https:// {{API_URL}} /users/{{card_id}}" \
Sucesso HTTP/1.1 200 OK
{
  "success" : true,
  "errors" : [],
  "result" : {}
}
Fracasso HTTP/1.1 200 OK
{
 "success" : false,
 "errors" : [erro-de-código],
 "result" : {}
}
erro-de-código
Erro
Descrição
INVALID_CREDENTIALS_ERROR
Senha ou e-mail inválido ou token inválido
  • Sugestões: repetir autenticação
CARD_ID_NOT_FOUND_ERROR
O Cartão de Visita cardId não existe ou você não possui autorizações para modificar este recurso
  • Sugestões: verifique a consulta
outros
consulte CÓDIGO-DE-ERRO na seção Autorização
Página anterior