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

# Incluir Assunto do CRM

> Serviço destinado a fazer a inclusão de assunto no CRM.

## Endpoint

```
POST https://api.tiny.com.br/api2/crm.incluir.assunto.php
```

## Parâmetros

| Parâmetro | Tipo   | Ocorrência  | Descrição                                 |
| --------- | ------ | ----------- | ----------------------------------------- |
| token     | string | obrigatório | Chave gerada para identificar sua empresa |
| assunto   | object | obrigatório | Dados do assunto conforme layout (1)      |
| formato   | string | obrigatório | Formato do retorno (json)                 |

### Layout do parâmetro "assunto"

**Dados do cliente:**

| Campo                              | Tipo   | Tamanho | Ocorrência  | Descrição                           |
| ---------------------------------- | ------ | ------- | ----------- | ----------------------------------- |
| assunto.cliente.codigo             | string | 30      | opcional    | Código do cliente (2)               |
| assunto.cliente.nome               | string | 50      | obrigatório | Nome do cliente (2)                 |
| assunto.cliente.tipo\_pessoa       | string | 1       | opcional    | F/J/E (Física/Jurídica/Estrangeiro) |
| assunto.cliente.cpf\_cnpj          | string | 18      | opcional    | CPF ou CNPJ (2)                     |
| assunto.cliente.ie                 | string | 18      | opcional    | Inscrição estadual                  |
| assunto.cliente.rg                 | string | 10      | opcional    | RG do cliente                       |
| assunto.cliente.endereco           | string | 50      | opcional    | Endereço                            |
| assunto.cliente.numero             | string | 10      | opcional    | Número do endereço                  |
| assunto.cliente.complemento        | string | 50      | opcional    | Complemento do endereço             |
| assunto.cliente.bairro             | string | 30      | opcional    | Bairro                              |
| assunto.cliente.cep                | string | 10      | opcional    | CEP                                 |
| assunto.cliente.cidade             | string | 30      | opcional    | Conforme Tabela de Cidades          |
| assunto.cliente.uf                 | string | 2       | opcional    | UF do cliente                       |
| assunto.cliente.pais               | string | 50      | opcional    | Conforme Tabela de Países           |
| assunto.cliente.fone               | string | 40      | opcional    | Telefone                            |
| assunto.cliente.email              | string | 50      | opcional    | E-mail do cliente                   |
| assunto.cliente.atualizar\_cliente | string | 1       | opcional    | "S" ou "N" (padrão "S") (3)         |

**Pessoas de contato:**

| Campo                                           | Tipo       | Ocorrência | Descrição                           |
| ----------------------------------------------- | ---------- | ---------- | ----------------------------------- |
| assunto.cliente.pessoa\_contato\[]              | list       | opcional   | Lista de pessoas de contato \[0..n] |
| assunto.cliente.pessoa\_contato\[].id\_pessoa   | int        | opcional   | ID da pessoa de contato (4)         |
| assunto.cliente.pessoa\_contato\[].nome         | string(50) | opcional   | Nome da pessoa (4)                  |
| assunto.cliente.pessoa\_contato\[].telefone     | string(30) | opcional   | Telefone                            |
| assunto.cliente.pessoa\_contato\[].ramal        | string(10) | opcional   | Ramal                               |
| assunto.cliente.pessoa\_contato\[].email        | string(50) | opcional   | E-mail                              |
| assunto.cliente.pessoa\_contato\[].departamento | string(20) | opcional   | Departamento                        |

**Dados do assunto:**

| Campo                      | Tipo   | Ocorrência  | Descrição                      |                       |
| -------------------------- | ------ | ----------- | ------------------------------ | --------------------- |
| assunto.descricao\_assunto | string | obrigatório | Título ou descrição do assunto |                       |
| assunto.estagio\_assunto   | string | 1           | obrigatório                    | Código do estágio (5) |

**Ações do assunto:**

| Campo                                  | Tipo   | Tamanho | Ocorrência  | Descrição                         |
| -------------------------------------- | ------ | ------- | ----------- | --------------------------------- |
| assunto.acoes\[]                       | list   | -       | obrigatório | Lista de ações do assunto \[1..n] |
| assunto.acoes\[].acao.descricao\_acao  | string | -       | obrigatório | Descrição da ação                 |
| assunto.acoes\[].acao.tipo\_data\_acao | string | 1       | obrigatório | Conforme tabela de tipos          |
| assunto.acoes\[].acao.data\_acao       | date   | 20      | opcional    | Formato dd/mm/yyyy (6)            |
| assunto.acoes\[].acao.situacao\_acao   | string | -       | opcional    | Padrão "0" (7)                    |

