Origens do SDK

Consultar origens do SDK

curl --request GET \
  --url https://api.omni.z-api.io/instances/{channelId}/sdk-info \
  --header 'Authorization: <api-key>'

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://api.omni.z-api.io/instances/{channelId}/sdk-info', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.omni.z-api.io/instances/{channelId}/sdk-info",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.omni.z-api.io/instances/{channelId}/sdk-info"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.omni.z-api.io/instances/{channelId}/sdk-info")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "allowOrigins": [
    "https://app.suaempresa.com",
    "http://localhost:3000"
  ]
}

{
  "error": 123,
  "message": "<string>"
}

{
  "error": 123,
  "message": "<string>"
}

GET

instances

{channelId}

sdk-info

Consultar origens do SDK

curl --request GET \
  --url https://api.omni.z-api.io/instances/{channelId}/sdk-info \
  --header 'Authorization: <api-key>'

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://api.omni.z-api.io/instances/{channelId}/sdk-info', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.omni.z-api.io/instances/{channelId}/sdk-info",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.omni.z-api.io/instances/{channelId}/sdk-info"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.omni.z-api.io/instances/{channelId}/sdk-info")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "allowOrigins": [
    "https://app.suaempresa.com",
    "http://localhost:3000"
  ]
}

{
  "error": 123,
  "message": "<string>"
}

{
  "error": 123,
  "message": "<string>"
}

Conceituação

O SDK de conexão resolve { success: false } sem dizer o motivo. Na prática ele falha por dois caminhos muito diferentes, e este endpoint resolve o primeiro.

Falha 1 — origem não liberada

O SDK só funciona a partir de domínios cadastrados em allowOrigins. Se a origem do navegador não estiver na lista, ele aborta com:

[Omni Z-API SDK] Origin "https://app.suaempresa.com" is not in the allowed origins list.

Use este endpoint antes de chamar o SDK para saber se a origem atual está liberada:

const info = await fetch(
  `https://api.omni.z-api.io/instances/${channelId}/sdk-info`,
  { headers: { Authorization: SUA_PUBLIC_KEY } },
).then((r) => r.json());

const liberado = info.allowOrigins.includes(window.location.origin);

O domínio do painel do Omni Z-API é sempre aceito, mesmo sem constar em allowOrigins. Você só precisa cadastrar os seus domínios — inclusive http://localhost:3000 para desenvolvimento.

Cadastrar origens é feito no painel, em Segurança. Não há endpoint público para isso.

O SDK abre uma janela com window.open. Se você chamar client.connect() depois de um await, o gesto do usuário já se perdeu e o navegador bloqueia o popup — o SDK também devolve { success: false }.

// Errado: o await consome o gesto do clique
async function onClick() {
  const dados = await carregarAlgo();
  await client.connect({ channelId });   // popup bloqueado
}

// Certo: connect() é a primeira coisa após o clique
async function onClick() {
  const promessa = client.connect({ channelId });
  const dados = await carregarAlgo();
  await promessa;
}

Autenticação

Este é o único endpoint que aceita a Public Key, e ela vai crua no header — sem Bearer:

curl https://api.omni.z-api.io/instances/ID_DO_CANAL/sdk-info \
  -H "Authorization: SUA_PUBLIC_KEY"

Isso é intencional: o endpoint é chamado do frontend, onde a Public Key pode ser exposta.

Autorizações

Authorization

string

header

obrigatório

Parâmetros de caminho

channelId

string

obrigatório

ID do canal

Exemplo:

"019E4C54B1B375A28970B605CA9B03C3"

Resposta

Origens do canal

allowOrigins

string[]

Origens liberadas para o SDK

Canais

Mensagens

Templates (WhatsApp)

Flows (WhatsApp)

Webhooks

Conceituação

Falha 1 — origem não liberada

Autenticação

Autorizações

Parâmetros de caminho

Resposta

​Conceituação

​Falha 1 — origem não liberada

​Falha 2 — popup bloqueado

​Autenticação

Autorizações

Parâmetros de caminho

Resposta

Conceituação

Falha 1 — origem não liberada

Falha 2 — popup bloqueado

Autenticação