Habilitando e Utilizando a API do eDirectory

Introdução

A API do eDirectory permite que aplicativos e serviços externos recuperem dados compatíveis do seu site eDirectory e os integrem a outros sistemas. Ela pode ser utilizada para finalidades como obter informações de anúncios, criar integrações com aplicativos externos e desenvolver soluções personalizadas que interajam com os endpoints disponibilizados pelo eDirectory.

Este artigo explica como habilitar a API do eDirectory, acessar sua documentação, entender seus métodos de autenticação e identificar seus recursos e limitações atuais.

Antes de desenvolver uma integração, é importante revisar os endpoints disponíveis e confirmar se a API oferece suporte às operações necessárias para o seu aplicativo.

1. Entendendo a API do eDirectory

A API do eDirectory permite acessar funcionalidades e dados específicos por meio de endpoints documentados. Atualmente, a API pública é projetada principalmente para a recuperação de dados e algumas operações relacionadas a contas.

Dependendo do endpoint, a API pode oferecer suporte a operações como:

• Recuperação de anúncios: obter informações sobre anúncios compatíveis, incluindo anúncios individuais por meio de seus IDs.
• Pesquisa e acesso a dados: acessar dados disponibilizados pelos endpoints da API.
• Operações relacionadas a contas: acessar funcionalidades compatíveis com contas por meio de endpoints específicos, sujeitos aos respectivos requisitos de autenticação.
• Integrações externas: conectar o eDirectory a outros aplicativos e serviços utilizando as operações disponibilizadas pela API.

2. Habilitando a API do eDirectory

Para habilitar a API no seu site, siga estas etapas.

2.1. Acesse as configurações da área administrativa

1. Faça login na área administrativa do eDirectory.
2. Navegue até Configurações.
3. Selecione Configurações gerais no submenu.

2.2. Habilite a API

1. Localize a seção API do eDirectory.
2. Marque a caixa Habilitar API.
3. A chave de API do seu domínio será exibida no campo correspondente.

2.3. Salve as alterações

Clique em Salvar alterações para aplicar as alterações.

Mantenha sua chave de API segura e não a exponha em códigos publicamente acessíveis ou em aplicativos executados no lado do cliente.

3. Acessando as informações e a documentação da API

Após habilitar a API, você poderá acessar as informações e a documentação disponíveis na área administrativa.

3.1. Abra a janela de informações da API

1. Acesse Configurações > Configurações gerais > API do eDirectory.
2. Clique no ícone de ponto de interrogação ao lado das configurações da API.

3.2. Acesse os dados da API

Uma janela intitulada API do eDirectory e como ela funciona... será exibida.

Essa janela fornece uma URL que pode ser utilizada para acessar os dados disponibilizados pela API.

1) Habilite sua API do eDirectory no formulário abaixo e anote a chave.

2) Use esta chave com a aplicação externa para acessar seus dados através do seguinte URL (como um exemplo):

Utilize somente o formato de URL e o método de autenticação especificados na documentação da API do seu site.

3.3. Abra a documentação completa da API

Clique no link aqui, na parte inferior da janela de informações, para acessar a documentação completa da API.

Antes de implementar uma integração, revise os endpoints documentados, os parâmetros das solicitações, os requisitos de autenticação e os formatos das respostas.

4. Métodos de autenticação da API

A API do eDirectory oferece diferentes métodos de autenticação, dependendo do endpoint e da operação.

4.1. Chave de API do domínio

A chave de API do domínio é enviada por meio do cabeçalho HTTP X-API-KEY .

Esse método de autenticação é adequado para integrações entre servidores que precisam acessar as funcionalidades de consulta disponibilizadas pela API.

Exemplo de cabeçalho:X-API-KEY: YOUR_DOMAIN_API_KEY

Substitua YOUR_DOMAIN_API_KEY  pela chave de API real do seu domínio. Não publique essa chave em códigos executados no lado do cliente, repositórios públicos ou outros locais acessíveis publicamente.

4.2. Autenticação JWT baseada no usuário

