> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanify.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Fluxo de Uso

> Aprenda o passo a passo para utilizar o Scanify e processar documentos com OCR e validação automática

<Info>
  **Pré-requisito**: Antes de começar, gere sua chave de API na plataforma do Scanify.
</Info>

<Steps>
  <Step title="Autentique-se com sua chave de API">
    Todas as requisições à API do Scanify exigem uma chave de autenticação no cabeçalho `Authorization`.

    Exemplo:

    ```bash theme={"dark"}
    -H "Authorization: Bearer SUA_API_KEY"
    ```

    <Info>
      Você pode copiar sua chave diretamente na área de onboarding da plataforma.
    </Info>
  </Step>

  <Step title="Escolha o modo de processamento">
    O Scanify oferece dois modos:

    **Assíncrono — `POST /extract`** (recomendado para produção)

    Retorna imediatamente com `request_id` e `status: "in_progress"`. O resultado chega via webhook (`callbackUrl`) ou pode ser consultado depois.

    ```bash theme={"dark"}
    curl -X POST https://api.scanify.com.br/extract \
      -H "Authorization: Bearer SUA_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"file":{"fileUrl":"https://seusistema.com/boleto.pdf"},"callbackUrl":"https://seusistema.com/webhook"}'
    ```

    Resposta imediata:

    ```json theme={"dark"}
    { "request_id": "abc123", "status": "in_progress" }
    ```

    **Síncrono — `POST /extract/sync`**

    Aguarda o processamento e retorna o resultado completo na própria resposta. Ideal para integrações simples ou testes.

    ```bash theme={"dark"}
    curl -X POST https://api.scanify.com.br/extract/sync \
      -H "Authorization: Bearer SUA_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"file":{"fileUrl":"https://seusistema.com/boleto.pdf"}}'
    ```

    <Info>
      O modo síncrono suporta um `timeout` configurável (mínimo: 10 000 ms, padrão: 60 000 ms, máximo: 300 000 ms).
    </Info>

    <Warning>
      Formatos suportados: **PDF, JPEG/JPG, PNG, TIFF**. XML é aceito **somente** para `documentType=NFE` via `POST /extract` — é rejeitado para outros tipos e não é aceito por `/classify`.
    </Warning>
  </Step>

  <Step title="Receba ou consulte o resultado">
    **Via webhook** (fluxo assíncrono com `callbackUrl`)

    O Scanify envia um POST para a URL configurada assim que o processamento for concluído:

    ```json theme={"dark"}
    {
      "request_id": "abc123",
      "document_type": "BOLETO",
      "status": "partial_success",
      "fields": {
        "barcode": { "value": "2379...", "error": null },
        "due_date": { "value": null, "error": "Formato inválido" }
      },
      "processed_at": "2025-05-15T21:00:00Z"
    }
    ```

    **Via polling** — `GET /extract/:requestId`

    Se não usou `callbackUrl`, consulte o resultado diretamente:

    ```bash theme={"dark"}
    curl https://api.scanify.com.br/extract/abc123 \
      -H "Authorization: Bearer SUA_API_KEY"
    ```

    <Info>
      Se o seu endpoint retornar erro, o Scanify tentará reenviar por um tempo limitado.
    </Info>
  </Step>
</Steps>

***

## Classificar apenas o tipo de documento (opcional)

Use `POST /classify` quando quiser descobrir o tipo do documento sem realizar a extração completa:

```bash theme={"dark"}
curl -X POST https://api.scanify.com.br/classify \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file":{"fileUrl":"https://seusistema.com/documento.pdf"}}'
```

***

## Consultar histórico manualmente (opcional)

Caso não utilize webhook, você pode acompanhar suas requisições diretamente pelo painel da plataforma, na seção **Atividade**, ou via `GET /extract/:requestId`.

***

## Resolução de Problemas

<AccordionGroup>
  <Accordion title="Erro 401 - Unauthorized"> Verifique se está enviando o header `Authorization: Bearer SUA_API_KEY` corretamente. </Accordion>
  <Accordion title="Erro 403 - Conta Inativa"> Sua conta pode estar desativada. Verifique seu painel ou entre em contato com o suporte. </Accordion>
  <Accordion title="Documento não retornou resultado"> Confirme se seu `callbackUrl` está acessível publicamente e aceitando requisições POST. </Accordion>
</AccordionGroup>