> ## 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 Contatos > Consulte cadastros de clientes, fornecedores, vendedores e outros contatos ## Endpoint ``` POST https://api.tiny.com.br/api2/contatos.pesquisa.php ``` Serviço destinado a fazer consulta de cadastros (clientes, fornecedores, vendedores, etc.) ## Parâmetros | Parâmetro | Tipo | Tamanho | Ocorrência | Descrição | | --------------------- | ------ | ------- | ----------- | --------------------------------------------------------- | | token | string | - | obrigatório | Chave gerada para identificar sua empresa | | pesquisa | string | - | obrigatório | Nome ou código (ou parte) do contato a consultar | | formato | string | - | obrigatório | Formato do retorno. Use `json` | | cpf\_cnpj | string | 18 | opcional | CPF ou CNPJ do contato a consultar | | idVendedor | int | 15 | opcional | Número de identificação do vendedor na Olist | | nomeVendedor | string | - | opcional | Nome do vendedor na Olist (1) | | situacao | string | 15 | opcional | Situação do contato: "Ativo" ou "Excluido" (2) | | pagina | int | - | opcional | Número da página (padrão: 1, 100 registros por página) | | dataCriacao | string | 19 | opcional | Data de criação no formato dd/mm/aaaa hh:mm:ss | | dataMinimaAtualizacao | string | 19 | opcional | Data mínima de atualização no formato dd/mm/aaaa hh:mm:ss | > (1) O parâmetro `nomeVendedor` é desconsiderado se `idVendedor` for informado. Se o vendedor não for localizado, a consulta não retorna registros. > > (2) Sem `situacao` especificada, todas as situações são consideradas. ## Retorno | Campo | Tipo | Tamanho | Ocorrência | Descrição | | ------------------------------------ | ------ | ------- | ----------- | ---------------------------------------------- | | retorno.status\_processamento | int | - | obrigatório | Código de status do processamento | | retorno.status | string | - | obrigatório | "OK" ou "Erro" | | retorno.codigo\_erro | int | - | condicional | Código do erro conforme tabela da API (3) | | retorno.erros | array | - | condicional | Lista de erros ocorridos (3) | | retorno.erros\[].erro | string | - | condicional | Descrição do erro | | retorno.pagina | int | - | obrigatório | Número da página retornada | | retorno.numero\_paginas | int | - | obrigatório | Quantidade total de páginas | | retorno.contatos | array | - | condicional | Lista de contatos encontrados (4) | | contatos\[].contato.id | int | - | condicional | Identificação do contato na Olist | | contatos\[].contato.codigo | string | 30 | condicional | Código do contato | | contatos\[].contato.nome | string | 50 | condicional | Razão social ou nome | | contatos\[].contato.fantasia | string | 60 | condicional | Nome fantasia | | contatos\[].contato.tipo\_pessoa | string | 1 | condicional | F (Física), J (Jurídica), E (Estrangeiro) | | contatos\[].contato.cpf\_cnpj | string | 18 | condicional | CPF ou CNPJ | | contatos\[].contato.endereco | string | 50 | condicional | Logradouro | | contatos\[].contato.numero | string | 10 | condicional | Número do endereço | | contatos\[].contato.complemento | string | 50 | condicional | Complemento do endereço | | contatos\[].contato.bairro | string | 30 | condicional | Bairro | | contatos\[].contato.cep | string | 10 | condicional | CEP | | contatos\[].contato.cidade | string | 30 | condicional | Nome da cidade | | contatos\[].contato.uf | string | 30 | condicional | Unidade Federativa | | contatos\[].contato.email | string | 50 | condicional | Endereço eletrônico | | contatos\[].contato.fone | string | 30 | condicional | Telefone | | contatos\[].contato.id\_lista\_preco | int | - | condicional | Identificação da lista de preço | | contatos\[].contato.id\_vendedor | int | 15 | condicional | Identificação do vendedor | | contatos\[].contato.nome\_vendedor | string | 15 | condicional | Nome do vendedor | | contatos\[].contato.situacao | string | 15 | condicional | "Ativo" ou "Excluido" | | contatos\[].contato.data\_criacao | string | 19 | condicional | Data de criação no formato dd/mm/aaaa hh:mm:ss | > (3) Retornado quando status = "Erro" > > (4) Retornado quando status = "OK" e há registros encontrados ## Exemplo de chamada ```bash theme={null} curl -X POST https://api.tiny.com.br/api2/contatos.pesquisa.php \ -d "token=SEU_TOKEN&formato=json&pesquisa=teste&pagina=1" ``` ```php theme={null} $url = 'https://api.tiny.com.br/api2/contatos.pesquisa.php'; $token = 'SEU_TOKEN'; $pesquisa = 'nome do contato'; $formato = 'json'; $data = "token=$token&pesquisa=$pesquisa&formato=$formato"; // Fazer requisição POST $ch = curl_init($url); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, $data); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); curl_close($ch); $resultado = json_decode($response, true); ``` ## Exemplo de retorno ### Sucesso ```json theme={null} { "retorno": { "status_processamento": 3, "status": "OK", "pagina": "1", "numero_paginas": "1", "contatos": [ { "contato": { "id": 46829055, "codigo": "123", "nome": "Contato Teste", "tipo_pessoa": "F", "fantasia": "Teste", "cpf_cnpj": "00000000000", "endereco": "Rua Teste", "numero": "123", "complemento": "sala 1", "bairro": "Centro", "cep": "95700-000", "cidade": "Bento Gonçalves", "uf": "RS", "email": "teste@teste.com.br", "situacao": "Ativo", "id_vendedor": "123456", "nome_vendedor": "Vendedor Teste", "data_criacao": "01/01/2020 10:00:00" } }, { "contato": { "id": 46829059, "codigo": "125", "nome": "Contato Teste 2", "tipo_pessoa": "F", "fantasia": "Teste 2", "cpf_cnpj": "00000000001", "endereco": "Rua Teste", "numero": "123", "complemento": "sala 1", "bairro": "Centro", "cep": "95700-000", "cidade": "Bento Gonçalves", "uf": "RS", "email": "teste2@teste.com.br", "situacao": "Ativo", "id_vendedor": "", "nome_vendedor": "", "data_criacao": "" } } ] } } ``` ### Erro - Token inválido ```json theme={null} { "retorno": { "status_processamento": 1, "status": "Erro", "codigo_erro": 2, "erros": [ { "erro": "token invalido" } ] } } ``` ### Erro - Nenhum resultado ```json theme={null} { "retorno": { "status_processamento": 2, "status": "Erro", "codigo_erro": 20, "erros": [ { "erro": "A Consulta não retornou registros" } ] } } ``` ## Observações * Por padrão, 100 registros são listados por página * Use o parâmetro `pagina` para navegar entre os resultados * Consulte a [tabela de cidades](/api-v2/tabelas/lista-municipios) para valores válidos * Consulte a [tabela de códigos de erro](/api-v2/tabelas/codigos-erros) para interpretação dos erros