Extrair dados de uma certidão de nascimento

POST /documents/birth-certificate

O que faz: extrai todos os campos de uma certidão de nascimento brasileira a partir de uma foto, um escaneamento ou um PDF.

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).

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.

O motor fast: "engine": "fast" o pede. Ele é tentado primeiro, e os motores padrão entram em seguida se ele não conseguir responder.

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.

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.

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

Autenticação

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

Parâmetros

accept-language header "en" ou "pt-BR", padrão "en" Opcional
O idioma das mensagens de recusas e erros: pt-BR para português, inglês nos outros casos.

Corpo da requisição

A imagem da certidão, em uma URL pública ou em base64: imageType diz qual.

Content-Type: application/json

imageType "url" ou "base64" Obrigatório
"url": a imagem está em imageUrl. "base64": a imagem está em imageBase64.
requestId string 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.
imageUrl string Com imageType: "url"
URL pública da imagem da certidão: um link direto que abre sem login.
imageBase64 string Com imageType: "base64"
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.
resizeImage boolean, padrão false Opcional
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.
engine "fast" Opcional
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.

Exemplos

A certidão de exemplo hospedada (dados fictícios)Um arquivo em base64 (encurtado aqui)Uma imagem abaixo do nosso padrão, redimensionada por 1 crédito a maisPedindo o motor fast

json

{
  "imageType": "url",
  "imageUrl": "https://docsocr.com/samples/certidao-nascimento-exemplo.jpg",
  "requestId": "6f1c2a9e-3b7d-4e5f-9a8b-1c2d3e4f5a6b"
}

json

{
  "imageType": "base64",
  "imageBase64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcG...",
  "requestId": "0b9d4c7e-58a1-4f2b-8c3d-6e7f8a9b0c1d"
}

json

{
  "imageType": "url",
  "imageUrl": "https://docsocr.com/samples/certidao-nascimento-exemplo-800x640.jpg",
  "requestId": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
  "resizeImage": true
}

json

{
  "imageType": "url",
  "imageUrl": "https://docsocr.com/samples/certidao-nascimento-exemplo.jpg",
  "requestId": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
  "engine": "fast"
}

Respostas

201 Created

Os dados da certidão. Com success: false, nenhum motor conseguiu responder: errorCode diz por quê, e nada foi cobrado.

Idempotent-Replayed header
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.

Campos da resposta

success boolean
true se a extração foi bem-sucedida. Verifique o campo error se false.
error string
O que deu errado. Presente apenas quando success é false.
errorCode "IMAGE_MISSING" ou "IMAGE_BASE64_INVALID" ou "IMAGE_TOO_LARGE" ou "IMAGE_TOO_MANY_PIXELS" ou "IMAGE_FORMAT_UNSUPPORTED" ou "IMAGE_UNREADABLE" ou "IMAGE_URL_NOT_ALLOWED" ou "IMAGE_RESOLUTION_TOO_LOW" ou "IMAGE_RESOLUTION_TOO_HIGH" ou "IMAGE_INVALID" ou "PDF_PASSWORD_PROTECTED" ou "PDF_UNREADABLE" ou "PDF_TOO_MANY_PAGES" ou "IMAGE_DOWNLOAD_FAILED" ou "IMAGE_NOT_PROCESSABLE" ou "DOCUMENT_NOT_RECOGNIZED" ou "EXTRACTION_TIMEOUT" ou "EXTRACTION_BUSY" ou "EXTRACTION_UNAVAILABLE"
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.
processingTimeMs number
Quanto tempo a extração levou, em milissegundos.
data objeto
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.
imageResized boolean
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.
originalImageSize objeto
Tamanho da imagem como você a enviou, na orientação de exibição. Presente apenas quando imageResized é true.
originalImageSize.width number
Largura, em pixels.
originalImageSize.height number
Altura, em pixels.
finalImageSize objeto
Tamanho da imagem depois de redimensionada ao nosso padrão. Presente apenas quando imageResized é true.
finalImageSize.width number
Largura, em pixels.
finalImageSize.height number
Altura, em pixels.
engine "mini" ou "large" ou "fast"
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.
creditsCharged number
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).

A certidão de exemplo, respondida por um motor padrãoA amostra de 800×640 com resizeImage: trueNenhum motor conseguiu responder: nada cobrado, envie de novo mais tardeNão é uma certidão de nascimento: nada cobrado, não repita

