WIKICC API

Generador de tarjetas de crédito sintéticas, realistas y coherentes para pruebas de integración.

Introducción

WIKICC API genera tarjetas de crédito de prueba: número válido según el algoritmo de Luhn, BIN real (marca, banco emisor, país), datos de titular (nombre, teléfono, email), dirección completa (calle, ciudad, estado, código postal) real y coherente, e IP geolocalizada al mismo estado.

Todos los datos generados son sintéticos y con fines de prueba (QA, checkout de e-commerce, validación de formularios, etc.). No representan personas, cuentas ni tarjetas reales.

Autenticación

Cada tienda/servicio recibe un token personal generado desde el panel de administración (/admin/ → Clientes API (tiendas) → "Generar token para una tienda").

El token se envía en cada petición mediante el header Authorization:

Authorization: Api-Key TU_TOKEN_AQUI

Si el token falta, es inválido o está desactivado, la API responde 401.

¿Por qué los datos son coherentes?

La dirección de cada tarjeta (calle, ciudad, estado y código postal) siempre se obtiene de un único registro geográfico real (dataset curado de USPS/GeoNames), nunca se combinan campos elegidos por separado. Esto evita el problema típico de otros generadores donde el zip code no corresponde a la ciudad o el estado.

La calle usa calles reales de OpenStreetMap para las ciudades cacheadas (comando fetch_streets_osm); si una ciudad no está cacheada, cae a calles plausibles por país (Faker para US/MX/CO/AR/CL/ES/GB/CA, JSON curado para PE/DO).

La IP geolocaliza al mismo estado que la dirección usando la base DB-IP City Lite (comando import_dbip). Si el estado no tiene rango, cae a nivel país. Siempre tiene valor.

Países soportados en esta versión: US, MX, CO, AR, CL, PE, DO, ES, GB, CA.

POST /api/v1/cards/generate/

Genera una o más tarjetas sintéticas coherentes.

Body (JSON)

Campo	Tipo	Requerido	Descripción
`country`	string	No	País ISO alpha-2 (US, MX, CO, AR, CL, PE, DO, ES, GB, CA). Si se omite, se elige uno soportado al azar.
`scheme`	string	No	Marca de tarjeta (VISA, MASTERCARD, AMEX, ...).
`bin`	string	No	BIN exacto a usar (debe existir en la base local).
`non_vbv`	bool	No	Si es true, solo BINs marcados non-VBV; si es false, solo los que no lo son.
`quantity`	int	No	Cantidad a generar (mínimo 1, sin límite máximo; por defecto 1).

Respuesta 200

{
  "count": 1,
  "results": [
    {
      "number": "4557360012345678",
      "scheme": "VISA",
      "card_type": "CREDIT",
      "card_tier": "CLASSIC",
      "issuer": "BANCO EJEMPLO",
      "bin": "455736",
      "non_vbv": false,
      "exp_month": "08",
      "exp_year": "29",
      "exp": "08/29",
      "cvv": "123",
      "holder": {
        "name": "Laura Martínez",
        "phone": "+52 55 1234 5678",
        "email": "[email protected]"
      },
      "address": {
        "street": "Avenida Chapultepec 1421",
        "city": "Guadalajara",
        "state": "Jalisco",
        "postal_code": "44100",
        "country": "MX",
        "country_name": "Mexico"
      },
      "ip": "187.162.45.10"
    }
  ]
}

GET /api/v1/meta/countries/

Lista los países soportados junto con la cantidad de localidades y BINs disponibles localmente.

{
  "count": 7,
  "results": [
    {"country_a2": "US", "localities_available": 30116, "bins_available": 42},
    {"country_a2": "MX", "localities_available": 2457, "bins_available": 15}
  ]
}

GET /api/v1/meta/schemes/?country=MX

Lista las marcas de tarjeta (schemes) disponibles, opcionalmente filtradas por país.

{"count": 3, "results": ["AMERICAN EXPRESS", "MASTERCARD", "VISA"]}

POST /api/v1/ops/bootstrap/

Recomendado para producción. Ejecuta en una sola llamada: siembra geodata, sincroniza BINs e importa rangos IP (DB-IP). Requiere token con can_sync_bins. Puede tardar 1–3 minutos la primera vez.

Body (JSON, opcional)

