Introdução ao Registro de Redes

Introdução

As APIs de rede são destinadas a empresas, e não a pessoas físicas, amadores ou desenvolvedores independentes. Portanto, antes de realizar chamadas às APIs de rede, você deve enviar o perfil da sua empresa para aprovação pelos Provedores de Serviços de Comunicação (CSPs) a fim de obter acesso. Para agilizar esse processo, a Vonage cuida do registro junto a vários CSPs nos bastidores para todas as APIs de rede compatíveis em qualquer país onde os serviços da Vonage estejam disponíveis.

O processo de aprovação consiste em duas etapas:

1. Crie um perfil empresarial.

2. Crie um perfil de aplicativo.

Ambas as etapas podem ser concluídas por meio do Registro de Rede da Vonage, seja a partir painel de controle ou por meio da API.

Pré-requisitos

Este tutorial pressupõe que você já tenha um Account na Vonage. Caso ainda não tenha um, você pode criar um aqui. 

Painel de controle do Registro de Rede

É possível acessar o Registro de Rede pelo painel do usuário. Faça login na sua conta da Vonage e, abaixo da imagem do seu avatar, no lado direito do portal, clique em “Meu painel”. Use o menu de navegação à esquerda para localizar a seção “Criar e gerenciar”. Em seguida, clique em Registro -> Registro de Rede.

Criar um perfil empresarial

O perfil da empresa inclui informações jurídicas sobre a sua empresa. Clique em “Adicionar perfil empresarial” e preencha o formulário fornecendo as seguintes informações sobre sua organização:

• País — onde seus usuários finais podem acessar suas Applications.

• Função — sua função na organização.

• Nome da empresa — o nome da pessoa jurídica proprietária das Applications que utilizarão as APIs da Rede Vonage.

• Tipo de organização — selecione o tipo mais adequado na lista suspensa.

• Endereço e país de registro da empresa — o endereço e o país onde sua organização está registrada.

• Número de identificação fiscal da empresa — sua referência fiscal utilizada pela Vonage e seus CSPs para validar sua organização.

• URL da política de privacidade — A Vonage e seus CSPs exigem que qualquer pessoa que utilize as APIs de rede tenha uma política de privacidade disponível publicamente na Internet. Forneça a URL da sua política.

• Endereço de e-mail do responsável pela política de privacidade — inclua um endereço de e-mail que possa ser utilizado para quaisquer dúvidas sobre sua política de privacidade.

• Endereço de e-mail do Encarregado da Proteção de Dados (DPO) — isso se aplica apenas caso você seja obrigado por lei a ter um.

New Business Profile

Após o envio, você verá um resumo do perfil da sua empresa. Esse resumo ajuda você a acompanhar o status do seu cadastro. Você receberá notificações por e-mail sempre que o status do seu cadastro for alterado.

As respostas do CSP aos pedidos de aprovação são assíncronas e podem ser recebidas pelo Registro de Rede da Vonage em momentos diferentes.

Criar um perfil de aplicativo

Os perfis de aplicação são utilizados para descrever um caso de uso específico, incluindo quais APIs de rede são necessárias e para que finalidade serão utilizadas. Eles serão compartilhados com os CSPs nos países incluídos no perfil de negócios associado.

Acesse a entrada “Registro de Rede” no menu de navegação à esquerda, clique no nome do perfil da empresa e, em seguida, selecione “Adicionar perfil de aplicativo”. Será exibido um formulário no qual você precisará fornecer mais informações sobre o tipo de aplicativo que está desenvolvendo:

• Nome do perfil - Dê um nome ao perfil do seu aplicativo para facilitar a identificação.

• Categoria - Selecione uma categoria de aplicativo na lista suspensa.

• Locais de infraestrutura — Especifique os países onde você poderá processar dados pessoais relacionados ao uso das APIs de rede solicitadas

• APIs de rede — Selecione as APIs de rede que você deseja utilizar.

• Finalidade — Para cada API de rede selecionada, confirme a finalidade na lista suspensa, por exemplo, “Prevenção e detecção de fraudes”.

• Descrição do caso de uso: Descreva seu aplicativo do ponto de vista do consumidor.

New Application Profile

Após o envio, você receberá um resumo do seu perfil de inscrição. Você receberá notificações por e-mail sempre que houver uma alteração no status da sua inscrição.

Acompanhando meu envio

Você pode acompanhar o andamento do processo de aprovação do perfil da sua inscrição. Acesse a entrada “Registro de Rede” no menu de navegação à esquerda e clique no seu perfil empresarial. A página de visão geral do perfil empresarial será exibida. Nessa página, expanda a seção “Perfis de Applications” na parte inferior da página. Será exibida uma lista de CSPs dos países que você selecionou durante a criação do seu perfil empresarial, juntamente com seus status de aprovação. 

Network APIs Submission Status

API do Registro de Rede

A API do Registro de Rede permite que os desenvolvedores enviem perfis de negócios e de aplicativos por meio de programação. Isso é particularmente útil quando diferentes equipes dentro da sua organização utilizam as APIs de Rede, permitindo que cada equipe crie e utilize perfis de aplicativos distintos, conforme necessário, por meio de processos internos.

Autenticação

Todas as chamadas à API do Network Registry exigem autenticação para serem concluídas. A autenticação é baseada na chave e no segredo da API, que podem ser encontrados na página de visão geral do seu painel e serão enviados na URL. 

API Key Secret

Aviso: Suas credenciais de API são confidenciais e destinam-se exclusivamente ao uso pessoal. Não as compartilhe com ninguém.

Perfis de Empresas

O /business-profile endpoint é utilizado para todas as operações relacionadas a perfis de negócios: criar, recuperar, excluir, etc.

