Skip to main content

Endpoint

POST https://api.tiny.com.br/api2/contato.incluir.php
Serviço destinado a permitir a criação e inclusão de cadastros de contatos dentro do sistema Olist.

Parâmetros

ParâmetroTipoOcorrênciaDescrição
tokenstringobrigatórioChave gerada para identificar sua empresa
contatoobjectobrigatórioEstrutura de dados do contato conforme layout
formatostringobrigatórioFormato do retorno. Use json

Estrutura do objeto contato

Campos principais

CampoTipoTamanhoOcorrênciaDescrição
sequenciaint-obrigatórioNúmero sequencial para identificar cada contato
codigostring30opcionalCódigo do contato
nomestring50obrigatórioNome ou razão social
fantasiastring60opcionalNome fantasia
tipo_pessoastring1opcionalF (Física), J (Jurídica), E (Estrangeiro)
cpf_cnpjstring18opcionalCPF ou CNPJ
situacaostring1obrigatórioA (Ativo), I (Inativo), S (Sem movimento)

Informações pessoais

CampoTipoTamanhoOcorrênciaDescrição
iestring18opcionalInscrição estadual
rgstring10opcionalRG
imstring18opcionalInscrição municipal
estadoCivilint-opcionalCódigo do estado civil (1)
profissaostring50opcionalProfissão (1)
sexostring10opcional”masculino” ou “feminino” (1)
data_nascimentostring10opcionalData de nascimento no formato dd/mm/aaaa (1) (2)
naturalidadestring40opcionalNaturalidade (1)
nome_paistring100opcionalNome do pai (1)
cpf_paistring18opcionalCPF do pai (1)
nome_maestring100opcionalNome da mãe (1)
cpf_maestring18opcionalCPF da mãe (1)

Endereço principal

CampoTipoTamanhoOcorrênciaDescrição
enderecostring50opcionalLogradouro
numerostring10opcionalNúmero do endereço
complementostring50opcionalComplemento do endereço
bairrostring30opcionalBairro
cepstring10opcionalCEP
cidadestring30opcionalCidade conforme tabela de municípios (3)
ufstring30opcionalUnidade Federativa
paisstring50opcionalPaís conforme tabela de países (3)

Endereço de cobrança

CampoTipoTamanhoOcorrênciaDescrição
endereco_cobrancastring50opcionalLogradouro de cobrança (4)
numero_cobrancastring10opcionalNúmero do endereço de cobrança (4)
complemento_cobrancastring50opcionalComplemento do endereço de cobrança (4)
bairro_cobrancastring30opcionalBairro de cobrança (4)
cep_cobrancastring10opcionalCEP de cobrança (4)
cidade_cobrancastring30opcionalCidade de cobrança (4)
uf_cobrancastring30opcionalUF de cobrança (4)

Informações de contato

CampoTipoTamanhoOcorrênciaDescrição
contatosstring100opcionalPessoas de contato
fonestring40opcionalTelefone
faxstring40opcionalFax
celularstring40opcionalTelefone celular
emailstring50opcionalE-mail
email_nfestring50opcionalE-mail para recebimento de NFe
sitestring40opcionalWebsite

Informações comerciais

CampoTipoTamanhoOcorrênciaDescrição
crtint1opcionalCódigo de regime tributário: 0 (Não informado), 1 (Simples Nacional), 3 (Normal) (5)
limite_creditodecimal-opcionalLimite de crédito (usar ”.” como separador decimal) (6)
contribuintestring1opcional0 (Não informado), 1 (Contribuinte ICMS), 2 (Isento), 9 (Não contribuinte)
id_vendedorint-opcionalID do vendedor (7)
nome_vendedorstring50opcionalNome do vendedor (8)
obsstring200opcionalObservações gerais

Listas de tipos e pessoas

