API V1 - Hub de Marketplaces - ERP

API utilizada al crear un canal ERP tipo plataforma en Marketplaces Hub

Para comenzar a desarrollar la integración de la plataforma ERP con Marketplaces Hub utilizando las nuevas API pasivas de Marketplaces Hub, es necesario entender que el flujo de procesamiento requiere que el canal ERP tenga un par de credenciales de acceso para utilizar las API. autenticado.

Este par de claves de autenticación se puede generar creando una nueva integración de Marketplaces Hub de tipo plataforma con el canal ERP.

Los entornos de producción y aprobación están divididos y se puede acceder a ellos a través de las siguientes URL:

Salvadera

• API: https://omni.sandbox.wapstore.com.br/omni-api
• Portal: https: //omni.sandbox.wapstore.com.br

Producción

• API: https://omni.wapstore.com.br/omni-api
• Portal: https:// omni.wapstore.com.br

Las solicitudes POST, PUT y DELETE tienen algunos encabezados útiles en su respuesta, que contienen el ID de la solicitud generada (Request-Id) y los límites de solicitud para cada punto final (X-RateLimit -Limit y X-RateLimit-Remaining). Si tiene problemas con una solicitud, simplemente informe al equipo de soporte del ID de la solicitud, ya que esto facilitará la obtención de los registros y reducirá el tiempo necesario para solucionar el problema.

Cache-Control: no-cache, private
Content-Type: application/json
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
Request-Id: 1R17E20190510133646C1557506206412V9676

Las API de Marketplaces Hub tienen dos niveles de autenticación: autenticación de aplicaciones y autenticación de canal de integración (canal tipo plataforma ERP).

Autenticación de aplicaciones

Todas las aplicaciones integradas tienen un token de identificación llamado AppToken que debe enviarse en el encabezado de todas las solicitudes, ya que sin él no es posible identificar la aplicación conectada y su conexión será denegada inmediatamente.

En producción, cada aplicación tiene un AppToken único; sin embargo, en la aprobación, todas las aplicaciones deben usar el AppToken de homologación, como se muestra en el siguiente ejemplo:

App-Token: homologacao
Content-Type: application/json
cache-control: no-cache

Autenticación de integración

El segundo nivel de autenticación es el de integración, es decir, de la cuenta del vendedor que se desea solicitar.

La autenticación de integración se realiza mediante un token de acceso temporal, generado en la autenticación y que debe ser enviado en el encabezado de todas las solicitudes en el índice Autorización (excepto la solicitud de autenticación, donde solo se debe enviar el AppToken).

App-Token: homologacao
Content-Type: application/json
cache-control: no-cache
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczpcL1wvYXBpLm9tbmkud2Fwc3RvcmUuY29tLmJyXC8iLCJhdWQiOiJBcGkgZGUgVGVzdGUiLCJpYXQiOjE1NTc0MjgzMjcsIm5iZiI6MTU1NzQyODMyNywiZXhwIjoxNTU3NDMwMTI3LCJ0aWQiOiIwOWI4ZGI5YWYxNjhkMDRhMmE2OTBhNTQ1NmEyZWRmMSJ9.Gfvm1Z54pUXZhlNhafV1fEoOBiMGS_sku4o2a8CKWmY

