SUMIDO DEVELOPER
API Operacional
Swagger UI ReDoc

SUMIDO SaaS WhatsApp API

Bem-vindo à documentação oficial para desenvolvedores do **SUMIDO**. Nossa API permite a gestão programática de conexões WhatsApp, cadastro de contatos, automação de fluxos de check-in integrados por QR Code e disparo automatizado de alertas de pós-venda/satisfação.

URL Base da API: http://localhost:8008

Autenticação

A maior parte dos endpoints da API requer autenticação via token **Bearer JWT**. O token deve ser enviado no cabeçalho Authorization em cada requisição.

POST /api/auth/register
Criação de novos usuários na plataforma.
Corpo da Requisição (JSON)
email string obrigatório
E-mail do usuário. Deve ser único.
password string obrigatório
Senha do usuário.
curl -X POST "[HOST]/api/auth/register"   -H "Content-Type: application/json"   -d '{
    "email": "dev@exemplo.com",
    "password": "senha-segura-123"
  }'
import httpx

res = httpx.post(
    "[HOST]/api/auth/register",
    json={
        "email": "dev@exemplo.com",
        "password": "senha-segura-123"
    }
)
print(res.json())
fetch("[HOST]/api/auth/register", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "dev@exemplo.com",
    password: "senha-segura-123"
  })
})
.then(res => res.json())
.then(console.log);
POST /api/auth/login
Geração de token de acesso para autenticação.
Corpo da Requisição (JSON)
email string obrigatório
E-mail cadastrado.
password string obrigatório
Senha cadastrada.
curl -X POST "[HOST]/api/auth/login"   -H "Content-Type: application/json"   -d '{
    "email": "dev@exemplo.com",
    "password": "senha-segura-123"
  }'
import httpx

res = httpx.post(
    "[HOST]/api/auth/login",
    json={
        "email": "dev@exemplo.com",
        "password": "senha-segura-123"
    }
)
data = res.json()
print("Token:", data["access_token"])
fetch("[HOST]/api/auth/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "dev@exemplo.com",
    password: "senha-segura-123"
  })
})
.then(res => res.json())
.then(data => console.log("Token:", data.access_token));

Instâncias WhatsApp (Evolution API)

Gerencie conexões do WhatsApp via Evolution API. Cada conta está limitada a 1 instância do WhatsApp.

GET /api/instances
Lista instâncias do WhatsApp pertencentes à conta ativa.
Autenticação
Authorization Header obrigatório
Bearer <token_jwt>
curl -X GET "[HOST]/api/instances"   -H "Authorization: Bearer seu_token_aqui"
import httpx

headers = {"Authorization": "Bearer seu_token_aqui"}
res = httpx.get("[HOST]/api/instances", headers=headers)
print(res.json())
fetch("[HOST]/api/instances", {
  method: "GET",
  headers: { "Authorization": "Bearer seu_token_aqui" }
})
.then(res => res.json())
.then(console.log);
POST /api/instances/create
Cria uma nova instância de conexão WhatsApp via Evolution API.
Autenticação
Authorization Header obrigatório
Bearer <token_jwt>
curl -X POST "[HOST]/api/instances/create"   -H "Authorization: Bearer seu_token_aqui"
import httpx

headers = {"Authorization": "Bearer seu_token_aqui"}
res = httpx.post("[HOST]/api/instances/create", headers=headers)
print(res.json())
fetch("[HOST]/api/instances/create", {
  method: "POST",
  headers: { "Authorization": "Bearer seu_token_aqui" }
})
.then(res => res.json())
.then(console.log);

Contatos & Visitas

Cadastre clientes manualmente ou consulte a lista ativa para ver a data do último check-in registrado.

GET /api/contacts
Lista todos os contatos vinculados à sua conta.
Autenticação
Authorization Header obrigatório
Bearer <token_jwt>
curl -X GET "[HOST]/api/contacts"   -H "Authorization: Bearer seu_token_aqui"
import httpx

