PrimuxDocs

Referência da API

API do Primux Omni

Integre o seu sistema ao Omni: envie mensagens de WhatsApp, cadastre contatos e leia os atendimentos e as respostas dos clientes. Tudo o que entra pela API aparece no Omni como uma conversa normal, e a sua equipe responde por lá.

Basehttps://dev-api.primux.cloud AuthBearer omn_… FormatoJSON · UTF-8
URL base
https://dev-api.primux.cloud/v1/omni

Visão geral

A API fica no endereço central da Primux, em /v1/omni, e fala JSON em UTF-8. Você só precisa de uma chave: o resto (empresa, plano e servidor) a Primux resolve.

  • Enviar mensagens de texto para qualquer número de WhatsApp pelo canal conectado da sua empresa.
  • Cadastrar e consultar contatos, sem duplicar: o telefone identifica o contato.
  • Listar os atendimentos e ler as mensagens, inclusive as respostas dos clientes.
  • Consultar os canais (conexões de WhatsApp) e o estado de cada um.
A API usa o WhatsApp que você conectou no Omni. Se o canal estiver desconectado, o envio falha com o erro canal_desconectado: conecte de novo lendo o QR code no Omni.
Resposta 200
{
  "empresa": { "codigo": "minha-empresa" },
  "chave": { "nome": "Sistema de pedidos", "acesso": "escrita" }
}

Início rápido

  1. No console da Primux, abra Omni e, em API de integração, crie uma chave de leitura e escrita.
  2. Copie a chave (ela só aparece uma vez) e guarde em uma variável de ambiente, como PRIMUX_OMNI_CHAVE.
  3. Confira a chave em GET /v1/omni/eu e os canais em GET /v1/omni/canais.
  4. Envie uma mensagem com POST /v1/omni/mensagens e leia a conversa em GET /v1/omni/atendimentos/{id}/mensagens.

O exemplo envia uma mensagem e lê a conversa, tratando os erros da API.

Enviar uma mensagem e ler a conversa
# 1) envia a mensagem (cria o contato e o atendimento se não existirem)
curl -X POST "https://dev-api.primux.cloud/v1/omni/mensagens" \
  -H "Authorization: Bearer $PRIMUX_OMNI_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"para":"77999999999","texto":"Olá! Seu pedido saiu para entrega."}'

# 2) lê a conversa (use o atendimento_id da resposta)
curl "https://dev-api.primux.cloud/v1/omni/atendimentos/ID_DO_ATENDIMENTO/mensagens" \
  -H "Authorization: Bearer $PRIMUX_OMNI_CHAVE"

Chaves de API

Cada sistema que usa a API deve ter a sua chave, para você revogar uma sem afetar as outras.

  • A chave aparece uma única vez, ao ser criada: copie na hora.
  • Chaves de leitura só consultam; para enviar mensagens e cadastrar contatos use uma chave com escrita.
  • Você pode ter até 10 chaves ativas e revogar qualquer uma na hora.
  • Se a assinatura do Omni estiver suspensa ou cancelada, todas as chaves deixam de funcionar até a regularização.

Abrir o Omni no console

Nunca coloque a chave em código de navegador ou de aplicativo distribuído: use sempre a partir do seu servidor.
Guarde a chave em uma variável de ambiente
export PRIMUX_OMNI_CHAVE="omn_COLE_AQUI_A_SUA_CHAVE"

Autenticação

Envie a chave em todas as chamadas, no cabeçalho Authorization, no formato Bearer.

Chave inválida ou revogada responde 401; muitas tentativas inválidas seguidas bloqueiam o endereço por um minuto.
Cabeçalho HTTP
Authorization: Bearer omn_0123456789abcdefghijklmnopqrstuvwxyz0123456

Referência da API

Empresa e chave

GET/v1/omni/eu

Devolve o código da empresa e o nome e o acesso da chave usada. Serve para conferir a chave.

Requisição
curl -X GET "https://dev-api.primux.cloud/v1/omni/eu" \
  -H "Authorization: Bearer $PRIMUX_OMNI_CHAVE"
Resposta
{
  "empresa": { "codigo": "minha-empresa" },
  "chave": { "nome": "Sistema de pedidos", "acesso": "escrita" }
}

