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

> a integração de clientes é o processo no qual os clientes criados na teceo são integrados a sistemas terceiros. o processo também contempla a criação de novos clientes via API, a atualização de clientes existentes e a captura de clientes cadastrados diretamente na teceo

export const entity_0 = "cliente"

## fluxo principal

<Steps>
  <Step title="buscar clientes pendentes">
    busque clientes 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 cliente">
    obtenha informações detalhadas de cada cliente para enviar ao seu sistema.
  </Step>

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

## endpoints

### listar clientes pendentes

```
GET /v1/customers
```

retorna a lista de clientes pendentes de sincronização. a listagem suporta paginação usando `skip` e `limit`.

### obter detalhes do cliente

```
GET /v1/customers/{customerId}
```

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

### sincronizar cliente

```
POST /v1/customers/{customerId}/sync
```

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

#### payload de sucesso

```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 cliente no seu ERP/sistema.
</ResponseField>

#### payload de erro

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

### atualizar dados do cliente

```
PATCH /v1/customers/{idOrCode}
```

<ParamField path="code" type="string" required>
  código do cliente.
</ParamField>

#### payload

```json theme={null}
{
  "phone": "string",
  "countryCode": "string",
  "status": "PENDING",
  "companyName": "string",
  "commercialName": "string",
  "stateInscription": "string",
  "email": "string",
  "observation": "string",
  "addresses": [
    {
      "zipCode": "string",
      "streetDescription": "string",
      "streetNumber": "string",
      "complement": "string",
      "reference": "string",
      "neighborhood": "string",
      "city": "string",
      "customerAddressId": "string",
      "state": "string",
      "country": "string",
      "code": "string",
      "type": "DELIVERY",
      "principal": false
    }
  ],
  "salesRepresentatives": [
    {
      "code": "string",
      "principal": false
    }
  ],
  "classifications": [
    {
      "name": "string",
      "code": "string",
      "classificationType": {
        "name": "string",
        "code": "string"
      }
    }
  ],
  "priceTable": {
    "integrationCode": "string"
  },
  "creditLimit": 0,
  "availableBalance": 0
}
```

para mais detalhes, consulte a [documentação no swagger](https://integration.teceo.co/swagger#/Customers%3A/CustomerController_patchCustomer).

## regras de negócio

ao criar ou atualizar clientes, as seguintes validações são aplicadas:

<AccordionGroup>
  <Accordion title="validação de documentos">- valida se o CPF ou CNPJ do novo cliente já está em uso - valida se o formato do `documentType` é `CPF` ou `CNPJ` para clientes do Brasil - valida se quando `isPJ = true` o `documentType` é `CNPJ` - valida se o cliente for internacional, o `documentType` não pode ser `CPF` ou `CNPJ` - valida formato do `cpfcnpj` se o cliente for do Brasil (apenas dígitos e algoritmo)</Accordion>
  <Accordion title="validação de código e telefone">- valida se o código do novo cliente já está em uso - valida se o formato de `phone` é válido (apenas dígitos, 10 caracteres)</Accordion>
</AccordionGroup>