Caso de Uso: Gerando uma Senha para um Cliente Identificado via API

Atualizado em 02 de julho de 2026
Pergunte à IA

O cenário

Sua empresa já possui um sistema próprio onde o cliente faz cadastro: um portal de agendamento, um app ou um sistema interno de recepção. Sem integração, o cliente precisaria se cadastrar no seu sistema e, ao chegar no local, ainda passar pelo totem ou pelo sistema para emitir a senha de atendimento. Ou seja, duas etapas de preenchimento para o mesmo atendimento.

Neste caso de uso, vamos eliminar essa duplicidade dividindo os papéis entre os dois sistemas:

  • Seu sistema é o dono de toda a etapa de emissão: é nele que o cliente se cadastra e é ele que dispara a criação da senha via API.
  • O Meu Atendimento Virtual cuida apenas do gerenciamento do atendimento: fila, chamada de senhas, painel de TV, guichês e relatórios.

O cliente se cadastra uma única vez, no seu sistema, e a senha já nasce na fila do Meu Atendimento Virtual vinculada a ele. Não existe etapa de emissão no totem nem nova identificação no balcão.

O fluxo tem três chamadas de API:

  1. Consultar os serviços disponíveis, obtendo a service_key da fila desejada.
  2. Cadastrar o cliente na plataforma via API, obtendo a client_key.
  3. Gerar a senha de atendimento vinculada a esse cliente.

Ao final, a senha entra na fila com os dados do cliente associados, e o atendente já sabe quem vai atender antes mesmo de chamar.

O que você precisa antes de começar

Todas as requisições usam os mesmos cabeçalhos:

  • accept: application/json
  • Authorization: Bearer <sua-chave-de-api>
  • Content-Type: application/json

Passo 1 - Obtendo a service_key do serviço

Consulte os serviços cadastrados na sua conta pelo endpoint de listagem:

curl -X GET https://painel.meuatendimentovirtual.com.br/api/v1/servicos/ \
-H "accept: application/json" \
-H "Authorization: Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999"

A resposta é paginada e traz os serviços em results:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "key": "pri459dn",
      "order": 1,
      "name": "Atendimento Geral",
      "code": "ATG",
      "priority": "normal"
    }
  ]
}

O campo key de cada serviço é a service_key que você vai usar na criação da senha. Se a conta tiver muitos serviços, use os parâmetros de query page e page_size para navegar entre as páginas.

Essa consulta pode ser feita uma única vez: guarde a service_key da fila desejada na configuração do seu sistema.

Passo 2 - Cadastrando o cliente

No momento em que o cliente conclui o cadastro no seu sistema, envie os dados dele para a plataforma:

curl -X POST https://painel.meuatendimentovirtual.com.br/api/v1/clientes/ \
-H "accept: application/json" \
-H "Authorization: Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999" \
-H "Content-Type: application/json" \
-d '{
  "name": "João Silva",
  "email": "joao@example.com",
  "phone": "11999999999",
  "cpf": "123.456.789-00"
}'

O único campo obrigatório é name. A resposta (201 Created) retorna a chave do cliente:

{
  "key": "xfrh3456s",
  "name": "João Silva",
  "email": "joao@example.com",
  "phone": "11999999999",
  "cpf": "123.456.789-00"
}

Guarde o campo key: essa é a client_key que vincula o cliente à senha no próximo passo.

Dica: se o cliente já foi cadastrado em uma visita anterior, não é necessário criá-lo de novo. Consulte a client_key existente pelo endpoint /api/v1/clients.

Passo 3 - Gerando a senha vinculada ao cliente

Com a client_key em mãos, crie o ticket informando o cliente e o serviço desejado:

curl -X POST https://painel.meuatendimentovirtual.com.br/api/v1/tickets/ \
-H "accept: application/json" \
-H "Authorization: Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999" \
-H "Content-Type: application/json" \
-d '{
  "client_key": "xfrh3456s",
  "services": [
    {
      "service_key": "pri459dn"
    }
  ]
}'
  • services é o único campo obrigatório: informe a service_key obtida no Passo 1.
  • client_key é o vínculo com o cliente cadastrado no Passo 2.
  • priority_name é opcional (padrão "Normal"). Para filas preferenciais, veja Como Configurar Prioridades de Atendimento.

Passo 4 - O fluxo completo em código

Juntando tudo em um único script Python, do cadastro no seu sistema à senha na fila:

import requests

BASE_URL = "https://painel.meuatendimentovirtual.com.br/api/v1"
HEADERS = {
    "accept": "application/json",
    "Authorization": "Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999",
    "Content-Type": "application/json",
}

# 1. Consulta os serviços e obtém a service_key da fila desejada
servicos = requests.get(f"{BASE_URL}/servicos/", headers=HEADERS).json()
service_key = servicos["results"][0]["key"]

# 2. Replica o cadastro feito no seu sistema para a plataforma
cliente = requests.post(
    f"{BASE_URL}/clientes/",
    json={"name": "João Silva", "phone": "11999999999"},
    headers=HEADERS,
).json()

# 3. Gera a senha já vinculada ao cliente, sem passar pelo totem
ticket = requests.post(
    f"{BASE_URL}/tickets/",
    json={
        "client_key": cliente["key"],
        "services": [{"service_key": service_key}],
    },
    headers=HEADERS,
)

print(ticket.status_code)
print(ticket.json())

O resultado

O cliente preenche os dados uma única vez, no seu sistema, e toda a emissão acontece lá, sem nenhuma etapa no totem ou no balcão. Do lado do Meu Atendimento Virtual, a senha entra na fila do serviço informado com o cadastro do cliente associado, e a plataforma assume o restante do fluxo: chamada de senhas, exibição no painel de TV, atendimento nos guichês e relatórios. O atendente vê o nome do cliente vinculado à senha, o atendimento começa sem retrabalho de identificação e os relatórios passam a registrar o histórico completo de cada cliente.

Erros comuns

  • 400 Bad Request: verifique se services está presente na criação do ticket e se name foi enviado no cadastro do cliente.
  • 401 Unauthorized: a chave de API está ausente ou incorreta no cabeçalho Authorization. Acesse Integração > Token para copiar a chave correta.
  • client_key inválida: confirme que está usando o valor do campo key retornado na criação do cliente, e não outro identificador do seu sistema.

Tutoriais relacionados