Alterar Contato - Olist ERP API v3

Endpoint

POST https://api.tiny.com.br/api2/contato.alterar.php

Serviço destinado a modificar cadastros de contatos existentes no sistema Olist.

Parâmetros

Parâmetro	Tipo	Ocorrência	Descrição
token	string	obrigatório	Chave gerada para identificar sua empresa
contato	object	obrigatório	Estrutura de dados do contato conforme layout
formato	string	obrigatório	Formato do retorno. Use `json`

Estrutura do objeto contato

Campos principais

Campo	Tipo	Tamanho	Ocorrência	Descrição
sequencia	int	-	obrigatório	Número sequencial para identificar cada contato
id	int	-	opcional	ID do contato na Olist (1)
codigo	string	30	opcional	Código do contato (1)
nome	string	50	obrigatório	Nome ou razão social
fantasia	string	60	opcional	Nome fantasia
tipo_pessoa	string	1	opcional	F (Física), J (Jurídica), E (Estrangeiro)
cpf_cnpj	string	18	opcional	CPF ou CNPJ (1)
situacao	string	1	obrigatório	A (Ativo), I (Inativo), S (Sem movimento)

Informações pessoais

Campo	Tipo	Tamanho	Ocorrência	Descrição
ie	string	18	opcional	Inscrição estadual
rg	string	10	opcional	RG
im	string	18	opcional	Inscrição municipal
estadoCivil	int	-	opcional	Código do estado civil (3)
profissao	string	50	opcional	Profissão (3)
sexo	string	10	opcional	”masculino” ou “feminino” (3)
data_nascimento	string	10	opcional	Data de nascimento no formato dd/mm/aaaa (3) (4)
naturalidade	string	40	opcional	Naturalidade (3)
nome_pai	string	100	opcional	Nome do pai (3)
cpf_pai	string	18	opcional	CPF do pai (3)
nome_mae	string	100	opcional	Nome da mãe (3)
cpf_mae	string	18	opcional	CPF da mãe (3)

Endereço principal

Campo	Tipo	Tamanho	Ocorrência	Descrição
endereco	string	50	opcional	Logradouro
numero	string	10	opcional	Número do endereço
complemento	string	50	opcional	Complemento do endereço
bairro	string	30	opcional	Bairro
cep	string	10	opcional	CEP
cidade	string	30	opcional	Cidade conforme tabela de municípios
uf	string	30	opcional	Unidade Federativa
pais	string	50	opcional	País conforme tabela de países

Endereço de cobrança

Campo	Tipo	Tamanho	Ocorrência	Descrição
endereco_cobranca	string	50	opcional	Logradouro de cobrança (2)
numero_cobranca	string	10	opcional	Número do endereço de cobrança (2)
complemento_cobranca	string	50	opcional	Complemento do endereço de cobrança (2)
bairro_cobranca	string	30	opcional	Bairro de cobrança (2)
cep_cobranca	string	10	opcional	CEP de cobrança (2)
cidade_cobranca	string	30	opcional	Cidade de cobrança (2)
uf_cobranca	string	30	opcional	UF de cobrança (2)

Informações de contato

Campo	Tipo	Tamanho	Ocorrência	Descrição
contatos	string	100	opcional	Pessoas de contato
fone	string	40	opcional	Telefone
fax	string	40	opcional	Fax
celular	string	40	opcional	Telefone celular
email	string	50	opcional	E-mail
email_nfe	string	50	opcional	E-mail para recebimento de NFe
site	string	40	opcional	Website

Informações comerciais

Campo	Tipo	Tamanho	Ocorrência	Descrição
crt	int	1	opcional	Código de regime tributário: 0 (Não informado), 1 (Simples Nacional), 3 (Normal) (10)
limite_credito	decimal	-	opcional	Limite de crédito (usar ”.” como separador decimal) (5)
id_vendedor	int	-	opcional	ID do vendedor (6)
nome_vendedor	string	50	opcional	Nome do vendedor (7)
obs	string	200	opcional	Observações gerais

Listas de tipos e pessoas

Campo	Tipo	Ocorrência	Descrição
tipos_contato	array	opcional	Lista de tipos de contato (8)
tipos_contato[].tipo	string	condicional	Descrição do tipo (ex: “Cliente”, “Fornecedor”)
pessoas_contato	array	opcional	Lista de pessoas de contato (9)
pessoas_contato[].nome	string	condicional	Nome da pessoa de contato (max 50)
pessoas_contato[].telefone	string	condicional	Telefone (max 30)
pessoas_contato[].ramal	string	condicional	Ramal (max 20)
pessoas_contato[].email	string	condicional	E-mail (max 50)
pessoas_contato[].departamento	string	condicional	Departamento (max 50)