json

{
  "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
}

json

{
  "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
}

json

{
  "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
}

json

{
  "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 Bad Request

O corpo não é válido: message lista o que corrigir. Nada foi cobrado.

Campos da resposta

statusCode number
Código de status HTTP (sempre 400)
message string[]
O que corrigir, uma linha por problema
error string
Categoria do erro

Um campo está ausente ou errado

json

{
  "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 Unauthorized

A chave de API está ausente, malformada, é desconhecida, foi revogada ou expirou.

Campos da resposta

error string
Categoria do erro (sempre Unauthorized)
message string
O que há de errado com a chave. Gerenciar chaves de API
timestamp string
Quando a requisição foi recusada, em UTC

Uma chave desconhecida, revogada ou expiradaSem chave

json

{
  "error": "Unauthorized",
  "message": "Invalid or expired API key",
  "timestamp": "2026-10-02T12:00:00.000Z"
}

json

{
  "error": "Unauthorized",
  "message": "API key is required. Provide Authorization: Bearer <your-api-key>",
  "timestamp": "2026-10-02T12:00:00.000Z"
}

402 Payment Required

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.

Campos da resposta

statusCode number
Código de status HTTP (sempre 402)
message string
O preço da requisição e o saldo, com o que fazer. Envie Accept-Language: pt-BR para recebê-la em português.
error string
Categoria do erro
errorCode string
Sempre NOT_ENOUGH_CREDITS
action string
O que fazer: comprar créditos ou mudar de plano
creditsAvailable number
Créditos que a organização pode usar agora, ao centésimo
creditsRequired number
O preço da requisição, que ela reserva enquanto roda
planCreditsRemaining number
Créditos restantes da franquia mensal do plano
purchasedCreditsRemaining number
Créditos restantes de compras

O saldo não paga a requisição

json

{
  "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 Conflict

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.

Retry-After header
Segundos para aguardar antes de enviar de novo, como retryAfter

Campos da resposta

statusCode number
Código de status HTTP (sempre 409)
message string
O que fazer — legível
error string
Categoria do erro
errorCode string
Sempre REQUEST_IN_PROGRESS
retryAfter number
Segundos para aguardar antes de enviar a requisição de novo

A mesma requisição ainda está rodando

json

{
  "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 Payload Too Large

O corpo da requisição passa de 15 MB: errorCode IMAGE_TOO_LARGE. Nada foi cobrado.

Campos da resposta

success boolean
Sempre false
errorCode string
Sempre IMAGE_TOO_LARGE
error string
O que enviar no lugar. Accept-Language: pt-BR a traz em português.
processingTimeMs number
Sempre 0: nada foi processado

O corpo passa do limite

json

{
  "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 Unprocessable Entity

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.

Campos da resposta

success boolean
true se a extração foi bem-sucedida. Verifique o campo error se false.
error string
O que deu errado. Presente apenas quando success é false.
errorCode "IMAGE_MISSING" ou "IMAGE_BASE64_INVALID" ou "IMAGE_TOO_LARGE" ou "IMAGE_TOO_MANY_PIXELS" ou "IMAGE_FORMAT_UNSUPPORTED" ou "IMAGE_UNREADABLE" ou "IMAGE_URL_NOT_ALLOWED" ou "IMAGE_RESOLUTION_TOO_LOW" ou "IMAGE_RESOLUTION_TOO_HIGH" ou "IMAGE_INVALID" ou "PDF_PASSWORD_PROTECTED" ou "PDF_UNREADABLE" ou "PDF_TOO_MANY_PAGES" ou "IMAGE_DOWNLOAD_FAILED" ou "IMAGE_NOT_PROCESSABLE" ou "DOCUMENT_NOT_RECOGNIZED" ou "EXTRACTION_TIMEOUT" ou "EXTRACTION_BUSY" ou "EXTRACTION_UNAVAILABLE"
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.
processingTimeMs number
Quanto tempo a extração levou, em milissegundos.
data objeto
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.
imageResized boolean
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.
originalImageSize objeto
Tamanho da imagem como você a enviou, na orientação de exibição. Presente apenas quando imageResized é true.
originalImageSize.width number
Largura, em pixels.
originalImageSize.height number
Altura, em pixels.
finalImageSize objeto
Tamanho da imagem depois de redimensionada ao nosso padrão. Presente apenas quando imageResized é true.
finalImageSize.width number
Largura, em pixels.
finalImageSize.height number
Altura, em pixels.
engine "mini" ou "large" ou "fast"
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.
creditsCharged number
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).

IMAGE_RESOLUTION_TOO_LOW: a amostra de 800×640 sem resizeImageIMAGE_DOWNLOAD_FAILED: o link respondeu 404IMAGE_FORMAT_UNSUPPORTED: não é uma imagem que lemos

json

{
  "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
}

json

{
  "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
}

json

{
  "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 Too Many Requests

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.

Campos da resposta

statusCode number
Código de status HTTP (sempre 429)
message string
Qual limite foi atingido, e o seu tamanho. Ver uso
error string
Categoria do erro
retryAfter number
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.

Requisições demais neste minutoO limite do dia foi atingido: ele volta à meia-noite UTC

json

{
  "statusCode": 429,
  "message": "Organization rate limit exceeded (10 requests per minute). Retry after 6 seconds.",
  "error": "Too Many Requests",
  "retryAfter": 6
}

json

{
  "statusCode": 429,
  "message": "Daily quota exceeded (1000 requests per day). Current usage: 1000",
  "error": "Too Many Requests",
  "retryAfter": 43200
}

503 Service Unavailable

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.

503

html

<html>
<head><title>503 Service Temporarily Unavailable</title></head>
<body>
<center><h1>503 Service Temporarily Unavailable</h1></center>
<hr><center>nginx</center>
</body>
</html>

Valores de errorCode

O errorCode de uma resposta sem dados diz por quê, como um código que o seu sistema pode tratar. Os valores desta operação:

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
NOT_ENOUGH_CREDITS
REQUEST_IN_PROGRESS

bash

#!/usr/bin/env bash
# Your first call: extract the hosted sample certificate (fictitious data).
# Needs DOCSOCR_API_KEY in the environment; create a key in the panel.
set -euo pipefail

REQUEST_ID="first-call-$(date +%s)-$RANDOM" # one id per document

# The API answers within 90 s
curl -sS --max-time 120 https://api.docsocr.com/api/v1/documents/birth-certificate \
  -H "Authorization: Bearer $DOCSOCR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
{
  "imageType": "url",
  "imageUrl": "https://docsocr.com/samples/certidao-nascimento-exemplo.jpg",
  "requestId": "$REQUEST_ID"
}
EOF

python

"""Your first call: extract the hosted sample certificate (fictitious data).

Needs the requests package and DOCSOCR_API_KEY in the environment.
"""
import os
import uuid

import requests

response = requests.post(
    "https://api.docsocr.com/api/v1/documents/birth-certificate",
    headers={"Authorization": f"Bearer {os.environ['DOCSOCR_API_KEY']}"},
    json={
        "imageType": "url",
        "imageUrl": "https://docsocr.com/samples/certidao-nascimento-exemplo.jpg",
        "requestId": str(uuid.uuid4()),  # one id per document
    },
    timeout=120,  # above the API's 90 s extraction budget
)
answer = response.json()
if response.status_code != 201 or not answer["success"]:
    raise SystemExit(f"{response.status_code} {answer.get('errorCode', '')} {answer.get('message') or answer.get('error')}")
print(answer["data"]["dados_pessoais"]["nome_completo"])

// Your first call: extract the hosted sample certificate (fictitious data).
// Needs Node.js 18+ and DOCSOCR_API_KEY in the environment.
import { randomUUID } from 'node:crypto'

const response = await fetch('https://api.docsocr.com/api/v1/documents/birth-certificate', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.DOCSOCR_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    imageType: 'url',
    imageUrl: 'https://docsocr.com/samples/certidao-nascimento-exemplo.jpg',
    requestId: randomUUID(), // one id per document
  }),
  signal: AbortSignal.timeout(120_000), // above the API's 90 s extraction budget
})
const answer = await response.json()
if (response.status !== 201 || !answer.success) {
  console.error(response.status, answer.errorCode ?? '', answer.message ?? answer.error)
  process.exit(1)
}
console.log(answer.data.dados_pessoais.nome_completo)

php

<?php
// Your first call: extract the hosted sample certificate (fictitious data).
// Needs the curl extension and DOCSOCR_API_KEY in the environment.

$request = curl_init('https://api.docsocr.com/api/v1/documents/birth-certificate');
curl_setopt_array($request, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 120, // above the API's 90 s extraction budget
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('DOCSOCR_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'imageType' => 'url',
        'imageUrl' => 'https://docsocr.com/samples/certidao-nascimento-exemplo.jpg',
        'requestId' => bin2hex(random_bytes(16)), // one id per document
    ]),
]);
$body = curl_exec($request);
if ($body === false) {
    fwrite(STDERR, curl_error($request) . PHP_EOL);
    exit(1);
}
$status = curl_getinfo($request, CURLINFO_RESPONSE_CODE);
$answer = json_decode($body, true);
if ($status !== 201 || empty($answer['success'])) {
    fwrite(STDERR, "$status " . ($answer['errorCode'] ?? '') . ' ' . implode('; ', (array) ($answer['message'] ?? $answer['error'] ?? '')) . PHP_EOL);
    exit(1);
}
echo $answer['data']['dados_pessoais']['nome_completo'], PHP_EOL;

