Chamar endpoints como fila (async)

Qualquer consulta do catálogo pode esperar o resultado (sync) ou responder imediatamente (queue / Async). O modo fila cria um Smart Batch de uma linha. Um worker chama depois o mesmo endpoint e registra a tentativa. Os créditos são cobrados nessa chamada do worker, não no enqueue.

Esta página é o guia de A a Z para chamar endpoints como fila no seu backend. Para o produto, o assistente e o dashboard, comece por SmartBatch.

Quando usar async

Use type=queue quando não quiser que seu cliente HTTP espere uma consulta lenta:

Você tratará o resultado depois com um webhook ou e-mail.
Abrirá o lote em ai.verifik.co e acompanhará o dashboard.
Fará poll em GET /v2/smart-batches/:id em api.verifik.co.

Use sync (omita type ou envie type=sync) quando precisar do payload de identidade na mesma resposta.

Autenticação

Use o mesmo JWT de cliente que você já envia para api.verifik.co.

Authorization: Bearer <client JWT>

async.verifik.co encaminha esse header. O Node valida o token, guarda o lote e depois emite um JWT de curta duração para o worker chamar o feature como seu cliente. Você não armazena uma segunda chave para a fila.

URL base

https://async.verifik.co

Acrescente o mesmo path de catálogo documentado para o feature. Exemplos:

Feature	Path
Cédula colombiana	`/v2/co/cedula`
Afiliações colombianas (SISPRO)	`/v2/co/afiliaciones`
DNI peruano	`/v2/pe/cedula`

Features passwordless e PDF sem URL de catálogo não podem ser enfileirados.

O parâmetro queue

Adicione type=queue à mesma query (GET) ou body (POST) que você já envia.

`type`	O que acontece	Resposta
omitido ou `sync`	Espera o feature e devolve esse body	`200` / `401` / `404` / `409` / `504`
`queue`	Cria um Smart Batch de uma linha. Não chama o feature nesta requisição	`202`

type deve ser omitido, sync ou queue. Qualquer outro valor é erro de validação.

Request

Cédula colombiana

curl
Node.js
Python

curl -sS -H "Authorization: Bearer $JWT" \
  "https://async.verifik.co/v2/co/cedula?documentType=CC&documentNumber=1032386359&type=queue"

import axios from 'axios';

const { data, status } = await axios.get(
  'https://async.verifik.co/v2/co/cedula',
  {
    params: {
      documentType: 'CC',
      documentNumber: '1032386359',
      type: 'queue',
    },
    headers: {
      Authorization: `Bearer ${process.env.JWT}`,
    },
  },
);

console.log(status, data);

import os
import requests

response = requests.get(
    "https://async.verifik.co/v2/co/cedula",
    params={
        "documentType": "CC",
        "documentNumber": "1032386359",
        "type": "queue",
    },
    headers={"Authorization": f"Bearer {os.environ['JWT']}"},
)
print(response.status_code, response.json())

Afiliações colombianas (SISPRO)

curl
Node.js
Python

curl -sS -H "Authorization: Bearer $JWT" \
  "https://async.verifik.co/v2/co/afiliaciones?documentType=CC&documentNumber=1007463534&date=09/05/2008&type=queue"

import axios from 'axios';

const { data, status } = await axios.get(
  'https://async.verifik.co/v2/co/afiliaciones',
  {
    params: {
      documentType: 'CC',
      documentNumber: '1007463534',
      date: '09/05/2008',
      type: 'queue',
    },
    headers: {
      Authorization: `Bearer ${process.env.JWT}`,
    },
  },
);

console.log(status, data);

import os
import requests

response = requests.get(
    "https://async.verifik.co/v2/co/afiliaciones",
    params={
        "documentType": "CC",
        "documentNumber": "1007463534",
        "date": "09/05/2008",
        "type": "queue",
    },
    headers={"Authorization": f"Bearer {os.environ['JWT']}"},
)
print(response.status_code, response.json())

DNI peruano

curl
Node.js
Python

curl -sS -H "Authorization: Bearer $JWT" \
  "https://async.verifik.co/v2/pe/cedula?documentType=DNI&documentNumber=12345678&type=queue"

import axios from 'axios';

