Pedidos de ligação

Um pedido de ligação (call request) é um cliente pedindo que a loja ligue de volta. O cliente deixa nome, telefone ou e-mail e, às vezes, uma janela de horário na loja. A API de Call Requests permite acompanhar, responder e gerenciar esses pedidos, que são consultas que exigem atendimento por telefone. Um pedido de ligação também pode vir de uma compra feita com "Comprar agora com 1 clique" (Buy now with 1-click), e nesse caso traz o pedido e o produto.

Use a API para alimentar suas ferramentas de suporte ou de CRM com os novos pedidos e para encerrá-los depois da ligação. Todas as chamadas usam HTTP Basic com o e-mail:chave_de_api do administrador.

Como funciona

1. O pedido chega

   Um cliente deixa um pedido de retorno na loja, ou você cria um com POST. Ele começa com o status new.

2. Sua equipe trabalha nele

   Liste os pedidos, filtre por status, nome, telefone ou loja (veja Paginação e filtros) e mude o status para in_progress quando alguém assumir.

3. Encerre

   Depois da ligação, atualize o pedido para completed, ou para no_answer quando o cliente não atendeu, e registre uma observação. Atualize sempre o status após cada tentativa de contato: é assim que você acompanha as interações com o cliente e a qualidade do atendimento.

Status do pedido de ligação

Conceitos-chave

Duas formas da API

As chamadas de listar, criar e atualizar descritas abaixo usam a base /api/call_requests. O mesmo recurso também é exposto em /api/2.0/call_requests, com chamadas para listar, criar, consultar um, atualizar e excluir, descritas em Endpoints e Exemplos. As duas formas mostram corpos de resposta diferentes, então use a página da forma que você está chamando.

Formato dos erros

Quando ocorre um erro, a API devolve um código de status HTTP e um corpo JSON com os detalhes do erro.

{
  "error": {
    "code": "validation_error",
    "message": "The request parameters are invalid.",
    "details": [
      {
        "field": "phone",
        "message": "Phone number is required and cannot be empty."
      }
    ]
  }
}

Avise sua equipe

Ao integrar com a API de Call Requests, considere enviar uma notificação automática ao suporte quando chegar um novo pedido. Isso reduz o tempo de resposta.

Endpoints

Listar pedidos de ligação

Retorna a lista de todos os pedidos de ligação, com filtros opcionais.

Exemplo de requisição

curl "$BASE_URL/api/call_requests?status=new&page=1" \
  -u "$EMAIL:$API_KEY"

Resposta

{
  "call_requests": [
    {
      "request_id": "123",
      "name": "John Smith",
      "phone": "+1 (555) 123-4567",
      "status": "new",
      "notes": "Customer has questions about product availability",
      "timestamp": "2025-04-14T15:30:00Z",
      "user_id": "45",
      "email": "john.smith@example.com",
      "preferred_time": "2025-04-15T10:00:00Z"
    },
    {
      "request_id": "124",
      "name": "Jane Doe",
      "phone": "+1 (555) 987-6543",
      "status": "completed",
      "notes": "Customer needed help with order #12345",
      "timestamp": "2025-04-13T09:15:00Z",
      "user_id": "67",
      "email": "jane.doe@example.com",
      "preferred_time": null
    }
  ],
  "pagination": {
    "total": 45,
    "current_page": 1,
    "items_per_page": 20,
    "total_pages": 3
  }
}

Criar um pedido de ligação

Cria um novo pedido de ligação no sistema.

Exemplo de requisição

curl -X POST "$BASE_URL/api/call_requests" \
  -u "$EMAIL:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Robert Johnson",
  "phone": "+1 (555) 234-5678",
  "email": "robert.johnson@example.com",
  "notes": "Interested in bulk pricing for corporate order",
  "preferred_time": "2025-04-16T14:00:00Z"
}'

Resposta

{
  "success": true,
  "request_id": "125",
  "message": "Call request created successfully"
}

Atualizar um pedido de ligação

Atualiza um pedido de ligação existente.

Exemplo de requisição

curl -X PUT "$BASE_URL/api/call_requests/123" \
  -u "$EMAIL:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "completed",
  "notes": "Spoke with customer on 2025-04-15. Provided information about bulk pricing and sent quote via email."
}'

Resposta

{
  "success": true,
  "message": "Call request updated successfully"
}

Erros comuns

• Criar um pedido sem os dados de contato que a forma exige. Aqui name e phone são obrigatórios; na outra forma, phone ou email.
• Ler items_per_page como 10 aqui. Esta forma da API documenta padrão 20 e máximo 100, enquanto a página de paginação documenta padrão 10.
• Esquecer de atualizar o status depois de uma tentativa de contato.
• Excluir um pedido de que você ainda precisa. A remoção é permanente.

Próximos passos