> ## 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 casos

> a integração de casos permite abrir casos na teceo a partir do seu sistema e acompanhar o andamento deles, incluindo casos de devolução com produtos, defeitos e notas

## o que é um caso

o caso criado pela API nasce no primeiro status de situação `new` do tipo de caso, pela ordem configurada na marca, e recebe um `code` sequencial gerado pela teceo. o `externalCode` que você envia é o que amarra o caso ao registro do seu sistema, e é único dentro da marca.

cada caso tem dois status. o `statusBase` é a situação padronizada (`new`, `open`, `pending` ou `closed`), boa para automações. o `status` é o nome que a marca deu ao status, e muda de marca para marca.

## fluxo principal

<Steps>
  <Step title="abrir o caso">
    envie o `externalCode`, o tipo de caso, o cliente e o assunto. casos de devolução levam também a nota e os produtos em `customData`.
  </Step>

  <Step title="guardar o número da teceo">
    o `code` sequencial do caso aparece na listagem. filtre pelo seu `externalCode` para encontrar o caso e guardar os dois números juntos.
  </Step>

  <Step title="acompanhar o andamento">
    use os [webhooks de casos](/integracoes/brand/webhooks/eventos-casos) para ser avisado a cada mudança de situação do caso, ou consulte o caso pelo `externalCode`.
  </Step>
</Steps>

## endpoints

| endpoint | o que faz |
| - | - |
| `POST /v1/cases` | abre um caso e devolve o caso completo, já no status inicial |
| `GET /v1/cases` | lista os casos, com filtro por data de alteração, código externo, tipo, situação e cliente |
| `GET /v1/cases/by/externalCode/{externalCode}` | traz um caso pelo código do seu sistema, com o histórico de mudanças de status |

os campos de cada rota, com tipo, obrigatoriedade e exemplo, estão na página da própria rota, no menu ao lado. a listagem é paginada por cursor, como descrito em [paginação](/integracoes/brand/paginacao).

## regras de negócio

### identificando o cliente

o caso pede o cliente por `customerId` ou por `customerCpfCnpj`. envie só um dos dois.

### tipo de caso e campos da marca

o `typeCode` precisa ser de um tipo de caso já configurado na marca. o `defectCode` e o `reasonCode` dos produtos apontam para defeitos e motivos cadastrados na marca, e os dois precisam ir em todo item. os campos aceitos dentro de `customData` acompanham a configuração de casos de cada marca. confirme com o time da teceo quais valem para a sua.

### caso de devolução

casos de devolução usam `customData` para levar dois blocos. o `caseDevolution` traz a nota de devolução, o código de rastreio e os arquivos da nota. o `caseProducts` traz cada peça devolvida, com quantidade, valor, defeito, motivo e fotos. a peça é identificada pela combinação do código do produto, do código da cor e do tamanho.

cada bloco só é gravado quando o tipo de caso tem a seção correspondente, que é a de notas fiscais de devolução para o `caseDevolution` e a de produtos para o `caseProducts`. sem a seção, o bloco é ignorado sem erro e não volta na resposta. quando gravados, os blocos voltam na resposta com os mesmos dados, e cada item de `caseProducts` ganha um `id` gerado pela teceo.

### listagem

a listagem vem ordenada por data de criação, da mais antiga para a mais nova, mesmo quando você filtra por data de alteração. pare de paginar quando a página vier vazia ou quando o `nextCursor` vier nulo.

## erros

| status | quando acontece |
| - | - |
| `409` | ao abrir, já existe um caso da marca com esse `externalCode` |
| `422` | ao abrir, o `typeCode` não corresponde a um tipo de caso da marca com a configuração de card. confira o código e, se ele estiver certo, peça para o time da teceo configurar o tipo |
| `422` | ao abrir, o cliente não foi encontrado, nem pelo `customerId` nem pelo `customerCpfCnpj` |
| `422` | ao abrir, os dois campos de cliente foram enviados juntos |
| `422` | ao abrir, um item de `caseProducts` veio sem o código do produto, o código da cor ou o tamanho |
| `404` | ao abrir, o tipo de caso não tem nenhum status de situação `new`. este também depende do time da teceo |
| `400` | ao abrir, o payload não passou na validação |
| `404` | ao consultar, não existe caso da marca com esse `externalCode` |

trate os erros de casos pelo status HTTP da resposta.

## exemplo de fluxo completo

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

    SYS->>API: POST /v1/cases
    API-->>SYS: caso aberto, com status inicial

    SYS->>API: GET /v1/cases?externalCode=...
    API-->>SYS: caso com o code da teceo

    API-->>SYS: webhook de mudança de status
    SYS->>API: GET /v1/cases/by/externalCode/{externalCode}
    API-->>SYS: caso com o histórico atualizado
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.