Referência da API

Listar canais

GET/v1/omni/canais

Lista os canais (conexões de WhatsApp) da empresa e o estado de cada um: conectado, desconectado ou aguardando leitura do QR.

Requisição
curl -X GET "https://dev-api.primux.cloud/v1/omni/canais" \
  -H "Authorization: Bearer $PRIMUX_OMNI_CHAVE"
Resposta
{
  "canais": [
    {
      "id": "0f6c3c3e-2c1a-4f0e-9a52-7a1d3f5b8c11",
      "nome": "Atendimento",
      "tipo": "whatsapp",
      "estado": "conectado",
      "numero": "5577999999999"
    }
  ]
}

Referência da API

Enviar mensagem

POST/v1/omni/mensagens

Envia uma mensagem de texto. Se o número ainda não for contato, o contato é criado; a mensagem entra num atendimento aberto (ou abre um novo) que a equipe vê e responde no Omni. Sem canal_id usa o primeiro canal conectado; sem fila_id, a primeira fila. Exige chave com escrita.

Parâmetros do corpo

para texto obrigatório
Telefone do destinatário, com DDD. Pode vir com máscara; o código do Brasil (55) é acrescentado se faltar.
texto texto obrigatório
Texto da mensagem, até 4096 caracteres.

Campos desconhecidos são ignorados.

Requisição
curl -X POST "https://dev-api.primux.cloud/v1/omni/mensagens" \
  -H "Authorization: Bearer $PRIMUX_OMNI_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"nome":"Maria","para":"77999999999","texto":"Olá! Seu pedido saiu para entrega."}'
Resposta
{
  "id": "b3c4d5e6-1111-4a2b-8c3d-9e0f1a2b3c4d",
  "atendimento_id": "7d8e9f0a-2222-4b3c-9d4e-0f1a2b3c4d5e",
  "contato_id": "1a2b3c4d-3333-4c4d-8e5f-1a2b3c4d5e6f",
  "canal_id": "0f6c3c3e-2c1a-4f0e-9a52-7a1d3f5b8c11",
  "para": "5577999999999",
  "estado": "enviada",
  "enviada_em": "2026-11-11T14:30:00Z"
}

Referência da API

Listar contatos

GET/v1/omni/contatos?busca=maria&limite=50

Lista os contatos da empresa, com busca por nome ou telefone e paginação (limite e deslocamento).

Requisição
curl -X GET "https://dev-api.primux.cloud/v1/omni/contatos?busca=maria&limite=50" \
  -H "Authorization: Bearer $PRIMUX_OMNI_CHAVE"
Resposta
{
  "contatos": [
    {
      "id": "1a2b3c4d-3333-4c4d-8e5f-1a2b3c4d5e6f",
      "nome": "Maria",
      "telefone": "5577999999999",
      "etiquetas": ["cliente"],
      "criado_em": "2026-11-11T14:30:00Z"
    }
  ],
  "total": 1
}

Referência da API

Ver contato

GET/v1/omni/contatos/1a2b3c4d-3333-4c4d-8e5f-1a2b3c4d5e6f

Devolve um contato pelo id (UUID).

Requisição
curl -X GET "https://dev-api.primux.cloud/v1/omni/contatos/1a2b3c4d-3333-4c4d-8e5f-1a2b3c4d5e6f" \
  -H "Authorization: Bearer $PRIMUX_OMNI_CHAVE"
Resposta
{
  "id": "1a2b3c4d-3333-4c4d-8e5f-1a2b3c4d5e6f",
  "nome": "Maria",
  "telefone": "5577999999999",
  "etiquetas": ["cliente"],
  "criado_em": "2026-11-11T14:30:00Z"
}

Referência da API

Criar contato

POST/v1/omni/contatos

Cria um contato. Se o telefone já existir, devolve o contato existente com status 200, então a chamada pode ser repetida sem duplicar. Exige chave com escrita.

Parâmetros do corpo

telefone texto obrigatório
Telefone do contato, com DDD.
nome texto obrigatório
Nome do contato (usado só ao criar um contato novo).

Campos desconhecidos são ignorados.

