ZapHero API - Documentação

Introdução Autenticação Variáveis Dinâmicas Endpoints Exemplos

Introdução

A API ZapHero permite que você envie mensagens WhatsApp programaticamente a partir de seus sistemas. Você pode agendar mensagens, enviar em lote e receber confirmações de entrega.

URL Base: https://hml.zaphero.com.br/api

Autenticação

Todas as requisições à API requerem uma chave de API (API Key) válida. A chave deve ser incluída no cabeçalho Authorization de todas as requisições usando o formato Bearer.

Exemplo de cabeçalho de autenticação

Authorization: Bearer zap_Kq3MPVTwMH6hRzP0SEXD2Cicz9NfuMLq

Nota: Você pode obter ou gerar uma chave de API no painel administrativo, na seção API Keys.

Variáveis Dinâmicas

O sistema suporta substituição de variáveis dinâmicas na mensagem. Você pode personalizar suas mensagens incluindo as seguintes variáveis:

{name} - Será substituído pelo valor do campo "name" enviado no JSON
{email} - Será substituído pelo valor do campo "email" enviado no JSON

Exemplo de mensagem com variáveis: "Olá, {name}! Enviamos uma confirmação para {email}."

Resultado após substituição: "Olá, João da Silva! Enviamos uma confirmação para [email protected]."

Endpoints

POST /api/enqueue-messages

Enfileirar Mensagens

Este endpoint permite enfileirar uma ou mais mensagens para envio. As mensagens podem ser enviadas imediatamente ou agendadas para envio futuro.

Parâmetros da Requisição

Parâmetro	Tipo	Descrição
`messages`	Array	Array de objetos de mensagem (obrigatório)
`messages.*.phone`	String	Número de telefone do destinatário no formato internacional (ex: 5511999999999)
`messages.*.message`	String	Conteúdo da mensagem
`messages.*.name`	String	Nome do destinatário (opcional)
`messages.*.email`	String	Email do destinatário (opcional)
`scheduled_at`	String	Data e hora para agendamento da mensagem no formato Y-m-d H:i:s (opcional)

Exemplo de Resposta (Sucesso)

{
    "success": true,
    "message": "2 mensagens foram enfileiradas com sucesso",
    "messages": [
        {
            "id": 1,
            "phone": "5511999999999",
            "status": "Pendente",
            "scheduled_at": null
        },
        {
            "id": 2,
            "phone": "5511888888888",
            "status": "Agendada",
            "scheduled_at": "2023-10-10 15:30:00"
        }
    ]
}

GET /api/status

Verificar Status da API

Este endpoint permite verificar se a API está online e obter informações sobre a versão atual.

Exemplo de Resposta

{
    "status": "online",
    "version": "1.0.0",
    "timestamp": "2023-10-10T10:30:00Z"
}

Exemplos de Uso

Enviar mensagens usando cURL

curl -X POST https://hml.zaphero.com.br/api/enqueue-messages \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer zap_Kq3MPVTwMH6hRzP0SEXD2Cicz9NfuMLq" \
  -d '{
    "messages": [
      {
        "phone": "5511999999999",
        "message": "Olá, {name}! Este é um teste para {email}.",
        "name": "João da Silva",
        "email": "[email protected]"
      },
      {
        "phone": "5511888888888",
        "message": "Mensagem 2 via API com token"
      }
    ],
    "scheduled_at": "2023-10-10 15:30:00"
  }'

Exemplo em PHP

<?php
$apiKey = 'zap_Kq3MPVTwMH6hRzP0SEXD2Cicz9NfuMLq';
$url = 'https://hml.zaphero.com.br/api/enqueue-messages';

$data = [
    'messages' => [
        [
            'phone' => '5511999999999',
            'message' => 'Olá, {name}! Este é um teste para {email}.',
            'name' => 'João da Silva',
            'email' => '[email protected]'
        ],
        [
            'phone' => '5511888888888',
            'message' => 'Mensagem 2 via API com token'
        ]
    ],
    'scheduled_at' => '2023-10-10 15:30:00'
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Accept: application/json',
    'Authorization: Bearer ' . $apiKey
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Exemplo em JavaScript

// Usando Fetch API
const apiKey = 'zap_Kq3MPVTwMH6hRzP0SEXD2Cicz9NfuMLq';
const url = 'https://hml.zaphero.com.br/api/enqueue-messages';

const data = {
    messages: [
        {
            phone: '5511999999999',
            message: 'Olá, {name}! Este é um teste para {email}.',
            name: 'João da Silva',
            email: '[email protected]'
        },
        {
            phone: '5511888888888',
            message: 'Mensagem 2 via API com token'
        }
    ],
    scheduled_at: '2023-10-10 15:30:00'
};

fetch(url, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
        'Authorization': `Bearer ${apiKey}`
    },
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Erro:', error));