Determinados endpoints relacionados a contas, incluindo rotas sob /api/v4/my/* , utilizam autenticação por JSON Web Token (JWT) após o login do usuário.

Esse método destina-se às operações compatíveis com contas de usuários e, em geral, não é o modelo de autenticação recomendado para automações entre servidores que precisam funcionar sem intervenção do usuário.

4.3. Recomendações de segurança

Ao desenvolver uma integração com o eDirectory, recomendamos as seguintes práticas:

• Utilize HTTPS em todas as comunicações com a API.
• Armazene as chaves de API e outras credenciais de forma segura no lado do servidor.
• Restrinja o acesso às credenciais e altere-as quando necessário.
• Considere utilizar restrições de IP, grupos de segurança ou um Web Application Firewall (WAF), quando apropriado.
• Utilize somente o método de autenticação compatível com o endpoint que deseja acessar.

Se sua integração exigir operações de gravação que não são compatíveis com a API pública, será necessário desenvolver um endpoint personalizado com seus próprios mecanismos de autenticação e controles de acesso.

5. Recursos e limitações da API

Antes de desenvolver uma integração, verifique se as operações necessárias estão disponíveis na API pública.

5.1. Recuperando anúncios

A API pública permite recuperar anúncios individuais por meio do endpoint:GET /api/v4/listings/{id}

Substitua {id}  pelo ID do anúncio que deseja recuperar.

5.2. Criando ou atualizando anúncios

Atualmente, a API pública não disponibiliza endpoints para criar ou atualizar diretamente anúncios comerciais.

Consequentemente, não é possível utilizar a API pública para criar um anúncio, atribuir seu produto ou nível de anúncio, preencher sua descrição e seus campos de SEO, enviar imagens ou definir seu status inicial como Pendente por meio de uma solicitação genérica de criação de anúncios.

Essas operações devem ser realizadas por meio das funcionalidades atualmente disponíveis no eDirectory, como o recurso de importação: Como Importar Anúncios.

5.3. Importando anúncios por meio de arquivos CSV

O eDirectory disponibiliza um processo padrão de importação de arquivos CSV por meio da área administrativa.

No entanto, atualmente, a API pública não oferece um endpoint para enviar um arquivo CSV e executar programaticamente o processo padrão de importação.

Se você precisar automatizar importações de arquivos CSV a partir de um aplicativo ou servidor externo, será necessário um desenvolvimento adicional. A solução proposta deverá ser avaliada para determinar se deve ser integrada ao processo de importação existente ou se deve implementar um fluxo de trabalho separado e compatível.

5.4. Gerenciando anúncios pendentes e assinaturas

Atualmente, a API pública não oferece uma solução de integração pronta que permita a um aplicativo externo criar anúncios com status Pendente enquanto impede a criação de assinaturas, o processamento de pagamentos, a ativação de anúncios ou alterações em registros existentes.

Embora seja possível ter anúncios sem uma assinatura associada, aplicar automaticamente essas condições por meio de uma integração externa exigiria uma implementação personalizada.

O comportamento necessário e as permissões envolvidas precisariam ser definidos e avaliados pela equipe de Desenvolvimento.

5.5. Recuperando o status da importação e os IDs dos anúncios

O importador padrão de arquivos CSV disponibiliza informações sobre os processos de importação, incluindo o progresso do processamento e os erros, por meio da área administrativa. No entanto, ele não fornece uma resposta imediata da API contendo o ID de cada anúncio criado.

A API pública permite recuperar um anúncio individual pelo seu ID quando ele está com status Ativo, mas atualmente não oferece um fluxo completo baseado em API para enviar arquivos de importação e recuperar os resultados do processamento de cada registro.

Se sua integração precisar receber diretamente em um aplicativo externo os IDs dos anúncios, os erros de validação, o status do processo de importação ou os resultados do processamento, será necessário um desenvolvimento adicional.

6. Limites de requisições, licenciamento e considerações sobre importações

Considere os seguintes pontos ao planejar uma integração com a API.

• Limites de requisições da API: atualmente, não há um limite de requisições implementado no código da API pública. No entanto, isso não deve ser interpretado como uma garantia de capacidade ou volume de processamento ilimitados. Qualquer integração proposta para processar grandes volumes de dados deverá ser avaliada quanto ao desempenho e aos requisitos de infraestrutura.
• Limites de importação de arquivos CSV: o importador padrão possui restrições operacionais. Como orientação geral, os arquivos de importação devem conter aproximadamente 10.000 linhas ou menos, dependendo do arquivo e dos requisitos de processamento.
• Licenciamento: o eDirectory é licenciado comercialmente por domínio. Confirme com a equipe comercial responsável quaisquer implicações de licenciamento relacionadas à implantação pretendida.
• Taxas adicionais e hospedagem: eventuais taxas adicionais, requisitos de hospedagem ou restrições associados a uma integração personalizada não são definidos pela própria API pública e devem ser confirmados com a equipe de Vendas.
• Desenvolvimento personalizado: integrações que exijam operações de gravação não compatíveis com a API, processamento automatizado de arquivos CSV, controles adicionais de autenticação ou respostas de processamento personalizadas precisam ser avaliadas separadamente.

7. Quando é necessário um desenvolvimento personalizado?

Um desenvolvimento personalizado pode ser necessário quando sua integração exige funcionalidades que não estão disponíveis na API existente.

Alguns exemplos incluem:

• Criar ou atualizar anúncios comerciais diretamente por meio de uma API.
• Atribuir automaticamente produtos aos anúncios ou definir seu status como Pending.
• Enviar arquivos CSV e iniciar o processo padrão de importação sem interação manual no Site Manager.
• Retornar os IDs dos anúncios recém-criados e os resultados detalhados da validação a um sistema externo.
• Impedir registros duplicados ou atualizações acidentais durante solicitações repetidas.
• Restringir uma integração a operações específicas e impedir a ativação não autorizada de anúncios ou a execução de ações relacionadas à cobrança.
• Oferecer métodos adicionais de autenticação ou controles de segurança para fluxos automatizados entre servidores.

Se você precisar de qualquer uma dessas funcionalidades, envie uma solicitação de personalização por meio do formulário de orçamento para customizações do eDirectory.

Nossa equipe de Vendas poderá ajudar a coordenar uma avaliação dos requisitos, da viabilidade, do prazo estimado e dos custos associados.

Conclusão

A API do eDirectory permite acessar dados e funcionalidades compatíveis por meio de endpoints documentados. Ao habilitar a API e consultar sua documentação, você poderá identificar quais operações estão disponíveis para a integração desejada.

Atualmente, a API pública é projetada principalmente para a recuperação de dados e algumas operações relacionadas a contas. A criação e a atualização direta de anúncios comerciais, as importações programáticas de arquivos CSV e a obtenção completa de relatórios de status das importações não estão disponíveis na API pública.

Para integrações que exijam esses recursos, pode ser necessário um desenvolvimento personalizado. A análise dos requisitos em conjunto com nossas equipes de Vendas e Desenvolvimento ajudará a determinar a solução mais adequada para o seu projeto.