A integração API Programada permite que a YOM obtenha dados atualizados de forma automática a partir dos sistemas de nossos clientes. Esta opção se adapta a empresas que têm a capacidade técnica de expor seus dados por meio de endpoints.
A integração API Programada significa que a YOM fará solicitações periódicas aos endpoints fornecidos pelo cliente para obter os dados necessários. Este método garante que os dados em nossos sistemas estejam sempre atualizados, refletindo as alterações feitas nos sistemas do cliente.
A seguir estão listados os requisitos técnicos necessários para implementar uma integração API Programada com a YOM.
O cliente deve expor endpoints que permitam à YOM realizar requests GET para obter os dados. Os endpoints necessários estão listados na seção Endpoints a disponibilizar. Deve indicar a URL Base para a qual serão direcionadas as requests.
<tu_dominio><tu_dominio>/api/commercesOs endpoints devem estar protegidos por um dos seguintes mecanismos de autenticação para garantir a segurança dos dados:
Todos os endpoints devem ser acessíveis apenas por meio de HTTPS para garantir a transmissão criptografada dos dados.
O cliente deve configurar uma whitelist de IPs, permitindo acesso apenas aos IPs especificados pela YOM.
<aside> 💡
Solicitar os IPs da YOM a incluir na whitelist no momento da implementação.
</aside>
Deve ser implementada a paginação. Isso permite extrair grandes volumes de dados de forma incremental. É necessária em todos os endpoints de extração de dados.
/api/commerces?page=1&limit=50No corpo da resposta, deve-se incluir o detalhe da paginação com os seguintes campos:
current_page → número da página atual.per_page → número de resultados por página.total_pages → número total de páginas disponíveis.total_items → número total de resultados disponíveis.next_page → URL para a próxima página (se aplicável).prev_page → URL para a página anterior (se aplicável).Exemplo de resposta:
{
"data": [
{
"id": "123",
"name": "Comercio A",
"category": "Retail"
},
{
"id": "124",
"name": "Comercio B",
"category": "Food"
}
// ... más resultados
],
"pagination": {
"current_page": 1,
"per_page": 50,
"total_pages": 10,
"total_items": 500,
"next_page": "/api/commerces?page=2&limit=50",
"prev_page": null
}
}
O tempo de resposta máximo permitido para as requests GET é de 100 segundos.
A resposta deve estar no formato JSON. Recomenda-se utilizar UTF-8 para todas as respostas.
Os endpoints devem ter alta disponibilidade e ser capazes de suportar o tráfego de consultas periódicas da YOM.
Os endpoints devem fornecer acesso ao histórico completo de dados. Isso significa que devem ser projetados para incluir tanto entidades ativas quanto inativas, permitindo que a YOM acesse a informação completa a qualquer momento, independentemente do status atual.