Crear una Validación de Teléfono manual

Endpoint

POST https://api.verifik.co/v2/phone-validations/manual

Crea una Phone Validation independiente y envía un OTP por SMS o WhatsApp. No se requiere project ni projectFlow. Es el mismo endpoint que usa Smart Tools → Mensajes de WhatsApp / SMS.

Tras un envío exitoso, continúa con Validar una Validación de Teléfono.

Facturación

Los créditos se verifican antes de enviar el mensaje, según el precio del país. Solo se cobran cuando el OTP se entrega (sent: true).

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í	Solo número nacional (se eliminan espacios). No incluyas el código de país aquí.
countryCode	string	Sí	Código con + (ej. +57). Envíalo siempre y muéstralo al usuario junto al teléfono (ej. +57 3001234567).
phoneGateway	string	Sí	sms o whatsapp.
title	string	No	Nombre de empresa en la plantilla (1–15 caracteres). Se usa en WhatsApp flow2 y en el texto SMS.
language	string	No	Idioma de la plantilla (en, es, …). Elige flow2_en / flow2_es cuando whatsappTemplate es flow2.
whatsappTemplate	string	No	Solo WhatsApp. authentication (por defecto) o flow2. Se ignora en SMS.
force	boolean	No	Si es true, omite la ventana de ~2 minutos de reenvío para el mismo teléfono + gateway. Úsalo en un botón “Reenviar”.
ipAddress	string	No	IP opcional para auditoría.

Plantillas de WhatsApp

whatsappTemplate	Plantilla Meta	Notas
authentication (por defecto)	authentication	OTP en el cuerpo + parámetro de botón URL.
flow2	flow2_es / flow2_en	Encabezado/cuerpo con marca (title como sección) + código + acción; el idioma elige la variante.

{
  "phone": "3001234567",
  "countryCode": "+57",
  "phoneGateway": "whatsapp",
  "title": "Company ABC",
  "language": "es",
  "whatsappTemplate": "flow2"
}

Ejemplos de solicitud

cURL

curl -X POST "https://api.verifik.co/v2/phone-validations/manual" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "3001234567",
    "countryCode": "+57",
    "phoneGateway": "whatsapp",
    "title": "Company ABC",
    "language": "es"
  }'

Node.js

import axios from "axios";

const { data } = await axios.post(
  "https://api.verifik.co/v2/phone-validations/manual",
  {
    phone: "3001234567",
    countryCode: "+57",
    phoneGateway: "whatsapp",
    title: "Company ABC",
    language: "es",
  },
  {
    headers: {
      Authorization: "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json",
    },
  }
);

console.log(data);

Vigencia del OTP y reenvío

Regla	Valor por defecto	Notas
TTL del OTP	10 minutos	Se devuelve en data.expiresAt tras un envío exitoso. Después, la verificación responde 412 phoneValidation_has_expired.
Ventana de reenvío	~2 minutos	Un segundo envío para el mismo cliente + teléfono + phoneGateway en ~2 minutos responde 409 otp_recently_sent (sin mensaje nuevo).
Forzar reenvío	"force": true	Omite la ventana de 2 minutos para enviar un código nuevo de inmediato (p. ej. botón “Reenviar”). Cada envío/reenvío exitoso reinicia expiresAt a +10 minutos.

Guía de UI

Muestra el destino como countryCode + phone nacional (ej. +57 3001234567). Usa expiresAt para la cuenta regresiva de expiración y habilita “Reenviar” tras la ventana de 2 minutos (o siempre con force: true).

Errores comunes

Status	Mensaje	Cuándo
403	insufficient_credits	Saldo insuficiente. No se envía el mensaje.
409	otp_recently_sent	Cooldown: ya se envió un OTP a este teléfono + gateway en ~2 minutos (y force no es true).
409	otp_not_sent	Falló el envío del proveedor. Distinto del cooldown.
409	MissingParameter	Faltan campos o countryCode no tiene formato +dígitos.
403	Forbidden	La función de mensajería SMS/WhatsApp no está disponible en la cuenta.

Siguiente paso

Verifica el código con PUT /v2/phone-validations.