const { data, status } = await axios.get(
  'https://async.verifik.co/v2/pe/cedula',
  {
    params: {
      documentType: 'DNI',
      documentNumber: '12345678',
      type: 'queue',
    },
    headers: {
      Authorization: `Bearer ${process.env.JWT}`,
    },
  },
);

console.log(status, data);

import os
import requests

response = requests.get(
    "https://async.verifik.co/v2/pe/cedula",
    params={
        "documentType": "DNI",
        "documentNumber": "12345678",
        "type": "queue",
    },
    headers={"Authorization": f"Bearer {os.environ['JWT']}"},
)
print(response.status_code, response.json())

Em endpoints POST, envie type no JSON junto com os demais campos. Não o grave como campo de entrada: o serviço remove type antes de salvar inputData.

Response

202

{
  "status": "queued",
  "batchId": "665f0c2e2c1a4a0012ab3456",
  "rowIndex": 0,
  "attemptCount": 0
}

Campo	Significado
`status`	Sempre `queued` em um enqueue bem-sucedido
`batchId`	Id do Smart Batch. Abra em ai.verifik.co ou faça poll no Node
`rowIndex`	Linha nesse lote (chamadas de API de uma linha usam `0`)
`attemptCount`	Tentativas já registradas (`0` no enqueue)

O que acontece depois

A requisição cria ou reutiliza uma configuração Async para o seu cliente e queue key.
Você recebe 202 imediatamente. Seu JWT não é armazenado na linha.
Um worker reivindica a linha, chama a URL do feature e acrescenta uma tentativa.
Quando a linha ou o lote é terminal, o Node faz POST no webhook da configuração e envia e-mails se você os configurou.

Queue keys:

Feature	Queue key	Nome da config
Cédula colombiana	`co.cedula.queue`	Queue Cedula
Afiliações colombianas	`co.sispro.queue`	Queue SISPRO
Qualquer outro feature do catálogo	`{featureCode}.queue`	`Queue {feature name}`

Edite uma vez a configuração automática Queue … (webhook, e-mails). Chamadas posteriores com type=queue a reutilizam.

Os créditos são cobrados na chamada do worker, não no 202.

Como obter o resultado

Webhook ou e-mail

Defina URL do webhook e E-mails ao concluir na configuração em lote em ai.verifik.co (assistente Criar → Revisar e criar, ou edite a config). Não são parâmetros de consulta.

A lista e o detalhe de webhooks no Smart Monitor mostram quais configurações em lote estão vinculadas.

Dashboard do Smart-Agent

Abra https://ai.verifik.co, vá ao lote (batchId do 202) e acompanhe status, tentativas, custo por linha e o webhook vinculado.

Você também pode criar primeiro a configuração (Modo de execução Async) e depois enfileirar pela API para que as linhas caiam nessa receita.

Poll do lote

GET https://api.verifik.co/v2/smart-batches/{batchId}
Authorization: Bearer <same client JWT>

O detalhe da linha inclui a linha do tempo de tentativas. Uma tentativa concluída contém o payload do feature.

Limites

Features passwordless e geradores PDF não têm URL de catálogo, então não podem ser enfileirados.
404 e erros de validação (MissingParameter e semelhantes) não são retentados.
Resultados retentáveis são 429, 5xx e códigos de timeout / upstream indisponível.
type só pode ser sync, queue ou omitido.

Enqueue explícito opcional

Prefira type=queue no path do catálogo. Se você já conhece o queue key, pode criar a linha diretamente:

POST https://api.verifik.co/v2/smart-batches/from-queue
Authorization: Bearer <client JWT>
Content-Type: application/json

{
  "queueKey": "peru_identity_lookup.queue",
  "name": "Queue Peru - National ID Verification",
  "featureCode": "peru_identity_lookup",
  "inputData": {
    "documentType": "DNI",
    "documentNumber": "12345678"
  }
}

Use https://async.verifik.co/{path}?type=queue salvo se precisar deste body explícito.

Relacionado

SmartBatch — assistente da UI, Async vs Sync, notificações
Peru — Cidadão (DNI)

Quando usar async​

Autenticação​

URL base​

O parâmetro queue​

Request​

Cédula colombiana​

Afiliações colombianas (SISPRO)​

DNI peruano​

Response​

O que acontece depois​

Como obter o resultado​

Webhook ou e-mail​

Dashboard do Smart-Agent​

Poll do lote​

Limites​

Enqueue explícito opcional​

Relacionado​