En producción tenemos varios servicios de protección conectados (firewall, protección anti-DDoS, TLS siempre actualizado, entre otros) y todos estos servicios trabajan para garantizar la integridad del sistema (principalmente porque los datos que pasan por la plataforma es confidencial (números de tarjetas de datos, direcciones, etc.).

Para que su sistema no sea bloqueado por nuestros servicios de seguridad y pueda crear una comunicación estable con nuestras API de producción, es extremadamente importante que todas las solicitudes se envíen agentes de usuario válidos, todas las conexiones se realizan utilizando el protocolo HTTPS y que su sistema admite los certificados TLS/SSL más actualizados (use un servicio en línea como SSL Labs para comprobar qué certificado TLS/SSL es compatible con los servidores de producción).

Además, el uso de una IP fija en La producción de solicitudes también es muy importante, ya que nuestro equipo de infraestructura y seguridad puede crear reglas específicas para esta IP, lo que aumenta en gran medida la seguridad y reduce el riesgo de bloqueo.

En el entorno de aprobación, el riesgo de bloqueo por seguridad Los servicios son bajos, así que siempre desarrolle su aplicación enfocándose en los niveles máximos de seguridad que se requerirán en producción.

POST /v1/logistic/auth

Recurso responsable de generar el token de autenticación de integración.

Para este recurso el único token que se debe enviar en el encabezado es el AppToken, ya que en este momento tienes aún no tendrá el token de integración.
Los datos enviados en el cuerpo (ApiKey y SecretKey) están relacionados con la cuenta de integración del Vendedor (cuenta de aprobación o producción).

Después de generar el token, tendrá una validez de 30 minutos y deberá enviarse en el encabezado Autorización de otras API.

Importante: Siempre que Se genera un nuevo token, el anterior será revocado y perderás el acceso inmediatamente.

Request

{
	"apiKey": "1234A5678B9012C3456",
	"secretKey":"3456D9012E5678F1234"
}

Detalles de la request

Response

{
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczpcL1wvYXBpLm9tbmkud2Fwc3RvcmUuY29tLmJyXC8iLCJhdWQiOiJBcGkgZGUgVGVzdGUiLCJpYXQiOjE1NTc0NTc2OTYsIm5iZiI6MTU1NzQ1NzY5NiwiZXhwIjoxNTU3NDU5NDk2LCJ0aWQiOiI5MzRjZTY2ZGY5MDQ1YWNmMzY1MGIyZWEzNWUxYjMwMSJ9.Ii148QGob19NI2-fsMbqvMpmVFyGR3bkJjSbOxaCxmg"
}

Detalles de la respuesta

GET /v1/logistic/orders/{id}/shipment_labels

Response

{
  "etiquetas": [
    {
      "conteudo": "YXJxdWl2byB0ZXN0ZQ==",
      "tipo": "pdf",
      "canal": "string",
      "idPedidoCanal": "123"
    },
    {
      "conteudo": "YXJxdWl2byB0ZXN0ZQ==",
      "tipo": "zpl",
      "canal": "string",
      "idPedidoCanal": "123"
    },
    {
      "conteudo": "YXJxdWl2byB0ZXN0ZQ==",
      "tipo": "png|jpg",
      "canal": "string",
      "idPedidoCanal": "123"
    }
  ],
  "info": {
    "filtros": [],
    "prev": "",
    "self": "http://localhost/v1/logistic/orders/13127721/shipment_labels?offset=0&limit=100",
    "next": "",
    "offset": 0,
    "limit": 100,
    "exibindo": 0,
    "total": 0
  }
}

Detalles de la respuesta

GET /v1/erp/channels

Response

{
    "canais":[
       {
          "id":123,
          "hash":"abc123",
          "nome":"Canal A",
          "ativo":true
       },
       {
          "id":456,
          "hash":"def456",
          "nome":"Canal B",
          "ativo":false
       }
    ],
    "info":{
       "total":2
    }
 }
 

Detalles de la respuesta

GET /v1/erp/products/security-stock

Recurso disponible para consultar el existencias de seguridad de productos

Este recurso se puede utilizar para comprobar la cantidad de stock de seguridad disponible para los productos de tu tienda.

Importante: Si el producto no dispone de stock de seguridad, no se devolverá

Response

{
    "produtosEstoqueSeguranca": {
        "Wapstore Marketplace": [
            {
                "idProduto": 4,
                "skuProduto": "produto-2-tete-36",
                "idCanalIntegracao": 459,
                "qtdEstoqueSeguranca": 12
            }
        ],
        "Shopee": [
            {
                "idProduto": 9,
                "skuProduto": "produto-teste-1",
                "idCanalIntegracao": 708,
                "qtdEstoqueSeguranca": 10
            }
        ]
    },
    "info": {
        "filtros": [],
        "prev": "",
        "self": "https://omni.wapstore.com.br/v1/erp/products/security-stock?offset=0&limit=5",
        "next": "https://omni.wapstore.com.br/v1/erp/products/security-stock?offset=5&limit=5",
        "offset": 0,
        "limit": 2,
        "exibindo": 2,
        "total": 55
    }
}

Detalles de la respuesta

PUT /v1/erp/products/security-stock

Recurso responsable de cambiar el existencias de seguridad de un producto

Este recurso se puede utilizar para actualizar un existencias de seguridad existente o crear uno nuevo.

Importante: El producto debe estar registrado en el HUB

Request

{
  "idCanalIntegracao": 205,
  "sku": "TESTE-ITEM02",
  "estoqueSeguranca": 8
}

Detalles de la request

Response

{
    "ProdutoEstoqueSeguranca": [
        {
            "idProduto": 3,
            "idAtributoSimples": 2,
            "idCanalIntegracao": 207,
            "idIntegracao": 3,
            "estoqueSeguranca": 10,
            "dataCadastro": "2024-02-15 20:28:35",
            "dataAtualizacao": "2024-02-15 21:39:29"
        },
        {
            "idProduto": 3,
            "idAtributoSimples": 3,
            "idCanalIntegracao": 207,
            "idIntegracao": 3,
            "estoqueSeguranca": 10,
            "dataCadastro": "2024-02-15 20:28:35",
            "dataAtualizacao": "2024-02-15 21:39:29"
        },
        {
            "idProduto": 3,
            "idAtributoSimples": 4,
            "idCanalIntegracao": 207,
            "idIntegracao": 3,
            "estoqueSeguranca": 10,
            "dataCadastro": "2024-02-15 20:28:35",
            "dataAtualizacao": "2024-02-15 21:39:29"
        }
    ]
}

Detalles de la respuesta

GET /v1/erp/products/customized-prices

Recurso disponible para consultar productos con precios personalizados en el HUB.

Esta funcionalidad se puede utilizar para consultar productos con precios personalizados en tu tienda, retornando precio "desde" y precio "por"

Importante: Si el producto no tiene precio personalizado, no será devuelto

Response

{
    "produtosPrecoPersonalizado": {
        "Dafiti": [
            {
                "idProduto": 77,
                "skuProduto": "Teste",
                "idCanalIntegracao": 177,
                "precoDePersonalizado": "100,00",
                "precoPorPersonalizado": "80,00"
            }
        ],
        "Mercado Livre": [
            {
                "idProduto": 58,
                "skuProduto": "produto-teste",
                "idCanalIntegracao": 177,
                "precoDePersonalizado": "20,00",
                "precoPorPersonalizado": "10,00"
            }
        ]
    },
    "info": {
        "filtros": [],
        "prev": "",
        "self": "https://omni.wapstore.com.br/v1/erp/products/customized-prices?offset=0&limit=2",
        "next": "https://omni.wapstore.com.br/v1/erp/products/customized-prices?offset=2&limit=2",
        "offset": "0",
        "limit": "2",
        "exibindo": 2,
        "total": "14"
    }
}

Detalles de la respuesta

PUT /v1/erp/products/customized-prices

Recurso disponible para cambiar/crear precios personalizados para productos registrados en el HUB.

Con esta funcionalidad es posible que un mismo producto tenga diferentes precios por canal de integración. Esto se puede aplicar en ambos niveles: (Producto/Variación).

Importante: El producto debe estar registrado en el HUB.

Request

{
    "precos": [
      {
        "idCanalIntegracao": 1,
        "skuProduto": "ABC123",
        "precoDe": 25.50,
        "precoPor": 20.00
      },
      {
        "idCanalIntegracao": 2,
        "skuProduto": "XYZ789",
        "precoDe": 35.75,
        "precoPor": 30.50
      },
      {
        "idCanalIntegracao": 1,
        "skuProduto": "DEF456",
        "precoDe": 18.99,
        "precoPor": 15.49
      }
    ]
  }
  

Detalles de la request

Response

{
    "resultados": [
      {
        "skuProduto": "ABC123",
        "sucessos": [
          {
            "idCanalIntegracao": 1,
            "precoDe": 25.50,
            "precoPor": 20.00
          },
          {
            "idCanalIntegracao": 2,
            "precoDe": 35.75,
            "precoPor": 30.50
          }
        ],
        "erros": []
      },
      {
        "skuProduto": "XYZ789",
        "sucessos": [],
        "erros": [
          {
            "idCanalIntegracao": 1,
            "mensagem": "Produto não encontrado"
          }
        ]
      },
      {
        "skuProduto": "DEF456",
        "sucessos": [
          {
            "idCanalIntegracao": 1,
            "precoDe": 18.99,
            "precoPor": 15.49
          }
        ],
        "erros": []
      }
    ]
  }
  

Detalles de la respuesta

DELETE /v1/erp/products/customized-prices/{idCanalIntegracao}/{skuProduto}

Recurso responsable de eliminar un precio personalizado.

PUT /v1/erp/mercadolivre/items/customized-prices

Recurso disponible para cambiar/crear precios personalizados para los anuncios del Hub que se publican en MercadoLivre.

Importante: El anuncio debe estar publicado en MercadoLibre.

Request

{
    "precos": [
      {
        "idCanalIntegracao": 1,
        "prefixoCanalIntegracao": "MLB",
        "skuProduto": "ABC123",
        "precoDe": 25.50,
        "precoPor": 20.00
      },
      {
        "idCanalIntegracao": 1,
        "prefixoCanalIntegracao": "MLP",
        "skuProduto": "ABC123",
        "precoDe": 35.75,
        "precoPor": 30.50
      },
      {
        "idCanalIntegracao": 1,
        "prefixoCanalIntegracao": "MLF",
        "skuProduto": "DEF456",
        "precoDe": 18.99,
        "precoPor": 15.49
      }
    ]
  }
  

Detalles de la request

Response

{
    "resultados": [
      {
        "skuProduto": "ABC123",
        "sucessos": [
          {
            "idCanalIntegracao": 1,
            "prefixoCanalIntegracao": "MLB",
            "codigoMlb": "MLB1999999999",
            "precoDe": 25.50,
            "precoPor": 20.00
          },
          {
            "idCanalIntegracao": 1,
            "prefixoCanalIntegracao": "MLP",
            "codigoMlb": "MLB2999999999",
            "precoDe": 35.75,
            "precoPor": 30.50
          }
        ],
        "erros": []
      },
      {
        "skuProduto": "DEF456",
        "sucessos": [],
        "erros": [
          {
            "idCanalIntegracao": 1,
            "prefixoCanalIntegracao": "MLF",
            "mensagem": "Não foi possível localizar anúncios Grátis para este SKU."
          }
        ]
      }
    ]
  }
  

Detalles de la respuesta

DELETE /v1/erp/mercadolivre/items/customized-prices/{idCanalIntegracao}/{prefixoCanalIntegracao}/{skuProduto}

Recurso responsable de eliminar un precio personalizado.

GET /v1/erp/fiscal-documents

Recurso responsable de listar los documentos fiscales (NF-e) vinculados a las operaciones de fulfillment de los canales conectados, ordenados por id ascendente.

Este recurso devuelve los datos principales de los documentos fiscales, incluyendo el XML completo. Para consultar un documento específico por su clave de acceso, utilice el recurso de consulta individual.

Importante: los parámetros dataEmissaoInicial y dataEmissaoFinal son obligatorios y deben estar en formato ISO-8601 completo (con hora y offset). Los parámetros idCanalIntegracao y tipoDocumento son opcionales — sin ellos, el listado devuelve documentos de todas las conexiones y todos los tipos.

Actualmente solo se admite NF-e. El campo status refleja el estado del documento en el vocabulario bruto del canal de origen (ej: authorized, canceled, denied).

Cuando una nota es cancelada, este recurso pasa a devolver dos registros para ella: la nota original (con status actualizado a canceled) y un segundo registro con tipoDocumento = evento-cancelamento, representando el evento SEFAZ de cancelación en sí (XML propio, protocolo propio en chaveAcesso). El campo documentosReferenciados del evento trae la clave de acceso de la nota original. Como el evento usa dataEmissao para registrar la fecha/hora de la propia cancelación (dhEvento), filtrar por dataEmissaoInicial/dataEmissaoFinal en esta misma ruta ya cubre tanto notas emitidas como cancelaciones ocurridas en el período, sin necesidad de un filtro de fecha separado — use tipoDocumento para restringir el listado a solo uno de los dos.

Response

{
    "documentosFiscais": [
        {
            "id": 3841,
            "chaveAcesso": "31260910500685000199550020000297521589865141",
            "tipoDocumento": "nfe",
            "tipo": "SALE",
            "canal": "mercadolivre",
            "idPedido": 918273,
            "status": "canceled",
            "documentosReferenciados": null,
            "dataEmissao": "2026-07-15 09:24:11",
            "xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><nfeProc>...</nfeProc>"
        },
        {
            "id": 3899,
            "chaveAcesso": "131267782988513",
            "tipoDocumento": "evento-cancelamento",
            "tipo": "CANCELAMENTO",
            "canal": "mercadolivre",
            "idPedido": 918273,
            "status": null,
            "documentosReferenciados": ["31260910500685000199550020000297521589865141"],
            "dataEmissao": "2026-07-15 09:41:18",
            "xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><procEventoNFe>...</procEventoNFe>"
        },
        {
            "id": 3842,
            "chaveAcesso": "31260910500685000199570010000010021589865223",
            "tipoDocumento": "nfe",
            "tipo": "INBOUND",
            "canal": "magazineluiza",
            "idPedido": null,
            "status": "authorized",
            "documentosReferenciados": null,
            "dataEmissao": "2026-07-15 11:02:47",
            "xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><nfeProc>...</nfeProc>"
        }
    ],
    "info": {
        "filtros": {
            "dataEmissaoInicial": "2026-07-01T00:00:00-03:00",
            "dataEmissaoFinal": "2026-07-31T23:59:59-03:00"
        },
        "prev": "",
        "self": "https://omni.wapstore.com.br/v1/erp/fiscal-documents?offset=0&limit=100&dataEmissaoInicial=2026-07-01T00:00:00-03:00&dataEmissaoFinal=2026-07-31T23:59:59-03:00",
        "next": "",
        "offset": 0,
        "limit": 100,
        "exibindo": 3,
        "total": 3
    }
}

Detalles de la respuesta

GET /v1/erp/fiscal-documents/{chaveAcesso}

Recurso de consulta individual de documentos fiscales responsable de devolver todos los datos de un documento a partir de su clave de acceso (o, para un evento-cancelamento, del protocolo del evento).

Cuando el valor informado tiene 44 dígitos, se valida contra el dígito verificador oficial de la SEFAZ (módulo 11) antes de la consulta — esta validación no aplica a protocolos de evento, que tienen otro formato.

Response

{
    "id": 3841,
    "chaveAcesso": "31260910500685000199550020000297521589865141",
    "tipoDocumento": "nfe",
    "tipo": "SALE",
    "canal": "mercadolivre",
    "idPedido": 918273,
    "status": "authorized",
    "documentosReferenciados": null,
    "dataEmissao": "2026-07-15 09:24:11",
    "xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><nfeProc>...</nfeProc>"
}

Detalles de la respuesta

Todas las solicitudes que resulten en errores tendrán el mismo patrón de devolución. El código de estado HTTP devuelto indicará si el problema está relacionado con la solicitud (sitio-cliente - 4xx) o con el procesamiento (sitio-servidor - 5xx) y el mensaje describirá detalles adicionales sobre el problema.

{
    "error": "Requisição rejeitada.",
    "details": [
        "O SKU 'TESTEAPISIMPLES' já está cadastrado"
    ]
}