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

# Fluxo Sugerido de Integração

> Conheça os fluxos recomendados para otimizar o processo de integração com a API

## Visão Geral

Esta página apresenta fluxos de integração sugeridos para otimizar o processo de integração com sua solução. Os workflows orientam plataformas sobre como incorporar pedidos no Olist e gerenciar processos associados.

## Cenário 1: Integração Básica de Pedidos

**Ideal para:** Plataformas que desejam incluir pedidos automaticamente e obter dados de envio

### Fluxo Passo a Passo

1. **Registrar o Pedido**
   * A plataforma registra o pedido no Olist através da API de inclusão de pedidos
   * Endpoint: `/api2/pedidos.incluir.php`

2. **Atualizar Status do Pedido**
   * **Aprovado**: Quando o pagamento for confirmado
   * **Cancelado**: Se o pagamento falhar
   * Endpoint: `/api2/pedidos.alterar.situacao.php`

3. **Pesquisar Notas Fiscais Emitidas**
   * Consultar notas fiscais para confirmar autorização
   * Endpoint: `/api2/notas.fiscais.pesquisa.php`

4. **Obter Dados da Nota Fiscal**
   * Recuperar dados da nota fiscal para informações de rastreamento
   * Endpoint: `/api2/notas.fiscais.obter.php`

5. **Obter URL da Nota Fiscal**
   * Recuperar a URL da nota fiscal para entrega ao cliente
   * Endpoint: `/api2/notas.fiscais.obter.link.php`

```mermaid theme={null}
graph TD
    A[Incluir Pedido] --> B{Pagamento?}
    B -->|Confirmado| C[Atualizar Status: Aprovado]
    B -->|Falhou| D[Atualizar Status: Cancelado]
    C --> E[Pesquisar Notas Fiscais]
    E --> F[Obter Dados da Nota]
    F --> G[Obter URL da Nota]
    G --> H[Enviar para Cliente]
```

## Cenário 2: Emissão Automática de Nota Fiscal

**Ideal para:** Clientes com certificados digitais A1 que desejam geração automática de notas fiscais

### Fluxo Passo a Passo

1. **Registrar o Pedido**
   * A plataforma registra o pedido no Olist
   * Endpoint: `/api2/pedidos.incluir.php`

2. **Atualizar Status**
   * Atualizar status baseado no resultado do pagamento
   * Endpoint: `/api2/pedidos.alterar.situacao.php`

3. **Gerar Nota Fiscal**
   * Gerar a nota fiscal vinculada ao pedido
   * Endpoint: `/api2/pedidos.gerar.nota.fiscal.php`

4. **Emitir a Nota Fiscal Eletrônica**
   * Emitir a NF-e automaticamente
   * Endpoint: `/api2/notas.fiscais.emitir.php`

5. **Obter Dados da Nota**
   * Recuperar dados para rastreamento
   * Endpoint: `/api2/notas.fiscais.obter.php`

6. **Obter URL da Nota**
   * Recuperar a URL para disponibilizar ao cliente
   * Endpoint: `/api2/notas.fiscais.obter.link.php`

```mermaid theme={null}
graph TD
    A[Incluir Pedido] --> B{Pagamento?}
    B -->|Confirmado| C[Atualizar Status: Aprovado]
    B -->|Falhou| D[Atualizar Status: Cancelado]
    C --> E[Gerar Nota Fiscal]
    E --> F[Emitir NF-e]
    F --> G[Obter Dados da Nota]
    G --> H[Obter URL da Nota]
    H --> I[Enviar para Cliente]
```

## Boas Práticas Indicadas

### Atualizações Condicionais de Status

* Vincule as atualizações de status à verificação de pagamento
* Não atualize o status antes de confirmar o pagamento

### Verificação Sistemática de Notas

* Sempre verifique se a nota fiscal foi emitida antes de prosseguir
* Implemente retry logic para casos onde a emissão ainda está em processamento

### Recuperação Estruturada de Dados

* Siga a ordem de recuperação: dados completos da nota → URL da nota
* Armazene as informações localmente para referência futura

### Comunicação com Cliente

* Envie o link da nota fiscal assim que estiver disponível
* Notifique o cliente sobre mudanças no status do pedido

## Webhooks para Automação

Considere configurar [webhooks](/api-v2/webhooks/webhooks) para automatizar partes do fluxo:

* **Atualização de estoque**: Receba notificações quando o estoque mudar
* **Mudança de situação do pedido**: Seja notificado automaticamente
* **Envio de nota fiscal**: Receba alertas quando notas forem emitidas
* **Código de rastreio**: Obtenha notificações de envio

Webhooks reduzem a necessidade de polling constante e melhoram a eficiência da integração.