> 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/installation/installation_instructions.md).

# Instalação e implantação do serviço

## 1. Instalação e implantação

O serviço está em um contêiner Docker, e existe uma imagem Docker em um repositório da Facephi. Para baixar a imagem, faça login da seguinte maneira:

```
docker login facephicorp.jfrog.io
user: username
pass: token
```

Baixe a imagem:

```bash
docker pull facephicorp.jfrog.io/docker-pro-fphi/facephi-ocr-service:#VERSION#
```

Onde `#VERSION#` é o número da versão que queremos baixar (por exemplo, `6.8.2`).

## 2. docker-compose

Uma forma de implantar o serviço é criar um arquivo `docker-compose.yml` com o seguinte conteúdo:

```yaml
version: '3.7'

services:
  ocr-service:
    image: facephicorp.jfrog.io/docker-pro-fphi/facephi-ocr-service:#VERSION#
    container_name: facephi-ocr-service
    ports:
      - "6982:6982"
    environment:
      # Optional JWT protection
      # - FACEPHI_OCR_REST_AUTH_ENABLED=true
      # - FACEPHI_OCR_REST_AUTH_JWT_SECRET=shared-secret
      # - FACEPHI_OCR_REST_AUTH_ACCEPT_AUTHORIZATION_HEADER=true
      # - FACEPHI_OCR_REST_AUTH_ACCEPT_API_KEY_HEADER=false
      # - FACEPHI_OCR_REST_AUTH_API_KEY_HEADER_NAME=x-api-key
    volumes:
      - ~/facephi_ocr_license:/service/license
      - ~/facephi_ocr_configuration:/service/config
      - ~/facephi_ocr_logs:/service/logs
      - ~/facephi_ocr_custom_templates:/service/custom_templates
```

Observe o volume montado no contêiner. Esse volume é usado para armazenar o arquivo de licença. O volume `facephi_ocr_configuration` é opcional, mas permite configurar o serviço. Consulte a seção `2.2 Service`. O volume `facephi_ocr_logs` é opcional, mas permite salvar os logs no armazenamento local, evitando perdê-los quando o contêiner Docker é interrompido. O volume `facephi_ocr_custom_templates` é opcional, mas permite adicionar modelos de documentos personalizados. Você pode copiar seus modelos personalizados para esta pasta e, em seguida, configurar o serviço para usá-los. Consulte a seção `3.2 Service`.

Execute o seguinte comando dentro da pasta onde está o arquivo docker-compose.yml para implantar o serviço:

```bash
docker compose up
```

## 3. Configuração da licença

Para usar este serviço, é necessário ter um arquivo de licença válido.

O arquivo de licença pode conter as seguintes informações:

```init
LICENSE_TYPE=         # License type, can be MACHINE, SHARED or LOCAL
LICENSE_BEHAVIOUR=    # License behaviour, can be ONLINE or OFFLINE
LICENSE_KEY=          # License key
LICENSE_ID=           # Product ID
LICENSE_DATA=         # Product data
LICENSE_URLS=         # Comma-separated license server URLs. Only needed if LICENSE_TYPE is LOCAL
LICENSE_PATH_OFFLINE= # Local file with data for offline activation. Only needed if LICENSE_TYPE=MACHINE and LICENSE_BEHAVIOUR=OFFLINE
```

O arquivo de licença pode ser passado como parâmetro para o serviço. Por padrão, o serviço procurará um arquivo chamado `/service/license/license.lic`. No caso do contêiner Docker, o arquivo de configuração pode estar localizado em um volume montado em `/service/license`.

Para se conectar aos nossos servidores de licenças, você deve adicionar as seguintes regras ao firewall:

| IP           | Porta | Tipo   |
| ------------ | ----- | ------ |
| 52.223.22.71 | 443   | TCP/IP |
| 35.71.188.31 | 443   | TCP/IP |
| 75.2.113.112 | 443   | TCP/IP |
| 99.83.149.57 | 443   | TCP/IP |

Em seguida, adicione as seguintes URLs à sua lista de permissões:

* <https://api.cryptlex.com:443>
* <https://api.eu.cryptlex.com:443>

## 4. Configuração do serviço

O arquivo de configuração pode conter as seguintes informações padrão:

