Pular para o conteúdo principal

Guia de Utilização da API

Este guia aborda as melhores práticas e padrões comuns para utilizar a API XD Soba de forma eficiente.

Padrões de Requisição​

Paginação​

A maioria dos endpoints de listagem suportam paginação usando os seguintes parâmetros:

?page=1&pageSize=20
  • page: O número da página (começa em 1)
  • pageSize: Número de itens por página (padrão: 20, máximo: 100)

Exemplo de resposta:

{
  "items": [...],
  "totalCount": 100,
  "pageSize": 20,
  "currentPage": 1,
  "totalPages": 5
}

Filtros​

Muitos endpoints suportam filtros usando parâmetros de query:

# Filtrar por intervalo de datas
?startDate=2024-01-01&endDate=2024-12-31

# Filtrar por estado
?status=active

# Pesquisar por texto
?search=query

Ordenação​

Ordene os resultados usando os parâmetros sortBy e sortDirection:

?sortBy=createdAt&sortDirection=desc

Operações Comuns​

Criar Recursos​

A maioria dos endpoints de criação seguem este padrão:

POST /gateway/{resource}
Content-Type: application/json

{
  "name": "Exemplo",
  "description": "Descrição opcional",
  "status": "active"
}

Atualizar Recursos​

Operações de atualização normalmente usam PUT ou PATCH:

PUT /gateway/{resource}/{id}
Content-Type: application/json

{
  "name": "Nome Atualizado",
  "status": "inactive"
}

Eliminar Recursos​

A eliminação é normalmente feita com o método DELETE:

DELETE /gateway/{resource}/{id}

Boas Práticas​

Tratamento de Erros​

  1. Verifique sempre o código de estado da resposta
  2. Analise as respostas de erro para informações detalhadas
  3. Implemente lógica de retry para erros 5xx
  4. Trate o rate limiting (429) adequadamente

Desempenho​

  1. Use paginação para limitar o tamanho da resposta
  2. Implemente caching do lado do cliente quando apropriado
  3. Use compressão (gzip) para respostas grandes
  4. Agrupe operações quando possível

Segurança​

  1. Nunca guarde tokens em código do lado do cliente
  2. Rotacione as chaves da API regularmente
  3. Use HTTPS para todos os pedidos
  4. Valide todos os dados de entrada

Casos de Uso Comuns​

Gestão de Entidades​

# Criar uma nova entidade
POST /gateway/entities
{
  "name": "Nova Entidade",
  "type": "customer"
}

# Listar entidades com filtros
GET /gateway/entities?type=customer&status=active

# Atualizar entidade
PUT /gateway/entities/{id}
{
  "status": "inactive"
}

Regiões de Entrega​

# Criar região de entrega
POST /gateway/delivery-regions
{
  "name": "Nome da Região",
  "boundaries": [...]
}

# Listar regiões
GET /gateway/delivery-regions?active=true

Itens e Grupos​

# Criar item
POST /gateway/items
{
  "name": "Nome do Item",
  "groupId": "group-id"
}

# Listar itens de um grupo
GET /gateway/items?groupId=group-id

Testes​

  1. Use o ambiente de sandbox para testes
  2. Teste cenários de erro
  3. Verifique o comportamento do rate limiting
  4. Teste com diferentes volumes de dados

Suporte​

Se precisar de ajuda: