For the complete documentation index, see llms.txt. This page is also available as Markdown.

Guia de referência da API

1. Introdução

Esta seção inclui a descrição da API do serviço fornecido no produto Serviço OCR Facephi.

2. API Rest

De forma resumida, existem os seguintes pontos de entrada disponíveis:

/api/v1/process e /api/v1/process_multi

Esses endpoints são usados para ler informações da imagem de um documento por meio da tecnologia OCR da Facephi e classificar as informações em campos. A diferença entre ambos os endpoints é que o primeiro processa apenas o alfabeto latino, enquanto o segundo processa múltiplos alfabetos (latino, cirílico, árabe, chinês etc.).

Significado dos parâmetros:

  • type (opcional): É necessário especificar o tipo de documento que se deseja processar, já que nosso serviço pode gerenciar diferentes tipos de documentos. Valores disponíveis no JSON: id_card, passport, driver_license, foreign_card, invoice, pdf.

    • Se não estiver presente, usa-se id_card.

  • model (opcional): Este parâmetro especifica o ID do documento que será processado. No caso de faturas ou documentos PDF, consulte a lista a seguir. Caso contrário, esse identificador corresponde ao país de origem do documento. Para especificar esse país, siga o padrão especificado em ISO_3166-1 alpha-3. No caso de invoice ou pdf, use a chave das tabelas a seguir.

    • Se não estiver presente, todos os países são considerados.

  • files: Array de strings. Cada posição do array é um buffer bruto de imagem codificado em base64 RFC4648. Máximo de dois arquivos. A primeira imagem será a frente de um id_card.

  • isCropped (opcional): Se a image já estiver recortada e alinhada, o serviço pode evitar realizar essas operações. Aplica-se apenas a documentos invoice.

  • forceDetection (OBSOLETO, opcional): Se o documento invoice não tiver a proporção correta, o serviço pode realizar uma operação para corrigi-la e melhorar a detecção do documento. Aplica-se apenas a documentos invoice.

  • retrieveImages (opcional): O serviço retornará a imagem recortada em base64 no resultado final.

    • Se não estiver presente, usa-se false.

Tipos de documentos suportados

Nome do documento

parâmetro type

Documento de identidade

id_card

Carteira de motorista

driver_license

Cartão de estrangeiro

foreign_card

PDF

pdf

Fatura

invoice

Modelos suportados pelo interpretador v1

Modelos suportados pelo interpretador v2

Você encontrará mais informações em documentos suportados por país na interpretação v2.

Faturas suportadas

PDFs suportados

Versão e codificação de PDF suportadas

/api/v1/health

O objetivo deste endpoint é garantir que o serviço funcione corretamente.

/api/v1/version

Este endpoint retorna a versão do serviço.

/api/v1/config

Este endpoint é usado para consultar (GET) e atualizar (POST) a configuração do serviço sem necessidade de reiniciá-lo. Apenas alguns parâmetros podem ser modificados em tempo de execução.

As configurações de inicialização da autenticação JWT são ocultadas intencionalmente na resposta GET e rejeitadas na operação POST.

A autenticação JWT opcional pode ser habilitada na inicialização a partir de config.json ou por meio das variáveis de ambiente FACEPHI_OCR_REST_AUTH_*. Quando o JWT está habilitado, GET /api/v1/version e GET /api/v1/health permanecem públicos, enquanto o restante dos endpoints requer um JWT válido por meio de Authorization: Bearer <jwt> ou do cabeçalho da chave de API configurada.

/api/v1/raw

Este endpoint é usado para ler informações da imagem de um documento por meio da tecnologia OCR da Facephi.

Significado dos parâmetros:

  • type: É necessário especificar o tipo de documento que se deseja processar, já que nosso serviço pode gerenciar diferentes tipos de documentos. Valores disponíveis no JSON: id_card, passport, driver_license, foreign_card, invoice, pdf.

  • image: Buffer bruto de imagem codificado em base64 RFC4648.

3. Erros

Mensagem
Significado
Solução

Licença inválida. Código de status: STATUS_CODE

Erro na licença

Entre em contato com a equipe de suporte da Facephi

Não foi possível ler o documento, buffer vazio

O arquivo enviado ao serviço está vazio

Revise a entrada do serviço

PDF inválido. Verifique as codificações suportadas

O arquivo PDF tem uma codificação não suportada

Revise a documentação para verificar a codificação suportada

Imagem inválida para o mecanismo OCR

A imagem enviada ao mecanismo OCR está incorreta

Revise a imagem enviada ao serviço ou entre em contato com a equipe de suporte da Facephi

Nenhum texto foi extraído do mecanismo de PDF

A biblioteca foi habilitada para extrair o texto do PDF, mas não conseguiu interpretá-lo

Entre em contato com a equipe de suporte da Facephi

Nenhum texto foi encontrado com o mecanismo OCR

O mecanismo OCR não conseguiu extrair texto da imagem

Revise a imagem enviada ao serviço, valide o formato de imagem suportado e a qualidade, ou entre em contato com a equipe de suporte da Facephi

O texto não foi interpretado pelo interpretador OCR

O modelo usado para essa imagem não é válido

Entre em contato com a equipe de suporte da Facephi

Arquivo de pipeline não encontrado

A configuração do serviço está incorreta

Entre em contato com a equipe de suporte da Facephi

Erro no pipeline de fatura

A configuração do serviço está incorreta

Entre em contato com a equipe de suporte da Facephi

Erro ao converter a configuração do pipeline para JSON a partir do caminho: RESOURCE_PATH

A configuração do serviço está incorreta

Entre em contato com a equipe de suporte da Facephi

Erro ao carregar a configuração do pipeline a partir do caminho: RESOURCE_PATH

A configuração do serviço está incorreta

Entre em contato com a equipe de suporte da Facephi

Modelo não encontrado. Verifique o caminho do modelo

A configuração do serviço está incorreta

Entre em contato com a equipe de suporte da Facephi

Atualizado