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

# integração de pedidos

> a integração de pedidos é o processo em que pedidos criados na teceo são integrados a sistemas terceiros (ERP, WMS, etc.)

export const entity_0 = "pedido"

## fluxo principal

o fluxo de integração envolve as seguintes etapas:

<Steps>
  <Step title="buscar pedidos pendentes">
    busque pedidos prontos para integração: aprovados (`status = APPROVED`) e que ainda não foram integrados ou tiveram erro anterior (`synchronizedStatus = NOT_SYNCHRONIZED`).

    <Tip>
      considere usar [webhooks](/integracoes/brand/webhooks) para ser notificado automaticamente quando novos {entity_0}s estiverem prontos para integração. assim essa etapa não é necessária e você pode ir direto para os detalhes do {entity_0} quando receber a notificação.
    </Tip>
  </Step>

  <Step title="detalhar pedido">
    obtenha informações detalhadas de cada pedido para enviar ao seu sistema.
  </Step>

  <Step title="sincronizar pedido">
    após processar o pedido no seu sistema, envie a confirmação de sucesso ou erro para a teceo.
  </Step>
</Steps>

## endpoints

### listar pedidos pendentes

```
GET /v1/orders
```

retorna a lista de pedidos pendentes de sincronização. a listagem é paginada usando `skip` e `limit`.

### obter detalhes do pedido

```
GET /v1/orders/{orderId}
```

<ParamField path="orderId" type="string" required>
  identificador único do pedido na teceo.
</ParamField>

### sincronizar pedido

```
POST /v1/orders/{orderId}/sync
```

<ParamField path="orderId" type="string" required>
  identificador único do pedido na teceo.
</ParamField>

#### payload de sucesso

quando a integração for bem-sucedida, envie:

```json theme={null}
{
  "status": "SUCCESS",
  "integrationCode": "123456"
}
```

<ResponseField name="status" type="string" required>
  deve ser `SUCCESS` para indicar sucesso na integração.
</ResponseField>

<ResponseField name="integrationCode" type="string" required>
  código do pedido no seu ERP/sistema.
</ResponseField>

#### payload de erro

se ocorrer um erro durante a sincronização:

```json theme={null}
{
  "status": "ERROR",
  "message": "descrição do erro ocorrido"
}
```

<ResponseField name="status" type="string" required>
  deve ser `ERROR` para indicar falha na integração.
</ResponseField>

<ResponseField name="message" type="string" required>
  descrição do problema ocorrido.
</ResponseField>

## integração reversa

a API também permite a sincronização reversa de pedidos já integrados usando o código do pedido no ERP (`externalCode`).

a sincronização reversa permite que os pedidos já integrados no sistema sejam atualizados com um novo status diretamente no ERP, sem a necessidade de reprocessar o pedido completo.

### atualizar status do pedido

```
PATCH /v1/orders/sync/reverse/{externalCode}
```

<ParamField path="externalCode" type="string" required>
  código do pedido no ERP (enviado anteriormente como `integrationCode`).
</ParamField>

#### payload

```json theme={null}
{
  "status": "APPROVED"
}
```

<ResponseField name="status" type="string" required>
  novo status do pedido. valores aceitos: `APPROVED`, `CANCELLED`, `REJECTED`, `ON_APPROVAL`.
</ResponseField>

## exemplo de fluxo completo

```mermaid theme={null}
sequenceDiagram
    participant ERP as seu sistema
    participant API as teceo API

    ERP->>API: GET /v1/orders (buscar pendentes)
    API-->>ERP: lista de pedidos

    loop para cada pedido
        ERP->>API: GET /v1/orders/{orderId}
        API-->>ERP: detalhes do pedido
        ERP->>ERP: processa pedido internamente
        ERP->>API: POST /v1/orders/{orderId}/sync
        API-->>ERP: confirmação
    end
```