{"openapi":"3.1.0","info":{"title":"datamockseed API","version":"1.0.0","description":"Generate and validate fake test data (Spanish DNI/NIE/CIF, IBAN, cards, phone numbers, identities…) with valid check digits. Anonymous, rate-limited per IP. Human-readable messages default to Spanish: add `lang=en` or send `Accept-Language: en` to get them in English.","contact":{"name":"datamockseed","url":"https://datamockseed.firstflip.es"}},"servers":[{"url":"https://datamockseed.firstflip.es/api/v1"}],"paths":{"/generators":{"get":{"summary":"List the available generators","operationId":"listGenerators","parameters":[{"name":"lang","in":"query","required":false,"schema":{"type":"string","enum":["es","en"],"default":"es"},"description":"Language of the human-readable texts in the response (validation `reason`, error `message`, generator `label`). Takes precedence over the `Accept-Language` header; defaults to Spanish. Generated data is the same in every language."}],"responses":{"200":{"description":"Generators and their default options","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/{locale}/{generator}":{"get":{"summary":"Generate records of one type","operationId":"generate","parameters":[{"name":"locale","in":"path","required":true,"schema":{"type":"string","enum":["es"]}},{"name":"generator","in":"path","required":true,"schema":{"type":"string","enum":["document","phone","identity","iban","card","passport","uuid","username","password"]}},{"name":"count","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":1}},{"name":"seed","in":"query","required":false,"schema":{"type":"string"},"description":"Same as the X-Seed header."},{"name":"X-Seed","in":"header","required":false,"schema":{"type":"string"}},{"name":"lang","in":"query","required":false,"schema":{"type":"string","enum":["es","en"],"default":"es"},"description":"Language of the human-readable texts in the response (validation `reason`, error `message`, generator `label`). Takes precedence over the `Accept-Language` header; defaults to Spanish. Generated data is the same in every language."}],"responses":{"200":{"description":"Generated records","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid locale or parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Unknown generator","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"\"count\" exceeds the limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/{locale}/bulk":{"post":{"summary":"Generate composite records from a schema","operationId":"bulkGenerate","parameters":[{"name":"locale","in":"path","required":true,"schema":{"type":"string","enum":["es"]}},{"name":"lang","in":"query","required":false,"schema":{"type":"string","enum":["es","en"],"default":"es"},"description":"Language of the human-readable texts in the response (validation `reason`, error `message`, generator `label`). Takes precedence over the `Accept-Language` header; defaults to Spanish. Generated data is the same in every language."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["fields"],"properties":{"seed":{"type":"string"},"count":{"type":"integer","minimum":1,"maximum":10000,"default":10},"format":{"type":"string","enum":["json","csv","sql","typescript","xml"],"default":"json"},"table":{"type":"string"},"createTable":{"type":"boolean"},"fields":{"type":"array","minItems":1,"items":{"type":"object","required":["name","type"],"properties":{"name":{"type":"string"},"type":{"type":"string","enum":["nombre_completo","nombre","apellidos","sexo","fecha_nacimiento","edad","documento","nss","email","usuario","telefono_movil","telefono_fijo","direccion","cp","municipio","provincia","comunidad","razon_social","cif","iban","bic","entidad_bancaria","ccc","tarjeta","uuid","numero","fecha","booleano","lorem","matricula","pasaporte","password"]},"options":{"type":"object"},"nullable":{"type":"number","minimum":0,"maximum":100}}}}}}}}},"responses":{"200":{"description":"JSON, or the exported text (CSV/SQL/XML/TypeScript) depending on `format`/`Accept`"},"400":{"description":"Invalid body or schema","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"\"count\" exceeds the limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/validate":{"post":{"summary":"Validate a DNI/NIE/CIF/IBAN/CCC/NSS/card number","operationId":"validate","parameters":[{"name":"lang","in":"query","required":false,"schema":{"type":"string","enum":["es","en"],"default":"es"},"description":"Language of the human-readable texts in the response (validation `reason`, error `message`, generator `label`). Takes precedence over the `Accept-Language` header; defaults to Spanish. Generated data is the same in every language."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["value"],"properties":{"value":{"type":"string"},"kind":{"type":"string","enum":["auto","DNI","NIE","CIF","IBAN","Tarjeta","NSS","CCC"],"default":"auto"}}}}}},"responses":{"200":{"description":"Validation result","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["success"]},"data":{"$ref":"#/components/schemas/ValidationResult"}},"required":["status","data"]}}}},"400":{"description":"\"value\" missing or empty","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}},"components":{"schemas":{"ApiError":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"code":{"type":"string","enum":["INVALID_PARAMS","INVALID_BODY","UNKNOWN_GENERATOR","UNSUPPORTED_LOCALE","COUNT_LIMIT_EXCEEDED","RATE_LIMIT_EXCEEDED","INTERNAL_ERROR"],"description":"Stable error code (see /en/docs/errors)."},"message":{"type":"string","description":"Human-readable message, in the requested language (`lang`)."},"details":{"type":"object","description":"Additional information (e.g. available generators)."}},"required":["status","code","message"]},"ValidationResult":{"oneOf":[{"type":"object","properties":{"valid":{"type":"boolean","const":true},"normalized":{"type":"string","description":"Normalized value (no spaces or separators)."},"kind":{"type":"string","description":"Detected type, or the one requested in `kind`."},"extra":{"type":"object","additionalProperties":{"type":"string"},"description":"Additional data when available (bank and BIC of an IBAN, card brand…)."}},"required":["valid","normalized","kind"]},{"type":"object","properties":{"valid":{"type":"boolean","const":false},"code":{"type":"string","enum":["unrecognized_format","invalid_dni_format","invalid_nie_format","invalid_cif_format","invalid_nif_format","invalid_nss_format","invalid_ccc_format","invalid_iban_format","invalid_bic_format","invalid_plate_format","invalid_phone_format","invalid_card_format","invalid_passport_format","invalid_uuid_format","invalid_check_letter","invalid_cif_check","invalid_cif_org_letter","invalid_nss_check","invalid_ccc_check","unsupported_iban_country","invalid_iban_length","invalid_iban_check_digits","invalid_iban_es_ccc","invalid_iban_fr_rib_key","invalid_iban_pt_nib","invalid_iban_de_bban","invalid_plate_letters","invalid_phone_range","unknown_test_bin","invalid_card_length","invalid_luhn_check"],"description":"Stable reason code in English, safe to compare in code (e.g. `invalid_check_digit`)."},"reason":{"type":"string","description":"Human-readable reason, in the requested language (`lang`)."},"expected":{"type":"string","description":"Expected check character or digit, when applicable."}},"required":["valid","code","reason"]}]}}},"x-rate-limit":{"requestsPerMinute":60,"scope":"IP"}}