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

• Argentina. model a utilizar: arg

  • Documento de identidade

• México. model a utilizar: mex

  • Documento de identidade

  • Cartão de estrangeiro

Modelos suportados pelo interpretador v2

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

Faturas suportadas

• TELMEX. model a utilizar: telmex

• CFE. model a utilizar: cfe

• MOVISTAR

• TELCEL

• TELNOR

• AT&T

• TOTALPLAY

• IZZI

PDFs suportados

• IVA: El Salvador: modelo F07 v12, F07 v13 e F07 v14. model a utilizar: IVA

• RENDA: El Salvador: modelo F11 v14, F11 v15, F11 v17 e F11 v18. model a utilizar: RENDA

Versão e codificação de PDF suportadas

• Versão de PDF: 1.4 ou superior

• Codificação: iText 2.1.7, macOS Version Quartz PDFContext com a opção de texto incorporado habilitada.

/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