Validar una Validación de Teléfono

Endpoint

PUT https://api.verifik.co/v2/phone-validations

Confirma el OTP que recibió el usuario. Verifik busca la Phone Validation más reciente en estado sent (y no expirada) para ese teléfono — incluyendo registros manuales / Smart Tools y registros de flujo de proyecto.

Combínalo con el envío

Los OTPs independientes se crean con POST /v2/phone-validations/manual.

Headers

Nombre	Valor
Content-Type	application/json
Authorization	Bearer {YOUR_ACCESS_TOKEN}

Parámetros del body

Parámetro	Tipo	Requerido	Descripción
phone	string	Sí	Mismo número nacional usado al enviar el OTP.
countryCode	string	Sí	Código con +.
otp	number	Sí	Código numérico recibido.
phoneGateway	string	No	sms o whatsapp.
project	string	No	Filtro opcional para registros de flujo.
projectFlow	string	No	Filtro opcional de project flow.

Ejemplo

cURL

curl -X PUT "https://api.verifik.co/v2/phone-validations" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "3001234567",
    "countryCode": "+57",
    "otp": 123456,
    "phoneGateway": "whatsapp"
  }'

Node.js

import axios from "axios";

const { data } = await axios.put(
  "https://api.verifik.co/v2/phone-validations",
  {
    phone: "3001234567",
    countryCode: "+57",
    otp: 123456,
    phoneGateway: "whatsapp",
  },
  {
    headers: {
      Authorization: "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json",
    },
  }
);

console.log(data);

Vigencia del OTP

Los OTP pendientes son válidos durante 10 minutos desde el último envío/reenvío exitoso (expiresAt en la respuesta de creación). Después, este endpoint responde 412 phoneValidation_has_expired. Envía un OTP nuevo (respetando la ventana de ~2 minutos, o usa force: true en el create manual) antes de pedir al usuario que intente de nuevo.

Intentos de OTP

Hoy no hay límite de intentos en el servidor. Un código incorrecto responde 403 otp_does_not_match hasta que expire el registro o se envíe un OTP nuevo. Si necesitan bloqueo o tope de intentos, impleméntenlo en su cliente.

Errores comunes

Status	Mensaje	Cuándo
403	otp_does_not_match	El código no coincide.
412	phoneValidation_has_expired	Expiró el TTL del OTP pendiente (~10 minutos).
409	otp_send_failed	El último registro falló al enviarse (no es lo mismo que expiración).
409	phone_validation_already_validated	El OTP ya fue validado.
404	phone_validation_not_found	No hay Phone Validation para este teléfono.
409	MissingParameter	Faltan campos requeridos.