Documentación de la API

Obtener acceso a la API

1. Pide a soporte que te abra una cuenta.
2. Envía a soporte los servicios que necesitas, tu cuenta y las IP de salida de tus servidores.
3. Después te enviamos una clave de API y la guía de integración completa. Las claves son válidas de 1 a 730 días, y cada clave admite hasta 32 IP de salida.

Conceptos básicos

Autenticación

Envía Authorization: Bearer <clave de API> en cada solicitud

User-Agent

Obligatorio. Cloudflare bloquea las solicitudes que no lo envían (error 1010)

Formato

Solicitudes y respuestas en JSON con UTF-8, excepto la carga de archivos

Hora

Marcas de tiempo Unix en UTC, en milisegundos

Montos

Hasta ocho decimales. Usa un tipo decimal y no redondees a dos decimales

Flujo de integración

1. Consulta los servicios y tu saldo. Guarda el productId que necesitas.
2. Lee la declaración de uso de datos y acéptala si aún no lo has hecho.
3. Sube el archivo de números y guarda el fileId que se devuelve.
4. Obtén una cotización con el productId y el fileId. Revisa la cantidad, el precio unitario y el total.
5. Crea y guarda una clave de idempotencia y después haz el pedido. Esto genera un cargo a tu saldo.
6. Configura un webhook para recibir los cambios de estado y concilia con updatedSince cada 5–10 minutos para no perder ninguno.
7. Cuando el pedido termine, lista los archivos de resultados, descárgalos todos y verifica su sha256. Descarga también los no exitosos.

Ejemplo con curl

Reemplaza los marcadores. Los parámetros completos de cotización y pedido están en la guía que recibes junto con el acceso.

1. Configura tu clave y lista los servicios

   Copiar

   export CHECKIM_TOKEN='reemplaza con la clave de API que te dio soporte'
   export CHECKIM_BASE='https://api.checkim.ai/openapi/v1'
   
   curl -H "Authorization: Bearer $CHECKIM_TOKEN" "$CHECKIM_BASE/products"

2. Sube un archivo de números

   Copiar

   curl -H "Authorization: Bearer $CHECKIM_TOKEN" \
     -F 'file=@./numbers.csv;type=text/csv' \
     "$CHECKIM_BASE/files"

3. Obtén una cotización

   Copiar

   curl -H "Authorization: Bearer $CHECKIM_TOKEN" \
     -H 'Content-Type: application/json' \
     -d '{"productId":"<productId>","name":"batch-001","fileId":"<fileId>"}' \
     "$CHECKIM_BASE/orders/check"

4. Haz el pedido

   Copiar

   # Genera un cargo a tu saldo. Al reintentar, mantén idénticos la clave y el cuerpo.
   curl -H "Authorization: Bearer $CHECKIM_TOKEN" \
     -H 'Content-Type: application/json' \
     -H 'Idempotency-Key: partner-request-001' \
     -d '{"quoteId":"<quoteId>","clientOrderId":"partner-batch-001"}' \
     "$CHECKIM_BASE/orders"

5. Consulta un pedido o concilia por hora de cambio

   Copiar

   curl -H "Authorization: Bearer $CHECKIM_TOKEN" "$CHECKIM_BASE/orders/<orderId>"
   
   curl -H "Authorization: Bearer $CHECKIM_TOKEN" \
     "$CHECKIM_BASE/orders?updatedSince=<UTC ms>&size=100"

6. Lista y descarga los resultados y verifica el sha256

   Copiar

   curl -H "Authorization: Bearer $CHECKIM_TOKEN" "$CHECKIM_BASE/orders/<orderId>/results"
   
   curl -H "Authorization: Bearer $CHECKIM_TOKEN" -o result.csv \
     "$CHECKIM_BASE/orders/<orderId>/results/<fileId>/download"
   shasum -a 256 result.csv

Endpoints

Listar y conciliar pedidos

• Los pedidos se listan del más reciente al más antiguo. Si una página trae nextCursor, envíalo como cursor para obtener la siguiente; la paginación con cursor nunca omite ni repite pedidos aunque lleguen nuevos.
• Filtra por status y por fecha de creación (createdFrom, createdTo, en milisegundos UTC), o busca un pedido por su clientOrderId.
• updatedSince devuelve solo los pedidos cuyo estado cambió después de esa hora, del cambio más antiguo al más reciente. Consúltalo con regularidad y un webhook perdido nunca te hará perder un estado.

Descargar resultados

• Cada archivo de la lista de resultados tiene un sha256. El ETag de la descarga es el mismo valor, así que compáralo después de descargar.
• Las solicitudes con Range reanudan una descarga. Antes verifica que el sha256 no haya cambiado; si cambió, el archivo se regeneró y debes descargarlo completo otra vez.
• Si ya tienes el archivo completo, envía If-None-Match: si no cambió, recibes 304 sin cuerpo.
• Los pedidos grandes con entrega por lotes muestran los lotes terminados mientras se ejecutan; el archivo final, al terminar, es la versión válida.
• En los servicios con foto de perfil (verificación ampliada o de género y edad de Telegram y WhatsApp), la columna avatar del CSV de resultados incluye un enlace de imagen firmado que se puede abrir directamente con GET mientras se conserven los resultados (sin enviar el encabezado Authorization; admite If-None-Match).

Webhooks

• Cuando cambia el estado de un pedido hecho por la API, enviamos un evento por POST a tu URL HTTPS. Requiere el permiso webhook:manage.
• Cada evento trae el encabezado CheckIM-Signature (t=marca de tiempo,v1=firma). Verifícalo con HMAC-SHA256 de "t.cuerpo original de la solicitud" usando tu secreto de firma.
• Cualquier 2xx cuenta como entregado; los fallos se reintentan 9 veces durante unos 2 días. Puedes recibir un evento más de una vez, así que elimina duplicados por su id.
• Las solicitudes salen de la IP fija 34.21.195.36, así que puedes permitir solo esa dirección.

Estados del pedido

Límites y notas

• De forma predeterminada, como máximo 1,200 solicitudes por minuto por IP de salida, 240 por cuenta y 120 por clave. Los encabezados RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset indican cuántas te quedan en el minuto.
• Las cotizaciones y las cargas son lentas, así que cada cuenta puede tener como máximo 3 en curso a la vez. Las demás reciben 429 TOO_MANY_CONCURRENT_REQUESTS.
• Ante un 429 o un 503, espera los segundos que indique Retry-After y reintenta la misma solicitud.
• No hay entorno de pruebas. Cada pedido genera un cargo real.
• Que una consulta exceda el tiempo de espera no significa que el pedido haya fallado. Busca el pedido por orderId o clientOrderId antes de volver a pedir.

Errores comunes

Los errores incluyen code, requestId, message y, opcionalmente, detail.field. Manéjalos según code; message llega en uno de 9 idiomas según Accept-Language y es solo para mostrar.