Campo	Tipo	Default	Descripción
`countries`	array[string]	todos	Países a procesar en geodata y BINs.
`flush_ip`	bool	false	Reimportar rangos IP desde DB-IP (actualización mensual).
`skip`	array[string]	[]	Omitir pasos: `geodata`, `bins`, `ip_ranges`.

Ejemplo

curl -X POST https://TU_DOMINIO/api/v1/ops/bootstrap/ \
  -H "Authorization: Api-Key TU_TOKEN_OPS" \
  -H "Content-Type: application/json" \
  -d '{}' \
  --max-time 300

Cuando readiness.all_ready es true, el generador está listo.

POST /api/v1/bins/sync/

Sincroniza BINs reales desde pm-api y hace upsert local. Usa el mismo token (Authorization: Api-Key <token>), pero el token debe tener activada la opción "puede sincronizar BINs" en el admin (Clientes API → campo can_sync_bins). Un token de tienda normal recibirá 403.

Body (JSON, opcional)

Campo	Tipo	Requerido	Descripción
`countries`	array[string]	No	Países ISO alpha-2 a sincronizar. Si se omite, sincroniza todos los soportados.

Ejemplo (token con permiso de sincronización)

curl -X POST https://TU_DOMINIO/api/v1/bins/sync/ \
  -H "Authorization: Api-Key TU_TOKEN_CON_PERMISO_SYNC" \
  -H "Content-Type: application/json" \
  -d '{"countries": ["US", "MX"]}'

Respuesta 200

{
  "results": [
    {"country_a2": "US", "created": 0, "updated": 3, "skipped": 0, "errors": []},
    {"country_a2": "MX", "created": 1, "updated": 0, "skipped": 0, "errors": []}
  ]
}

Configuración: IP que coincide con el estado

La IP usa la base DB-IP City Lite (gratuita, sin token, CC BY 4.0). El comando la descarga e importa automáticamente (solo los 7 países):

python manage.py import_dbip
# O desde archivo local:
python manage.py import_dbip --file /ruta/dbip-city-lite.csv.gz
# Re-importar desde cero:
python manage.py import_dbip --flush

Tras importar, la IP geolocaliza al mismo estado que la dirección. Distintos proveedores de geo-IP pueden discrepar en ~10-15% de los rangos; whatismyipaddress.com usa IP2Location (existe también import_iplocation para máxima coincidencia con ese servicio).

Atribución requerida: IP geolocation by DB-IP (https://db-ip.com).

Calles reales por ciudad (opcional)

Para usar calles reales de OpenStreetMap en vez de calles plausibles, precarga la caché:

python manage.py fetch_streets_osm --country DO
python manage.py fetch_streets_osm --country MX --limit 100
python manage.py fetch_streets_osm --country CO --city "Medellín"

Atribución requerida: "This site or product includes IP2Location LITE data available from https://lite.ip2location.com."

Errores

Todos los errores siguen el mismo formato:

{"error": {"code": "bin_not_found", "message": "..."}}

HTTP	Código	Causa
401	`invalid_api_key`	Token ausente, inválido o desactivado.
403	`error`	El token no tiene permiso para la acción (p. ej. sincronizar BINs sin `can_sync_bins`).
400	`unsupported_country`	País no soportado todavía.
400	`validation_error`	Parámetros inválidos en el body.
404	`bin_not_found`	El BIN indicado no existe localmente.
503	`no_locality_available`	Falta sembrar datos geográficos del país.

Ejemplos de integración

cURL

curl -X POST https://TU_DOMINIO/api/v1/cards/generate/ \
  -H "Authorization: Api-Key TU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{"country": "MX", "scheme": "VISA", "quantity": 3}'

Python (requests)

import requests

resp = requests.post(
    "https://TU_DOMINIO/api/v1/cards/generate/",
    headers={"Authorization": "Api-Key TU_TOKEN_AQUI"},
    json={"country": "US", "quantity": 5},
)
print(resp.json())

JavaScript (fetch)

const res = await fetch("https://TU_DOMINIO/api/v1/cards/generate/", {
  method: "POST",
  headers: {
    "Authorization": "Api-Key TU_TOKEN_AQUI",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ country: "CO", quantity: 1 }),
});
const data = await res.json();
console.log(data);

También puedes explorar y probar la API de forma interactiva en Swagger UI, o descargar el esquema OpenAPI. Para integraciones automatizadas por IA, consulta el archivo API_DOCS.md en la raíz del repositorio.