--- title: "Leitura de FunCaptcha por Imagem" description: "Resolve o desafio de imagem do FunCaptcha (Arkose) a partir da imagem em base64 (PNG, JPEG, GIF ou WebP, até 1 MiB) e da instrução do desafio em inglês, e devolve a resposta em texto, as coordenadas do clique, o formato e a data e hora da leitura. Aceita, opcionalmente, o formato da resposta (coordenadas ou indices). Cobrada quando há resposta lida, certa ou errada: o serviço não confere se o desafio foi resolvido. Sem resposta, ou com um código de erro do serviço de leitura no lugar dela, a resposta é 404 e não é cobrada; resposta fora do formato esperado ou erro da base devolve 502 e não é cobrada. Disponível para contas PJ." lang: pt-BR canonical: https://doc.apibrasil.io/apis/creditos/1639764f-de5b-11f1-98bb-bc24118aba26 markdown: https://doc.apibrasil.io/apis/creditos/1639764f-de5b-11f1-98bb-bc24118aba26.md source: apibrasil-documentation --- # Leitura de FunCaptcha por Imagem > Resolve o desafio de imagem do FunCaptcha (Arkose) a partir da imagem em base64 (PNG, JPEG, GIF ou WebP, até 1 MiB) e da instrução do desafio em inglês, e devolve a resposta em texto, as coordenadas do clique, o formato e a data e hora da leitura. Aceita, opcionalmente, o formato da resposta (coordenadas ou indices). Cobrada quando há resposta lida, certa ou errada: o serviço não confere se o desafio foi resolvido. Sem resposta, ou com um código de erro do serviço de leitura no lugar dela, a resposta é 404 e não é cobrada; resposta fora do formato esperado ou erro da base devolve 502 e não é cobrada. Disponível para contas PJ. - **Categoria:** CEP e Utilidades - **Cobrança:** por consulta, só com o Bearer Token - **Preço:** R$ 4,49 por consulta - **Limite:** 990.000 por mês - **Cadastro:** exige CNPJ - **Versão:** v2 - **Publicada por:** APIBrasil - **Especificação OpenAPI:** https://doc.apibrasil.io/apis/creditos/1639764f-de5b-11f1-98bb-bc24118aba26/openapi.json ## Como chamar **Endereço base:** `https://gateway.apibrasil.io/api/v2` Autenticação: cabeçalho `Authorization: Bearer `. Nada além disso. Com `homolog: true` no corpo, o gateway responde de uma base fixa, com a forma real da resposta, e não cobra. O CPF 00000000000 é dessa base e não é de ninguém: use-o nos testes, nunca em produção. ## Endpoints (1 endpoint) ### 1. POST /consulta/captcha-funcaptcha/credits ⚠️ Aviso: Cobra quando a resposta traz um texto lido com ao menos uma letra ou um dígito, certo ou errado. Não cobra sem resposta ou com código de erro do serviço no lugar dela (404), com entrada inválida (400), com resposta que não é texto, dados nulos ou erro sinalizado pela base (502), nem em falha ou demora da base (5xx). Envie um POST com tipo=captcha-funcaptcha e: - body (obrigatório): Imagem do desafio em base64 (PNG, JPEG, GIF ou WebP), de até 1 MiB decodificada. O prefixo data:image/...;base64, é aceito e retirado. Imagem acima de ~750 KB pode ser recusada pela borda (413) até o limite de corpo ser ampliado. - textinstructions (obrigatório): Instrução do desafio, em inglês, como o desafio a pede (por exemplo, Pick the image that is the correct way up). Volta em dados, ao lado da leitura. - formato (opcional): Formato da resposta. Sem ele, a base devolve coordenadas (medido). indices não foi medido: a única tentativa com ele não foi concluída pela base (422, sem débito). Resolve o desafio de imagem do FunCaptcha (Arkose) a partir da imagem em base64 (PNG, JPEG, GIF ou WebP, até 1 MiB) e da instrução do desafio em inglês, e devolve a resposta em texto, as coordenadas do clique, o formato e a data e hora da leitura. Aceita, opcionalmente, o formato da resposta (coordenadas ou indices). Cobrada quando há resposta lida, certa ou errada: o serviço não confere se o desafio foi resolvido. Sem resposta, ou com um código de erro do serviço de leitura no lugar dela, a resposta é 404 e não é cobrada; resposta fora do formato esperado ou erro da base devolve 502 e não é cobrada. Respostas de erro (nenhuma é cobrada): HTTP 400: Sem imagem, base64 que não é imagem PNG, JPEG, GIF ou WebP, imagem acima de 1 MiB, instrução ausente, vazia ou acima de 1000 caracteres, ou formato fora de coordenadas e indices. A base não é chamada. Sem cobrança. HTTP 404: A base não devolveu leitura (resposta vazia, nula, sem letra nem dígito, ou ausente, mesmo com coordenadas), ou devolveu no lugar do texto um código de erro do serviço de leitura (ERROR_CAPTCHA_UNSOLVABLE, CAPCHA_NOT_READY e os outros da lista clássica) ou um placeholder (N/A, null, None, undefined). Sem cobrança. HTTP 502: A base recusou a imagem ou não concluiu a leitura, sinalizou erro junto da resposta, ou respondeu fora do formato esperado (leitura que não é texto, resposta sem a leitura, dados nulos ou ausentes). Sem cobrança; a leitura pode ter sido concluída na base, então não repita automaticamente. HTTP 503: Base indisponível por problema nosso com a fonte (credencial, saldo ou limite de uso). Sem cobrança; tente de novo em alguns minutos. HTTP 504: A base não respondeu em 45 s. Sem cobrança; a leitura pode ter sido concluída na base, então não repita em seguida. Em homologação (homolog=true), sem cobrança, a resposta traz dados fictícios no mesmo formato. - **Método:** `POST` - **Endereço:** `https://gateway.apibrasil.io/api/v2/consulta/captcha-funcaptcha/credits` - **Versão da rota:** v2 **Cabeçalhos** | Cabeçalho | Valor | | --- | --- | | `Content-Type` | `application/json` | | `Authorization` | `Bearer $APIBRASIL_TOKEN` | **Corpo da requisição** ```json { "tipo": "captcha-funcaptcha", "body": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==", "textinstructions": "Pick the image that is the correct way up", "formato": "coordenadas", "homolog": true } ``` **Em cURL** ```bash curl -X POST "https://gateway.apibrasil.io/api/v2/consulta/captcha-funcaptcha/credits" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $APIBRASIL_TOKEN" \ -d '{"tipo":"captcha-funcaptcha","body":"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==","textinstructions":"Pick the image that is the correct way up","formato":"coordenadas","homolog":true}' ``` Este endpoint aceita `homolog: true` no corpo: a resposta volta com dados válidos, `api_limit_for` igual a `homolog` e sem tarifação. **Resposta de exemplo, do catálogo** ```json { "user": { "first_name": "[omitido]", "email": "[omitido]", "cellphone": "[omitido]", "notification": "yes" }, "balance": "395,510", "balance_before": "400,000", "tax": "4,490", "status_code": 200, "error": false, "message": "Dados validos! Voce foi tarifado em R$ 4,49.", "valor_consulta": 4.49, "api_limit_for": "credit", "homolog": false, "data": { "captcha": { "resposta": "coordinates:x=50,y=50", "formato": "coordenadas", "resolvido_em": "2026-01-01T00:00:00+00:00", "coordenadas": [ { "x": 50, "y": 50 } ] }, "textinstructions": "Pick the image that is the correct way up", "formato": "coordenadas" } } ``` Nos exemplos de resposta, os campos da conta que gerou o exemplo (`user.first_name`, `user.email`, `user.cellphone`) saem como `[omitido]`. O resto é o que o catálogo publica. ## Armadilhas: o que uma integração erra sem avisar Apuradas nas respostas que o próprio catálogo publica. Em todas elas o código funciona no caminho feliz e falha em silêncio no resto: 1. **O erro chega no CORPO, com HTTP 200.** A resposta traz um campo `error` booleano e uma `message`. Checar só `response.ok` ou o status HTTP deixa passar falha como sucesso. Confira SEMPRE `error === false` antes de ler `data`. 2. **`balance`, `tax` e `extra_charges.total` são STRING em formato brasileiro — e o formato varia entre APIs.** Valores observados no catálogo: `"154,380"`, `"497,84"`, `"0,000"` e `"0.19"`. Vírgula em umas, ponto em outra; três casas decimais em umas, duas em outra. Em JavaScript, `parseFloat("154,380")` devolve `154` e perde os centavos sem erro nenhum, e `Number("154,380")` devolve `NaN`. Escreva um conversor que trate os dois separadores, e nunca use esses campos numa decisão financeira sem convertê-los. 3. **Cada chamada custa dinheiro.** Retry cego multiplica a conta. Nunca repita automaticamente um 4xx: parâmetro errado repetido continua errado e continua cobrando. Repita só tempo esgotado e 5xx, com recuo exponencial e um teto pequeno de tentativas. 4. **HTTP 402 é saldo insuficiente, e repetir não resolve.** É o único status que exige ação humana — recarregar. Trate-o como erro terminal, com mensagem própria, e não o jogue no mesmo balde dos 4xx genéricos. 5. **`extra_charges` cobra à parte do preço da consulta.** Quando o corpo pede serviços adicionais, a resposta traz cada um com o preço e um `total` que NÃO está incluso no valor base. Se você mostra custo a quem usa, some os dois. ## Ver também - Especificação OpenAPI: https://doc.apibrasil.io/apis/creditos/1639764f-de5b-11f1-98bb-bc24118aba26/openapi.json - Catálogo de APIs: [Catálogo de APIs](https://doc.apibrasil.io/apis.md) - SDKs oficiais: [SDKs oficiais](https://doc.apibrasil.io/sdks.md) - Índice da documentação: https://doc.apibrasil.io/llms.txt - Versão HTML desta página: https://doc.apibrasil.io/apis/creditos/1639764f-de5b-11f1-98bb-bc24118aba26