Requisição
curl -X POST "https://dev-api.primux.cloud/v1/omni/contatos" \
  -H "Authorization: Bearer $PRIMUX_OMNI_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"etiquetas":["cliente"],"nome":"Maria","telefone":"(77) 99999-9999"}'
Resposta
{
  "id": "1a2b3c4d-3333-4c4d-8e5f-1a2b3c4d5e6f",
  "nome": "Maria",
  "telefone": "5577999999999",
  "etiquetas": ["cliente"],
  "criado_em": "2026-11-11T14:30:00Z"
}

Referência da API

Listar atendimentos

GET/v1/omni/atendimentos?estado=ativo&limite=50

Lista os atendimentos (conversas), do mais novo para o mais antigo, com filtro por estado e paginação.

Requisição
curl -X GET "https://dev-api.primux.cloud/v1/omni/atendimentos?estado=ativo&limite=50" \
  -H "Authorization: Bearer $PRIMUX_OMNI_CHAVE"
Resposta
{
  "atendimentos": [
    {
      "id": "7d8e9f0a-2222-4b3c-9d4e-0f1a2b3c4d5e",
      "protocolo": "20261111-0001",
      "contato_id": "1a2b3c4d-3333-4c4d-8e5f-1a2b3c4d5e6f",
      "canal_id": "0f6c3c3e-2c1a-4f0e-9a52-7a1d3f5b8c11",
      "fila_id": "5e6f7a8b-4444-4d5e-8f6a-2b3c4d5e6f7a",
      "estado": "ativo",
      "criado_em": "2026-11-11T14:30:00Z"
    }
  ],
  "total": 1
}

Referência da API

Mensagens do atendimento

GET/v1/omni/atendimentos/7d8e9f0a-2222-4b3c-9d4e-0f1a2b3c4d5e/mensagens

Lista as mensagens de um atendimento, com a origem de cada uma: cliente, equipe ou automacao. Notas internas da equipe nunca aparecem.

Requisição
curl -X GET "https://dev-api.primux.cloud/v1/omni/atendimentos/7d8e9f0a-2222-4b3c-9d4e-0f1a2b3c4d5e/mensagens" \
  -H "Authorization: Bearer $PRIMUX_OMNI_CHAVE"
Resposta
{
  "mensagens": [
    {
      "id": "b3c4d5e6-1111-4a2b-8c3d-9e0f1a2b3c4d",
      "origem": "equipe",
      "autor": "Primux",
      "tipo": "texto",
      "texto": "Olá! Seu pedido saiu para entrega.",
      "enviada_em": "2026-11-11T14:30:00Z"
    },
    {
      "id": "c4d5e6f7-5555-4e6f-9a7b-3c4d5e6f7a8b",
      "origem": "cliente",
      "autor": "Maria",
      "tipo": "texto",
      "texto": "Obrigada!",
      "enviada_em": "2026-11-11T14:31:10Z"
    }
  ],
  "total": 2
}

Campos e parâmetros

Parâmetros aceitos pela API, no corpo (JSON) ou na consulta (query string).

para texto (telefone com DDD) obrigatório
Telefone do destinatário, com DDD. Pode vir com máscara; o código do Brasil (55) é acrescentado se faltar.
texto texto (até 4096) obrigatório
Texto da mensagem, até 4096 caracteres.
canal_id UUID (opcional: padrão, o primeiro canal conectado)
Canal usado no envio. Sem ele, vale o primeiro canal conectado.
fila_id UUID (opcional: padrão, a primeira fila)
Fila do atendimento quando ele for aberto. Sem ela, vale a primeira fila.
nome texto (opcional: nome do contato novo)
Nome do contato (usado só ao criar um contato novo).
telefone texto (com DDD; o 55 do Brasil é acrescentado) obrigatório
Telefone do contato, com DDD.
etiquetas lista de textos
Etiquetas do contato.
estado ativo | espera | resolvido (filtro dos atendimentos)
Filtro dos atendimentos: ativo, espera ou resolvido.
busca texto (nome ou telefone do contato)
Texto para procurar por nome ou telefone.
limite inteiro (padrão 50, máximo 100)
Quantos itens devolver (padrão 50, máximo 100).
deslocamento inteiro (quantos itens pular)
Quantos itens pular, para paginar.
Os ids (contato, canal, fila, atendimento) são UUID e vêm nas respostas das listagens.
Corpo de exemplo para enviar uma mensagem
{
  "para": "77999999999",
  "texto": "Olá! Seu pedido saiu para entrega.",
  "nome": "Maria"
}

