Sincronização por CSV: especificação completa

Para a sincronização entre os clientes e o Portal Hero utilizamos um sistema de ficheiros CSV. O principal ficheiro CSV é o de artigos (ou feed de artigos), onde se listam todos os artigos que se publicam nos diferentes portais. Neste ficheiro encontram-se os artigos com as suas características.

Funcionamento da sincronização

A forma de identificar cada artigo será através do campo id, no qual nos basearemos como identificador único para decidir se um artigo é atualizado ou deixa de existir. Quando um artigo aparecer pela primeira vez no feed de artigos, este será enviado para todos os portais selecionados pelo cliente. Quando um artigo deixar de estar presente no feed, será marcado como vendido, e quando se alterar qualquer dado do artigo também será atualizado nos portais. Para teres mais detalhes sobre a sincronização em si, podes consultá-los aqui.

O formato geral destes ficheiros CSV é o seguinte:

• Campos separados por vírgulas
• O cabeçalho tem de estar presente para poder identificar os campos
• Campos delimitados por aspas duplas (se necessário ou sempre)
• Codificação do ficheiro UTF-8

Partilha de ficheiros

Temos duas opções para nos fazeres chegar o ficheiro:

• SFTP
  Dispomos de um SFTP para partilhar os ficheiros e facilitar a troca de informação de forma segura. Os dados de acesso ao SFTP (utilizador e palavra-passe) serão fornecidos durante o processo de onboarding.
  Os restantes dados comuns de ligação são os seguintes:
  • Host: sftp.portalhero.pro
  • Port: 2222
  
  Além disso, o SFTP está protegido e restringido ao nível de rede e precisaremos de um ou vários IPs para os adicionar à nossa lista de IPs de acesso permitidos.
  Dentro do SFTP há criada uma pasta chamada upload onde se escreverão os ficheiros: para o de artigos o nome do ficheiro será: item_feed.csv
• url
  O feed de artigos também pode ser enviado através de um URL público, de onde o processo do Portal Hero o descarregará em cada execução diária do processo.
  O URL deverá ser informado pelo cliente durante o processo de onboarding. Caso sejam necessárias mais medidas de segurança, podes fornecer-nos qualquer header(s) que adicionaremos ao pedido.

Formato dos ficheiros CSV

Relação dos campos, tipologia de detalhes e exemplos do ficheiro CSV de artigos:

* Para os artigos de carros, devem fornecer-se os seguintes atributos no campo 'attributes' como uma string JSON serializada:

Quanto ao campo status, que faz referência ao estado dos artigos, as opções são as seguintes:

["new", "as_good_as_new", "good", "fair", "has_given_it_all"]

Atributos do Carro

Os atributos do carro são um conjunto de características que descrevem um carro. Utilizam-se no feed e para o publicar nos marketplaces.

Exemplo (python):

car_attrs = {
    "version": "1.6 TDI Toyota",
    "year": "2018",
    "horse_power": 100,
    "mileage": 12000,
    "engine": "gasoil",
    "gearbox": "manual"
}

attributes = json.dumps(car_attrs)

Atributos da mota

Para integrar motas, o artigo deve incluir a informação específica do veículo. Os dados técnicos são enviados serializados como JSON no campo 'attributes', enquanto a marca e o modelo viajam nos campos 'brand' e 'model' do CSV.

O campo 'external_category' deve tomar um dos valores '2', 'Motos', 'Motorbikes' para que o artigo seja processado como mota. Esta integração requer ter ativo o serviço de ERP de motas na tua conta.

Os valores de 'brand' e 'model' têm de coincidir exatamente com os da nossa taxonomia de motas. Para consultar os valores válidos dispomos de dois endpoints públicos (requerem autenticação e o serviço ERP de motas ativo):

• GET /motorbike_brands — devolve a lista completa de marcas disponíveis, com o seu 'uid' e 'value'.
• GET /motorbike_models?brand_id={uid} — devolve os modelos associados à marca indicada através de 'brand_id'.

Tem em conta que o título do artigo é gerado automaticamente a partir da marca, do modelo, da versão (se informada) e do ano, pelo que o valor do campo 'title' será sobrescrito nas motas.

Exemplo (python):

motorbike_attrs = {
    "year": 2020,
    "version": "modelo actual",
    "km": 5420,
    "horse_power": 47,
    "engine_capacity_cc": 400,
    "fuel_type": "gasoline",
    "license_plate": "1234 ABC"
}

attributes = json.dumps(motorbike_attrs)