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

# Pesquisar Produtos

> Serviço destinado a fazer consulta de Produtos.

## Endpoint

```
POST https://api.tiny.com.br/api2/produtos.pesquisa.php
```

## Parâmetros

| Parâmetro    | Tipo   | Ocorrência  | Descrição                                                                                   |
| ------------ | ------ | ----------- | ------------------------------------------------------------------------------------------- |
| token        | string | obrigatório | Chave gerada para identificar sua empresa                                                   |
| formato      | string | obrigatório | Formato do retorno (json)                                                                   |
| pesquisa     | string | obrigatório | Nome ou código (ou parte) do produto que deseja consultar                                   |
| idTag        | int    | opcional    | Número de identificação da tag na Olist                                                     |
| idListaPreco | int    | opcional    | Número de identificação da lista de preço (preços calculados conforme lista informada)      |
| pagina       | int    | opcional    | Número da página (padrão: 100 registros/página, valor padrão = 1)                           |
| gtin         | string | opcional    | GTIN/EAN do produto                                                                         |
| situacao     | string | opcional    | Situação dos produtos ("A" - Ativo, "I" - Inativo, "E" - Excluído); padrão: Ativo e Inativo |
| dataCriacao  | string | opcional    | Data de criação do produto. Formato: dd/mm/aaaa hh:mm:ss                                    |

## 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 | Contém "OK" ou "Erro"                                           |
| retorno.codigo\_erro                            | int     | -       | condicional | Conforme tabela "Códigos de erro" (presente se status = "Erro") |
| retorno.erros\[]                                | list    | -       | condicional | Lista dos erros encontrados                                     |
| retorno.erros\[].erro                           | string  | -       | condicional | Mensagem descritiva do erro                                     |
| retorno.pagina                                  | int     | -       | obrigatório | Número da página retornada                                      |
| retorno.numero\_paginas                         | int     | -       | obrigatório | Número total de páginas                                         |
| retorno.produtos\[]                             | list    | -       | condicional | Lista de resultados (presente se status = "OK")                 |
| retorno.produtos\[].produto                     | object  | -       | condicional | Elemento representando um produto                               |
| retorno.produtos\[].produto.id                  | int     | -       | obrigatório | Número de identificação do produto                              |
| retorno.produtos\[].produto.nome                | string  | 120     | obrigatório | Nome do produto                                                 |
| retorno.produtos\[].produto.codigo              | string  | 30      | condicional | Código do produto                                               |
| retorno.produtos\[].produto.preco               | decimal | -       | obrigatório | Preço de venda do produto                                       |
| retorno.produtos\[].produto.preco\_promocional  | decimal | -       | obrigatório | Preço promocional do produto                                    |
| retorno.produtos\[].produto.preco\_custo        | decimal | -       | condicional | Preço de custo do produto                                       |
| retorno.produtos\[].produto.preco\_custo\_medio | decimal | -       | condicional | Preço médio de custo do produto                                 |
| retorno.produtos\[].produto.unidade             | string  | 3       | condicional | Unidade do produto                                              |
| retorno.produtos\[].produto.gtin                | string  | 14      | condicional | GTIN/EAN do produto                                             |
| retorno.produtos\[].produto.tipoVariacao        | string  | 1       | obrigatório | Tipo de variação: "N" - Normal, "P" - Pai, "V" - Variação       |
| retorno.produtos\[].produto.localizacao         | string  | 50      | condicional | Localização física no estoque                                   |
| retorno.produtos\[].produto.situacao            | string  | 1       | condicional | Situação ("A" - Ativo, "I" - Inativo, "E" - Excluído)           |
| retorno.produtos\[].produto.data\_criacao       | string  | 19      | condicional | Data de criação. Formato: dd/mm/aaaa hh:mm:ss                   |

> Campos com valores decimais utilizam "." (ponto) como separador de decimais, exemplo "5.25".

## Exemplo de chamada

```bash theme={null}
curl -X POST https://api.tiny.com.br/api2/produtos.pesquisa.php \
  -d "token=SEU_TOKEN&formato=json&pesquisa=nome_produto"
```

## Exemplos de retorno

### Sucesso

```json theme={null}
{
  "retorno": {
    "status_processamento": 3,
    "status": "OK",
    "pagina": "1",
    "numero_paginas": "1",
    "produtos": [
      {
        "produto": {
          "id": 46829062,
          "codigo": "123",
          "nome": "produto teste",
          "preco": "1.20",
          "preco_promocional": "1.10",
          "preco_custo": "1.05",
          "preco_custo_medio": "1.02",
          "unidade": "UN",
          "tipoVariacao": "P"
        }
      },
      {
        "produto": {
          "id": 46829066,
          "codigo": "1234",
          "nome": "produto teste 2",
          "preco": "15.25",
          "preco_promocional": "13.10",
          "preco_custo": "12.75",
          "preco_custo_medio": "11.89",
          "unidade": "PC",
          "tipoVariacao": "N"
        }
      }
    ]
  }
}
```

### Erro - Token inválido

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

### Erro - Consulta sem registros

```json theme={null}
{
  "retorno": {
    "status_processamento": 2,
    "status": "Erro",
    "codigo_erro": 20,
    "erros": [
      {
        "erro": "A Consulta não retornou registros"
      }
    ]
  }
}
```