Erros

Os erros voltam em JSON com erro (código fixo, para o seu código tratar) e mensagem (texto para pessoas).

StatusCódigoQuando acontece
400json_invalidoO corpo não é um JSON válido.
401nao_autenticadoA chave não foi enviada no cabeçalho Authorization.
401chave_invalidaChave inválida ou revogada.
402assinatura_bloqueadaA assinatura do Omni está suspensa ou cancelada.
403empresa_inativaA empresa está suspensa, cancelada ou com a cobrança em atraso.
403sem_permissaoA chave é só de leitura e a rota exige escrita.
404nao_encontradoO contato ou o atendimento não existe.
404rota_inexistenteA rota ou o método não existe.
409canal_desconectadoNão há canal de WhatsApp conectado: conecte no Omni.
409sem_filaA empresa ainda não tem fila de atendimento.
409envio_indisponivelO atendimento não aceita envio agora (resolvido ou com envio desligado).
413corpo_grandeO corpo passa de 64 KB.
422telefone_invalidoTelefone inválido: informe DDD e número.
422texto_invalidoO texto é obrigatório e vai até 4096 caracteres.
422canal_invalidoO canal_id não existe nesta empresa.
429limite_excedidoPassou do limite de 120 requisições por minuto da chave.
502falha_envioO WhatsApp não aceitou a mensagem agora: tente de novo.
502servico_indisponivelO Omni está indisponível no momento: tente de novo.
Exemplo de resposta de erro
{
  "erro": "canal_desconectado",
  "mensagem": "não há canal de WhatsApp conectado: conecte o WhatsApp no Omni"
}

Limites e boas práticas

  • 120 requisições por minuto por chave (429 limite_excedido, com o cabeçalho Retry-After).
  • Corpo de até 64 KB por requisição.
  • Texto de mensagem de até 4096 caracteres.
  • Listas devolvem até 100 itens por chamada; use deslocamento para paginar.
  • Os limites de atendentes e canais do seu plano valem dentro do Omni e também para a API.

Boas práticas

  • Guarde a chave em variável de ambiente e use só no servidor.
  • Dê um intervalo entre mensagens em lote: disparos em massa podem levar o WhatsApp a bloquear o número.
  • Trate sempre o campo erro das respostas, não só o status.
  • Repita só 429 e 502, com espera crescente.

Tentar de novo com segurança

Em 429 e 502 vale repetir a chamada depois de uma espera, respeitando o Retry-After quando existir.

Tentar de novo com segurança
import os, time, requests

def chamar(metodo, url, corpo=None, tentativas=4):
    espera = 1
    for _ in range(tentativas):
        r = requests.request(metodo, url, json=corpo, timeout=15,
                             headers={"Authorization": f"Bearer {os.environ['PRIMUX_OMNI_CHAVE']}"})
        if r.status_code not in (429, 502):
            return r
        time.sleep(float(r.headers.get("Retry-After", espera)))
        espera *= 2
    return r

Perguntas frequentes

As mensagens enviadas pela API aparecem no Omni?

Sim. Cada mensagem vira parte de um atendimento do contato, que a equipe vê e responde normalmente no Omni.

Como recebo as respostas dos clientes?

Leia as mensagens do atendimento em GET /v1/omni/atendimentos/{id}/mensagens. As respostas vêm com origem cliente.

Posso enviar imagens e arquivos?

Nesta versão a API envia mensagens de texto. Imagens e arquivos podem ser enviados pela equipe no próprio Omni.

O que acontece se o WhatsApp estiver desconectado?

O envio falha com 409 canal_desconectado e nada é enviado. Conecte o canal no Omni e repita.

A API cobra por mensagem?

Não. O uso da API está incluído no plano do Omni, dentro dos limites de requisições.