{"openapi":"3.1.0","info":{"title":"Veflat Banner API","version":"1.0.0","description":"Generación de imágenes y PDFs desde plantillas. Autenticación: Bearer API key (`vef_…`)."},"servers":[{"url":"https://banner.veflat.com"}],"tags":[{"name":"renders"},{"name":"templates"},{"name":"account"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key con prefijo vef_"}},"schemas":{"ApiError":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}},"Modification":{"type":"object","properties":{"name":{"type":"string"},"text":{"type":"string"},"image_url":{"type":"string","format":"uri"},"color":{"type":"string"}},"required":["name"]},"RenderRequest":{"type":"object","properties":{"template_id":{"type":"string"},"modifications":{"type":"array","items":{"$ref":"#/components/schemas/Modification"}},"format":{"type":"string","enum":["png","jpg","jpeg","webp"]},"webhook_url":{"type":"string","format":"uri"}},"required":["template_id"]},"Render":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["queued","rendering","completed","failed"]},"output_url":{"type":"string","nullable":true},"error":{"type":"string","nullable":true},"template_id":{"type":"string"},"batch_id":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true}}},"BatchRequest":{"type":"object","properties":{"template_id":{"type":"string"},"webhook_url":{"type":"string","format":"uri"},"items":{"type":"array","items":{"type":"object","properties":{"modifications":{"type":"array","items":{"$ref":"#/components/schemas/Modification"}}}}}},"required":["template_id","items"]},"Batch":{"type":"object","properties":{"id":{"type":"string"},"template_id":{"type":"string"},"status":{"type":"string"},"total":{"type":"integer"},"completed":{"type":"integer"},"failed":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}},"Usage":{"type":"object","additionalProperties":true}}},"security":[{"bearerAuth":[]}],"paths":{"/api/v1/images":{"post":{"tags":["renders"],"summary":"Crear render de imagen","parameters":[{"name":"sync","in":"query","schema":{"type":"boolean"},"description":"Esperar hasta ~25s al resultado"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenderRequest"}}}},"responses":{"202":{"description":"Encolado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Render"}}}},"402":{"description":"Sin créditos"},"429":{"description":"Rate limit"}}}},"/api/v1/pdfs":{"post":{"tags":["renders"],"summary":"Crear render PDF (una página)","parameters":[{"name":"sync","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenderRequest"}}}},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Render"}}}}}}},"/api/v1/batches":{"post":{"tags":["renders"],"summary":"Crear lote de renders","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchRequest"}}}},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}}}},"get":{"tags":["renders"],"summary":"Listar lotes","responses":{"200":{"description":"OK"}}}},"/api/v1/batches/{id}":{"get":{"tags":["renders"],"summary":"Estado de lote y renders","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/renders/{id}":{"get":{"tags":["renders"],"summary":"Consultar render","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Render"}}}}}}},"/api/v1/renders":{"get":{"tags":["renders"],"summary":"Listar renders","parameters":[{"name":"template_id","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/templates":{"get":{"tags":["templates"],"summary":"Listar plantillas","responses":{"200":{"description":"OK"}}}},"/api/v1/templates/{id}":{"get":{"tags":["templates"],"summary":"Detalle de plantilla","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/templates/{id}/preview":{"post":{"tags":["templates"],"summary":"Render de prueba (1 crédito)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"sync","in":"query","schema":{"type":"boolean"}}],"responses":{"202":{"description":"Encolado"}}}},"/api/v1/account/usage":{"get":{"tags":["account"],"summary":"Créditos y uso del periodo","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}}}}}}}