> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-pt-br/sdks/backend-sdk/ocr/technical_documentation/api_reference.md). # 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](https://en.wikipedia.org/wiki/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 * [x] Argentina. `model` a utilizar: **arg** * Documento de identidade * [x] 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](https://github.com/facephi/facephi-gitbook-docs/tree/master/docs/sdks/backend-sdk/ocr/technical_documentation/api_reference/models_v2.md). #### Faturas suportadas * [x] TELMEX. `model` a utilizar: **telmex** * [x] CFE. `model` a utilizar: **cfe** * [ ] MOVISTAR * [ ] TELCEL * [ ] TELNOR * [ ] AT\&T * [ ] TOTALPLAY * [ ] IZZI #### PDFs suportados * [x] IVA: El Salvador: modelo F07 v12, F07 v13 e F07 v14. `model` a utilizar: **IVA** * [x] 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** * [x] Versão de PDF: 1.4 ou superior * [x] 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 ` 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 |