Importação de Anúncios (Inserção/Edição/Deleção)

Autenticação oAuth no Eu Preciso

Para utilizar a integração de anúncios via API, é necessário autenticar-se em nome de um usuário do Eu Preciso através do protocolo oAuth. A documentação da autenticação oAuth encontra-se aqui.

Na autenticação, o sistema solicitante receberá o client_id e o client_secret que deverão ser usados na URL de conexão. Durante o fluxo oAuth será requisitado que o usuário dê permissão ao integrador para gerenciar seus anúncios no Eu Preciso. No handshake do oAuth, é requisitado também o scope que a aplicação-cliente necessitará. Para utilizar o sistema de integração de anúncios via API, é preciso o scope autoupload.

Importação de Anúncios

O processo de integração de anúncios via API consiste no envio de um arquivo no formato JSON descrevendo um ou mais anúncios para inserção, edição ou deleção.

A URL usada para envio da requisição é: https://apps.eupreciso.com.br/v1.0/integradores/autoupload/import

O nosso servidor deve receber a chamada com método do tipo POST e o header enviado deverá ser: Content-type: application/json, Authorization: seu access_token. O formato do encode do JSON deverá ser UTF-8 e o tamanho do payload não pode ultrapassar 1 MB.

Inserção ou Edição de Anúncios

Para uma inserção ou edição de anúncios, é necessário montar o JSON com parâmetros básicos para quaisquer categorias, além de específicos de cada categoria e/ou subcategoria.

A seguir um JSON de exemplo com uma inserção:

{
  "ad_list": [
    {
      "id": "12345678910",
      "action": "insert",
      "category": "Autos e peças",
      "subcategory": "Carros, vans e utilitários",
      "title": "BMW X1 2022 em Excelente Estado",
      "body": "Vendo carro...",
      "operation": "venda",
      "price": 240000,
      "zipcode": 89221000,
      "showPhone": "1",
      "acceptNoValidatedChat": false,
      "images": ["..."],
      "params": {
        //inserir parâmetros específicos da subcategoria
      }
    }
  ]
}

Parâmetros Básicos

Parâmetros Específicos

• As peças e os veículos são cadastrados sob a mesma categoria no Eu Preciso, sendo que a identificação será dada em params, conforme será demonstrado nessa documentação.
• Outras categorias ainda não são suportadas pela API EU PRECISO.
• As subcategorias não listadas ainda estão sendo implementadas e não são suportadas pela API EU PRECISO.

Pagamento

Os anúncios no Eu Preciso são grátis, independentemente da quantidade, mas o usuário deve ter um plano PRO ativo para usar a integração de terceiros.

A seguir um JSON de exemplo com uma deleção:

{
  "ad_list": [
    {
      "id": "12345678910",
      "action": "delete"
    }
  ]
}

Deleção de Anúncios

Para uma deleção, basta enviar o id e a action delete.

O access_token deve ser sempre enviado no headers da requisição Authorization.

O anúncio permanecerá publicado a menos que uma operação de deleção seja enviada para o Eu Preciso com o id utilizado em sua inserção. Portanto recomendamos atenção redobrada para o integrador enviar a deleção para o Eu Preciso, para evitar que anúncios de produtos já vendidos continuem publicados - prejudicando a experiência do anunciante e do comprador.

Exemplos de JSONs de retorno da API:

{
  "token": "78dvsfb4ZdTpMllCgIEqUbWWiOhT",
  "statusCode": 0,
  "statusMessage": "The ads were imported and will be processed",
  "errors": []
}

{
  "token": null,
  "statusCode": -4,
  "statusMessage": "An ad had problems on import",
  "errors": [
    {
      "id": "78192371",
      "status": "error",
      "messages": [
        {
          "category": "NO_REGION"
        }
      ]
    }
  ]
}

Retorno Esperado

O formato do retorno de nosso servidor será do tipo JSON, que contém a seguinte estrutura:

Os statusCode e statusMessage possíveis são os seguintes:

No caso do erro do tipo -4, alguma validação síncrona aconteceu e, por isso, algum dos anúncios deixou de ser importado com sucesso. Os possíveis motivos são os seguintes: