Documentação da API ProvedorZAP

Bem-vindo à documentação oficial da API ProvedorZAP. Com nossa API, você pode integrar o envio de mensagens do WhatsApp diretamente em seus sistemas, sites e aplicações.

Autenticação

Todas as requisições à API devem ser autenticadas. A autenticação é feita através de uma chave de API (API Key) que deve ser enviada em todas as chamadas como um cabeçalho (header) HTTP.

Qualquer requisição feita sem uma API Key válida retornará um erro 401 Unauthorized ou 403 Forbidden.

URL Base da API

Todos os endpoints listados abaixo devem ser prefixados com a URL base da nossa API:

https://provedorzap.com.br/api

Ciclo de Vida da Sessão

{
    "success": false,
    "errorMessage": "A sessão não está conectada ou pronta. Verifique o status no painel."
}

Endpoints Principais

POST /message/send

Este é o endpoint principal para o envio de mensagens de texto.

Corpo da Requisição (JSON)

Resposta de Sucesso (200 OK)

{"success": true, "messageId": "true_5511..._..."}

POST /message/send-media

Envia um arquivo (imagem, documento, etc.) com uma legenda opcional. A requisição deve ser do tipo multipart/form-data.

Corpo da Requisição (Form Data)

Resposta de Sucesso (200 OK)

{"success": true, "message": "Arquivo enviado com sucesso."}

GET /session/status

Use este endpoint para verificar o status atual da sua conexão com o WhatsApp.

Respostas Possíveis (200 OK)

// Conectado
{ "status": "CONNECTED", "qrCode": null }

// Aguardando leitura de QR Code
{ "status": "PENDING_QR", "qrCode": "2@...longa string..." }

// Desconectado
{ "status": "DISCONNECTED", "qrCode": null }

POST /session/start

Se o status da sua sessão for DISCONNECTED, use este endpoint para iniciar o processo de conexão e gerar um novo QR Code.

Resposta (202 Accepted)

{"message": "Comando de inicialização de sessão enviado."}

Fluxo de Trabalho: Após receber esta resposta, faça chamadas GET para /session/status a cada 3-5 segundos até que o campo qrCode seja preenchido ou o status mude para CONNECTED.

Exemplos de Código

Exemplo Robusto em PHP (cURL)

Este exemplo demonstra como enviar uma mensagem de texto, já implementando a lógica de nova tentativa para lidar com o erro de "Sessão Não Pronta".

<?php

function enviarWhatsApp(string $apiKey, string $numero, string $mensagem): bool {
    $numeroLimpo = preg_replace('/[^0-9]/', '', $numero);
    if (strlen($numeroLimpo) <= 11) {
        $numeroLimpo = '55' . $numeroLimpo;
    }

    $url = "https://provedorzap.com.br/api/message/send";
    $payload = json_encode(['number' => $numeroLimpo, 'message' => $mensagem] );
    $headers = [
        'Content-Type: application/json',
        'x-api-key: ' . $apiKey
    ];

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => $payload,
        CURLOPT_HTTPHEADER => $headers,
        CURLOPT_TIMEOUT => 20
    ]);

    $response = curl_exec($ch);
    $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE );
    curl_close($ch);

    $responseData = json_decode($response, true);

    // Lógica de nova tentativa para sessão "fria"
    if ($http_code === 500 && isset($responseData['errorMessage'] ) && strpos($responseData['errorMessage'], 'sessão não está conectada') !== false) {
        error_log("ProvedorZAP: Sessão não pronta. Aguardando 15 segundos para tentar novamente...");
        sleep(15);
        
        $ch = curl_init($url);
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_POST => true,
            CURLOPT_POSTFIELDS => $payload,
            CURLOPT_HTTPHEADER => $headers,
            CURLOPT_TIMEOUT => 20
        ]);
        $response = curl_exec($ch);
        $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE );
        curl_close($ch);
    }
    
    return $http_code === 200;
}

// --- Exemplo de uso ---
$suaApiKey = 'zap_...';
$numeroDestino = '5511999998888';
$textoMensagem = 'Lembrete: Sua fatura vence amanhã!';

if (enviarWhatsApp($suaApiKey, $numeroDestino, $textoMensagem )) {
    echo "Mensagem enviada com sucesso!";
} else {
    echo "Falha ao enviar a mensagem após todas as tentativas.";
}

?>