{"openapi":"3.1.0","info":{"title":"CPF Direto API","version":"1.1.0","description":"API autenticada por chave individual. 1 crédito por CPF encontrado; lotes são atômicos quando o saldo é insuficiente."},"servers":[{"url":"https://cpfdireto.com","description":"Produção"},{"url":"/","description":"Servidor que hospeda esta documentação"}],"externalDocs":{"description":"Guia de integração para desenvolvedores e agentes","url":"https://cpfdireto.com/api-guide.md"},"security":[{"apiKey":[]}],"components":{"schemas":{"ErrorResponse":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"object","required":["code","message"],"additionalProperties":false,"properties":{"code":{"type":"string","description":"Combine com o status HTTP; request_error tem vários significados."},"message":{"type":"string","description":"Mensagem legível; não use o texto como identificador estável."}}}}},"Person":{"type":"object","additionalProperties":false,"required":["name","cpf","birthday","gender"],"properties":{"name":{"type":"string","example":"Pessoa de exemplo"},"cpf":{"type":"string","pattern":"^[0-9]{11}$","example":"12345678909"},"birthday":{"type":"string","format":"date","example":"1990-06-15"},"gender":{"type":["string","null"],"enum":["M","F",null],"example":"M","description":"M ou F. Valores I e campos sem informação retornam null; os demais dados do cadastro continuam disponíveis."}}},"QueryMeta":{"type":"object","additionalProperties":false,"required":["remainingCredits","consultedAt"],"properties":{"remainingCredits":{"type":"integer","minimum":0,"description":"Saldo após o processamento desta requisição."},"consultedAt":{"type":"string","format":"date-time","description":"Data e hora da consulta em UTC (ISO 8601)."}}},"QueryResult":{"type":"object","additionalProperties":false,"required":["success","data"],"properties":{"success":{"type":"boolean","description":"Indica se um cadastro foi encontrado."},"data":{"anyOf":[{"$ref":"#/components/schemas/Person"},{"type":"null"}]}},"oneOf":[{"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Person"}}},{"properties":{"success":{"const":false},"data":{"type":"null"}}}]},"QueryResponse":{"type":"object","additionalProperties":false,"required":["success","data","meta"],"properties":{"success":{"type":"boolean","description":"Indica se um cadastro foi encontrado."},"data":{"anyOf":[{"$ref":"#/components/schemas/Person"},{"type":"null"}]},"meta":{"$ref":"#/components/schemas/QueryMeta"}},"oneOf":[{"properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Person"}}},{"properties":{"success":{"const":false},"data":{"type":"null"}}}]},"Consultation":{"type":"object","additionalProperties":false,"required":["id","document","status","type","date","chargedCredits"],"properties":{"id":{"type":"string"},"document":{"type":"string","example":"***.456.789-**"},"status":{"type":"string","enum":["Encontrado","Não encontrado","Inválido"]},"type":{"type":"string","enum":["Individual","Em lote"]},"date":{"type":"string","format":"date-time"},"chargedCredits":{"type":"integer","minimum":0,"maximum":1}}},"BatchResponse":{"type":"object","additionalProperties":false,"required":["results","meta"],"properties":{"results":{"type":"array","description":"Resultados na mesma ordem dos CPFs enviados, incluindo repetições. Itens inválidos ou não encontrados retornam success: false e data: null.","items":{"$ref":"#/components/schemas/QueryResult"}},"meta":{"$ref":"#/components/schemas/QueryMeta"}}},"BalanceResponse":{"type":"object","additionalProperties":false,"required":["remainingCredits","includedCredits","includedUsed","extraCredits","renewsAt"],"properties":{"remainingCredits":{"type":"integer","minimum":0},"includedCredits":{"type":"integer","minimum":0},"includedUsed":{"type":"integer","minimum":0},"extraCredits":{"type":"integer","minimum":0},"renewsAt":{"type":"string","format":"date-time"}}},"HistoryResponse":{"type":"object","additionalProperties":false,"required":["rows","total"],"properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/Consultation"}},"total":{"type":"integer","minimum":0}}}},"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Chave de CPF Direto no servidor. Não é um token OAuth/Auth0. Não envie em URL, frontend ou X-API-Key."}}},"paths":{"/api/v1/consultas":{"post":{"operationId":"consultarCpf","tags":["Consultas"],"summary":"Consultar um CPF","description":"Informe o CPF como string, com ou sem pontuação, até 32 caracteres. Os 11 dígitos e os verificadores são validados. Preserve zeros iniciais. Um registro encontrado consome 1 crédito; um CPF válido sem registro retorna HTTP 200, success: false e data: null, sem cobrança. Não há garantia de idempotência. Não repita automaticamente um POST após timeout ou falha de transporte: o processamento pode ter ocorrido.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cpf"],"properties":{"cpf":{"type":"string","maxLength":32,"description":"CPF com ou sem pontuação. Validação de 11 dígitos e verificadores; mantenha zeros iniciais."}}},"example":{"cpf":"12345678909"}}}},"responses":{"200":{"description":"Processado; só registros encontrados consomem créditos. Ausência de registro também retorna HTTP 200.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"Limite de requisições por conta na janela de um minuto; padrão 120.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requisições restantes na janela, quando disponível.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Fim da janela, timestamp Unix em segundos, quando disponível.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryResponse"},"examples":{"encontrado":{"value":{"success":true,"data":{"name":"Pessoa de exemplo","cpf":"12345678909","birthday":"1990-06-15","gender":null},"meta":{"remainingCredits":19,"consultedAt":"2026-10-14T15:30:00.000Z"}}},"naoEncontrado":{"value":{"success":false,"data":null,"meta":{"remainingCredits":20,"consultedAt":"2026-10-14T15:30:00.000Z"}}}}}}},"400":{"description":"invalid_cpf: CPF individual com formato ou dígitos inválidos. Corrija o CPF antes de reenviar. request_error: JSON, lista ou filtros inválidos. O texto da mensagem explica o campo. Confira o corpo e os parâmetros. Não repita a mesma entrada.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_cpf":{"summary":"CPF individual com formato ou dígitos inválidos.","value":{"error":{"code":"invalid_cpf","message":"Confira os 11 dígitos e digite um CPF válido."}}},"request_error":{"summary":"JSON, lista ou filtros inválidos. O texto da mensagem explica o campo.","value":{"error":{"code":"request_error","message":"Envie de 1 a 100 CPFs."}}}}}}},"401":{"description":"unauthorized: Credencial ausente. Envie Authorization: Bearer SUA_CHAVE. invalid_api_key: A chave não está ativa. Confira ou substitua a chave no painel. request_error: Formato do cabeçalho Authorization incorreto. Use Bearer, um espaço e a chave, sem aspas.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"unauthorized":{"summary":"Credencial ausente.","value":{"error":{"code":"unauthorized","message":"Entre na sua conta para continuar."}}},"invalid_api_key":{"summary":"A chave não está ativa.","value":{"error":{"code":"invalid_api_key","message":"Chave de API inválida ou revogada."}}},"request_error":{"summary":"Formato do cabeçalho Authorization incorreto.","value":{"error":{"code":"request_error","message":"Use Authorization: Bearer SUA_CHAVE."}}}}}}},"402":{"description":"credits_exhausted: Saldo insuficiente para os registros encontrados. Adicione créditos. Um lote não debita parcialmente.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"credits_exhausted":{"summary":"Saldo insuficiente para os registros encontrados.","value":{"error":{"code":"credits_exhausted","message":"Créditos insuficientes. Este envio precisa de 1 crédito(s); seu saldo é 0."}}}}}}},"403":{"description":"email_unverified: Confirmação de e-mail pendente. Confirme o e-mail da conta antes de consultar. billing_hold: Conta com pendência de pagamento. Resolva a pendência pelo suporte. request_error: Origem de navegador não permitida ou proteção de sessão ausente. Integre pelo backend com a chave de API.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"email_unverified":{"summary":"Confirmação de e-mail pendente.","value":{"error":{"code":"email_unverified","message":"Confirme seu e-mail para consultar e contratar um plano."}}},"billing_hold":{"summary":"Conta com pendência de pagamento.","value":{"error":{"code":"billing_hold","message":"Há uma pendência de pagamento. Entre em contato com o suporte."}}},"request_error":{"summary":"Origem de navegador não permitida ou proteção de sessão ausente.","value":{"error":{"code":"request_error","message":"Origem não autorizada."}}}}}}},"404":{"description":"request_error: Caminho ou método HTTP não suportado. Confira a rota e o método; não confunda com CPF não encontrado.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"request_error":{"summary":"Caminho ou método HTTP não suportado.","value":{"error":{"code":"request_error","message":"Endpoint não encontrado."}}}}}}},"413":{"description":"request_error: Corpo maior que 128.000 bytes. Reduza o corpo; envie no máximo 100 CPFs por lote.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"request_error":{"summary":"Corpo maior que 128.000 bytes.","value":{"error":{"code":"request_error","message":"A requisição ultrapassa 128 KB."}}}}}}},"415":{"description":"request_error: Content-Type incorreto no POST. Envie Content-Type: application/json.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"request_error":{"summary":"Content-Type incorreto no POST.","value":{"error":{"code":"request_error","message":"Envie JSON no corpo da requisição."}}}}}}},"429":{"description":"rate_limited: Limite de requisições atingido. Respeite Retry-After (segundos). Use fila e tentativas limitadas.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Segundos a aguardar antes de uma nova tentativa.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"rate_limited":{"summary":"Limite de requisições atingido.","value":{"error":{"code":"rate_limited","message":"Muitas requisições. Aguarde um minuto e tente novamente."}}}}}}},"500":{"description":"server_error: Falha interna inesperada. Registre X-Request-Id. Não repita POST automaticamente: o resultado pode ser incerto.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"server_error":{"summary":"Falha interna inesperada.","value":{"error":{"code":"server_error","message":"Não foi possível concluir. Tente novamente."}}}}}}},"503":{"description":"catalog_unavailable: Catálogo indisponível. Aguarde e limite novas tentativas. Se persistir, contate o suporte. catalog_busy: Fila de consultas ocupada. Reduza a concorrência e use espera progressiva com variação aleatória. real_data_disabled: Consultas temporariamente desabilitadas no serviço. Aguarde a habilitação pelo responsável do serviço.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"catalog_unavailable":{"summary":"Catálogo indisponível.","value":{"error":{"code":"catalog_unavailable","message":"Catálogo temporariamente indisponível. Tente novamente."}}},"catalog_busy":{"summary":"Fila de consultas ocupada.","value":{"error":{"code":"catalog_busy","message":"Serviço ocupado. Tente novamente em instantes."}}},"real_data_disabled":{"summary":"Consultas temporariamente desabilitadas no serviço.","value":{"error":{"code":"real_data_disabled","message":"A operação com dados reais precisa ser habilitada pelo responsável."}}}}}}}}}},"/api/v1/lotes":{"post":{"operationId":"consultarLote","tags":["Consultas"],"summary":"Consultar em lote","description":"Envie cpfs como uma lista de 1 a 100 strings, com até 32 caracteres cada. A resposta é síncrona e mantém a ordem, incluindo repetições. Itens inválidos e não encontrados retornam success: false e data: null. Valide os dígitos antes de enviar para distingui-los. Cada ocorrência encontrada custa 1 crédito; repetições também são cobradas. Com saldo insuficiente, todo o envio retorna 402 sem débito parcial. Não há garantia de idempotência. Não repita automaticamente um POST após timeout ou falha de transporte: o processamento pode ter ocorrido.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cpfs"],"properties":{"cpfs":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","maxLength":32}}}},"example":{"cpfs":["12345678909","52998224725"]}}}},"responses":{"200":{"description":"Processado; só registros encontrados consomem créditos. Ausência de registro também retorna HTTP 200.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"Limite de requisições por conta na janela de um minuto; padrão 120.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requisições restantes na janela, quando disponível.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Fim da janela, timestamp Unix em segundos, quando disponível.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResponse"},"example":{"results":[{"success":true,"data":{"name":"Pessoa de exemplo","cpf":"12345678909","birthday":"1990-06-15","gender":null}},{"success":false,"data":null}],"meta":{"remainingCredits":19,"consultedAt":"2026-10-14T15:30:00.000Z"}}}}},"400":{"description":"request_error: JSON, lista ou filtros inválidos. O texto da mensagem explica o campo. Confira o corpo e os parâmetros. Não repita a mesma entrada.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"request_error":{"summary":"JSON, lista ou filtros inválidos. O texto da mensagem explica o campo.","value":{"error":{"code":"request_error","message":"Envie de 1 a 100 CPFs."}}}}}}},"401":{"description":"unauthorized: Credencial ausente. Envie Authorization: Bearer SUA_CHAVE. invalid_api_key: A chave não está ativa. Confira ou substitua a chave no painel. request_error: Formato do cabeçalho Authorization incorreto. Use Bearer, um espaço e a chave, sem aspas.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"unauthorized":{"summary":"Credencial ausente.","value":{"error":{"code":"unauthorized","message":"Entre na sua conta para continuar."}}},"invalid_api_key":{"summary":"A chave não está ativa.","value":{"error":{"code":"invalid_api_key","message":"Chave de API inválida ou revogada."}}},"request_error":{"summary":"Formato do cabeçalho Authorization incorreto.","value":{"error":{"code":"request_error","message":"Use Authorization: Bearer SUA_CHAVE."}}}}}}},"402":{"description":"credits_exhausted: Saldo insuficiente para os registros encontrados. Adicione créditos. Um lote não debita parcialmente.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"credits_exhausted":{"summary":"Saldo insuficiente para os registros encontrados.","value":{"error":{"code":"credits_exhausted","message":"Créditos insuficientes. Este envio precisa de 1 crédito(s); seu saldo é 0."}}}}}}},"403":{"description":"email_unverified: Confirmação de e-mail pendente. Confirme o e-mail da conta antes de consultar. billing_hold: Conta com pendência de pagamento. Resolva a pendência pelo suporte. request_error: Origem de navegador não permitida ou proteção de sessão ausente. Integre pelo backend com a chave de API.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"email_unverified":{"summary":"Confirmação de e-mail pendente.","value":{"error":{"code":"email_unverified","message":"Confirme seu e-mail para consultar e contratar um plano."}}},"billing_hold":{"summary":"Conta com pendência de pagamento.","value":{"error":{"code":"billing_hold","message":"Há uma pendência de pagamento. Entre em contato com o suporte."}}},"request_error":{"summary":"Origem de navegador não permitida ou proteção de sessão ausente.","value":{"error":{"code":"request_error","message":"Origem não autorizada."}}}}}}},"404":{"description":"request_error: Caminho ou método HTTP não suportado. Confira a rota e o método; não confunda com CPF não encontrado.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"request_error":{"summary":"Caminho ou método HTTP não suportado.","value":{"error":{"code":"request_error","message":"Endpoint não encontrado."}}}}}}},"413":{"description":"request_error: Corpo maior que 128.000 bytes. Reduza o corpo; envie no máximo 100 CPFs por lote.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"request_error":{"summary":"Corpo maior que 128.000 bytes.","value":{"error":{"code":"request_error","message":"A requisição ultrapassa 128 KB."}}}}}}},"415":{"description":"request_error: Content-Type incorreto no POST. Envie Content-Type: application/json.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"request_error":{"summary":"Content-Type incorreto no POST.","value":{"error":{"code":"request_error","message":"Envie JSON no corpo da requisição."}}}}}}},"429":{"description":"rate_limited: Limite de requisições atingido. Respeite Retry-After (segundos). Use fila e tentativas limitadas.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Segundos a aguardar antes de uma nova tentativa.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"rate_limited":{"summary":"Limite de requisições atingido.","value":{"error":{"code":"rate_limited","message":"Muitas requisições. Aguarde um minuto e tente novamente."}}}}}}},"500":{"description":"server_error: Falha interna inesperada. Registre X-Request-Id. Não repita POST automaticamente: o resultado pode ser incerto.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"server_error":{"summary":"Falha interna inesperada.","value":{"error":{"code":"server_error","message":"Não foi possível concluir. Tente novamente."}}}}}}},"503":{"description":"catalog_unavailable: Catálogo indisponível. Aguarde e limite novas tentativas. Se persistir, contate o suporte. catalog_busy: Fila de consultas ocupada. Reduza a concorrência e use espera progressiva com variação aleatória. real_data_disabled: Consultas temporariamente desabilitadas no serviço. Aguarde a habilitação pelo responsável do serviço.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"catalog_unavailable":{"summary":"Catálogo indisponível.","value":{"error":{"code":"catalog_unavailable","message":"Catálogo temporariamente indisponível. Tente novamente."}}},"catalog_busy":{"summary":"Fila de consultas ocupada.","value":{"error":{"code":"catalog_busy","message":"Serviço ocupado. Tente novamente em instantes."}}},"real_data_disabled":{"summary":"Consultas temporariamente desabilitadas no serviço.","value":{"error":{"code":"real_data_disabled","message":"A operação com dados reais precisa ser habilitada pelo responsável."}}}}}}}}}},"/api/v1/saldo":{"get":{"operationId":"consultarSaldo","tags":["Conta"],"summary":"Consultar saldo","description":"Retorna o saldo atual, a franquia do plano, o consumo da franquia, os créditos adicionais e a próxima renovação. Não consome créditos, mas conta no limite de requisições. O saldo é informativo e não reserva créditos para outra requisição.","responses":{"200":{"description":"Consultar saldo","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"Limite de requisições por conta na janela de um minuto; padrão 120.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requisições restantes na janela, quando disponível.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Fim da janela, timestamp Unix em segundos, quando disponível.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceResponse"},"example":{"remainingCredits":19,"includedCredits":20,"includedUsed":1,"extraCredits":0,"renewsAt":"2026-11-01T03:00:00.000Z"}}}},"401":{"description":"unauthorized: Credencial ausente. Envie Authorization: Bearer SUA_CHAVE. invalid_api_key: A chave não está ativa. Confira ou substitua a chave no painel. request_error: Formato do cabeçalho Authorization incorreto. Use Bearer, um espaço e a chave, sem aspas.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"unauthorized":{"summary":"Credencial ausente.","value":{"error":{"code":"unauthorized","message":"Entre na sua conta para continuar."}}},"invalid_api_key":{"summary":"A chave não está ativa.","value":{"error":{"code":"invalid_api_key","message":"Chave de API inválida ou revogada."}}},"request_error":{"summary":"Formato do cabeçalho Authorization incorreto.","value":{"error":{"code":"request_error","message":"Use Authorization: Bearer SUA_CHAVE."}}}}}}},"403":{"description":"request_error: Origem de navegador não permitida ou proteção de sessão ausente. Integre pelo backend com a chave de API.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"request_error":{"summary":"Origem de navegador não permitida ou proteção de sessão ausente.","value":{"error":{"code":"request_error","message":"Origem não autorizada."}}}}}}},"404":{"description":"request_error: Caminho ou método HTTP não suportado. Confira a rota e o método; não confunda com CPF não encontrado.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"request_error":{"summary":"Caminho ou método HTTP não suportado.","value":{"error":{"code":"request_error","message":"Endpoint não encontrado."}}}}}}},"429":{"description":"rate_limited: Limite de requisições atingido. Respeite Retry-After (segundos). Use fila e tentativas limitadas.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Segundos a aguardar antes de uma nova tentativa.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"rate_limited":{"summary":"Limite de requisições atingido.","value":{"error":{"code":"rate_limited","message":"Muitas requisições. Aguarde um minuto e tente novamente."}}}}}}},"500":{"description":"server_error: Falha interna inesperada. Registre X-Request-Id. Não repita POST automaticamente: o resultado pode ser incerto.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"server_error":{"summary":"Falha interna inesperada.","value":{"error":{"code":"server_error","message":"Não foi possível concluir. Tente novamente."}}}}}}}}}},"/api/v1/historico":{"get":{"operationId":"consultarHistorico","tags":["Conta"],"summary":"Consultar histórico","description":"Retorna somente as operações da sua conta, da mais recente para a mais antiga, com documentos mascarados. rows contém a página; total é o número de itens que correspondem aos filtros, antes da paginação. Sem resultados: rows: [] e total: 0. Não consome créditos; conta no limite de requisições.","parameters":[{"name":"limit","description":"Itens por página: 1 a 500. Padrão: 500.","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":500}},{"name":"offset","description":"Itens a pular, a partir de 0. Padrão: 0.","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}},{"name":"from","description":"Data inicial inclusiva, AAAA-MM-DD, no horário de Brasília.","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"to","description":"Data final inclusiva, AAAA-MM-DD, no horário de Brasília. Deve ser igual ou posterior a from.","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"status","description":"Filtre por resultado: Encontrado, Não encontrado ou Inválido.","in":"query","required":false,"schema":{"type":"string","enum":["Encontrado","Não encontrado","Inválido"]}},{"name":"type","description":"Filtre por tipo: Individual ou Em lote.","in":"query","required":false,"schema":{"type":"string","enum":["Individual","Em lote"]}},{"name":"q","description":"Busca textual no documento mascarado, resultado e tipo. Até 120 caracteres; não busca nome ou CPF completo.","in":"query","required":false,"schema":{"type":"string","maxLength":120}}],"responses":{"200":{"description":"Consultar histórico","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"Limite de requisições por conta na janela de um minuto; padrão 120.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requisições restantes na janela, quando disponível.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Fim da janela, timestamp Unix em segundos, quando disponível.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HistoryResponse"},"example":{"rows":[{"id":"10946738-6d63-40a0-bd01-5ee2a40de9cd","document":"***.456.789-**","status":"Encontrado","type":"Individual","date":"2026-10-14T15:30:00.000Z","chargedCredits":1}],"total":1}}}},"400":{"description":"request_error: JSON, lista ou filtros inválidos. O texto da mensagem explica o campo. Confira o corpo e os parâmetros. Não repita a mesma entrada.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"request_error":{"summary":"JSON, lista ou filtros inválidos. O texto da mensagem explica o campo.","value":{"error":{"code":"request_error","message":"Envie de 1 a 100 CPFs."}}}}}}},"401":{"description":"unauthorized: Credencial ausente. Envie Authorization: Bearer SUA_CHAVE. invalid_api_key: A chave não está ativa. Confira ou substitua a chave no painel. request_error: Formato do cabeçalho Authorization incorreto. Use Bearer, um espaço e a chave, sem aspas.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"unauthorized":{"summary":"Credencial ausente.","value":{"error":{"code":"unauthorized","message":"Entre na sua conta para continuar."}}},"invalid_api_key":{"summary":"A chave não está ativa.","value":{"error":{"code":"invalid_api_key","message":"Chave de API inválida ou revogada."}}},"request_error":{"summary":"Formato do cabeçalho Authorization incorreto.","value":{"error":{"code":"request_error","message":"Use Authorization: Bearer SUA_CHAVE."}}}}}}},"403":{"description":"request_error: Origem de navegador não permitida ou proteção de sessão ausente. Integre pelo backend com a chave de API.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"request_error":{"summary":"Origem de navegador não permitida ou proteção de sessão ausente.","value":{"error":{"code":"request_error","message":"Origem não autorizada."}}}}}}},"404":{"description":"request_error: Caminho ou método HTTP não suportado. Confira a rota e o método; não confunda com CPF não encontrado.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"request_error":{"summary":"Caminho ou método HTTP não suportado.","value":{"error":{"code":"request_error","message":"Endpoint não encontrado."}}}}}}},"429":{"description":"rate_limited: Limite de requisições atingido. Respeite Retry-After (segundos). Use fila e tentativas limitadas.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Segundos a aguardar antes de uma nova tentativa.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"rate_limited":{"summary":"Limite de requisições atingido.","value":{"error":{"code":"rate_limited","message":"Muitas requisições. Aguarde um minuto e tente novamente."}}}}}}},"500":{"description":"server_error: Falha interna inesperada. Registre X-Request-Id. Não repita POST automaticamente: o resultado pode ser incerto.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"server_error":{"summary":"Falha interna inesperada.","value":{"error":{"code":"server_error","message":"Não foi possível concluir. Tente novamente."}}}}}}}}}},"/api/v1/historico.csv":{"get":{"operationId":"exportarHistorico","tags":["Conta"],"summary":"Exportar histórico","description":"Mesmos filtros e paginação do histórico JSON, inclusive o máximo de 500 linhas por chamada. Retorna text/csv; charset=utf-8 com BOM, separador ponto e vírgula e campos entre aspas. Use offset para exportar mais páginas. Erros continuam sendo JSON. Não consome créditos; conta no limite de requisições.","parameters":[{"name":"limit","description":"Itens por página: 1 a 500. Padrão: 500.","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":500}},{"name":"offset","description":"Itens a pular, a partir de 0. Padrão: 0.","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}},{"name":"from","description":"Data inicial inclusiva, AAAA-MM-DD, no horário de Brasília.","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"to","description":"Data final inclusiva, AAAA-MM-DD, no horário de Brasília. Deve ser igual ou posterior a from.","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"status","description":"Filtre por resultado: Encontrado, Não encontrado ou Inválido.","in":"query","required":false,"schema":{"type":"string","enum":["Encontrado","Não encontrado","Inválido"]}},{"name":"type","description":"Filtre por tipo: Individual ou Em lote.","in":"query","required":false,"schema":{"type":"string","enum":["Individual","Em lote"]}},{"name":"q","description":"Busca textual no documento mascarado, resultado e tipo. Até 120 caracteres; não busca nome ou CPF completo.","in":"query","required":false,"schema":{"type":"string","maxLength":120}}],"responses":{"200":{"description":"Exportar histórico","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"Limite de requisições por conta na janela de um minuto; padrão 120.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requisições restantes na janela, quando disponível.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Fim da janela, timestamp Unix em segundos, quando disponível.","schema":{"type":"integer"}},"Content-Disposition":{"schema":{"type":"string"},"example":"attachment; filename=\"cpf-direto-historico.csv\""}},"content":{"text/csv":{"schema":{"type":"string"},"example":"\"Documento\";\"Resultado\";\"Tipo\";\"Data\";\"Créditos consumidos\"\r\n\"***.456.789-**\";\"Encontrado\";\"Individual\";\"2026-10-14T15:30:00.000Z\";\"1\""}}},"400":{"description":"request_error: JSON, lista ou filtros inválidos. O texto da mensagem explica o campo. Confira o corpo e os parâmetros. Não repita a mesma entrada.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"request_error":{"summary":"JSON, lista ou filtros inválidos. O texto da mensagem explica o campo.","value":{"error":{"code":"request_error","message":"Envie de 1 a 100 CPFs."}}}}}}},"401":{"description":"unauthorized: Credencial ausente. Envie Authorization: Bearer SUA_CHAVE. invalid_api_key: A chave não está ativa. Confira ou substitua a chave no painel. request_error: Formato do cabeçalho Authorization incorreto. Use Bearer, um espaço e a chave, sem aspas.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"unauthorized":{"summary":"Credencial ausente.","value":{"error":{"code":"unauthorized","message":"Entre na sua conta para continuar."}}},"invalid_api_key":{"summary":"A chave não está ativa.","value":{"error":{"code":"invalid_api_key","message":"Chave de API inválida ou revogada."}}},"request_error":{"summary":"Formato do cabeçalho Authorization incorreto.","value":{"error":{"code":"request_error","message":"Use Authorization: Bearer SUA_CHAVE."}}}}}}},"403":{"description":"request_error: Origem de navegador não permitida ou proteção de sessão ausente. Integre pelo backend com a chave de API.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"request_error":{"summary":"Origem de navegador não permitida ou proteção de sessão ausente.","value":{"error":{"code":"request_error","message":"Origem não autorizada."}}}}}}},"404":{"description":"request_error: Caminho ou método HTTP não suportado. Confira a rota e o método; não confunda com CPF não encontrado.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"request_error":{"summary":"Caminho ou método HTTP não suportado.","value":{"error":{"code":"request_error","message":"Endpoint não encontrado."}}}}}}},"429":{"description":"rate_limited: Limite de requisições atingido. Respeite Retry-After (segundos). Use fila e tentativas limitadas.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Segundos a aguardar antes de uma nova tentativa.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"rate_limited":{"summary":"Limite de requisições atingido.","value":{"error":{"code":"rate_limited","message":"Muitas requisições. Aguarde um minuto e tente novamente."}}}}}}},"500":{"description":"server_error: Falha interna inesperada. Registre X-Request-Id. Não repita POST automaticamente: o resultado pode ser incerto.","headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte; presente também nos erros.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"server_error":{"summary":"Falha interna inesperada.","value":{"error":{"code":"server_error","message":"Não foi possível concluir. Tente novamente."}}}}}}}}}}}}