java

// Your first call: extract the hosted sample certificate (fictitious data).
// Needs Java 17+ and DOCSOCR_API_KEY in the environment. Run: java FirstCall.java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.UUID;

public class FirstCall {
    public static void main(String[] args) throws Exception {
        String body = """
            {
              "imageType": "url",
              "imageUrl": "https://docsocr.com/samples/certidao-nascimento-exemplo.jpg",
              "requestId": "%s"
            }""".formatted(UUID.randomUUID()); // one id per document

        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.docsocr.com/api/v1/documents/birth-certificate"))
            .timeout(Duration.ofSeconds(120)) // above the API's 90 s extraction budget
            .header("Authorization", "Bearer " + System.getenv("DOCSOCR_API_KEY"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());

        // The answer is JSON: read data.dados_pessoais.nome_completo with your JSON library
        System.out.println(response.body());
        if (response.statusCode() != 201 || !response.body().contains("\"success\":true")) {
            System.exit(1);
        }
    }
}

csharp

// Your first call: extract the hosted sample certificate (fictitious data).
// Needs .NET 8+ and DOCSOCR_API_KEY in the environment. Run: dotnet run FirstCall.cs (.NET 10)
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Text.Json.Nodes;

using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(120) }; // above the API's 90 s extraction budget
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("DOCSOCR_API_KEY"));

