NAV Navbar
ruby
  • Tópicos
  • Introdução
  • Formatos
  • Autorização
  • Conta de testes
  • Resources
  • Itens do estoque
  • Erros
  • Introdução

    Nossa API RESTful permite que seus sistemas fiquem em sincronia com nosso banco de dados, de onde registros são enviados para serviços externos para geração de anúncios e mais.

    Utilizamos o formato JSON:API em todos os endpoints.

    O endereço da API é https://api.apisync.io

    Caso sua linguagem/framework esteja listada abaixo, recomendamos o uso da respectiva biblioteca para interação com a API.

    URLs e domínios

    O servidor da API está localizado em https://api.apisync.io. Esta parte da URL será omitida dos exemplos. Por exemplo, GET /inventory-items significa uma requisição HTTP GET para https://api.apisync.io/inventory-items.

    Requisição HTTP

    Content-Type: application/vnd.api+json
    Accept: application/vnd.api+json
    

    Você deve definir os seguintes cabeçalhos Content-Type e Accept para application/vnd.api+json como formato da requisição.

    Nota: defina application/vnd.api+json em vez de application/json para evitar inconsistências.

    IDs e reference-id no Apisync

    UUID tem o formato do ID a seguir:

    {
      "data": {
        "id": "35b87e73-3fec-4f2c-86dd-6afe36a0dbd2",
        "attributes": {
          "reference-id": "your-own-id"
        }
      }
    }
    

    Todo registro enviado por você receberão automaticamente um identificador único, chamado id no formato UUID.

    Você também pode enviar um id personalizado usando o atributo reference-id.

    Se uma requisição POST possuir um atributo reference-id de um registro já existente, tal objeto será atualizado. Se não existe um objeto com o reference-id enviado ou este é nulo, um novo registro é criado.

    Caracteres especiais em URLs

    Embora uma URL com caracteres inválidos possa funcionar, nós recomendamos a utilização de caracteres codificados. A RFC3986 define o que esperar em uma URL.

    Se você precisar utilizar caracteres especiais em uma URL, recomendamos que você substitua-os por um caractere codificado. Por exemplo,

    /admin?ids=1,2,3

    é uma URL inválida porque vírgulas são consideradas caracteres reservados. A URL abaixo, entretanto, é totalmente válida:

    /admin?ids=1%2C2%2C3%2C

    Para ver a lista completa de caracteres codificados, veja esta página que inclui o %2C acima.

    Formatos

    Hifenização

    {
      "custom-attributes": [{
        "title": "Custom attribute",
        "identifier": "custom-attribute",
        "value": "Some value"
      }]
    }
    

    Para que possamos gerar anúncios adequadamente, bem como processar dados enviados de forma determinística, todos os atributos precisam ser hifenizados (dasherized), ou seja, descritos no formato word-word. Desta forma, evitamos diferenças entre my-key, myKey e my_key.

    Moedas

    Todas as moedas são especificadas usando padrão ISO 4217. Por exemplo, especifique BRL para real brasileiro. Veja o link para os detalhes.

    Datas

    {
      "created-at": "20171012T101200Z"
    }
    

    Todas as datas devem ser criadas e são retornadas no formato ISO-8601.

    Tipos

    Todos os tipos especificados neste documento são do tipo JSON. Por exemplo, "word" é do tipo string enquanto {"key": "value"} é do tipo objeto.

    Autorização

    Para autenticar uma requisição, envie no cabeçalho sua API token:

    token = "seu-token"
    client = Apisync.new(api_key: token)
    

    Todos clientes possuem uma chave única para acesso à API chamada API Token. Você pode copiar a sua na página Configurações do seu painel de administração. Ela é secreta e você não deve compartilhá-la com ninguém.

    Você deve incluir sua API token em todas as requisições em um cabeçalho chamado Authorization, no formato Authorization: ApiToken sua-token-aqui, como no exemplo a seguir:

    curl -H "Authorization: ApiToken $API_TOKEN" "https://api.apisync.io/inventory-items"

    Com isto, autenticamos sua requisição e reconhecemos a conta sendo usada.

    Conta de testes

    Todos os clientes possuem uma conta de testes. Esta conta não possui limites ou restrições em relação à quantidade mensal de requisições à API, sendo assim recomendada para desenvolvimento e testes.

    Para usar a conta de testes nas suas requisições de API, utilize a API Token da conta de testes. Ela está visível na tela de configurações no painel de administração da conta de testes.

    Para acessá-la, entre no seu painel de administração, clique no menu de Opções e em seguida Ir para a conta de testes. Lá você encontrará sua API Token para testes.

    Em produção, utilize a API Token da conta principal.

    Resources

    Itens do estoque

    Um Item do estoque representa um produto ou mercadoria.

    A entidade

    Estes são os atributos deste resource.

    {
      "data": {
        "id": "35b87e73-3fec-4f2c-86dd-6afe36a0dbd2",
        "attributes": {
          "ad-template-type": "vehicle",
          "available": true,
          "brand": "Volkswagen",
          "condition": "new",
          "content-language": "pt-br",
          "custom-attributes": [{
            "name": "Custom attribute",
            "identifier": "custom-attribute",
            "value": "Some value"
          }, {
            "name": "Fabricante",
            "identifier": "make",
            "value": "Volkswagen"
          }, {
            "name": "Cidade",
            "identifier": "cidade",
            "value": "Sao Paulo"
          }],
          "description": "Este carro pode ser seu.",
          "images": [{
            "uri": "https://example.com/house.jpg",
            "order": 1
          }, {
            "uri": "https://example.com/bike.jpg",
            "order": 2
          }],
          "link": "https://mywebsite.com/products/volkswagen-gol-2011",
          "model": "Gol",
          "reference-id": "my-custom-id",
          "price": {
            "amount": 2117990,
            "currency": "BRL",
          }
          "title": "Gol 2011 por apenas R$21.179,90",
          "year":  2011
        }
      }
    }
    
    Atributos  
    ad‑template‑type requerido string String livre para identificar o tipo do item. Anúncios serão gerados segundo o tipo do item.

    Só são permitidos letras letras do alfabeto, números, hífens e sublinhado. Acentos e derivações (ex.: ç, ú) não são permitidos.
    available requerido boolean Indica disponibilidade do produto. Valores aceitos:
    • true: o item está disponível à venda
    • false: o item não está mais disponível à venda
    content‑language requerido string Idioma deste produto. Únicos valores aceitos no momento são: pt-br.
    brand string, opcional Nome da marca do produto ou fabricante, ex: Google, Apple, Nike, Ford.
    condition string, opcional Condição do produto. Para produtos indefinidos ou digitais, não utilize esse campo. Valores aceitos:
    • new: para produtos novos
    • used: para produtos usados ou seminovos
    • refurbished: para produtos recondicionados
    custom‑attributes lista de objetos, opcional Lista de objetos contendo atributos customizados e que descrevem o item com detalhes adicionais. Estas são as chaves aceitas:
    • identifier: um valor livre que identifique este atributo para que você use-o depois com templates de anúncios. Por exemplo, se seu atributo chama-se "Método de entrega", recomendamos usar metodo-de-entrega como id (hifenizado).
    • name: nome humano deste atributo, ex.: "Método de entrega".
    • value: valor do atributo, ex.: "Sedex10".
    Se você especificar um template de anúncio que use um atributo customizado, usaremos os identifier para encontrar o valor.
    description string, opcional Descrição do produto. Um ou dois parágrafos descrevendo o produto. Ele será mostrado na tela do produto (caso uma seja usada). Você pode usar \n.
    images lista de objetos, opcional Objeto contendo URLs para as imagens do produto. Se você definiu o atributo link, não é necessário o envio de imagens porque seu produto será visto no link. Contém 2 chaves:
    • uri (string): endereço da imagem, começando com http.
    • order (integer): define a ordem que cada item será mostrada em uma galeria de imagens. A imagem com order igual a 1 será considerada a principal/de capa.
    link string, opcional Caso o produto já possua uma página na internet, especifique um endereço começando com http. Quando especificado, anúncios levam os usuários para este endereço. Caso seja null, usuários verão o produto em uma tela genérica gerada dinamicamente.
    model string, opcional Nome ou modelo do item, ex: Mustang em Ford Mustang, 3/4 em Mangueira 3/4, Airmax em Nike Airmax.
    price objeto, opcional Objeto com 2 atributos:
    • amount: preço do item com centavos, ex.: 1012 para R$10,12. Não pode ser 0. Para não definir preço, deixe-o como nil.
    • currency: a moeda em questão, ex.: BRL, USD.
    reference‑id string, opcional Identificador do item no banco de dados do cliente. Se você deixar em branco, você precisará guardar o id retornado para poder sincronizar o item conosco.
    title string, opcional Título do produto. Ele será usado na tela genérica de vendas (caso o produto use uma). Caso seja deixado em branco, o título será a concatenação de outros atributos, como brand, model e outros.
    year integer, opcional Ano de fabricação do item com 4 digitos numéricos, ex: 1994, 2017.
    fingerprint string, somente leitura Hash única (assinatura, HMAC) gerada automaticamente representando os valores de brand, model, year, reference-id, como uma impressão digital. Usada para identificar objetos duplicados.

    Durante a criação de um objeto (POST), se o valor deste campo já existe, o objeto pré-existente será atualizado, não criado.
    sold‑out‑at string, somente leitura Data de quando a disponibilidade do produto (available) foi definido como false. Gerado automaticamente, ex.: 20171012T101200Z.
    created‑at string, somente leitura Data de criação do registro, ex.: 20171012T101200Z.

    Mais detalhes

    ad‑template‑type: este valor identifica o tipo do item e é usado para geração de anúncios específicos. Por exemplo, temos templates de anúncios para itens do tipo vehicle (carros). Portanto, use o valor vehicle aqui se o item é um carro.

    No editor de templates de anúncios, no painel de administração, você define o alvo dos templates. Você pode definir templates qualquer tipo. Por exemplo, se você possui vinhos e quer segmentar os templates, pode criar itens como vinho-cabernet-sauvignon e vinho-merlot.

    Criando itens

    Definição
    POST /inventory-items

    Para criar um novo item no seu estoque, use este endpoint.

    Quando id é omitido, o item é criado.

    client = Apisync.new(api_key: token)
    client.inventory_items.save({
      attributes: {
        ad_template_type: "vehicle",
        available: true,
        brand: "Volkswagen",
        condition: "new",
        content_language: "pt-br",
        custom_attributes: [{
          name: "Meu atributo",
          identifier: "custom-attribute",
          value: "Some value"
        }, {
          name: "Fabricante",
          identifier: "make",
          value: "Volkswagen"
        }, {
          name: "Cidade",
          identifier: "cidade",
          value: "Sao Paulo"
        }],
        description: "Este carro pode ser seu.",
        images: [{
          uri: "https://example.com/house.jpg",
          order: 1
        }, {
          uri: "https://example.com/bike.jpg",
          order: 2
        }],
        link: "https://mywebsite.com/products/volkswagen-gol-2011",
        model: "Gol",
        reference_id: "my-custom-id",
        price: {
          amount: 2117990,
          currency: "BRL",
        },
        title: "Gol 2011 por apenas R$21.179,90",
        year: 2011
      }
    })
    
    Argumentos  
    ad‑template‑type requerido string String livre para identificar o tipo do item. Anúncios serão gerados segundo o tipo do item.

    Só são permitidos letras letras do alfabeto, números, hífens e sublinhado. Acentos e derivações (ex.: ç, ú) não são permitidos.
    available requerido boolean Indica disponibilidade do produto. Valores aceitos:
    • true: o item está disponível à venda
    • false: o item não está mais disponível à venda
    content‑language requerido string Idioma deste produto. Únicos valores aceitos no momento são: pt-br.
    brand string, opcional Nome da marca do produto ou fabricante, ex: Google, Apple, Nike, Ford.
    condition string, opcional Condição do produto. Para produtos indefinidos ou digitais, não utilize esse campo. Valores aceitos:
    • new: para produtos novos
    • used: para produtos usados ou seminovos
    • refurbished: para produtos recondicionados
    custom‑attributes lista de objetos, opcional Lista de objetos contendo atributos customizados e que descrevem o item com detalhes adicionais. Estas são as chaves aceitas:
    • identifier: um valor livre que identifique este atributo para que você use-o depois com templates de anúncios. Por exemplo, se seu atributo chama-se "Método de entrega", recomendamos usar metodo-de-entrega como id (hifenizado).
    • name: nome humano deste atributo, ex.: "Método de entrega".
    • value: valor do atributo, ex.: "Sedex10".
    Se você especificar um template de anúncio que use um atributo customizado, usaremos os identifier para encontrar o valor.
    description string, opcional Descrição do produto. Um ou dois parágrafos descrevendo o produto. Ele será mostrado na tela do produto (caso uma seja usada). Você pode usar \n.
    images lista de objetos, opcional Objeto contendo URLs para as imagens do produto. Se você definiu o atributo link, não é necessário o envio de imagens porque seu produto será visto no link. Contém 2 chaves:
    • uri (string): endereço da imagem, começando com http.
    • order (integer): define a ordem que cada item será mostrada em uma galeria de imagens. A imagem com order igual a 1 será considerada a principal/de capa.
    link string, opcional Caso o produto já possua uma página na internet, especifique um endereço começando com http. Quando especificado, anúncios levam os usuários para este endereço. Caso seja null, usuários verão o produto em uma tela genérica gerada dinamicamente.
    model string, opcional Nome ou modelo do item, ex: Mustang em Ford Mustang, 3/4 em Mangueira 3/4, Airmax em Nike Airmax.
    price objeto, opcional Objeto com 2 atributos:
    • amount: preço do item com centavos, ex.: 1012 para R$10,12. Não pode ser 0. Para não definir preço, deixe-o como nil.
    • currency: a moeda em questão, ex.: BRL, USD.
    reference‑id string, opcional Identificador do item no banco de dados do cliente. Se você deixar em branco, você precisará guardar o id retornado para poder sincronizar o item conosco.
    title string, opcional Título do produto. Ele será usado na tela genérica de vendas (caso o produto use uma). Caso seja deixado em branco, o título será a concatenação de outros atributos, como brand, model e outros.
    year integer, opcional Ano de fabricação do item com 4 digitos numéricos, ex: 1994, 2017.

    Em caso de sucesso, você receberá de volta a entidade criada. Caso contrário, uma mensagem de erro.

    Importante:

    Atualizando itens

    Inclua o id para efetuar a atualização.

    client = Apisync.new(api_key: token)
    client.inventory_items.save({
      id: "35b87e73-3fec-4f2c-86dd-6afe36a0dbd2",
      attributes: {
        ad_template_type: "vehicle",
        available: true,
        brand: "Volkswagen",
        condition: "new",
        content_language: "pt-br",
        custom_attributes: [{
          name: "Meu atributo",
          identifier: "custom-attribute",
          value: "Some value"
        }, {
          name: "Fabricante",
          identifier: "make",
          value: "Volkswagen"
        }, {
          name: "Cidade",
          identifier: "cidade",
          value: "Sao Paulo"
        }],
        description: "Este carro pode ser seu.",
        images: [{
          uri: "https://example.com/house.jpg",
          order: 1
        }, {
          uri: "https://example.com/bike.jpg",
          order: 2
        }],
        link: "https://mywebsite.com/products/volkswagen-gol-2011",
        model: "Gol",
        reference_id: "my-custom-id",
        price: {
          amount: 2117990,
          currency: "BRL",
        },
        title: "Gol 2011 por apenas R$21.179,90",
        year: 2011
      }
    })
    

    PATCH /inventory-items/:id

    Você deve substituir :id pelo ID único do registro que você quer atualizar.

    Estes são os atributos que podem ser atualizados.

    Argumentos  
    ad‑template‑type requerido string String livre para identificar o tipo do item. Anúncios serão gerados segundo o tipo do item.

    Só são permitidos letras letras do alfabeto, números, hífens e sublinhado. Acentos e derivações (ex.: ç, ú) não são permitidos.
    available requerido boolean Indica disponibilidade do produto. Valores aceitos:
    • true: o item está disponível à venda
    • false: o item não está mais disponível à venda
    content‑language requerido string Idioma deste produto. Únicos valores aceitos no momento são: pt-br.
    brand string, opcional Nome da marca do produto ou fabricante, ex: Google, Apple, Nike, Ford.
    condition string, opcional Condição do produto. Para produtos indefinidos ou digitais, não utilize esse campo. Valores aceitos:
    • new: para produtos novos
    • used: para produtos usados ou seminovos
    • refurbished: para produtos recondicionados
    custom‑attributes lista de objetos, opcional Lista de objetos contendo atributos customizados e que descrevem o item com detalhes adicionais. Estas são as chaves aceitas:
    • identifier: um valor livre que identifique este atributo para que você use-o depois com templates de anúncios. Por exemplo, se seu atributo chama-se "Método de entrega", recomendamos usar metodo-de-entrega como id (hifenizado).
    • name: nome humano deste atributo, ex.: "Método de entrega".
    • value: valor do atributo, ex.: "Sedex10".
    Se você especificar um template de anúncio que use um atributo customizado, usaremos os identifier para encontrar o valor.
    description string, opcional Descrição do produto. Um ou dois parágrafos descrevendo o produto. Ele será mostrado na tela do produto (caso uma seja usada). Você pode usar \n.
    images lista de objetos, opcional Objeto contendo URLs para as imagens do produto. Se você definiu o atributo link, não é necessário o envio de imagens porque seu produto será visto no link. Contém 2 chaves:
    • uri (string): endereço da imagem, começando com http.
    • order (integer): define a ordem que cada item será mostrada em uma galeria de imagens. A imagem com order igual a 1 será considerada a principal/de capa.
    link string, opcional Caso o produto já possua uma página na internet, especifique um endereço começando com http. Quando especificado, anúncios levam os usuários para este endereço. Caso seja null, usuários verão o produto em uma tela genérica gerada dinamicamente.
    model string, opcional Nome ou modelo do item, ex: Mustang em Ford Mustang, 3/4 em Mangueira 3/4, Airmax em Nike Airmax.
    price objeto, opcional Objeto com 2 atributos:
    • amount: preço do item com centavos, ex.: 1012 para R$10,12. Não pode ser 0. Para não definir preço, deixe-o como nil.
    • currency: a moeda em questão, ex.: BRL, USD.
    reference‑id string, opcional Identificador do item no banco de dados do cliente. Se você deixar em branco, você precisará guardar o id retornado para poder sincronizar o item conosco.
    title string, opcional Título do produto. Ele será usado na tela genérica de vendas (caso o produto use uma). Caso seja deixado em branco, o título será a concatenação de outros atributos, como brand, model e outros.
    year integer, opcional Ano de fabricação do item com 4 digitos numéricos, ex: 1994, 2017.

    Importante:

    Caso a requisição funcione, você receberá de volta a entidade. Caso contrário, uma mensagem de erro.

    Lendo um item

    client = Apisync.new(api_key: token)
    client.inventory_items.find(id: "35b87e73-3fec-4f2c-86dd-6afe36a0dbd2")
    

    O comando acima retorna um JSON estruturado como este:

    {
      "data": {
        "id": "35b87e73-3fec-4f2c-86dd-6afe36a0dbd2",
        "attributes": {
          "ad-template-type": "vehicle",
          "available": true,
          "brand": "Volkswagen",
          "condition": "new",
          "content-language": "pt-br",
          "custom-attributes": [{
            "name": "Custom attribute",
            "identifier": "custom-attribute",
            "value": "Some value"
          }, {
            "name": "Fabricante",
            "identifier": "make",
            "value": "Volkswagen"
          }, {
            "name": "Cidade",
            "identifier": "cidade",
            "value": "Sao Paulo"
          }],
          "description": "Este carro pode ser seu.",
          "images": [{
            "uri": "https://example.com/house.jpg",
            "order": 1
          }, {
            "uri": "https://example.com/bike.jpg",
            "order": 2
          }],
          "link": "https://mywebsite.com/products/volkswagen-gol-2011",
          "model": "Gol",
          "reference-id": "my-custom-id",
          "price": {
            "amount": 2117990,
            "currency": "BRL",
          }
          "title": "Gol 2011 por apenas R$21.179,90",
          "year":  2011
        }
      }
    }
    

    GET /inventory-items/:id

    Você deve especificar o ID do item que você deseja ver.

    Exemplos

    GET /inventory-items/35b87e73-3fec-4f2c-86dd-6afe36a0dbd2

    Retornará apenas o item que tem o ID 35b87e73-3fec-4f2c-86dd-6afe36a0dbd2.

    Excluindo um item

    client = Apisync.new(api_key: token)
    client.inventory_items.delete(id: "35b87e73-3fec-4f2c-86dd-6afe36a0dbd2")
    

    DELETE /inventory-items/:id

    Para excluir um item, faça uma requisição para a URL acima.

    Se você apenas deseja indicar que um item não está mais disponível à venda, mas não quer exclui-lo, faça um PUT (atualização/update) passando available: false. Isto é recomendado para que o histórico de performance e eficiência deste item e seus anúncios não sejam perdidos.

    Exemplos

    DELETE /inventory-items/35b87e73-3fec-4f2c-86dd-6afe36a0dbd2

    Esta requisição excluirá o item com id 35b87e73-3fec-4f2c-86dd-6afe36a0dbd2.

    Erros

    Estes são os erros que podem ser retornados sempre que uma requisição for feita.

    Código HTTP Significado
    400 Sua requisição está incorreta.
    401 Sua API key é inválida.
    403 Você requisitou um resource que você não tem permissão.
    404 O item requisitado não pode ser encontrado.
    405 O método que você utilizou não existe ou não é suportado.
    406 Sua requisição está em um formato não aceitável.
    410 O resource requisitado não existe mais no servidor.
    422 A requisição está correta mas não pode ser processada por erros semânticos.
    429 Você está realizando muitos requests, mais do que sua conta permite. Diminua a quantidade de requests por minuto.
    500 Houve um problema temporário no servidor. Tente novamente.
    503 Serviço não disponível porque estamos em manutenção.