(1) Para localizar o contato a ser alterado, são utilizados os campos de busca na seguinte ordem: id → codigo → cpf_cnpj. Informe ao menos um desses campos (2) Campos de endereço de cobrança são opcionais e devem ser informados apenas se diferentes do endereço principal (3) Campos de informações pessoais se aplicam apenas a pessoas físicas e devem ser informados somente quando necessário (4) Data de nascimento deve estar no formato dd/mm/aaaa. Exemplo: “01/01/2012” (5) Valores decimais devem usar ”.” como separador decimal. Exemplo: “5.25” (6) O ID do vendedor informado deve existir no sistema, caso contrário retornará erro (7) O campo nome_vendedor é desconsiderado se id_vendedor for informado (8) Tipos de contato informados serão apenas adicionados. Tipos existentes não serão removidos ou alterados (9) Pessoas de contato informadas serão apenas adicionadas. Se o nome já existir, não haverá remoção ou alteração (10) O campo CRT é desconsiderado se tipo_pessoa for igual a “F”

Retorno

Campo	Tipo	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 (11)
retorno.erros	array	condicional	Lista de erros ocorridos (11)
retorno.erros[].erro	string	condicional	Descrição do erro
retorno.registros	array	condicional	Lista de resultados para cada contato enviado (12)
registros[].registro.sequencia	int	condicional	Número sequencial do contato
registros[].registro.status	string	condicional	”OK” ou “Erro”
registros[].registro.codigo_erro	int	condicional	Código do erro específico do registro
registros[].registro.id	int	condicional	ID do contato alterado na Olist (13)
registros[].registro.erros	array	condicional	Erros específicos do registro
registros[].registro.erros[].erro	string	condicional	Descrição do erro

(11) Retornado quando status = “Erro” (12) Retornado quando o processamento gera resultados individuais por registro (13) Retornado quando o registro foi alterado com sucesso

Exemplo de chamada

curl -X POST https://api.tiny.com.br/api2/contato.alterar.php \
  -d "token=SEU_TOKEN&formato=json&contato={\"contatos\":[{\"contato\":{\"sequencia\":\"1\",\"codigo\":\"1234\",\"nome\":\"Contato Alterado\",\"situacao\":\"A\"}}]}"

$url = 'https://api.tiny.com.br/api2/contato.alterar.php';
$token = 'SEU_TOKEN';

$contato = json_encode([
    'contatos' => [
        [
            'contato' => [
                'sequencia' => '1',
                'codigo' => '1234',
                'nome' => 'Contato Teste 1 Alterado',
                'situacao' => 'A'
            ]
        ],
        [
            'contato' => [
                'sequencia' => '2',
                'codigo' => '1235',
                'nome' => 'Contato Teste 2 Alterado',
                'tipo_pessoa' => 'F',
                'cpf_cnpj' => '22755777850',
                'endereco' => 'Rua Teste',
                'numero' => '123',
                'bairro' => 'Teste',
                'cep' => '95700-000',
                'cidade' => 'Bento Gonçalves',
                'uf' => 'RS',
                'email' => 'teste@teste.com.br',
                'id_vendedor' => '123',
                'situacao' => 'A'
            ]
        ]
    ]
]);

$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": 2,
    "status": "OK",
    "registros": [
      {
        "registro": {
          "sequencia": "1",
          "status": "OK",
          "id": "49644545"
        }
      }
    ]
  }
}

Sucesso - Múltiplos registros

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

Erro - Token inválido

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

Erro - Contato não encontrado

{
  "retorno": {
    "status_processamento": 2,
    "status": "OK",
    "registros": [
      {
        "registro": {
          "sequencia": "1",
          "status": "Erro",
          "codigo_erro": 32,
          "erros": [
            {
              "erro": "Contato não localizado"
            }
          ]
        }
      }
    ]
  }
}

Observações

É possível alterar múltiplos contatos em uma única chamada através do array contatos
O contato é localizado pelos campos id, codigo ou cpf_cnpj nessa ordem de prioridade
Apenas os campos informados serão atualizados. Campos não enviados manterão seus valores atuais
Tipos de contato e pessoas de contato são sempre adicionados, nunca removidos
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
Para obter o ID de um contato, use o endpoint de pesquisa de contatos

​Endpoint

​Parâmetros

​Estrutura do objeto contato

​Campos principais

​Informações pessoais

​Endereço principal

​Endereço de cobrança

​Informações de contato

​Informações comerciais

​Listas de tipos e pessoas

​Retorno

​Exemplo de chamada

​Exemplo de retorno

​Sucesso

​Sucesso - Múltiplos registros

​Erro - Token inválido

​Erro - Contato não encontrado

​Observações

Endpoint

Parâmetros

Estrutura do objeto contato

Campos principais

Informações pessoais

Endereço principal

Endereço de cobrança

Informações de contato

Informações comerciais

Listas de tipos e pessoas

Retorno

Exemplo de chamada

Exemplo de retorno

Sucesso

Sucesso - Múltiplos registros

Erro - Token inválido

Erro - Contato não encontrado

Observações