> 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/api-rest/midapi-v2.md).

# MIDAPI v2

**MIDAPI v2** é a API REST síncrona do ecossistema de APIs da Facephi. Expõe os serviços de Verificação de Identidade e antifraude por meio de endpoints REST autenticados com OAuth2, pensados para integradores e desenvolvedores de backend.

### Conceitos: plataforma do cliente e consumer

Antes de integrar qualquer serviço da MIDAPI v2, convém conhecer os dois conceitos sobre os quais o acesso é organizado:

* **Plataforma do cliente**: representa a relação única entre o cliente e a Facephi. É identificada pelo cabeçalho `platform-id` e tem uma API Key associada. Existe uma única plataforma por cliente.
* **Consumer**: representa um canal ou vertical de negócios do cliente (por exemplo, o canal web e o app móvel, ou verticais como seguros e investimentos). É identificado pelo cabeçalho `consumer-id`. Cada consumer tem habilitados apenas os serviços contratados para esse canal, com limites de uso e rastreabilidade independentes.

Como parte da ativação do serviço, serão fornecidos ao cliente a **URL base** da API, as **credenciais da plataforma** e **pelo menos um consumer** (um para cada canal ou vertical que precise integrar). Todas as rotas deste guia são relativas a essa URL base (por exemplo, `POST <URL base>/consumer/token`). Esse modelo permite gerenciar permissões, limites e rastreabilidade de forma independente por canal, mantendo uma única plataforma por cliente.

Com esses dois conceitos, obtém-se o token de acesso: a plataforma emite tokens para seus consumers, e cada chamada operacional é feita em nome de um consumer. O detalhe está em [Autenticação](/docs.facephi-pt-br/api-rest/midapi-v2/autenticacion.md).

#### Autorizações

Todas as chamadas aos endpoints operacionais devem incluir as seguintes chaves no cabeçalho da solicitação:

| Chave           | Valor                                              | Obrigatório |
| --------------- | -------------------------------------------------- | ----------- |
| `Authorization` | Token de consumer no formato `Bearer <token>`      | **Sim**     |
| `consumer-id`   | Identificador do consumer                          | **Sim**     |
| `operation-id`  | Identificador da operação dos assets referenciados | Condicional |

O cabeçalho `operation-id` é obrigatório quando a solicitação referencia algum asset por chave. Veja [Armazenamento](/docs.facephi-pt-br/api-rest/midapi-v2/storage.md).

#### Respostas de erro

Todos os endpoints devolvem os erros com a mesma estrutura:

| Parâmetro    | Tipo    | Descrição                |
| ------------ | ------- | ------------------------ |
| `message`    | string  | Descrição do erro.       |
| `statusCode` | integer | Código HTTP da resposta. |

```json
{
  "message": "Missing operation-id header, required when the request references stored assets",
  "statusCode": 400
}
```

### O modelo de assets

Os serviços de validação da MIDAPI v2 trabalham com **assets**: as capturas do usuário final. Um asset pode ser fornecido com o conteúdo em linha na própria chamada, ou por referência a um asset previamente armazenado.

A referência por chave está disponível em todos os serviços de validação **de identidade**. As exceções são explícitas: [Form OCR](/docs.facephi-pt-br/api-rest/midapi-v2/document-services/form-ocr.md) e os serviços de [voz](/docs.facephi-pt-br/api-rest/midapi-v2/voice-services.md) são exclusivamente em linha, e [Document Validation](/docs.facephi-pt-br/api-rest/midapi-v2/document-services/document-validation.md) é exclusivamente por referência.

O fluxo por referência é: criar a [operação](/docs.facephi-pt-br/api-rest/midapi-v2/operations/create-operation.md), [armazenar](/docs.facephi-pt-br/api-rest/midapi-v2/storage/save-asset.md) cada asset e enviar as chaves obtidas ao serviço de validação juntamente com o cabeçalho `operation-id`. Está desenvolvido passo a passo, com seu diagrama, em [Fluxo comum](/docs.facephi-pt-br/api-rest/midapi-v2/flujo-comun.md). Os serviços que admitem os dois modos identificam a referência com `source: FILE_KEY`; os que só admitem referência não trazem esse campo. O modo de asset, os contextos disponíveis e o formato da chave estão em [Armazenamento](/docs.facephi-pt-br/api-rest/midapi-v2/storage.md).

### Serviços disponíveis

* [**Operações**](/docs.facephi-pt-br/api-rest/midapi-v2/operations.md): ciclo de vida da operação que agrupa os assets de uma sessão e define sua expiração.
* [**Armazenamento**](/docs.facephi-pt-br/api-rest/midapi-v2/storage.md): armazenamento dos assets que depois referenciam os serviços de validação, com o modo de asset, os contextos e o formato da chave.
* [**Serviços de documentos**](/docs.facephi-pt-br/api-rest/midapi-v2/document-services.md): validação de autenticidade do documento de identidade, OCR de identidade e OCR de impressos.
* [**Serviços biométricos**](/docs.facephi-pt-br/api-rest/midapi-v2/biometric-services.md): teste de vida e comparação de rostos.
* [**Coleções de rostos**](/docs.facephi-pt-br/api-rest/midapi-v2/face-collections.md): registro e busca 1:N de rostos em coleções.
* [**Segurança e conformidade**](/docs.facephi-pt-br/api-rest/midapi-v2/security-compliance.md): Detecção de Ataques de Injeção sobre a Captura Facial.
* [**Serviços de validação**](/docs.facephi-pt-br/api-rest/midapi-v2/validation-services.md): risco de fraude de IP, e-mail e telefone.
* [**Serviços de voz**](/docs.facephi-pt-br/api-rest/midapi-v2/voice-services.md): enrolamento e autenticação de voz.