headers = {"Authorization": "Bearer seu_token_aqui"}
res = httpx.get("[HOST]/api/contacts", headers=headers)
print(res.json())
fetch("[HOST]/api/contacts", {
  method: "GET",
  headers: { "Authorization": "Bearer seu_token_aqui" }
})
.then(res => res.json())
.then(console.log);
POST /api/contacts
Cadastra um novo contato individual.
Corpo da Requisição (JSON)
name string obrigatório
Nome completo do contato.
phone string obrigatório
Número de WhatsApp (ex: 11999999999).
curl -X POST "[HOST]/api/contacts"   -H "Authorization: Bearer seu_token_aqui"   -H "Content-Type: application/json"   -d '{
    "name": "Maria Souza",
    "phone": "11988887777"
  }'
import httpx

headers = {"Authorization": "Bearer seu_token_aqui"}
res = httpx.post(
    "[HOST]/api/contacts",
    headers=headers,
    json={"name": "Maria Souza", "phone": "11988887777"}
)
print(res.json())
fetch("[HOST]/api/contacts", {
  method: "POST",
  headers: {
    "Authorization": "Bearer seu_token_aqui",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name: "Maria Souza",
    phone: "11988887777"
  })
})
.then(res => res.json())
.then(console.log);

Check-ins & Validação

Endpoints públicos para o fluxo de QR Code do estabelecimento físico. O cliente insere o WhatsApp, recebe um código de validação, valida o código e confirma sua presença.

POST /api/checkin/initiate
Inicia o fluxo gerando e disparando o código de verificação por WhatsApp.
Corpo da Requisição (JSON)
phone string obrigatório
Número do cliente que está fazendo check-in.
establishment_user_id string obrigatório
ID do estabelecimento (UUID).
name string opcional
Nome do cliente (caso seja o primeiro check-in).
curl -X POST "[HOST]/api/checkin/initiate"   -H "Content-Type: application/json"   -d '{
    "phone": "11999999999",
    "establishment_user_id": "f8d8b671-872e-4b47-b283-2d2c18ab9344",
    "name": "João Silva"
  }'
import httpx

res = httpx.post(
    "[HOST]/api/checkin/initiate",
    json={
        "phone": "11999999999",
        "establishment_user_id": "f8d8b671-872e-4b47-b283-2d2c18ab9344",
        "name": "João Silva"
    }
)
print(res.json())
fetch("[HOST]/api/checkin/initiate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    phone: "11999999999",
    establishment_user_id: "f8d8b671-872e-4b47-b283-2d2c18ab9344",
    name: "João Silva"
  })
})
.then(res => res.json())
.then(console.log);
POST /api/checkin/verify
Valida o código de 6 dígitos recebido e conclui a presença do cliente.
Corpo da Requisição (JSON)
phone string obrigatório
Número do cliente.
establishment_user_id string obrigatório
ID do estabelecimento (UUID).
code string obrigatório
Código numérico de 6 dígitos recebido pelo cliente.
curl -X POST "[HOST]/api/checkin/verify"   -H "Content-Type: application/json"   -d '{
    "phone": "11999999999",
    "establishment_user_id": "f8d8b671-872e-4b47-b283-2d2c18ab9344",
    "code": "123456"
  }'
import httpx

res = httpx.post(
    "[HOST]/api/checkin/verify",
    json={
        "phone": "11999999999",
        "establishment_user_id": "f8d8b671-872e-4b47-b283-2d2c18ab9344",
        "code": "123456"
    }
)
print(res.json())
fetch("[HOST]/api/checkin/verify", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    phone: "11999999999",
    establishment_user_id: "f8d8b671-872e-4b47-b283-2d2c18ab9344",
    code: "123456"
  })
})
.then(res => res.json())
.then(console.log);

Webhooks

Receba atualizações em tempo real da Evolution API sobre o status das mensagens enviadas e respostas das pesquisas de satisfação respondidas.

POST /api/webhook/whatsapp
Endpoint receptor das atualizações da Evolution API.
Funcionamento

Ao conectar uma instância WhatsApp na nossa plataforma, configuramos automaticamente a URL de webhook do nosso backend na Evolution API correspondente. Quando o cliente interage respondendo a pesquisa de satisfação, o webhook recebe a resposta ("SIM", "NÃO" ou nota de 1 a 5) e avança no fluxo da pesquisa localmente. 

{
  "event": "messages.upsert",
  "instance": "sumido_instancia_123",
  "data": {
    "key": {
      "remoteJid": "5511999999999@s.whatsapp.net",
      "fromMe": false,
      "id": "ABCD1234EFGH5678"
    },
    "message": {
      "conversation": "Sim"
    },
    "messageType": "conversation"
  }
}