CampoTipoOcorrênciaDescrição
tipos_contatoarrayopcionalLista de tipos de contato
tipos_contato[].tipostringcondicionalDescrição do tipo (ex: “Cliente”, “Fornecedor”)
pessoas_contatoarrayopcionalLista de pessoas de contato
pessoas_contato[].nomestringcondicionalNome da pessoa de contato (max 50)
pessoas_contato[].telefonestringcondicionalTelefone (max 30)
pessoas_contato[].ramalstringcondicionalRamal (max 20)
pessoas_contato[].emailstringcondicionalE-mail (max 50)
pessoas_contato[].departamentostringcondicionalDepartamento (max 50)
(1) Campos de informações pessoais se aplicam apenas a pessoas físicas (tipo_pessoa = “F”) (2) Data de nascimento deve estar no formato dd/mm/aaaa. Exemplo: “01/01/2012” (3) Os valores de cidade e país devem estar de acordo com as tabelas oficiais de municípios e países (4) Campos de endereço de cobrança são opcionais e devem ser informados apenas se diferentes do endereço principal (5) O campo CRT é desconsiderado para pessoas físicas (tipo_pessoa = “F”) (6) Valores decimais devem usar ”.” como separador decimal. Exemplo: “5.25” (7) O ID do vendedor informado deve existir no sistema, caso contrário retornará erro (8) O campo nome_vendedor é desconsiderado se id_vendedor for informado

Retorno

CampoTipoOcorrênciaDescrição
retorno.status_processamentointobrigatórioCódigo de status do processamento
retorno.statusstringobrigatório”OK” ou “Erro”
retorno.codigo_errointcondicionalCódigo do erro conforme tabela da API (9)
retorno.errosarraycondicionalLista de erros ocorridos (9)
retorno.erros[].errostringcondicionalDescrição do erro
retorno.registrosarraycondicionalLista de resultados para cada contato enviado (10)
registros[].registro.sequenciaintcondicionalNúmero sequencial do contato
registros[].registro.statusstringcondicional”OK” ou “Erro”
registros[].registro.codigo_errointcondicionalCódigo do erro específico do registro
registros[].registro.idintcondicionalID do contato criado na Olist (11)
registros[].registro.errosarraycondicionalErros específicos do registro
registros[].registro.erros[].errostringcondicionalDescrição do erro
(9) Retornado quando status = “Erro” (10) Retornado quando o processamento gera resultados individuais por registro (11) Retornado quando o registro foi incluído com sucesso

Exemplo de chamada

curl -X POST https://api.tiny.com.br/api2/contato.incluir.php \
  -d "token=SEU_TOKEN&formato=json&contato={\"contatos\":[{\"contato\":{\"sequencia\":\"1\",\"nome\":\"Contato Teste\",\"situacao\":\"A\"}}]}"
$url = 'https://api.tiny.com.br/api2/contato.incluir.php';
$token = 'SEU_TOKEN';

$contato = json_encode([
    'contatos' => [
        [
            'contato' => [
                'sequencia' => '1',
                'codigo' => '1234',
                'nome' => 'Contato Teste 1',
                'fantasia' => 'Teste 1',
                'tipo_pessoa' => 'F',
                'cpf_cnpj' => '12345678900',
                'endereco' => 'Rua Teste',
                'numero' => '123',
                'bairro' => 'Centro',
                'cep' => '95700-000',
                'cidade' => 'Bento Gonçalves',
                'uf' => 'RS',
                'email' => 'teste@teste.com.br',
                'fone' => '(54) 3055-3808',
                'situacao' => 'A',
                'tipos_contato' => [
                    ['tipo' => 'Cliente'],
                    ['tipo' => 'Fornecedor']
                ]
            ]
        ]
    ]
]);

$data = "token=$token&contato=$contato&formato=json";

$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

{
  "retorno": {
    "status_processamento": 3,
    "status": "OK",
    "registros": [
      {
        "registro": {
          "sequencia": "1",
          "status": "OK",
          "id": "49644545"
        }
      }
    ]
  }
}

Erro - Token inválido

{
  "retorno": {
    "status_processamento": 1,
    "status": "Erro",
    "codigo_erro": 2,
    "erros": [
      {
        "erro": "token invalido"
      }
    ]
  }
}

Erro - Dados inválidos

{
  "retorno": {
    "status_processamento": 2,
    "status": "OK",
    "registros": [
      {
        "registro": {
          "sequencia": "1",
          "status": "Erro",
          "codigo_erro": 6,
          "erros": [
            {
              "erro": "Campo obrigatório não informado: nome"
            }
          ]
        }
      }
    ]
  }
}

Observações

  • É possível incluir múltiplos contatos em uma única chamada através do array contatos
  • O campo sequencia é obrigatório para identificar cada contato no retorno
  • Consulte a tabela de cidades para valores válidos de município
  • Consulte a tabela de códigos de erro para interpretação dos erros
  • Campos de pessoa física são aplicáveis apenas quando tipo_pessoa = “F”