> (1) O parâmetro "assunto" deve ser enviado em formato XML ou JSON

> (2) Campos de pesquisa: Código, nome e CPF/CNPJ identificam cliente existente; demais dados carregam-se do cadastro

> (3) Clientes não cadastrados são incluídos automaticamente (ignora "atualizar\_cliente")

> (4) ID ou nome identificam contatos existentes no cliente

> (5) Estágio obtido através da "Lista de estágios de assuntos do CRM"

> (6) Data considerada apenas quando tipo\_data\_acao = "D"

> (7) Se situacao\_acao não for enviado, assume-se "0" como padrão

## Retorno

| Campo                                          | Tipo   | Tamanho | Ocorrência  | Descrição                                 |
| ---------------------------------------------- | ------ | ------- | ----------- | ----------------------------------------- |
| retorno                                        | object | -       | obrigatório | Elemento raiz do retorno                  |
| retorno.status\_processamento                  | int    | -       | obrigatório | Conforme tabela "Status de Processamento" |
| retorno.status                                 | string | -       | obrigatório | "OK" ou "Erro"                            |
| retorno.codigo\_erro                           | int    | -       | obrigatório | Conforme tabela "Códigos de erro"         |
| retorno.erros\[]                               | list   | -       | condicional | Lista dos erros encontrados \[0..n]       |
| retorno.erros\[].erro                          | string | -       | condicional | Descrição do erro                         |
| retorno.registros\[]                           | list   | -       | condicional | Lista de resultados da inclusão           |
| retorno.registros\[].registro                  | object | -       | condicional | Representação de um assunto               |
| retorno.registros\[].registro.sequencia        | int    | -       | condicional | Número sequencial                         |
| retorno.registros\[].registro.status           | string | -       | condicional | "OK" ou "Erro"                            |
| retorno.registros\[].registro.codigo\_erro     | int    | -       | condicional | Código do erro                            |
| retorno.registros\[].registro.erros\[]         | list   | -       | condicional | Lista de erros \[0..n]                    |
| retorno.registros\[].registro.erros\[].erro    | string | -       | condicional | Descrição do erro                         |
| retorno.registros\[].registro.id               | int    | -       | condicional | ID do assunto na Olist                    |
| retorno.registros\[].registro.acoes\[]         | list   | -       | condicional | Conjunto de ações                         |
| retorno.registros\[].registro.acoes\[].acao.id | int    | -       | condicional | ID da ação na Olist                       |

## Exemplo de chamada

```bash theme={null}
curl -X POST https://api.tiny.com.br/api2/crm.incluir.assunto.php \
  -d 'token=SEU_TOKEN&formato=json&assunto={
    "cliente": {
      "nome": "Cliente Teste",
      "tipo_pessoa": "F",
      "cpf_cnpj": "12345678900",
      "fone": "5199999999"
    },
    "descricao_assunto": "Teste de assunto",
    "estagio_assunto": "1",
    "acoes": [
      {
        "acao": {
          "descricao_acao": "Realizar contato",
          "tipo_data_acao": "Q",
          "situacao_acao": "0"
        }
      }
    ]
  }'
```

## Exemplos de retorno

### Erro - Token inválido

```json theme={null}
{
  "retorno": {
    "status_processamento": 1,
    "status": "Erro",
    "codigo_erro": 2,
    "erros": [
      {
        "erro": "token invalido"
      }
    ]
  }
}
```

### Erro - Duplicidade

```json theme={null}
{
  "retorno": {
    "status_processamento": 2,
    "status": "Erro",
    "registros": [
      {
        "registro": {
          "sequencia": "1",
          "status": "Erro",
          "codigo_erro": "30",
          "erros": [
            {
              "erro": "Registro em duplicidade"
            }
          ]
        }
      }
    ]
  }
}
```

### Sucesso

```json theme={null}
{
  "retorno": {
    "status_processamento": 3,
    "status": "OK",
    "registros": [
      {
        "registro": {
          "sequencia": "1",
          "status": "OK",
          "id": "49644545",
          "acoes": [
            {
              "acao": {
                "id": "49644546"
              }
            },
            {
              "acao": {
                "id": "49644547"
              }
            }
          ]
        }
      }
    ]
  }
}
```