var body = new JsonObject
{
    ["imageType"] = "url",
    ["imageUrl"] = "https://docsocr.com/samples/certidao-nascimento-exemplo.jpg",
    ["requestId"] = Guid.NewGuid().ToString(), // one id per document
};
using var content = new StringContent(body.ToJsonString(), Encoding.UTF8, "application/json");
using var response = await http.PostAsync("https://api.docsocr.com/api/v1/documents/birth-certificate", content);
using var answer = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
var root = answer.RootElement;

if ((int)response.StatusCode != 201 || !root.GetProperty("success").GetBoolean())
{
    Console.Error.WriteLine($"{(int)response.StatusCode} {root}");
    return 1;
}
Console.WriteLine(root.GetProperty("data").GetProperty("dados_pessoais").GetProperty("nome_completo").GetString());
return 0;

Testar

Envia esta requisição para a API em produção, com a sua chave.

Chave de API

A chave fica só nesta aba do navegador e vai apenas para a API. Gerar chave no painel

Idioma das mensagens (Accept-Language)

Corpo (JSON)

Lendo os preços…

Cole a sua chave de API para enviar.

Resposta 201

json

{
  "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
}

Extrair dados de uma certidão de nascimento ​

Autenticação ​

Parâmetros ​

Corpo da requisição ​

Exemplos ​

Respostas ​

201 Created ​

400 Bad Request ​

401 Unauthorized ​

402 Payment Required ​

409 Conflict ​

413 Payload Too Large ​

422 Unprocessable Entity ​

429 Too Many Requests ​

503 Service Unavailable ​

Valores de errorCode ​

Testar

Extrair dados de uma certidão de nascimento

Autenticação

Parâmetros

Corpo da requisição

Exemplos

Respostas

201 Created

400 Bad Request

401 Unauthorized

402 Payment Required

409 Conflict

413 Payload Too Large

422 Unprocessable Entity

429 Too Many Requests

503 Service Unavailable

Valores de errorCode