Pular para o conteúdo principal
POST
/
instances
/
{instanceId}
/
token
/
{token}
/
passkey-prologue
Concluir o Challenge
curl --request POST \
  --url https://api.z-api.io/instances/{instanceId}/token/{token}/passkey-prologue \
  --header 'Client-Token: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": "<string>",
  "rawId": "<string>",
  "type": "<string>",
  "response": {
    "authenticatorData": "<string>",
    "clientDataJSON": "<string>",
    "signature": "<string>",
    "userHandle": "<string>"
  }
}
'

​
Conceituação

Em alguns dispositivos, o WhatsApp passou a exigir uma verificação adicional ao tentar conectar ao WhatsApp, chamada de Chave de Acesso (Passkey). Devido a isso, tais dispositivos, quando tentarem ler o QR Code podem receber o retorno do Challenge.
Este método faz parte do fluxo de conexão da instância via Passkey (WebAuthn), sendo a etapa final desse processo:
  1. O endpoint de QR Code é chamado e retorna um challenge.
  2. Esse challenge é resolvido no dispositivo / autenticador (procedimento feito fora do Z-API, e que não depende da nossa API).
  3. O resultado dessa resolução (a assertion WebAuthn) é enviado para este endpoint, para que a instância conclua a conexão.
A resolução do challenge acontece diretamente entre o dispositivo do usuário e o autenticador (Passkey), fora do ecossistema Z-API. Este endpoint apenas recebe o resultado já processado.Pensando nessa nova autenticação do WhatsApp, o Z-API criou uma extensão chamada Z-API Connector, justamente para facilitar essa validação da Chave de Acesso.

​
Atributos

​
Obrigatórios

​
instanceId
string
obrigatório
ID da sua instância. Disponível no painel Z-API em Instâncias.
​
token
string
obrigatório
Token da sua instância Z-API.

​
Obrigatórios

​
id
string
obrigatório
Identificador da credencial gerada pelo autenticador
​
rawId
string
obrigatório
Identificador bruto (raw) da credencial
​
type
string
obrigatório
Tipo da credencial. Sempre “public-key”
​
response
object
obrigatório
Dados da assinatura WebAuthn retornados pelo autenticador

​
Opcionais

​
clientExtensionResults
object
Extensões do cliente retornadas pelo autenticador

​
Request Body

{
  "id": "...",
  "rawId": "...",
  "type": "public-key",
  "response": {
    "authenticatorData": "...",
    "clientDataJSON": "...",
    "signature": "...",
    "userHandle": null
  },
  "clientExtensionResults": { "uvm": [] }
}

​
Response

​
200

Retorna o resultado do processamento da assertion pelo middleware da instância. Existem três variações possíveis: Sucesso: 
{ "success": true }
Falha — campos obrigatórios ausentes: 
{ "success": false, "reason": "assertion (rawId + response) is required" }
Falha — tipo de campo inválido: 
{ "success": false, "reason": "assertion fields must be strings" }
Respostas com success: false indicam que o payload da assertion está malformado — é necessário corrigir o corpo enviado e reenviar. Não se trata de um erro de infraestrutura do Z-API.

​
400

Retornado nos seguintes casos:
  • Instância não encontrada para o par instanceId + token:
{ "error": "Instance not found", "value": null }

​
405

Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.

​
415

Caso você receba um erro 415, certifique de adicionar na headers da requisição o “Content-Type” do objeto que você está enviando, em sua grande maioria “application/json”.