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": [{
        "label": "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": [{
            "url": "https://example.com/house.jpg",
            "order": 1
          }, {
            "url": "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).
    • label: nome humano deste atributo, ex.: "Método de entrega". Este valor será usado em formulários.
    • 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. Contém 2 chaves:
    • url (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: [{
          url: "https://example.com/house.jpg",
          order: 1
        }, {
          url: "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).
    • label: nome humano deste atributo, ex.: "Método de entrega". Este valor será usado em formulários.
    • 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. Contém 2 chaves:
    • url (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: [{
          url: "https://example.com/house.jpg",
          order: 1
        }, {
          url: "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).
    • label: nome humano deste atributo, ex.: "Método de entrega". Este valor será usado em formulários.
    • 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. Contém 2 chaves:
    • url (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": [{
            "url": "https://example.com/house.jpg",
            "order": 1
          }, {
            "url": "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.