Para criar um novo perfil empresarial, precisamos enviar uma solicitação POST . O corpo da chamada conterá as mesmas informações solicitadas pelo painel do Registro de Rede (função, país, número de identificação fiscal etc.).

O exemplo a seguir usa o cURL para criar um novo perfil de empresa chamado “Meu perfil de empresa”, solicitando acesso a operadoras na Espanha e na Alemanha:

curl -X POST "http://api-eu.vonage.com/v1/network-registry/business-profiles" \
-H "Content-Type: application/json" \
-u ${API_Key}:${API_Password} \
-d '{
  "contact_role":"developer",
  "name":"my business profile",
  "organisation_type":"forProfitOrganisation",
  "country":"ES",
  "tax_number":"1234567890",
  "privacy_policy_url":"https://1LThiQzd.com",
  "privacy_policy_manager_email":"manager@test.com",
  "dpo_email":"dpo@test.com",
  "dpo_required":true,
  "countries":[
    "ES",
    "DE"
  ],
  "business_information":{
    "address_street_1":"address 1",
    "address_street_2":"address 2",
    "city":"Madrid",
    "province":"Madrid",
    "postal_code":"28020",
    "country":"ES"
  },
  "email_notifications_enabled":true,
  "terms_and_conditions_accepted":true
}'

Poderíamos enviar uma solicitação GET para recuperar uma lista de perfis de empresas e monitorar seu status:

curl "http://api-eu.vonage.com/v1/network-registry/business-profiles" -u ${API_Key}:${API_Password}

Também é possível recuperar as informações do perfil comercial de um determinado CSP enviando um solicitação GET para o /business-profile/{id}/csps ponto de extremidade:

curl "http://api-eu.vonage.com/v1/network-registry/business-profiles/0934561-99ce-123/csps" -u ${API_Key}:${API_Password}

Caso queiramos modificar um perfil de empresa, podemos enviar uma solicitação PUT para a rota /change-request

curl -X PUT "http://api-eu.vonage.com/v1/network-registry/business-profiles/0934561-99ce-123/change-request" \
-H "Content-Type: application/json" \
-u ${API_Key}:${API_Password} \
-d '{
   "countries": [
      "ES"
   ],
   "contact_role": "A Business Profile",
   "name": "A Business Profile",
   "trading_name": "A Business Profile Ltd.",
   "organisation_type": "For-Profit Organisation",
   "tax_number": "98284687G",
   "privacy_policy_url": "https://www.businessinc.com/privacy_policy",
   "privacy_policy_manager_email": "privacy.manager@business.com",
   "dpo_email": "dpo@business.com",
   "dpo_required": true,
   "terms_and_conditions_accepted": true,
   "business_information": {
      "address_street_1": "Main Street 5",
      "address_street_2": "Extra long address",
      "postal_code": "W1 5DU",
      "country": "UK",
      "city": "London",
      "province": "City of London"
   },
   "email_notifications_enabled": true
}'

Por fim, poderíamos excluir um perfil comercial existente executando este comando:

curl -X DELETE "http://api-eu.vonage.com/v1/network-registry/business-profiles/0934561-99ce-123

Perfil da aplicação

Da mesma forma que nos perfis de negócios, podemos usar o /application-profiles ponto de extremidade para realizar todas as operações relacionadas aos perfis de aplicativos.

O exemplo a seguir envia uma solicitação POST para criar um novo perfil de aplicativo:

curl -X POST "http://api-eu.vonage.com/v1/network-registry/application-profiles" \
-H "Content-Type: application/json" \
-u ${API_Key}:${API_Password} \
-d '{
   "business_profile_id": "string",
   "name": "Network Application Profile",
   "description": "This is an example use case for Fraud Prevention",
   "category_id": "finance",
   "network_apis": [
      {
         "network_api_id": "sim-swap",
         "purpose_ids": [
            "FraudPreventionAndDetection"
         ]
      }
   ],
   "terms_and_conditions_accepted": true,
   "infrastructure_locations": [
      "ES"
}'

Poderíamos recuperar uma lista de perfis de aplicativos enviando uma solicitação GET. Poderíamos filtrar o resultado enviando parâmetros de consulta como status (pendente, aceito, rejeitado etc.) ou business_profile_id, para obter perfis de aplicativos de um perfil de negócios específico.

curl "http://api-eu.vonage.com/v1/network-registry/application-profiles" -u ${API_Key}:${API_Password}

A Referência da API contém uma descrição detalhada das demais operações.

Mais operações

Além das operações para gerenciar perfis de negócios e de Applications, a API do Registro de Redes oferece pontos de extremidade úteis para trabalhar com outros recursos, como países, APIs de rede compatíveis ou tipos de organização.

Para obter uma lista dos países compatíveis, poderíamos enviar uma solicitação GET como nesta exemplo:

curl "http://api-eu.vonage.com/v1/network-registry/catalogue/countries" -u ${API_Key}:${API_Password}

Da mesma forma, ao enviar uma solicitação GET para a /network-api , poderíamos recuperar uma lista das APIs de rede compatíveis:

curl "http://api-eu.vonage.com/v1/network-registry/catalogue/network-apis" -u ${API_Key}:${API_Password}

O catálogo seção da Referência da API contém uma lista de recursos que podem ser acessados por meio de /catálogo .

E agora?

Assim que sua inscrição for aprovada por pelo menos um de seus CSPs, você poderá vinculá-la a um ou mais aplicativos da Vonage para começar a usar as APIs de rede. O aplicativo da Vonage contém as credenciais necessárias para realizar chamadas de API.

Entre em contato

Adoraríamos receber seu contato! Participe da canal da Comunidade Vonage no Slack para compartilhar suas experiências com o Network Registry. Você também pode seguir a equipe de Experiência do Desenvolvedor da Vonage no X, anteriormente conhecido como Twitter.