Appeler les endpoints en file (async)

Toute consultation du catalogue peut attendre le résultat (sync) ou répondre immédiatement (queue / Async). Le mode file crée un Smart Batch d'une ligne. Un worker appelle ensuite le même endpoint et enregistre la tentative. Les crédits sont débités sur cet appel worker, pas à l'enqueue.

Cette page est le guide de A à Z pour appeler les endpoints en file depuis votre backend. Pour le produit, l'assistant et le tableau de bord, commencez par SmartBatch.

Quand utiliser async

Utilisez type=queue lorsque vous ne voulez pas que votre client HTTP attende une consultation lente :

• Vous traiterez le résultat plus tard avec un webhook ou un e-mail.
• Vous ouvrirez le lot sur ai.verifik.co et suivrez le tableau de bord.
• Vous ferez un poll GET /v2/smart-batches/:id sur api.verifik.co.

Utilisez sync (omettez type, ou envoyez type=sync) lorsque vous avez besoin du payload d'identité sur la même réponse.

Authentification

Utilisez le même JWT client que vous envoyez déjà à api.verifik.co.

Authorization: Bearer <client JWT>

async.verifik.co transmet cet en-tête. Node valide le jeton, enregistre le lot, puis émet un JWT de courte durée pour que le worker appelle la fonctionnalité en tant que votre client. Vous ne stockez pas une deuxième clé pour la file.

URL de base

https://async.verifik.co

Ajoutez le même chemin catalogue documenté pour la fonctionnalité. Exemples :

Fonctionnalité	Chemin
Cédula colombienne	/v2/co/cedula
Affiliations colombiennes (SISPRO)	/v2/co/afiliaciones
DNI péruvien	/v2/pe/cedula

Les fonctionnalités passwordless et PDF sans URL de catalogue ne peuvent pas être enfilées.

Le paramètre queue

Ajoutez type=queue à la même query (GET) ou au même body (POST) que vous envoyez déjà.

type	Ce qui se passe	Réponse
omis ou sync	Attend la fonctionnalité et renvoie ce body	200 / 401 / 404 / 409 / 504
queue	Crée un Smart Batch d'une ligne. N'appelle pas la fonctionnalité sur cette requête	202

type doit être omis, sync ou queue. Toute autre valeur est une erreur de validation.

Request

Cédula colombienne

curl

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

Node.js

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);

Python

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())

Affiliations colombiennes (SISPRO)

curl

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

Node.js

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);

Python

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 péruvien

curl

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

Node.js

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);

Python

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())

Sur les endpoints POST, envoyez type dans le JSON avec le reste des champs. Ne le stockez pas comme champ d'entrée : le service retire type avant d'enregistrer inputData.

Response

202

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

Champ	Signification
status	Toujours queued après un enqueue réussi
batchId	Id du Smart Batch. Ouvrez-le sur ai.verifik.co ou faites un poll Node
rowIndex	Ligne dans ce lot (les appels API d'une ligne utilisent 0)
attemptCount	Tentatives déjà enregistrées (0 à l'enqueue)

Ce qui se passe ensuite

1. La requête crée ou réutilise une configuration Async pour votre client et votre queue key.
2. Vous recevez 202 immédiatement. Votre JWT n'est pas stocké sur la ligne.
3. Un worker revendique la ligne, appelle l'URL de la fonctionnalité et ajoute une tentative.
4. Lorsque la ligne ou le lot est terminal, Node POSTe le webhook de la configuration et envoie les e-mails si vous les avez configurés.

Queue keys :

Fonctionnalité	Queue key	Nom de la config
Cédula colombienne	co.cedula.queue	Queue Cedula
Affiliations colombiennes	co.sispro.queue	Queue SISPRO
Toute autre fonctionnalité catalogue	{featureCode}.queue	Queue {feature name}

Modifiez une fois la configuration automatique Queue … (webhook, e-mails). Les appels type=queue suivants la réutilisent.

Les crédits sont débités sur l'appel worker, pas sur le 202.

Comment obtenir le résultat

Webhook ou e-mail

Définissez URL du webhook et E-mails à la fin sur la configuration de lot dans ai.verifik.co (assistant Créer → Examiner et créer, ou modifiez la config). Ce ne sont pas des paramètres de requête.

La liste et le détail des webhooks dans Smart Monitor indiquent quelles configurations de lot sont liées.

Tableau de bord Smart-Agent

Ouvrez https://ai.verifik.co, allez au lot (batchId du 202) et suivez le statut, les tentatives, le coût par ligne et le webhook lié.

Vous pouvez aussi créer d'abord la configuration (Mode d'exécution Async), puis enfiler depuis l'API pour que les lignes atterrissent sur cette recette.

Poll du lot

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

Le détail de la ligne inclut la chronologie des tentatives. Une tentative terminée contient le payload de la fonctionnalité.

Limites

• Les fonctionnalités passwordless et générateurs PDF n'ont pas d'URL de catalogue, elles ne peuvent pas être enfilées.
• 404 et les erreurs de validation (MissingParameter et similaires) ne sont pas relancées.
• Les résultats relançables sont 429, 5xx et les codes timeout / upstream indisponible.
• type n'est que sync, queue, ou omis.

Enqueue explicite facultatif

Préférez type=queue sur le chemin catalogue. Si vous connaissez déjà la queue key, vous pouvez créer la ligne directement :

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"
  }
}

Utilisez https://async.verifik.co/{path}?type=queue sauf si vous avez besoin de ce body explicite.

Voir aussi

• SmartBatch — assistant UI, Async vs Sync, notifications
• Pérou — Citoyen (DNI)