{"openapi":"3.0.0","paths":{"/documents/types":{"get":{"description":"Retorna todos os tipos de documentos que você pode processar, com seus endpoints e status.","operationId":"listDocumentTypes","parameters":[],"responses":{"200":{"description":"Tipos de documentos disponíveis","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentTypesResponseDto"}}}},"401":{"description":"Chave de API inválida ou ausente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedErrorDto"},"examples":{"invalidKey":{"summary":"A key that is unknown, revoked or expired","value":{"error":"Unauthorized","message":"Invalid or expired API key","timestamp":"2026-10-02T12:00:00.000Z"}},"missingKey":{"summary":"No key","value":{"error":"Unauthorized","message":"API key is required. Provide Authorization: Bearer <your-api-key>","timestamp":"2026-10-02T12:00:00.000Z"}}}}}}},"security":[{"api-key":[]}],"summary":"Listar tipos de documentos disponíveis","tags":["documents"],"x-codeSamples":[{"lang":"Shell","label":"cURL","source":"#!/usr/bin/env bash\n# The document types the API reads, and the endpoint of each.\n# Needs DOCSOCR_API_KEY in the environment; create a key in the panel.\nset -euo pipefail\n\ncurl -sS --max-time 30 https://api.docsocr.com/api/v1/documents/types \\\n  -H \"Authorization: Bearer $DOCSOCR_API_KEY\"\n"},{"lang":"Python","label":"Python","source":"\"\"\"The document types the API reads, and the endpoint of each.\n\nNeeds the requests package and DOCSOCR_API_KEY in the environment.\n\"\"\"\nimport os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.docsocr.com/api/v1/documents/types\",\n    headers={\"Authorization\": f\"Bearer {os.environ['DOCSOCR_API_KEY']}\"},\n    timeout=30,\n)\nresponse.raise_for_status()\nfor document_type in response.json()[\"types\"]:\n    print(f\"{document_type['id']}: POST {document_type['endpoint']}\")\n"},{"lang":"JavaScript","label":"Node.js","source":"// The document types the API reads, and the endpoint of each.\n// Needs Node.js 18+ and DOCSOCR_API_KEY in the environment.\nconst response = await fetch('https://api.docsocr.com/api/v1/documents/types', {\n  headers: { Authorization: `Bearer ${process.env.DOCSOCR_API_KEY}` },\n  signal: AbortSignal.timeout(30_000),\n})\nif (!response.ok) {\n  console.error(response.status, await response.text())\n  process.exit(1)\n}\nfor (const type of (await response.json()).types) {\n  console.log(`${type.id}: POST ${type.endpoint}`)\n}\n"},{"lang":"PHP","label":"PHP","source":"<?php\n// The document types the API reads, and the endpoint of each.\n// Needs the curl extension and DOCSOCR_API_KEY in the environment.\n\n$request = curl_init('https://api.docsocr.com/api/v1/documents/types');\ncurl_setopt_array($request, [\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_TIMEOUT => 30,\n    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('DOCSOCR_API_KEY')],\n]);\n$body = curl_exec($request);\n$status = curl_getinfo($request, CURLINFO_RESPONSE_CODE);\nif ($body === false || $status !== 200) {\n    fwrite(STDERR, \"$status \" . ($body === false ? curl_error($request) : $body) . PHP_EOL);\n    exit(1);\n}\nforeach (json_decode($body, true)['types'] as $type) {\n    echo \"{$type['id']}: POST {$type['endpoint']}\", PHP_EOL;\n}\n"},{"lang":"Java","label":"Java","source":"// The document types the API reads, and the endpoint of each.\n// Needs Java 17+ and DOCSOCR_API_KEY in the environment. Run: java DocumentTypes.java\nimport java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class DocumentTypes {\n    public static void main(String[] args) throws Exception {\n        HttpRequest request = HttpRequest.newBuilder(URI.create(\"https://api.docsocr.com/api/v1/documents/types\"))\n            .timeout(Duration.ofSeconds(30))\n            .header(\"Authorization\", \"Bearer \" + System.getenv(\"DOCSOCR_API_KEY\"))\n            .GET()\n            .build();\n        HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());\n\n        // The answer is JSON, e.g. {\"types\": [{\"id\": \"birth-certificate\", ...}]}; read it with your JSON library\n        System.out.println(response.body());\n        if (response.statusCode() != 200) {\n            System.exit(1);\n        }\n    }\n}\n"},{"lang":"C#","label":"C#","source":"// The document types the API reads, and the endpoint of each.\n// Needs .NET 8+ and DOCSOCR_API_KEY in the environment. Run: dotnet run DocumentTypes.cs (.NET 10)\nusing System.Net.Http.Headers;\nusing System.Text.Json;\n\nusing var http = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\nhttp.DefaultRequestHeaders.Authorization =\n    new AuthenticationHeaderValue(\"Bearer\", Environment.GetEnvironmentVariable(\"DOCSOCR_API_KEY\"));\n\nusing var response = await http.GetAsync(\"https://api.docsocr.com/api/v1/documents/types\");\nvar body = await response.Content.ReadAsStringAsync();\nif (!response.IsSuccessStatusCode)\n{\n    Console.Error.WriteLine($\"{(int)response.StatusCode} {body}\");\n    return 1;\n}\n\nusing var answer = JsonDocument.Parse(body);\nforeach (var type in answer.RootElement.GetProperty(\"types\").EnumerateArray())\n{\n    Console.WriteLine($\"{type.GetProperty(\"id\").GetString()}: POST {type.GetProperty(\"endpoint\").GetString()}\");\n}\nreturn 0;\n"}]}},"/documents/prices":{"get":{"description":"Quanto uma extração custa agora: nos motores padrão, no motor fast quando a requisição o pede, e o adicional de `resizeImage`. Não precisa de chave de API. O preço do fast pode mudar: consulte-o aqui.","operationId":"getExtractionPrices","parameters":[],"responses":{"200":{"description":"Os preços em vigor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractionPricesDto"}}}}},"security":[],"summary":"Preços de uma extração, em créditos","tags":["documents"],"x-codeSamples":[{"lang":"Shell","label":"cURL","source":"#!/usr/bin/env bash\n# The price of an extraction, in credits, per engine and for resizeImage.\n# A public endpoint: no key needed.\nset -euo pipefail\n\ncurl -sS --max-time 30 https://api.docsocr.com/api/v1/documents/prices\n"},{"lang":"Python","label":"Python","source":"\"\"\"The price of an extraction, in credits, per engine and for resizeImage.\n\nA public endpoint: no key needed. Needs the requests package.\n\"\"\"\nimport requests\n\nresponse = requests.get(\"https://api.docsocr.com/api/v1/documents/prices\", timeout=30)\nresponse.raise_for_status()\nfor name, credits in response.json().items():\n    print(f\"{name}: {credits} credit(s)\")\n"},{"lang":"JavaScript","label":"Node.js","source":"// The price of an extraction, in credits, per engine and for resizeImage.\n// A public endpoint: no key needed. Needs Node.js 18+.\nconst response = await fetch('https://api.docsocr.com/api/v1/documents/prices', {\n  signal: AbortSignal.timeout(30_000),\n})\nif (!response.ok) {\n  console.error(response.status)\n  process.exit(1)\n}\nfor (const [name, credits] of Object.entries(await response.json())) {\n  console.log(`${name}: ${credits} credit(s)`)\n}\n"},{"lang":"PHP","label":"PHP","source":"<?php\n// The price of an extraction, in credits, per engine and for resizeImage.\n// A public endpoint: no key needed. Needs the curl extension.\n\n$request = curl_init('https://api.docsocr.com/api/v1/documents/prices');\ncurl_setopt_array($request, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30]);\n$body = curl_exec($request);\nif ($body === false || curl_getinfo($request, CURLINFO_RESPONSE_CODE) !== 200) {\n    fwrite(STDERR, 'The price list did not answer' . PHP_EOL);\n    exit(1);\n}\nforeach (json_decode($body, true) as $name => $credits) {\n    echo \"$name: $credits credit(s)\", PHP_EOL;\n}\n"},{"lang":"Java","label":"Java","source":"// The price of an extraction, in credits, per engine and for resizeImage.\n// A public endpoint: no key needed. Needs Java 17+. Run: java Prices.java\nimport java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class Prices {\n    public static void main(String[] args) throws Exception {\n        HttpRequest request = HttpRequest.newBuilder(URI.create(\"https://api.docsocr.com/api/v1/documents/prices\"))\n            .timeout(Duration.ofSeconds(30))\n            .GET()\n            .build();\n        HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());\n\n        // The answer is JSON, e.g. {\"standard\": 1, ...}; read it with your JSON library\n        System.out.println(response.body());\n        if (response.statusCode() != 200) {\n            System.exit(1);\n        }\n    }\n}\n"},{"lang":"C#","label":"C#","source":"// The price of an extraction, in credits, per engine and for resizeImage.\n// A public endpoint: no key needed. Needs .NET 8+. Run: dotnet run Prices.cs (.NET 10)\nusing System.Text.Json;\n\nusing var http = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\nusing var prices = JsonDocument.Parse(await http.GetStringAsync(\"https://api.docsocr.com/api/v1/documents/prices\"));\n\nforeach (var price in prices.RootElement.EnumerateObject())\n{\n    Console.WriteLine($\"{price.Name}: {price.Value} credit(s)\");\n}\n"}]}},"/documents/birth-certificate":{"post":{"description":"\n**O que faz:** extrai todos os campos de uma certidão de nascimento brasileira a partir de uma foto, um escaneamento ou um PDF.\n\n**Envie a imagem** em uma URL pública (`imageType: \"url\"` com `imageUrl`) ou no corpo (`imageType: \"base64\"` com `imageBase64`). Teste com a certidão de exemplo hospedada, https://docsocr.com/samples/certidao-nascimento-exemplo.jpg (dados fictícios).\n\n**Nosso padrão de imagem:** 1344 a 2048 px no lado maior, onde todos os motores leem melhor. Uma imagem fora dele é recusada com 422, sem custo, a menos que `resizeImage: true` peça que a redimensionemos, por 1 crédito a mais; isso soma tempo à resposta.\n\n**O motor fast:** `\"engine\": \"fast\"` o pede. Ele é tentado primeiro, e os motores padrão entram em seguida se ele não conseguir responder.\n\n**A resposta:** os campos da certidão em `data`, o motor que respondeu (`engine`) e quanto a requisição custou (`creditsCharged`). Quando nenhum motor consegue responder, o status continua 201, com `success: false`, um `errorCode` e nada cobrado: `EXTRACTION_BUSY`, `EXTRACTION_TIMEOUT` e `EXTRACTION_UNAVAILABLE` podem passar quando você envia a mesma requisição de novo mais tarde; `DOCUMENT_NOT_RECOGNIZED` e `IMAGE_NOT_PROCESSABLE` pedem outra imagem.\n\n**Repetindo uma requisição:** o mesmo `requestId`, arquivo e opções em até 15 minutos da resposta recebem a mesma resposta sem custo, sem rodar os motores, com o header `Idempotent-Replayed: true`. Enquanto a primeira requisição ainda roda, uma repetição recebe 409 `REQUEST_IN_PROGRESS` com `Retry-After`.\n\n**Preço:** 1 crédito por resposta com dados, nos motores padrão; com `\"engine\": \"fast\"`, o preço do fast quando o fast responde (`GET /documents/prices`). **[Verificar saldo](https://app.docsocr.com/admin/billing/credits)**\n    ","operationId":"extractBirthCertificate","parameters":[{"name":"accept-language","required":false,"in":"header","description":"O idioma das mensagens de recusas e erros: `pt-BR` para português, inglês nos outros casos.","schema":{"type":"string","enum":["en","pt-BR"],"default":"en"}}],"requestBody":{"required":true,"description":"A imagem da certidão, em uma URL pública ou em base64: `imageType` diz qual.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BirthCertificateOcrRequestWithUrl"},{"$ref":"#/components/schemas/BirthCertificateOcrRequestWithBase64"}],"discriminator":{"propertyName":"imageType","mapping":{"url":"#/components/schemas/BirthCertificateOcrRequestWithUrl","base64":"#/components/schemas/BirthCertificateOcrRequestWithBase64"}}},"examples":{"sample":{"summary":"A certidão de exemplo hospedada (dados fictícios)","value":{"imageType":"url","imageUrl":"https://docsocr.com/samples/certidao-nascimento-exemplo.jpg","requestId":"6f1c2a9e-3b7d-4e5f-9a8b-1c2d3e4f5a6b"}},"base64":{"summary":"Um arquivo em base64 (encurtado aqui)","value":{"imageType":"base64","imageBase64":"data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcG...","requestId":"0b9d4c7e-58a1-4f2b-8c3d-6e7f8a9b0c1d"}},"resize":{"summary":"Uma imagem abaixo do nosso padrão, redimensionada por 1 crédito a mais","value":{"imageType":"url","imageUrl":"https://docsocr.com/samples/certidao-nascimento-exemplo-800x640.jpg","requestId":"9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d","resizeImage":true}},"fast":{"summary":"Pedindo o motor fast","value":{"imageType":"url","imageUrl":"https://docsocr.com/samples/certidao-nascimento-exemplo.jpg","requestId":"3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f","engine":"fast"}}}}}},"responses":{"201":{"description":"Os dados da certidão. Com `success: false`, nenhum motor conseguiu responder: `errorCode` diz por quê, e nada foi cobrado.","headers":{"Idempotent-Replayed":{"description":"`true` quando a resposta é a guardada para uma repetição: a mesma resposta da primeira vez, sem custo, sem os motores. Ausente nos outros casos.","schema":{"type":"string","enum":["true"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BirthCertificateOcrResponseDto"},"examples":{"data":{"summary":"A certidão de exemplo, respondida por um motor padrão","value":{"success":true,"processingTimeMs":6120,"data":{"documento":{"tipo":"Certidão de Nascimento","órgão_emissor":"CARTÓRIO DO 1º OFÍCIO DE REGISTRO CIVIL DE RECIFE - PE"},"dados_pessoais":{"nome_completo":"ANA BEATRIZ DOS SANTOS TESTE","cpf":"123.456.789-09","matrícula":"123456 01 55 2020 1 00012 123 0001234 56","data_nascimento":{"texto_completo":"","dia":"15","mês":"03","ano":"2020"},"hora_nascimento":"08:45","naturalidade":"RECIFE - PE","sexo":"FEMININO"},"local_nascimento":{"estabelecimento":"HOSPITAL EXEMPLO","município":"RECIFE","uf":"PE"},"registro":{"município":"RECIFE","uf":"PE","cartório":"CARTÓRIO DO 1º OFÍCIO DE REGISTRO CIVIL DE RECIFE - PE","data_registro":"20/03/2020","número_dnv":"","livro":"A-123","folha":"045","termo":"00012"},"filiação":{"genitor_1":{"nome_completo":"CARLA DOS SANTOS TESTE","naturalidade":""},"genitor_2":{"nome_completo":"JOÃO PEREIRA TESTE","naturalidade":""}},"avós":{"paternos":{"avô":"ANTÔNIO PEREIRA","avó":"LÚCIA PEREIRA"},"maternos":{"avô":"JOSÉ DOS SANTOS","avó":"MARIA DOS SANTOS"}},"gêmeos":{"status":"Não","informações_adicionais":""},"observações":{"averbações":"","anotações":""},"autenticação":{"selo_digital":"","oficial_registro":"PEDRO EXEMPLO","data_emissão":"20/03/2020"}},"engine":"mini","creditsCharged":1}},"resized":{"summary":"A amostra de 800×640 com resizeImage: true","value":{"success":true,"processingTimeMs":6120,"data":{"documento":{"tipo":"Certidão de Nascimento","órgão_emissor":"CARTÓRIO DO 1º OFÍCIO DE REGISTRO CIVIL DE RECIFE - PE"},"dados_pessoais":{"nome_completo":"ANA BEATRIZ DOS SANTOS TESTE","cpf":"123.456.789-09","matrícula":"123456 01 55 2020 1 00012 123 0001234 56","data_nascimento":{"texto_completo":"","dia":"15","mês":"03","ano":"2020"},"hora_nascimento":"08:45","naturalidade":"RECIFE - PE","sexo":"FEMININO"},"local_nascimento":{"estabelecimento":"HOSPITAL EXEMPLO","município":"RECIFE","uf":"PE"},"registro":{"município":"RECIFE","uf":"PE","cartório":"CARTÓRIO DO 1º OFÍCIO DE REGISTRO CIVIL DE RECIFE - PE","data_registro":"20/03/2020","número_dnv":"","livro":"A-123","folha":"045","termo":"00012"},"filiação":{"genitor_1":{"nome_completo":"CARLA DOS SANTOS TESTE","naturalidade":""},"genitor_2":{"nome_completo":"JOÃO PEREIRA TESTE","naturalidade":""}},"avós":{"paternos":{"avô":"ANTÔNIO PEREIRA","avó":"LÚCIA PEREIRA"},"maternos":{"avô":"JOSÉ DOS SANTOS","avó":"MARIA DOS SANTOS"}},"gêmeos":{"status":"Não","informações_adicionais":""},"observações":{"averbações":"","anotações":""},"autenticação":{"selo_digital":"","oficial_registro":"PEDRO EXEMPLO","data_emissão":"20/03/2020"}},"imageResized":true,"originalImageSize":{"width":800,"height":640},"finalImageSize":{"width":1344,"height":1075},"engine":"mini","creditsCharged":2}},"busy":{"summary":"Nenhum motor conseguiu responder: nada cobrado, envie de novo mais tarde","value":{"success":false,"processingTimeMs":1203,"error":"The extraction service is busy. Please retry in a few moments. No credit was charged.","errorCode":"EXTRACTION_BUSY","data":{"documento":{"tipo":"","órgão_emissor":""},"dados_pessoais":{"nome_completo":"","cpf":"","matrícula":"","data_nascimento":{"texto_completo":"","dia":"","mês":"","ano":""},"hora_nascimento":"","naturalidade":"","sexo":""},"local_nascimento":{"estabelecimento":"","município":"","uf":""},"registro":{"município":"","uf":"","cartório":"","data_registro":"","número_dnv":""},"filiação":{"genitor_1":{"nome_completo":"","naturalidade":""},"genitor_2":{"nome_completo":"","naturalidade":""}},"avós":{"paternos":{"avô":"","avó":""},"maternos":{"avô":"","avó":""}},"gêmeos":{"status":"Não","informações_adicionais":""},"observações":{"averbações":"","anotações":""},"autenticação":{"selo_digital":"","oficial_registro":"","data_emissão":""}},"creditsCharged":0}},"notRecognized":{"summary":"Não é uma certidão de nascimento: nada cobrado, não repita","value":{"success":false,"processingTimeMs":2410,"error":"The document could not be processed. Check that the image shows a birth certificate. No credit was charged.","errorCode":"DOCUMENT_NOT_RECOGNIZED","data":{"documento":{"tipo":"","órgão_emissor":""},"dados_pessoais":{"nome_completo":"","cpf":"","matrícula":"","data_nascimento":{"texto_completo":"","dia":"","mês":"","ano":""},"hora_nascimento":"","naturalidade":"","sexo":""},"local_nascimento":{"estabelecimento":"","município":"","uf":""},"registro":{"município":"","uf":"","cartório":"","data_registro":"","número_dnv":""},"filiação":{"genitor_1":{"nome_completo":"","naturalidade":""},"genitor_2":{"nome_completo":"","naturalidade":""}},"avós":{"paternos":{"avô":"","avó":""},"maternos":{"avô":"","avó":""}},"gêmeos":{"status":"Não","informações_adicionais":""},"observações":{"averbações":"","anotações":""},"autenticação":{"selo_digital":"","oficial_registro":"","data_emissão":""}},"creditsCharged":0}}}}}},"400":{"description":"O corpo não é válido: `message` lista o que corrigir. Nada foi cobrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorDto"},"examples":{"validation":{"summary":"Um campo está ausente ou errado","value":{"message":["imageUrl is required when imageType is \"url\"","requestId may only contain letters, digits, _, -, . and : (up to 128 characters)"],"error":"Bad Request","statusCode":400}}}}}},"401":{"description":"A chave de API está ausente, malformada, é desconhecida, foi revogada ou expirou.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedErrorDto"},"examples":{"invalidKey":{"summary":"Uma chave desconhecida, revogada ou expirada","value":{"error":"Unauthorized","message":"Invalid or expired API key","timestamp":"2026-10-02T12:00:00.000Z"}},"missingKey":{"summary":"Sem chave","value":{"error":"Unauthorized","message":"API key is required. Provide Authorization: Bearer <your-api-key>","timestamp":"2026-10-02T12:00:00.000Z"}}}}}},"402":{"description":"Créditos insuficientes para esta requisição (`errorCode` `NOT_ENOUGH_CREDITS`). Uma requisição reserva o seu preço enquanto roda: o preço do motor (veja `GET /documents/prices`), mais 1 crédito a mais com `resizeImage: true`. `message` traz o preço e o saldo; envie `Accept-Language: pt-BR` para recebê-la em português. A repetição de uma requisição respondida nos últimos 15 minutos não precisa de créditos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredErrorDto"},"examples":{"notEnoughCredits":{"summary":"O saldo não paga a requisição","value":{"statusCode":402,"message":"This request costs 1 credit, and the available balance is 0 credits. Buy credits or upgrade your plan to continue.","error":"Payment Required","errorCode":"NOT_ENOUGH_CREDITS","action":"purchase_credits","creditsAvailable":0,"creditsRequired":1,"planCreditsRemaining":0,"purchasedCreditsRemaining":0}}}}}},"409":{"description":"Uma requisição com o mesmo `requestId`, arquivo e opções ainda está rodando (`errorCode` `REQUEST_IN_PROGRESS`). Nada rodou e nada foi cobrado. Aguarde os segundos do `Retry-After` e envie de novo: você recebe a resposta sem custo.","headers":{"Retry-After":{"description":"Segundos para aguardar antes de enviar de novo, como `retryAfter`","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestInProgressErrorDto"},"examples":{"inProgress":{"summary":"A mesma requisição ainda está rodando","value":{"statusCode":409,"message":"A request with this requestId and the same content is still being processed. Try again in a few seconds to get its answer, at no charge.","error":"Conflict","errorCode":"REQUEST_IN_PROGRESS","retryAfter":5}}}}}},"413":{"description":"O corpo da requisição passa de 15 MB: `errorCode` `IMAGE_TOO_LARGE`. Nada foi cobrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayloadTooLargeErrorDto"},"examples":{"tooLarge":{"summary":"O corpo passa do limite","value":{"success":false,"errorCode":"IMAGE_TOO_LARGE","error":"The image is larger than 10 MB. Send a smaller image, for example a JPG with lower resolution or quality.","processingTimeMs":0}}}}}},"422":{"description":"A imagem não pode ser usada, ou a `imageUrl` não pôde ser baixada. `success` é false, `errorCode` informa o problema (por exemplo `IMAGE_TOO_LARGE`, `IMAGE_FORMAT_UNSUPPORTED`, `IMAGE_RESOLUTION_TOO_LOW`, `IMAGE_DOWNLOAD_FAILED`) e `error` o explica em palavras simples, com o que corrigir. Envie PDF*, JPG, PNG, WebP ou GIF, com até 10 MB, dentro do nosso padrão de 1344 a 2048 px no lado maior. *Lemos apenas a primeira página do PDF. Uma requisição recusada não custa nada. Envie `Accept-Language: pt-BR` para receber a mensagem em português.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BirthCertificateOcrResponseDto"},"examples":{"resolutionTooLow":{"summary":"IMAGE_RESOLUTION_TOO_LOW: a amostra de 800×640 sem resizeImage","value":{"success":false,"processingTimeMs":35,"error":"The image has 800 px on its long side; our standard is 1,344 to 2,048 px. Send a photo with more resolution, or set resizeImage: true to have it enlarged (1 extra credit).","errorCode":"IMAGE_RESOLUTION_TOO_LOW","data":{"documento":{"tipo":"","órgão_emissor":""},"dados_pessoais":{"nome_completo":"","cpf":"","matrícula":"","data_nascimento":{"texto_completo":"","dia":"","mês":"","ano":""},"hora_nascimento":"","naturalidade":"","sexo":""},"local_nascimento":{"estabelecimento":"","município":"","uf":""},"registro":{"município":"","uf":"","cartório":"","data_registro":"","número_dnv":""},"filiação":{"genitor_1":{"nome_completo":"","naturalidade":""},"genitor_2":{"nome_completo":"","naturalidade":""}},"avós":{"paternos":{"avô":"","avó":""},"maternos":{"avô":"","avó":""}},"gêmeos":{"status":"Não","informações_adicionais":""},"observações":{"averbações":"","anotações":""},"autenticação":{"selo_digital":"","oficial_registro":"","data_emissão":""}},"creditsCharged":0}},"downloadFailed":{"summary":"IMAGE_DOWNLOAD_FAILED: o link respondeu 404","value":{"success":false,"processingTimeMs":410,"error":"We could not download the image from imageUrl: the link answered HTTP 404 (file not found). Use a public, direct link to a PDF, JPG, PNG, WebP or GIF file that opens without a login, or send the image as imageBase64.","errorCode":"IMAGE_DOWNLOAD_FAILED","data":{"documento":{"tipo":"","órgão_emissor":""},"dados_pessoais":{"nome_completo":"","cpf":"","matrícula":"","data_nascimento":{"texto_completo":"","dia":"","mês":"","ano":""},"hora_nascimento":"","naturalidade":"","sexo":""},"local_nascimento":{"estabelecimento":"","município":"","uf":""},"registro":{"município":"","uf":"","cartório":"","data_registro":"","número_dnv":""},"filiação":{"genitor_1":{"nome_completo":"","naturalidade":""},"genitor_2":{"nome_completo":"","naturalidade":""}},"avós":{"paternos":{"avô":"","avó":""},"maternos":{"avô":"","avó":""}},"gêmeos":{"status":"Não","informações_adicionais":""},"observações":{"averbações":"","anotações":""},"autenticação":{"selo_digital":"","oficial_registro":"","data_emissão":""}},"creditsCharged":0}},"formatUnsupported":{"summary":"IMAGE_FORMAT_UNSUPPORTED: não é uma imagem que lemos","value":{"success":false,"processingTimeMs":35,"error":"The file is not in one of these formats: PDF, JPG, PNG, WebP or GIF. Convert it to one of them and send it again.","errorCode":"IMAGE_FORMAT_UNSUPPORTED","data":{"documento":{"tipo":"","órgão_emissor":""},"dados_pessoais":{"nome_completo":"","cpf":"","matrícula":"","data_nascimento":{"texto_completo":"","dia":"","mês":"","ano":""},"hora_nascimento":"","naturalidade":"","sexo":""},"local_nascimento":{"estabelecimento":"","município":"","uf":""},"registro":{"município":"","uf":"","cartório":"","data_registro":"","número_dnv":""},"filiação":{"genitor_1":{"nome_completo":"","naturalidade":""},"genitor_2":{"nome_completo":"","naturalidade":""}},"avós":{"paternos":{"avô":"","avó":""},"maternos":{"avô":"","avó":""}},"gêmeos":{"status":"Não","informações_adicionais":""},"observações":{"averbações":"","anotações":""},"autenticação":{"selo_digital":"","oficial_registro":"","data_emissão":""}},"creditsCharged":0}}}}}},"429":{"description":"Acima de um dos limites do seu plano. `retryAfter` diz quantos segundos aguardar; não há header Retry-After. Um limite por dia volta à meia-noite UTC.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorDto"},"examples":{"perMinute":{"summary":"Requisições demais neste minuto","value":{"statusCode":429,"message":"Organization rate limit exceeded (10 requests per minute). Retry after 6 seconds.","error":"Too Many Requests","retryAfter":6}},"perDay":{"summary":"O limite do dia foi atingido: ele volta à meia-noite UTC","value":{"statusCode":429,"message":"Daily quota exceeded (1000 requests per day). Current usage: 1000","error":"Too Many Requests","retryAfter":43200}}}}}},"503":{"description":"O serviço está reiniciando: o proxy responde com uma página HTML, e pode responder 502 ou 504 da mesma forma. Envie a mesma requisição de novo depois de alguns segundos, com o mesmo `requestId`, para nunca pagar duas vezes.","content":{"text/html":{"schema":{"type":"string"},"example":"<html>\r\n<head><title>503 Service Temporarily Unavailable</title></head>\r\n<body>\r\n<center><h1>503 Service Temporarily Unavailable</h1></center>\r\n<hr><center>nginx</center>\r\n</body>\r\n</html>\r\n"}}}},"security":[{"api-key":[]}],"summary":"Extrair dados de uma certidão de nascimento","tags":["documents"],"x-codeSamples":[{"lang":"Shell","label":"cURL","source":"#!/usr/bin/env bash\n# Your first call: extract the hosted sample certificate (fictitious data).\n# Needs DOCSOCR_API_KEY in the environment; create a key in the panel.\nset -euo pipefail\n\nREQUEST_ID=\"first-call-$(date +%s)-$RANDOM\" # one id per document\n\n# The API answers within 90 s\ncurl -sS --max-time 120 https://api.docsocr.com/api/v1/documents/birth-certificate \\\n  -H \"Authorization: Bearer $DOCSOCR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  --data-binary @- <<EOF\n{\n  \"imageType\": \"url\",\n  \"imageUrl\": \"https://docsocr.com/samples/certidao-nascimento-exemplo.jpg\",\n  \"requestId\": \"$REQUEST_ID\"\n}\nEOF\n"},{"lang":"Python","label":"Python","source":"\"\"\"Your first call: extract the hosted sample certificate (fictitious data).\n\nNeeds the requests package and DOCSOCR_API_KEY in the environment.\n\"\"\"\nimport os\nimport uuid\n\nimport requests\n\nresponse = requests.post(\n    \"https://api.docsocr.com/api/v1/documents/birth-certificate\",\n    headers={\"Authorization\": f\"Bearer {os.environ['DOCSOCR_API_KEY']}\"},\n    json={\n        \"imageType\": \"url\",\n        \"imageUrl\": \"https://docsocr.com/samples/certidao-nascimento-exemplo.jpg\",\n        \"requestId\": str(uuid.uuid4()),  # one id per document\n    },\n    timeout=120,  # above the API's 90 s extraction budget\n)\nanswer = response.json()\nif response.status_code != 201 or not answer[\"success\"]:\n    raise SystemExit(f\"{response.status_code} {answer.get('errorCode', '')} {answer.get('message') or answer.get('error')}\")\nprint(answer[\"data\"][\"dados_pessoais\"][\"nome_completo\"])\n"},{"lang":"JavaScript","label":"Node.js","source":"// Your first call: extract the hosted sample certificate (fictitious data).\n// Needs Node.js 18+ and DOCSOCR_API_KEY in the environment.\nimport { randomUUID } from 'node:crypto'\n\nconst response = await fetch('https://api.docsocr.com/api/v1/documents/birth-certificate', {\n  method: 'POST',\n  headers: {\n    Authorization: `Bearer ${process.env.DOCSOCR_API_KEY}`,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({\n    imageType: 'url',\n    imageUrl: 'https://docsocr.com/samples/certidao-nascimento-exemplo.jpg',\n    requestId: randomUUID(), // one id per document\n  }),\n  signal: AbortSignal.timeout(120_000), // above the API's 90 s extraction budget\n})\nconst answer = await response.json()\nif (response.status !== 201 || !answer.success) {\n  console.error(response.status, answer.errorCode ?? '', answer.message ?? answer.error)\n  process.exit(1)\n}\nconsole.log(answer.data.dados_pessoais.nome_completo)\n"},{"lang":"PHP","label":"PHP","source":"<?php\n// Your first call: extract the hosted sample certificate (fictitious data).\n// Needs the curl extension and DOCSOCR_API_KEY in the environment.\n\n$request = curl_init('https://api.docsocr.com/api/v1/documents/birth-certificate');\ncurl_setopt_array($request, [\n    CURLOPT_POST => true,\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_TIMEOUT => 120, // above the API's 90 s extraction budget\n    CURLOPT_HTTPHEADER => [\n        'Authorization: Bearer ' . getenv('DOCSOCR_API_KEY'),\n        'Content-Type: application/json',\n    ],\n    CURLOPT_POSTFIELDS => json_encode([\n        'imageType' => 'url',\n        'imageUrl' => 'https://docsocr.com/samples/certidao-nascimento-exemplo.jpg',\n        'requestId' => bin2hex(random_bytes(16)), // one id per document\n    ]),\n]);\n$body = curl_exec($request);\nif ($body === false) {\n    fwrite(STDERR, curl_error($request) . PHP_EOL);\n    exit(1);\n}\n$status = curl_getinfo($request, CURLINFO_RESPONSE_CODE);\n$answer = json_decode($body, true);\nif ($status !== 201 || empty($answer['success'])) {\n    fwrite(STDERR, \"$status \" . ($answer['errorCode'] ?? '') . ' ' . implode('; ', (array) ($answer['message'] ?? $answer['error'] ?? '')) . PHP_EOL);\n    exit(1);\n}\necho $answer['data']['dados_pessoais']['nome_completo'], PHP_EOL;\n"},{"lang":"Java","label":"Java","source":"// Your first call: extract the hosted sample certificate (fictitious data).\n// Needs Java 17+ and DOCSOCR_API_KEY in the environment. Run: java FirstCall.java\nimport java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\nimport java.util.UUID;\n\npublic class FirstCall {\n    public static void main(String[] args) throws Exception {\n        String body = \"\"\"\n            {\n              \"imageType\": \"url\",\n              \"imageUrl\": \"https://docsocr.com/samples/certidao-nascimento-exemplo.jpg\",\n              \"requestId\": \"%s\"\n            }\"\"\".formatted(UUID.randomUUID()); // one id per document\n\n        HttpRequest request = HttpRequest.newBuilder(URI.create(\"https://api.docsocr.com/api/v1/documents/birth-certificate\"))\n            .timeout(Duration.ofSeconds(120)) // above the API's 90 s extraction budget\n            .header(\"Authorization\", \"Bearer \" + System.getenv(\"DOCSOCR_API_KEY\"))\n            .header(\"Content-Type\", \"application/json\")\n            .POST(HttpRequest.BodyPublishers.ofString(body))\n            .build();\n        HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());\n\n        // The answer is JSON: read data.dados_pessoais.nome_completo with your JSON library\n        System.out.println(response.body());\n        if (response.statusCode() != 201 || !response.body().contains(\"\\\"success\\\":true\")) {\n            System.exit(1);\n        }\n    }\n}\n"},{"lang":"C#","label":"C#","source":"// Your first call: extract the hosted sample certificate (fictitious data).\n// Needs .NET 8+ and DOCSOCR_API_KEY in the environment. Run: dotnet run FirstCall.cs (.NET 10)\nusing System.Net.Http.Headers;\nusing System.Text;\nusing System.Text.Json;\nusing System.Text.Json.Nodes;\n\nusing var http = new HttpClient { Timeout = TimeSpan.FromSeconds(120) }; // above the API's 90 s extraction budget\nhttp.DefaultRequestHeaders.Authorization =\n    new AuthenticationHeaderValue(\"Bearer\", Environment.GetEnvironmentVariable(\"DOCSOCR_API_KEY\"));\n\nvar body = new JsonObject\n{\n    [\"imageType\"] = \"url\",\n    [\"imageUrl\"] = \"https://docsocr.com/samples/certidao-nascimento-exemplo.jpg\",\n    [\"requestId\"] = Guid.NewGuid().ToString(), // one id per document\n};\nusing var content = new StringContent(body.ToJsonString(), Encoding.UTF8, \"application/json\");\nusing var response = await http.PostAsync(\"https://api.docsocr.com/api/v1/documents/birth-certificate\", content);\nusing var answer = JsonDocument.Parse(await response.Content.ReadAsStringAsync());\nvar root = answer.RootElement;\n\nif ((int)response.StatusCode != 201 || !root.GetProperty(\"success\").GetBoolean())\n{\n    Console.Error.WriteLine($\"{(int)response.StatusCode} {root}\");\n    return 1;\n}\nConsole.WriteLine(root.GetProperty(\"data\").GetProperty(\"dados_pessoais\").GetProperty(\"nome_completo\").GetString());\nreturn 0;\n"}]}},"/health":{"get":{"description":"Se a API está no ar. Não precisa de chave de API.","operationId":"getHealth","parameters":[],"responses":{"200":{"description":"API está saudável","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"timestamp":{"type":"string","format":"date-time"},"uptime":{"type":"number","example":123.4},"environment":{"type":"string","example":"production"},"loadTestMode":{"type":"boolean","example":false}}}}}},"503":{"description":"API está com problemas"}},"security":[],"summary":"Verificação básica de saúde","tags":["health"],"x-codeSamples":[{"lang":"Shell","label":"cURL","source":"#!/usr/bin/env bash\n# Whether the API is up: \"status\": \"ok\" when it is.\n# A public endpoint: no key needed.\nset -euo pipefail\n\ncurl -sS --max-time 30 https://api.docsocr.com/api/v1/health\n"},{"lang":"Python","label":"Python","source":"\"\"\"Whether the API is up: \"status\": \"ok\" when it is.\n\nA public endpoint: no key needed. Needs the requests package.\n\"\"\"\nimport requests\n\nresponse = requests.get(\"https://api.docsocr.com/api/v1/health\", timeout=30)\nresponse.raise_for_status()\nprint(response.json()[\"status\"])\n"},{"lang":"JavaScript","label":"Node.js","source":"// Whether the API is up: \"status\": \"ok\" when it is.\n// A public endpoint: no key needed. Needs Node.js 18+.\nconst response = await fetch('https://api.docsocr.com/api/v1/health', {\n  signal: AbortSignal.timeout(30_000),\n})\nif (!response.ok) {\n  console.error(response.status)\n  process.exit(1)\n}\nconsole.log((await response.json()).status)\n"},{"lang":"PHP","label":"PHP","source":"<?php\n// Whether the API is up: \"status\": \"ok\" when it is.\n// A public endpoint: no key needed. Needs the curl extension.\n\n$request = curl_init('https://api.docsocr.com/api/v1/health');\ncurl_setopt_array($request, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30]);\n$body = curl_exec($request);\nif ($body === false || curl_getinfo($request, CURLINFO_RESPONSE_CODE) !== 200) {\n    fwrite(STDERR, 'The API is not up' . PHP_EOL);\n    exit(1);\n}\necho json_decode($body, true)['status'], PHP_EOL;\n"},{"lang":"Java","label":"Java","source":"// Whether the API is up: \"status\": \"ok\" when it is.\n// A public endpoint: no key needed. Needs Java 17+. Run: java Health.java\nimport java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class Health {\n    public static void main(String[] args) throws Exception {\n        HttpRequest request = HttpRequest.newBuilder(URI.create(\"https://api.docsocr.com/api/v1/health\"))\n            .timeout(Duration.ofSeconds(30))\n            .GET()\n            .build();\n        HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());\n\n        // The answer is JSON, e.g. {\"status\": \"ok\", ...}; read it with your JSON library\n        System.out.println(response.body());\n        if (response.statusCode() != 200) {\n            System.exit(1);\n        }\n    }\n}\n"},{"lang":"C#","label":"C#","source":"// Whether the API is up: \"status\": \"ok\" when it is.\n// A public endpoint: no key needed. Needs .NET 8+. Run: dotnet run Health.cs (.NET 10)\nusing System.Text.Json;\n\nusing var http = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\nusing var response = await http.GetAsync(\"https://api.docsocr.com/api/v1/health\");\nif (!response.IsSuccessStatusCode)\n{\n    Console.Error.WriteLine((int)response.StatusCode);\n    return 1;\n}\n\nusing var health = JsonDocument.Parse(await response.Content.ReadAsStringAsync());\nConsole.WriteLine(health.RootElement.GetProperty(\"status\").GetString());\nreturn 0;\n"}]}}},"info":{"title":"DocsOCR API","description":"\nExtraia os dados de uma certidão de nascimento brasileira a partir de uma foto, um escaneamento ou um PDF, com uma requisição.\n\n- **Sua primeira chamada:** envie a certidão de exemplo hospedada, https://docsocr.com/samples/certidao-nascimento-exemplo.jpg (dados fictícios), para **POST /documents/birth-certificate**. Os exemplos de código rodam como estão, em seis linguagens.\n- **Autenticação:** `Authorization: Bearer <sua chave de API>`. **[Crie uma chave](https://app.docsocr.com/admin/api-keys)**. As chaves começam com `dso_live_v1_` ou `dso_test_v1_`; as duas chamam os motores e usam créditos.\n- **Preços:** **GET /documents/prices**, sem chave. Os créditos só são cobrados quando a resposta traz os dados da certidão.\n- **Repetições:** o mesmo `requestId`, arquivo e opções em até 15 minutos recebem a mesma resposta sem custo.\n- **Erros:** toda recusa diz o motivo em `errorCode` e como corrigir na mensagem. Envie `Accept-Language: pt-BR` para recebê-la em português.\n\nGuias: **[docs.docsocr.com](https://docs.docsocr.com)**.\n","version":"2.2.1","contact":{"name":"Suporte DocsOCR","url":"https://docsocr.com","email":"support@docsocr.com"}},"tags":[{"name":"documents","description":"Extrair dados estruturados de imagens de documentos"},{"name":"health","description":"Verificar disponibilidade e status da API"}],"servers":[{"url":"https://api.docsocr.com/api/v1","description":"Production"}],"components":{"securitySchemes":{"api-key":{"type":"http","scheme":"bearer","description":"Sua chave de API DocsOCR, enviada como `Authorization: Bearer <chave>`. As chaves começam com `dso_live_v1_` ou `dso_test_v1_`; as duas chamam os motores e usam créditos. **[Gerenciar chaves](https://app.docsocr.com/admin/api-keys)**"}},"schemas":{"DocumentTypeDto":{"type":"object","properties":{"id":{"type":"string","description":"Identificador único do tipo de documento","example":"birth-certificate"},"name":{"type":"string","description":"Nome legível do tipo de documento","example":"Certidão de Nascimento"},"description":{"type":"string","description":"Breve descrição do tipo de documento","example":"Brazilian birth certificate OCR extraction"},"icon":{"type":"string","description":"Emoji ícone do tipo de documento","example":"📜"},"enabled":{"type":"boolean","description":"Se este tipo de documento está habilitado para processamento","example":true},"endpoint":{"type":"string","description":"Endpoint da API para processar este tipo de documento","example":"/documents/birth-certificate"}},"required":["id","name","description","icon","enabled","endpoint"]},"DocumentTypesResponseDto":{"type":"object","properties":{"types":{"description":"Lista de tipos de documentos disponíveis","type":"array","items":{"$ref":"#/components/schemas/DocumentTypeDto"}}},"required":["types"]},"UnauthorizedErrorDto":{"type":"object","properties":{"error":{"type":"string","description":"Categoria do erro (sempre `Unauthorized`)","example":"Unauthorized"},"message":{"type":"string","description":"O que há de errado com a chave. **[Gerenciar chaves de API](https://app.docsocr.com/admin/api-keys)**","example":"Invalid or expired API key"},"timestamp":{"type":"string","description":"Quando a requisição foi recusada, em UTC","example":"2026-10-02T12:00:00.000Z"}},"required":["error","message","timestamp"]},"ExtractionPricesDto":{"type":"object","properties":{"standard":{"type":"number","description":"Créditos de uma extração respondida pelos motores padrão: uma requisição sem `engine`.","example":1},"fast":{"type":"number","description":"Créditos de uma extração respondida pelo motor fast, quando a requisição o pede com `engine: \"fast\"`. Quando o fast não consegue responder e um motor padrão responde, a extração custa `standard`. Este preço pode mudar: consulte-o aqui."},"resizeImage":{"type":"number","description":"Créditos a mais quando o servidor redimensiona a imagem para o nosso padrão, como `resizeImage: true` pede.","example":1}},"required":["standard","fast","resizeImage"]},"BirthCertificateOcrRequestWithUrl":{"type":"object","properties":{"requestId":{"type":"string","description":"**Obrigatório.** Seu ID para esta requisição, com até 128 caracteres: letras, dígitos, `_`, `-`, `.` e `:`. Não coloque dados pessoais nele. O mesmo `requestId` com o mesmo arquivo e as mesmas opções em até 15 minutos da resposta devolve a mesma resposta sem custo, sem rodar os motores; com outro arquivo ou outras opções, é uma nova requisição. A resposta não o repete.","example":"6f1c2a9e-3b7d-4e5f-9a8b-1c2d3e4f5a6b","maxLength":128,"pattern":"^[\\w.:-]+$"},"resizeImage":{"type":"boolean","description":"Redimensiona uma imagem fora do nosso padrão (1344 a 2048 px no lado maior) para caber nele, em vez de recusá-la: a extração passa a custar 1 crédito a mais, e a resposta traz `imageResized: true`. A requisição precisa do seu preço mais o redimensionamento disponíveis enquanto roda (2 créditos nos motores padrão). Sem ele, essa imagem é recusada com 422 e não custa nada. Uma imagem dentro do padrão nunca é redimensionada e custa o preço da extração de qualquer forma.","default":false,"example":false},"engine":{"type":"string","description":"Pede o motor fast: ele é tentado primeiro e, quando não consegue responder, os motores padrão entram em seguida. Deixe de fora para usar os motores padrão. Só `\"fast\"` é aceito; qualquer outro valor é recusado com 400 e não custa nada.","enum":["fast"],"example":"fast"},"imageType":{"type":"string","description":"**Obrigatório.** `\"url\"`: a imagem está em `imageUrl`.","enum":["url"],"example":"url"},"imageUrl":{"type":"string","description":"**Obrigatório.** URL pública da imagem da certidão: um link direto que abre sem login.","example":"https://docsocr.com/samples/certidao-nascimento-exemplo.jpg"}},"required":["requestId","imageType","imageUrl"],"additionalProperties":false},"BirthCertificateOcrRequestWithBase64":{"type":"object","properties":{"requestId":{"type":"string","description":"**Obrigatório.** Seu ID para esta requisição, com até 128 caracteres: letras, dígitos, `_`, `-`, `.` e `:`. Não coloque dados pessoais nele. O mesmo `requestId` com o mesmo arquivo e as mesmas opções em até 15 minutos da resposta devolve a mesma resposta sem custo, sem rodar os motores; com outro arquivo ou outras opções, é uma nova requisição. A resposta não o repete.","example":"6f1c2a9e-3b7d-4e5f-9a8b-1c2d3e4f5a6b","maxLength":128,"pattern":"^[\\w.:-]+$"},"resizeImage":{"type":"boolean","description":"Redimensiona uma imagem fora do nosso padrão (1344 a 2048 px no lado maior) para caber nele, em vez de recusá-la: a extração passa a custar 1 crédito a mais, e a resposta traz `imageResized: true`. A requisição precisa do seu preço mais o redimensionamento disponíveis enquanto roda (2 créditos nos motores padrão). Sem ele, essa imagem é recusada com 422 e não custa nada. Uma imagem dentro do padrão nunca é redimensionada e custa o preço da extração de qualquer forma.","default":false,"example":false},"engine":{"type":"string","description":"Pede o motor fast: ele é tentado primeiro e, quando não consegue responder, os motores padrão entram em seguida. Deixe de fora para usar os motores padrão. Só `\"fast\"` é aceito; qualquer outro valor é recusado com 400 e não custa nada.","enum":["fast"],"example":"fast"},"imageType":{"type":"string","description":"**Obrigatório.** `\"base64\"`: a imagem está em `imageBase64`.","enum":["base64"],"example":"base64"},"imageBase64":{"type":"string","description":"**Obrigatório.** O arquivo da certidão em base64, com ou sem o prefixo data URI, por exemplo `data:image/jpeg;base64,/9j/4AAQ...`. PDF*, JPG, PNG, WebP ou GIF, com até 10 MB; o tipo é lido do próprio arquivo. *Lemos apenas a primeira página do PDF.","example":"data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcG..."}},"required":["requestId","imageType","imageBase64"],"additionalProperties":false},"DocumentoDto":{"type":"object","properties":{"tipo":{"type":"string","description":"Tipo do documento","example":"Certidão de Nascimento"},"órgão_emissor":{"type":"string","description":"Órgão emissor","example":"Cartório Civil"}},"required":["tipo","órgão_emissor"]},"DataNascimentoDto":{"type":"object","properties":{"texto_completo":{"type":"string","description":"Texto completo da data de nascimento","example":"Primeiro de Janeiro de Dois Mil"},"dia":{"type":"string","description":"Dia do nascimento","example":"01"},"mês":{"type":"string","description":"Mês do nascimento","example":"01"},"ano":{"type":"string","description":"Ano do nascimento","example":"2000"}},"required":["texto_completo","dia","mês","ano"]},"DadosPessoaisDto":{"type":"object","properties":{"nome_completo":{"type":"string","description":"**Nome completo** como escrito na certidão.","example":"João Pedro da Silva Santos"},"cpf":{"type":"string","description":"**Número do CPF** (Cadastro de Pessoa Física). Formato: `XXX.XXX.XXX-XX`","example":"123.456.789-00"},"matrícula":{"type":"string","description":"**Número de matrícula** — o identificador único da certidão.","example":"123456 01 55 2000 1 00012 034 0001234-56"},"data_nascimento":{"description":"Detalhes da data de nascimento (dia, mês, ano, texto completo).","allOf":[{"$ref":"#/components/schemas/DataNascimentoDto"}]},"hora_nascimento":{"type":"string","description":"Hora do nascimento no formato 24 horas.","example":"13:45"},"naturalidade":{"type":"string","description":"Local de nascimento — nome da cidade.","example":"São Paulo"},"sexo":{"type":"string","description":"Sexo conforme escrito na certidão.","example":"Masculino"}},"required":["nome_completo","cpf","matrícula","data_nascimento","hora_nascimento","naturalidade","sexo"]},"LocalNascimentoDto":{"type":"object","properties":{"estabelecimento":{"type":"string","description":"Estabelecimento de nascimento","example":"Hospital São Luiz"},"município":{"type":"string","description":"Município de nascimento","example":"São Paulo"},"uf":{"type":"string","description":"Estado de nascimento","example":"SP"}},"required":["estabelecimento","município","uf"]},"RegistroDto":{"type":"object","properties":{"município":{"type":"string","description":"Município de registro","example":"São Paulo"},"uf":{"type":"string","description":"Estado de registro","example":"SP"},"cartório":{"type":"string","description":"Cartório de registro","example":"Cartório do 1º Ofício"},"data_registro":{"type":"string","description":"Data de registro","example":"15/01/2000"},"número_dnv":{"type":"string","description":"Número da Declaração de Nascido Vivo","example":"12345678"},"livro":{"type":"string","description":"Livro do registro: como impresso nas certidões antigas; nas atuais, extraído da matrícula de 32 dígitos","example":"345"},"folha":{"type":"string","description":"Folha do registro: como impressa nas certidões antigas; nas atuais, extraída da matrícula de 32 dígitos","example":"210"},"termo":{"type":"string","description":"Termo do registro: como impresso nas certidões antigas; nas atuais, extraído da matrícula de 32 dígitos","example":"4567"}},"required":["município","uf","cartório","data_registro","número_dnv"]},"GenitorDto":{"type":"object","properties":{"nome_completo":{"type":"string","description":"Nome completo","example":"José da Silva"},"naturalidade":{"type":"string","description":"Local de nascimento","example":"Rio de Janeiro"}},"required":["nome_completo","naturalidade"]},"FiliacaoDto":{"type":"object","properties":{"genitor_1":{"description":"O genitor impresso primeiro na certidão (na ordem impressa, sem indicar gênero)","allOf":[{"$ref":"#/components/schemas/GenitorDto"}]},"genitor_2":{"description":"O genitor impresso em segundo na certidão (na ordem impressa, sem indicar gênero)","allOf":[{"$ref":"#/components/schemas/GenitorDto"}]}},"required":["genitor_1","genitor_2"]},"AvosParentescoDto":{"type":"object","properties":{"avô":{"type":"string","description":"Nome do avô","example":"José da Silva"},"avó":{"type":"string","description":"Nome da avó","example":"Ana da Silva"}},"required":["avô","avó"]},"AvosDto":{"type":"object","properties":{"paternos":{"description":"Avós paternos","allOf":[{"$ref":"#/components/schemas/AvosParentescoDto"}]},"maternos":{"description":"Avós maternos","allOf":[{"$ref":"#/components/schemas/AvosParentescoDto"}]}},"required":["paternos","maternos"]},"GemeosDto":{"type":"object","properties":{"status":{"type":"string","description":"Status de gêmeos","example":"Não"},"informações_adicionais":{"type":"string","description":"Informações adicionais sobre gêmeos","example":""}},"required":["status","informações_adicionais"]},"ObservacoesDto":{"type":"object","properties":{"averbações":{"type":"string","description":"Averbações do registro","example":""},"anotações":{"type":"string","description":"Anotações adicionais","example":""}},"required":["averbações","anotações"]},"AutenticacaoDto":{"type":"object","properties":{"selo_digital":{"type":"string","description":"Selo digital","example":"ABC123XYZ"},"oficial_registro":{"type":"string","description":"Oficial de registro","example":"Maria Oliveira"},"data_emissão":{"type":"string","description":"Data de emissão","example":"20/01/2000"}},"required":["selo_digital","oficial_registro","data_emissão"]},"DocumentoEstruturaDto":{"type":"object","properties":{"documento":{"description":"Informações do documento","allOf":[{"$ref":"#/components/schemas/DocumentoDto"}]},"dados_pessoais":{"description":"Dados pessoais","allOf":[{"$ref":"#/components/schemas/DadosPessoaisDto"}]},"local_nascimento":{"description":"Local de nascimento","allOf":[{"$ref":"#/components/schemas/LocalNascimentoDto"}]},"registro":{"description":"Informações de registro","allOf":[{"$ref":"#/components/schemas/RegistroDto"}]},"filiação":{"description":"Informações de filiação","allOf":[{"$ref":"#/components/schemas/FiliacaoDto"}]},"avós":{"description":"Informações dos avós","allOf":[{"$ref":"#/components/schemas/AvosDto"}]},"gêmeos":{"description":"Informações de gêmeos","allOf":[{"$ref":"#/components/schemas/GemeosDto"}]},"observações":{"description":"Observações e anotações","allOf":[{"$ref":"#/components/schemas/ObservacoesDto"}]},"autenticação":{"description":"Informações de autenticação","allOf":[{"$ref":"#/components/schemas/AutenticacaoDto"}]}},"required":["documento","dados_pessoais","local_nascimento","registro","filiação","avós","gêmeos","observações","autenticação"]},"ImageSizeDto":{"type":"object","properties":{"width":{"type":"number","description":"Largura, em pixels.","example":4000},"height":{"type":"number","description":"Altura, em pixels.","example":3000}},"required":["width","height"]},"BirthCertificateOcrResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` se a extração foi bem-sucedida. Verifique o campo `error` se `false`.","example":true},"error":{"type":"string","description":"O que deu errado. *Presente apenas quando success é false.*","example":"The extraction service is busy. Please retry in a few moments. No credit was charged."},"errorCode":{"type":"string","description":"Por que a extração falhou, como um código que o seu sistema pode tratar. `error` explica em palavras simples. *Presente apenas quando success é false.*","enum":["IMAGE_MISSING","IMAGE_BASE64_INVALID","IMAGE_TOO_LARGE","IMAGE_TOO_MANY_PIXELS","IMAGE_FORMAT_UNSUPPORTED","IMAGE_UNREADABLE","IMAGE_URL_NOT_ALLOWED","IMAGE_RESOLUTION_TOO_LOW","IMAGE_RESOLUTION_TOO_HIGH","IMAGE_INVALID","PDF_PASSWORD_PROTECTED","PDF_UNREADABLE","PDF_TOO_MANY_PAGES","IMAGE_DOWNLOAD_FAILED","IMAGE_NOT_PROCESSABLE","DOCUMENT_NOT_RECOGNIZED","EXTRACTION_TIMEOUT","EXTRACTION_BUSY","EXTRACTION_UNAVAILABLE"],"example":"EXTRACTION_BUSY"},"processingTimeMs":{"type":"number","description":"Quanto tempo a extração levou, em milissegundos.","example":1847},"data":{"description":"**Dados extraídos da certidão.** Contém todos os campos encontrados no documento — nome, data de nascimento, pais, informações de registro e mais. Quando `success` é false, todos os campos vêm vazios.","allOf":[{"$ref":"#/components/schemas/DocumentoEstruturaDto"}]},"imageResized":{"type":"boolean","description":"`true` quando a imagem estava fora do nosso padrão (1344 a 2048 px no lado maior) e foi redimensionada para caber nele, como `resizeImage` pediu: a extração custou 1 crédito a mais. *Presente apenas quando isso aconteceu.*","example":true},"originalImageSize":{"description":"Tamanho da imagem como você a enviou, na orientação de exibição. *Presente apenas quando imageResized é true.*","allOf":[{"$ref":"#/components/schemas/ImageSizeDto"}]},"finalImageSize":{"description":"Tamanho da imagem depois de redimensionada ao nosso padrão. *Presente apenas quando imageResized é true.*","allOf":[{"$ref":"#/components/schemas/ImageSizeDto"}]},"engine":{"type":"string","description":"O motor que respondeu com dados: `fast` quando a requisição o pediu e o fast respondeu, ou `mini` ou `large` para os motores padrão. *Presente apenas quando um motor respondeu.*","enum":["mini","large","fast"],"example":"fast"},"creditsCharged":{"type":"number","description":"Créditos que esta requisição custou, ao centésimo: o preço do motor que respondeu (nunca mais que o do motor que você pediu), mais o redimensionamento. 0 quando nada foi cobrado: uma imagem recusada, nenhum motor conseguiu responder, ou uma repetição respondida com a resposta guardada (`Idempotent-Replayed: true`).","example":1}},"required":["success","processingTimeMs","creditsCharged"]},"ValidationErrorDto":{"type":"object","properties":{"statusCode":{"type":"number","description":"Código de status HTTP (sempre 400)","example":400},"message":{"description":"**O que corrigir**, uma linha por problema","example":["imageUrl is required when imageType is \"url\""],"type":"array","items":{"type":"string"}},"error":{"type":"string","description":"Categoria do erro","example":"Bad Request"}},"required":["statusCode","message","error"]},"PaymentRequiredErrorDto":{"type":"object","properties":{"statusCode":{"type":"number","description":"Código de status HTTP (sempre 402)","example":402},"message":{"type":"string","description":"O preço da requisição e o saldo, com o que fazer. Envie `Accept-Language: pt-BR` para recebê-la em português.","example":"This request costs 1 credit, and the available balance is 0 credits. Buy credits or upgrade your plan to continue."},"error":{"type":"string","description":"Categoria do erro","example":"Payment Required"},"errorCode":{"type":"string","description":"Sempre `NOT_ENOUGH_CREDITS`","example":"NOT_ENOUGH_CREDITS"},"action":{"type":"string","description":"O que fazer: comprar créditos ou mudar de plano","example":"purchase_credits"},"creditsAvailable":{"type":"number","description":"Créditos que a organização pode usar agora, ao centésimo","example":0},"creditsRequired":{"type":"number","description":"O preço da requisição, que ela reserva enquanto roda","example":1},"planCreditsRemaining":{"type":"number","description":"Créditos restantes da franquia mensal do plano","example":0},"purchasedCreditsRemaining":{"type":"number","description":"Créditos restantes de compras","example":0}},"required":["statusCode","message","error","errorCode","action","creditsAvailable","creditsRequired","planCreditsRemaining","purchasedCreditsRemaining"]},"RequestInProgressErrorDto":{"type":"object","properties":{"statusCode":{"type":"number","description":"Código de status HTTP (sempre 409)","example":409},"message":{"type":"string","description":"O que fazer — *legível*","example":"A request with this requestId and the same content is still being processed. Try again in a few seconds to get its answer, at no charge."},"error":{"type":"string","description":"Categoria do erro","example":"Conflict"},"errorCode":{"type":"string","description":"Sempre `REQUEST_IN_PROGRESS`","example":"REQUEST_IN_PROGRESS"},"retryAfter":{"type":"number","description":"Segundos para aguardar antes de enviar a requisição de novo","example":5}},"required":["statusCode","message","error","errorCode","retryAfter"]},"PayloadTooLargeErrorDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Sempre `false`","example":false},"errorCode":{"type":"string","description":"Sempre `IMAGE_TOO_LARGE`","example":"IMAGE_TOO_LARGE"},"error":{"type":"string","description":"O que enviar no lugar. `Accept-Language: pt-BR` a traz em português.","example":"The image is larger than 10 MB. Send a smaller image, for example a JPG with lower resolution or quality."},"processingTimeMs":{"type":"number","description":"Sempre 0: nada foi processado","example":0}},"required":["success","errorCode","error","processingTimeMs"]},"RateLimitErrorDto":{"type":"object","properties":{"statusCode":{"type":"number","description":"Código de status HTTP (sempre 429)","example":429},"message":{"type":"string","description":"Qual limite foi atingido, e o seu tamanho. **[Ver uso](https://app.docsocr.com/admin/analytics)**","example":"Organization rate limit exceeded (10 requests per minute). Retry after 6 seconds."},"error":{"type":"string","description":"Categoria do erro","example":"Too Many Requests"},"retryAfter":{"type":"number","description":"**Segundos para aguardar** antes de enviar a requisição de novo. Um limite por dia dura até a meia-noite UTC, então a espera pode ser de horas.","example":6}},"required":["statusCode","message","error","retryAfter"]}}},"security":[{"api-key":[]}]}