```json
{
    "port": 6982,                     # Service port number.

    # The number of used by the REST service, 1 by default.
    # If the value is set to 0, the number of threads is autodetected.
    "number_of_threads": 1,

    "connection_timeout": 60,         # The lifetime of the connection without read or write.

    # Set the maximum number of requests that can be served through one keep-alive connection.
    # After the maximum number of requests are made, the connection is closed.
    # The default value of 0 means no limit.
    "keep_alive_request_number": 0,

    # The maximum size of the body allowed in the requests in Mb. The default value of 100 Mb.
    "client_max_body_size": 100,

    "logger_path": "./logs",         # Set the path to store log files.
    "logger_level": "trace",         # Possible values are [trace|debug|info|warning|error|critical|off].
    "logger_rotation": "daily",      # Possible values are [hourly|daily].
    "logger_max_files": 31,          # The default value of 0 means no limit.

    "auth_enabled": false,          # Enable JWT protection for non-public endpoints.
    "auth_jwt_secret": "",         # Shared secret used to validate HS256 JWT tokens.
    "auth_accept_authorization_header": true,
    "auth_accept_api_key_header": false,
    "auth_api_key_header_name": "x-api-key",

    # Folder containing the models, templates and other and resources.
    "config_path": "data",

    # Path to the folder that contains the templates.
    "templates_path": "data/templates",

    # Version of the document interpreter to use. 1 legacy version, 2 new version. By default, it is set to 1.
    "document_interpreter_version": 1,

    # By default, it is 0 (use legacy output format). If 1, use universal one.
    "document_interpreter_use_universal": 0,

    # The number of threads in the pool for processing document images in parallel.
    # By default, it is set to 2. If the value is set to 0, the number of threads is autodetected.
    "processor_threads_pool_size": 2,

    # The number of threads in the flow pool for processing inferences in parallel when executing the pipeline.
    "pipeline_threads_pool_size": 1,

    # The number of threads in the pool for creating interpreters in parallel.
    "global_threads_pool_size": 1,

    # Maximum number of threads used during inference. If 0, use as many threads as cores.
    "max_inference_threads": 0,

    # Number of OCR regions of interest that can be processed concurrently.
    "ocr_latin_batch_size": 1,

    # Multi service configuration
    "multi_service_base_url": "http://localhost", # Base URL of the remote multi service.
    "multi_service_api_key": "fake_key",          # API key for authenticating with the remote multi service.
    "multi_service_connection_timeout": 10000,    # Connection timeout in milliseconds for requests to the remote multi service.
    "multi_service_request_timeout": 60000,       # Request timeout in milliseconds for requests to the remote multi service.
    "multi_service_max_retries": 3,               # Número máximo de tentativas ao serviço remoto multi.
    "multi_service_verify_ssl": true              # Se os certificados SSL devem ser verificados ao conectar-se ao serviço remoto multi.
}
```

O arquivo de configuração pode ser passado como parâmetro para o serviço. Por padrão, o serviço buscará um arquivo chamado `/service/config/config.json`. No caso do contêiner Docker, o arquivo de configuração pode estar localizado em um volume montado em `/service/config`.

Todos os parâmetros são opcionais. Se algum parâmetro não estiver presente, será usado o valor padrão.

A autenticação JWT é opcional e fica desabilitada por padrão. As configurações de inicialização anteriores também podem ser fornecidas por meio de variáveis de ambiente com o prefixo `FACEPHI_OCR_REST_AUTH_`:

* `FACEPHI_OCR_REST_AUTH_ENABLED`
* `FACEPHI_OCR_REST_AUTH_JWT_SECRET`
* `FACEPHI_OCR_REST_AUTH_ACCEPT_AUTHORIZATION_HEADER`
* `FACEPHI_OCR_REST_AUTH_ACCEPT_API_KEY_HEADER`
* `FACEPHI_OCR_REST_AUTH_API_KEY_HEADER_NAME`

Quando o JWT está habilitado, `GET /api/v1/version` e `GET /api/v1/health` permanecem públicos. Os demais endpoints exigem um JWT válido por meio de `Authorization: Bearer <jwt>` ou do cabeçalho de API Key configurado.

As configurações de inicialização do JWT são aplicadas somente quando o serviço é iniciado. `GET /api/v1/config` não expõe esses campos e `POST /api/v1/config` rejeita as tentativas de modificá-los.

### 4.1. `document_interpreter_version`

Há dois intérpretes distintos disponíveis para o processamento de documentos de identidade e documentos de estrangeiros.

Esses intérpretes se diferenciam nos seguintes aspectos:

* Países aceitos
* Formato de saída
* Campos disponíveis

#### Países aceitos

Versão 1:

* Argentina (ARG)
* México (MEX)

A versão 2 aceita oficialmente um conjunto mais amplo de países, entre eles:

* Argentina (ARG)
* Bolívia (BOL)
* Brasil (BRA)
* Canadá (CAN)
* Chile (CHL)
* Colômbia (COL)
* Costa Rica (CRI)
* República Dominicana (DOM)
* Equador (ECU)
* El Salvador (SLV)
* Guatemala (GTM)
* Honduras (HND)
* Jordânia (JOR)
* México (MEX)
* Nicarágua (NIC)
* Nigéria (NGA)
* Panamá (PAN)
* Paraguai (PRY): PRY I v3, PRY I v2
* Peru (PER): PER I v5, PER I v2
* África do Sul (ZAF)
* Coreia do Sul (KOR)
* Espanha (ESP)
* Uganda (UGA)
* Uruguai (URY)
* Vietnã (VNM)

#### Formato de saída

Cada versão estrutura os dados de saída de maneira diferente.

A versão 1 organiza os dados extraídos usando as chaves `front` e `back` para distinguir a frente e o verso do documento:

```json
{
    "back": {
        "Address": "REDACTED",
        ...
    },
    "front": {
        "DateOfBirth": "01/09/1972",
        ...
    }
}
```

Já a versão 2 usa uma estrutura aninhada sob a chave `reader`, com identificadores numéricos para representar cada face do documento (0 para a frente e 1 para o verso), junto com chaves de caminho mais detalhadas:

```json
{
    "reader": {
        "0/MRZ/DateOfBirth": "01/09/1972",
        ...
        "1/ML/Address": "Redacted",
        ...
    }
}
```

A versão 2 também aceita a saída universal (`document_interpreter_use_universal=1`)

#### Campos disponíveis

Além das variações na estrutura dos dados, os próprios campos também podem diferir. Alguns campos podem existir somente em um formato e, mesmo quando um campo aparece em todos os formatos, seu conteúdo pode mudar.
