{"openapi":"3.0.3","info":{"title":"Hiper API","version":"1.0.323","description":"API pública para consultar a Workspace, listar produtos, criar execuções assíncronas, listar o histórico de execuções e consultar resultados. Cada produto publica os schemas e a documentação necessários para integração. A versão deste campo corresponde à versão da release do Hiper API, lida diretamente de composer.json. A linha de compatibilidade HTTP continua identificada por /api/v1.","x-scalar-links":[{"name":"Hiper API","url":"/"}]},"servers":[{"url":"https://api.hiper.esp.br","description":"Servidor da API pública"}],"tags":[{"name":"Workspace","description":"Contexto da Workspace autenticada."},{"name":"Produtos","description":"Catálogo de produtos disponíveis para a API Key."},{"name":"Documentação","description":"Contrato OpenAPI publicado pela própria API."},{"name":"Execuções","description":"Criação e consulta de execuções."}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API-Key"}},"schemas":{"ApiError":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["UNAUTHORIZED","NOT_FOUND","FORBIDDEN","VALIDATION_ERROR","INVALID_JSON","INVALID_HEADER","PAYLOAD_TOO_LARGE","RATE_LIMIT_EXCEEDED","SERVICE_UNAVAILABLE","APPLICATION_ERROR","INSUFFICIENT_FUNDS","IDEMPOTENCY_KEY_CONFLICT","IDEMPOTENCY_IN_PROGRESS","MAX_PRICE_EXCEEDED"]},"message":{"type":"string"},"details":{"description":"Informações adicionais sobre o erro.","oneOf":[{"$ref":"#/components/schemas/ValidationErrorDetails"},{"$ref":"#/components/schemas/MaxPriceExceededDetails"},{"$ref":"#/components/schemas/RateLimitErrorDetails"}]}}},"ApiErrorEnvelope":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean","enum":[false]},"error":{"$ref":"#/components/schemas/ApiError"}}},"ManagedFileReference":{"type":"object","required":["mimeType","fileName","contentLength","key","url","urlExpiresAt"],"properties":{"mimeType":{"type":"string","description":"MIME type declarado pelo crawler."},"fileName":{"type":"string","description":"Nome de arquivo informado pelo crawler."},"contentLength":{"type":"integer","minimum":0,"description":"Tamanho dos bytes armazenados."},"key":{"type":"string","description":"Chave estável do objeto no storage temporário."},"url":{"type":"string","format":"uri","description":"URL pré-assinada para download."},"urlExpiresAt":{"type":"string","format":"date-time","description":"Data de expiração da URL pré-assinada."}},"additionalProperties":false,"description":"Referência pública a um arquivo temporário. O link para download tem validade limitada."},"ValidationFieldError":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string","description":"Campo associado ao erro."},"code":{"type":"string","enum":["REQUIRED","TYPE_MISMATCH","INVALID_VALUE"]},"message":{"type":"string"}}},"ValidationErrorDetails":{"type":"object","required":["fields"],"properties":{"fields":{"type":"array","description":"Lista de erros encontrados no input ou nas regras de validação.","items":{"$ref":"#/components/schemas/ValidationFieldError"}}}},"MaxPriceExceededDetails":{"type":"object","required":["price","max_price","currency"],"properties":{"price":{"type":"string","pattern":"^\\d+\\.\\d{5}$","description":"Preço aplicável à execução."},"max_price":{"type":"string","pattern":"^\\d+\\.\\d{5}$","description":"Limite informado no header Max-Price."},"currency":{"type":"string","example":"BRL"}}},"RateLimitErrorDetails":{"type":"object","required":["retry_after"],"properties":{"retry_after":{"type":"integer","minimum":1,"description":"Tempo de espera antes de tentar novamente, em segundos."}}},"Product":{"type":"object","required":["name","slug","description","input_schema","output_schema","documentation","timeout_seconds"],"properties":{"name":{"type":"string"},"slug":{"type":"string","description":"Identificador público do produto."},"description":{"type":"string","description":"Descrição resumida do produto."},"input_schema":{"type":"object","description":"Schema usado para validar o input enviado à API.","additionalProperties":true},"output_schema":{"type":"object","description":"Schema público esperado para o output.","additionalProperties":true},"documentation":{"type":"string","description":"Instruções de integração disponibilizadas pelo produto."},"timeout_seconds":{"type":"integer","minimum":1,"description":"Timeout configurado para a execução deste produto, em segundos."}}},"ProductInput":{"type":"object","description":"Dados enviados para executar o produto.","additionalProperties":true},"ExecutionReference":{"type":"object","required":["execution_id","product_slug","status","created_at"],"properties":{"execution_id":{"type":"string","pattern":"^[a-f0-9]{32}$","minLength":32,"maxLength":32,"description":"Identificador da execução."},"product_slug":{"type":"string","description":"Identificador público do produto."},"status":{"type":"string","enum":["PENDING","QUEUED","RUNNING","SUCCEEDED","FAILED","TIMEOUT","REJECTED"]},"created_at":{"type":"string","format":"date-time"}}},"ExecutionError":{"type":"object","required":["code","message","category"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"category":{"type":"string","enum":["CLIENT_ERROR","BUSINESS_ERROR","TIMEOUT","EXECUTION_ERROR"]}}},"Execution":{"allOf":[{"$ref":"#/components/schemas/ExecutionReference"},{"type":"object","required":["cache_hit","billing_status","price","started_at","finished_at"],"properties":{"cache_hit":{"type":"boolean","nullable":true,"description":"true quando a execução utilizou resultado do cache; false quando não utilizou; null enquanto a verificação ainda está pendente."},"billing_status":{"type":"string","enum":["PENDING","CHARGED","NOT_CHARGED","REFUNDED"],"description":"Situação pública da cobrança associada à execução."},"price":{"type":"string","nullable":true,"pattern":"^-?\\d+\\.\\d{5}$","description":"Preço associado à execução."},"started_at":{"type":"string","format":"date-time","nullable":true},"finished_at":{"type":"string","format":"date-time","nullable":true},"output":{"type":"object","description":"Resultado da execução.","additionalProperties":true},"error":{"$ref":"#/components/schemas/ExecutionError"}}}]},"Plan":{"type":"object","required":["name","slug"],"properties":{"name":{"type":"string"},"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","description":"Identificador público do plano."}}},"Workspace":{"type":"object","required":["name","billing_type","plan"],"properties":{"name":{"type":"string"},"billing_type":{"type":"string","enum":["PREPAID","POSTPAID"]},"plan":{"$ref":"#/components/schemas/Plan"}}},"ExecutionHistoryPagination":{"type":"object","required":["limit","has_more","next_cursor"],"properties":{"limit":{"type":"integer","minimum":1,"maximum":100},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true,"pattern":"^[a-f0-9]{32}$","minLength":32,"maxLength":32}}},"ExecutionSummary":{"allOf":[{"$ref":"#/components/schemas/ExecutionReference"},{"type":"object","required":["billing_status","price","started_at","finished_at"],"properties":{"billing_status":{"type":"string","enum":["PENDING","CHARGED","NOT_CHARGED","REFUNDED"]},"price":{"type":"string","nullable":true,"pattern":"^-?\\d+\\.\\d{5}$"},"started_at":{"type":"string","format":"date-time","nullable":true},"finished_at":{"type":"string","format":"date-time","nullable":true}}}]},"ExecutionHistoryData":{"type":"object","required":["executions","pagination"],"properties":{"executions":{"type":"array","items":{"$ref":"#/components/schemas/ExecutionSummary"}},"pagination":{"$ref":"#/components/schemas/ExecutionHistoryPagination"}}},"ExecutionHistoryResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/ExecutionHistoryData"}}},"ProductsResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","required":["products"],"properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}}}}},"ExecutionReferenceResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/ExecutionReference"}}},"ExecutionResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Execution"}}},"WorkspaceResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Workspace"}}}},"responses":{"Unauthorized":{"description":"API Key inválida ou ausente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"},"examples":{"error":{"value":{"success":false,"error":{"code":"UNAUTHORIZED","message":"API Key inválida ou ausente."}}}}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"},"example":"Bearer"}}},"Forbidden":{"description":"A solicitação não pode ser atendida com as permissões atuais.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"},"examples":{"error":{"value":{"success":false,"error":{"code":"FORBIDDEN","message":"A solicitação não pode ser atendida com as permissões atuais."}}}}}}},"NotFound":{"description":"Recurso não encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"},"examples":{"error":{"value":{"success":false,"error":{"code":"NOT_FOUND","message":"Recurso não encontrado."}}}}}}},"InvalidRequest":{"description":"JSON inválido/ilegível ou valor inválido em header opcional.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"},"examples":{"invalidJson":{"value":{"success":false,"error":{"code":"INVALID_JSON","message":"O corpo da requisição contém JSON inválido."}}},"invalidCacheBypass":{"value":{"success":false,"error":{"code":"INVALID_HEADER","message":"O cabeçalho Cache-Bypass aceita apenas true ou false."}}},"invalidMaxPrice":{"value":{"success":false,"error":{"code":"INVALID_HEADER","message":"Max-Price deve ser um valor decimal não negativo, com até 5 casas decimais."}}}}}}},"ValidationError":{"description":"Um parâmetro da solicitação não é válido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"},"examples":{"error":{"value":{"success":false,"error":{"code":"VALIDATION_ERROR","message":"Um parâmetro da solicitação não é válido."}}}}}}},"InsufficientFunds":{"description":"Saldo disponível insuficiente para processar a solicitação.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"},"examples":{"error":{"value":{"success":false,"error":{"code":"INSUFFICIENT_FUNDS","message":"Saldo disponível insuficiente para processar a solicitação."}}}}}}},"IdempotencyConflict":{"description":"A chave já foi usada por outra operação (IDEMPOTENCY_KEY_CONFLICT) ou uma solicitação concorrente ainda está sendo criada (IDEMPOTENCY_IN_PROGRESS).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"},"examples":{"keyConflict":{"value":{"success":false,"error":{"code":"IDEMPOTENCY_KEY_CONFLICT","message":"A Idempotency-Key já foi utilizada com outro request."}}},"inProgress":{"value":{"success":false,"error":{"code":"IDEMPOTENCY_IN_PROGRESS","message":"A chamada idempotente já está sendo processada."}}}}}}},"PayloadTooLarge":{"description":"O corpo da requisição excede o limite permitido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"},"examples":{"error":{"value":{"success":false,"error":{"code":"PAYLOAD_TOO_LARGE","message":"O corpo da requisição excede o limite permitido."}}}}}}},"UnprocessableExecution":{"description":"Corpo vazio ou cuja raiz não seja um objeto JSON, input incompatível com input_schema, Idempotency-Key vazia ou acima do limite, ou preço acima do valor máximo enviado em Max-Price.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"},"examples":{"validation":{"value":{"success":false,"error":{"code":"VALIDATION_ERROR","message":"Input inválido.","details":{"fields":[{"field":"cnpj","code":"REQUIRED","message":"Campo obrigatório não informado."}]}}}},"bodyMustBeObject":{"value":{"success":false,"error":{"code":"VALIDATION_ERROR","message":"O corpo da requisição deve ser um objeto JSON."}}},"invalidIdempotencyKey":{"value":{"success":false,"error":{"code":"VALIDATION_ERROR","message":"Idempotency-Key excede o limite permitido."}}},"maxPriceExceeded":{"value":{"success":false,"error":{"code":"MAX_PRICE_EXCEEDED","message":"O preço da execução excede o limite informado por Max-Price.","details":{"price":"15.00000","max_price":"5.00000","currency":"BRL"}}}}}}}},"RateLimitExceeded":{"description":"Limite de requisições excedido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"},"examples":{"rateLimited":{"value":{"success":false,"error":{"code":"RATE_LIMIT_EXCEEDED","message":"Limite de requisições excedido.","details":{"retry_after":30}}}}}}},"headers":{"Retry-After":{"schema":{"type":"integer","format":"int32","minimum":1},"description":"Tempo de espera antes de tentar novamente, em segundos."}}},"ServiceUnavailable":{"description":"Serviço temporariamente indisponível.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"},"examples":{"error":{"value":{"success":false,"error":{"code":"SERVICE_UNAVAILABLE","message":"Serviço temporariamente indisponível."}}}}}}},"ApplicationError":{"description":"Erro interno da aplicação.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"},"examples":{"error":{"value":{"success":false,"error":{"code":"APPLICATION_ERROR","message":"Erro interno da aplicação."}}}}}}}}},"paths":{"/api/v1/openapi.json":{"get":{"security":[],"tags":["Documentação"],"summary":"Obter a especificação OpenAPI","description":"Retorna o contrato OpenAPI 3.0.3 da API pública. Esta rota não exige autenticação.","operationId":"getOpenApiDocument","responses":{"200":{"description":"Documento OpenAPI.","content":{"application/json":{"schema":{"type":"object"}}}},"500":{"$ref":"#/components/responses/ApplicationError"}}}},"/api/v1/products":{"get":{"tags":["Produtos"],"summary":"Listar produtos disponíveis","description":"Retorna os produtos disponíveis para a chave autenticada.","operationId":"listProducts","responses":{"200":{"description":"Lista de produtos disponíveis para esta API Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductsResponse"},"examples":{"success":{"value":{"success":true,"data":{"products":[{"name":"CND Porto Alegre","slug":"cnd-porto-alegre","description":"Consulta de Certidão Negativa de Débitos (CND) emitida pela Prefeitura de Porto Alegre.","input_schema":{"type":"object","required":["cnpj"],"properties":{"cnpj":{"type":"string"}},"additionalProperties":false},"output_schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":false},"documentation":"# Documentação de integração do produto CND Porto Alegre","timeout_seconds":120}]}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"500":{"$ref":"#/components/responses/ApplicationError"}}}},"/api/v1/products/{product}/execute":{"post":{"tags":["Execuções"],"summary":"Criar uma execução de um produto","description":"Cria uma execução assíncrona para o produto indicado. Uma nova solicitação aceita retorna 202; uma repetição idempotente da mesma operação já aceita retorna 200 com a Execution original.","operationId":"executeProduct","parameters":[{"name":"product","in":"path","required":true,"description":"Slug do produto a executar.","schema":{"type":"string","example":"cnd-porto-alegre"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Identificador usado para reconhecer repetições da mesma solicitação e evitar execuções duplicadas.","schema":{"type":"string","minLength":1,"maxLength":255},"example":"exec-2026-0001"},{"name":"Cache-Bypass","in":"header","required":false,"description":"Indica se a execução deve ignorar o cache.","schema":{"type":"boolean","default":false},"example":true},{"name":"Max-Price","in":"header","required":false,"description":"Preço máximo que o cliente aceita pagar pela execução, na moeda configurada em CURRENCY.","schema":{"type":"string","pattern":"^[\\d]+(\\.[\\d]{1,5})?$"},"example":"5.00000"}],"requestBody":{"required":true,"description":"Dados de entrada da execução.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductInput"},"examples":{"request":{"summary":"Exemplo de input","value":{"cnpj":"00000000000191"}}}}}},"responses":{"202":{"description":"Solicitação aceita para processamento assíncrono.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecutionReferenceResponse"},"examples":{"accepted":{"value":{"success":true,"data":{"execution_id":"0123456789abcdef0123456789abcdef","product_slug":"cnd-porto-alegre","status":"QUEUED","created_at":"2026-10-05T23:00:00+00:00"}}}}}}},"200":{"description":"Resposta de uma repetição da mesma solicitação.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecutionReferenceResponse"},"examples":{"replay":{"value":{"success":true,"data":{"execution_id":"0123456789abcdef0123456789abcdef","product_slug":"cnd-porto-alegre","status":"QUEUED","created_at":"2026-10-05T23:00:00+00:00"}}}}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientFunds"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/IdempotencyConflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableExecution"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"500":{"$ref":"#/components/responses/ApplicationError"}}}},"/api/v1/executions":{"get":{"tags":["Execuções"],"summary":"Listar histórico de execuções","description":"Lista as execuções mais recentes criadas pela API Key autenticada. Cada item contém metadados operacionais e de cobrança; consulte uma execução individual para obter seu resultado ou erro. A listagem e o cursor são limitados à mesma Workspace e à mesma API Key.","operationId":"listExecutions","parameters":[{"name":"limit","in":"query","required":false,"description":"Quantidade máxima de itens retornados. Padrão 50; mínimo 1 e máximo 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"Identificador next_cursor da página anterior. Só é aceito quando pertence à mesma API Key autenticada.","schema":{"type":"string","pattern":"^[a-f0-9]{32}$","minLength":32,"maxLength":32}}],"responses":{"200":{"description":"Página do histórico de execuções.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecutionHistoryResponse"},"examples":{"success":{"value":{"success":true,"data":{"executions":[{"execution_id":"0123456789abcdef0123456789abcdef","product_slug":"cnd-porto-alegre","status":"SUCCEEDED","billing_status":"CHARGED","price":"0.01000","created_at":"2026-10-16T12:00:00+00:00","started_at":"2026-10-16T12:00:01+00:00","finished_at":"2026-10-16T12:00:02+00:00"}],"pagination":{"limit":50,"has_more":false,"next_cursor":null}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"500":{"$ref":"#/components/responses/ApplicationError"}}}},"/api/v1/executions/{id}":{"get":{"tags":["Execuções"],"summary":"Consultar uma execução","description":"Retorna o estado e, quando disponível, o resultado de uma execução acessível pela chave autenticada.","operationId":"getExecution","parameters":[{"name":"id","in":"path","required":true,"description":"Identificador da execução retornado pela API.","schema":{"type":"string","pattern":"^[a-f0-9]{32}$","minLength":32,"maxLength":32,"example":"0123456789abcdef0123456789abcdef"}}],"responses":{"200":{"description":"Execução encontrada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecutionResponse"},"examples":{"queued":{"value":{"success":true,"data":{"execution_id":"0123456789abcdef0123456789abcdef","product_slug":"cnd-porto-alegre","status":"QUEUED","cache_hit":null,"created_at":"2026-10-05T23:00:00+00:00","billing_status":"PENDING","price":"0.20000","started_at":null,"finished_at":null}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"500":{"$ref":"#/components/responses/ApplicationError"}}}},"/api/v1/workspace":{"get":{"tags":["Workspace"],"summary":"Consultar a Workspace autenticada","description":"Retorna as informações da Workspace associada à chave autenticada.","operationId":"getWorkspace","responses":{"200":{"description":"Workspace autenticada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceResponse"},"examples":{"success":{"value":{"success":true,"data":{"name":"Acme Workspace","billing_type":"PREPAID","plan":{"name":"Default","slug":"default"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"500":{"$ref":"#/components/responses/ApplicationError"}}}}}}