Fastcommerce Developers Center

Sobre a Adm360

O Adm360 é uma API (Application Programming Interface) do Fastcommerce permite a sistematização remota de diversas tarefas realizadas regularmente pelos usuários através do site administrativo da loja virtual. Com esta API é possível integrar aplicativos externos tais como ERPs, CRMs, sistemas de BI, gateways de pagamento etc, e através destes aplicativos executar métodos da API para gerenciamento de produtos e pedidos, obter dados de relatórios e executar utilitários do Fastcommerce.

1 - Acessando a API

O acesso à API ocorre sempre através do protocolo HTTPS (porta 443), com certificação EV SSL. A execução de cada método inicia-se através de uma solicitação enviada via FORM POST e termina em seguida com uma única resposta em XML.

A resposta à execução de cada método é síncrona e pode ocorrer de forma quase imediata ou pode demorar até alguns minutos, dependendo do método e da quantidade de registros lidos ou alterados.

ATENÇÃO:

Existe um limite no volume de acessos por hora aos métodos da API. Veja os detalhes no parágrafo 2 do item Melhores Práticas).

2 - Histórico de Versões

A versão atual da API é 1.0.

3 - Loja para testes

O Fastcommerce não tem um ambiente de sandbox para realizar testes. Sugerimos portanto que crie uma loja para testes para desenvolver com a API.

Acesse o endereço http://novaloja.fastcommerce.com.br para criar sua loja de testes. Após cadastrá-la, avise-nos qual é o nome e o ID desta nova loja através do e-mail comercial@fastcommerce.com.br para que possamos deixar a loja em implantação e a mesma não seja cancelada após o prazo de avaliação.

4 - Usuário para testes

O usuário que vai consumir a API precisa basicamente de acesso aos relatórios e utilitários da loja, pois é através dele que as consultas e alterações são feitas.

Essa etapa deve ser realizada por um usuário da loja com permissão para criar novos usuários.

Acesse a administração da loja e no menu "Usuários" clique na opção "Incluir usuário".

O cadastro pode ser preenchido como no exemplo abaixo.

5 - Melhores Práticas

Seguem algumas dicas para melhor utilização da API:

• 5.1) Para maximizar a performance na alteração de pedidos, inclua no JSON somente os campos obrigatórios e os campos que serão alterados. Não inclua no JSON campos que não serão alterados.

• 5.2) Existe um limite de até 100 chamadas à API de pedidos por hora. Para maximizar o uso de cada chamada ao comando OrderManagement (OMN), é possível incluir mais de um registro que será afetado em cada chamada. Por exemplo, é possível incluir e alterar vários pedidos em uma mesma chamada. Se este limite for excedido, novas requisições serão bloqueadas até a próxima virada da hora. Por exemplo, se forem feitas mais de 100 requisições entre 13h e 14h, somente após as 14h será possível fazer novos acessos à API, e assim por diante. Quando o limite for excedido, o erro "ErrOrdersAccessLimit" será retornado pela API, com a seguinte mensagem: Reached limit of access per hour.

6 - Comandos da API

O comando informa qual a ação desejada na chamada à API. Cada chamada deve obrigatoriamente conter um dos comandos abaixo:

• LIN (Login) - Login para obtenção do token
• OMN (Order Management) - Inclusão e alteração de pedidos

A comunicação se inicia através de um FORM POST para o seguinte endereço:
https://www.rumo.com.br/adm/Adm360.asp

Seguem abaixo os campos obrigatórios deste POST:

Caso o comando seja OMN (Order Management) os campos são:

Exemplo de FORM para Login (LIN):

                
<form name="Logon" action="https://www.rumo.com.br/adm/Adm360.asp" method="POST">
  <input type="text" name="StoreName" value="Nome da loja">
  <input type="text" name="StoreID" value="99999">
  <input type="text" name="Username" value="Admin">
  <input type="password" name="Password" value="******">
  <input type="text" name="cmd" value="LIN">
</form>
                
              

Exemplo de FORM para Order Management (OMN):

                
<form name="Logon" action="https://www.rumo.com.br/adm/Adm360.asp" method="POST">
  <input type="text" name="StoreID" value="99999">
  <input type="text" name="token" value="9999999999999">
  <input type="text" name="cmd" value="LIN">
  <input type="text" name="OrdersData" value="{...JSON...}"> <!-- *** -->
</form>
                
              

7 - Permissões de acesso

Para o acesso a API, é necessário que o usuário tenha permissões de acordo com cada método:

Atenção:

Acessos à API não devem estar diretamente relacionados aos acessos a qualquer página da loja virtual, ou seja, cada acesso de cliente da loja não deve corresponder a um acesso à API. Para evitar que isto ocorra, existe uma limitação no volume de acessos por hora aos métodos da API.

Obs: É extramente recomendado criar um usuário específico para cada aplicação que for utilizar a API. Este usuário deve ter nome de usuário e senha fortes e únicas. Insira as permissões de acordo com que a aplicação irá utilizar. Por exemplo, se a aplicação irá apenas acessar os dados de pedidos, basta inserir acesso a relatórios de pedidos e em todos os demais campos deixar sem acesso.

8 - Exemplos de requisições

8.1 - API de pedidos

Estrutura do JSON:

Para inclusão o comando (cmd) dentro de cada registro do array "orders" deve ser insert e para atualização update. Para alteração devem ser enviados somente os campos que tiverem alterações, não é necessário enviar todos os campos.

                
{
  "send-webhook-notifications": true,
  "sync-marketplaces": true,
  "sync-stores": true,
  "manage-stock": true,
  "accept-only-store-products": true,
  "orders": [
    {
      "cmd": "insert/update",
      "order": {
        "number": "165240550",
        "ref_number": "MYNUMBER00001",
        "transaction_status": "WAITING PAYMENT",
        "payment_status": "PENDING",
        "custom_data": "Informações personalizadas",
        "invoice": "111111111111111111111",
        "amount_without_shipping": 31.5,
        "coupon_discount": 0,
        "discount_without_shipping": 10,
        "short_obs": "OBS CURTA",
        "status": "New"
      },
      "customer": {
        "name": "Nome da pessoa",
        "gender": "male",
        "birth_date": "1978-01-01T03:00:00Z",
        "email": "email@cliente.com.br",
        "phone": "(21) 5555-1234",
        "cellphone": "11988886666",
        "custom_1": "info 1",
        "custom_2": "info 2",
        "custom_3": "info 3",
        "document": {
          "type": "CPF",
          "number": "01234567890"
        },
        "additional_document": {
          "type": "RG",
          "number": "1111111111"
        },
        "address": {
          "country": "Brasil",
          "street": "Rua Sete de Setembro",
          "street_number": "123",
          "complement": "Comp1",
          "neighborhood": "Centro Casa",
          "city": "Rio de Janeiro",
          "state": "RJ",
          "zipcode": "20050-001"
        }
      },
      "payment": {
        "method": "Cartão de Crédito",
        "processed_by": "Pagar.me",
        "brand": "VISA",
        "installments": 3,
        "interest": 0
      },
      "shipping": {
        "name": "Nome destinatário",
        "email": "email@destino.com.br",
        "amount": 10.5,
        "amount_packaging": 0,
        "custom_1": "info 1",
        "custom_2": "info 2",
        "custom_3": "info 3",
        "discount": 0,
        "message": "Mensagem do cliente",
        "gift": false,
        "phone": "(21) 2222-2222",
        "info": "CEP 04516-001 (SEDEX 10)",
        "obs": "3 dias",
        "tracking_code": "SDX00011",
        "delivery_date": "",
        "address": {
          "country": "Brasil",
          "street": "Rua Sete de Setembro",
          "street_number": "123",
          "complement": "comple",
          "neighborhood": "Centro Casa",
          "city": "Rio de Janeiro",
          "state": "RJ",
          "zipcode": "20050-001"
        }
      },
      "items": [
        {
          "id": 170070,
          "sku_code": "111",
          "name": "Camiseta",
          "category_name": "Moda",
          "bar_code": null,
          "descriptor_1": null,
          "descriptor_2": "P",
          "descriptor_3": null,
          "simple_descriptor_1": null,
          "simple_descriptor_2": null,
          "simple_descriptor_3": null,
          "color": "Branco",
          "filters": null,
          "unit_price": 11,
          "quantity": 1,
          "weight": 12000
        },
        {
          "id": 170071,
          "sku_code": "222",
          "name": "Camiseta",
          "category_name": "Moda",
          "bar_code": null,
          "descriptor_1": null,
          "descriptor_2": "M",
          "descriptor_3": null,
          "simple_descriptor_1": null,
          "simple_descriptor_2": null,
          "simple_descriptor_3": null,
          "color": "Branco",
          "filters": null,
          "unit_price": 12,
          "quantity": 2,
          "weight": 0
        }
      ]
    }
  ]
}
                
              

É possível incluir/alterar múltiplos pedidos por vez.

O resultado desta operação será retornado em JSON. Segue o modelo:

                
{
  "begin": "2025-01-16T20:08:02-03:00",
  "srv": "serverName",
  "cmd": "OMN",
  "send-webhook-notifications": true,
  "sync-marketplaces": true,
  "sync-stores": true,
  "manage-stock": true,
  "accept-only-store-products": true,
  "order_1": {
    "cmd": "insert",
    "ref_number": "MYNUMBER00001",
    "shipping_amount": 10.5,
    "order_totalItems": 35,
    "order_amount_without_shipping": 31.5,
    "order_totalAmount": 42,
    "customer_id": 2449,
    "customer_updated": true,
    "customer_inserted": false,
    "order_updated": false,
    "order_inserted": true,
    "order_id": 6240,
    "order_number": 165240724,
    "items_1": "OK: inserted [170070]",
    "items_2": "OK: inserted [170071]",
    "err": "OK"
  },
  "received": 1,
  "valid": 1,
  "invalid": 0,
  "inserted": 1,
  "updated": 0,
  "sess": "173403027",
  "end": "2025-01-16T20:08:02-03:00",
  "et": 200
}
                
              

Obs: Note que o order_number gerado automaticamente pelo sistema é retornado neste JSON.

Veja a lista com os possíveis códigos de erros (<err>) e suas descrições (<errDescr>):

Se houver erros, o resultado desta operação será retornado em JSON da seguinte forma:

{
  "begin": "2025-01-16T20:10:45-03:00",
  "srv": "dom0web7",
  "cmd": "OMN",
  "err": "ErrOrderManagementInvData",
  "errDescr": "Invalid OrderData",
  "sess": "173403027",
  "end": "2025-01-16T20:10:45-03:00",
  "et": 32
}
              

{
  "begin": "2025-01-16T20:12:36-03:00",
  "srv": "dom0web7",
  "cmd": "OMN",
  "send-webhook-notifications": true,
  "sync-marketplaces": true,
  "sync-stores": true,
  "manage-stock": true,
  "accept-only-store-products": true,
  "order_1": {
    "cmd": "update",
    "order_number": 1652405501,
    "ref_number": "MYNUMBER00001",
    "shipping_amount": 10.5,
    "order_amount_without_shipping": 31.5,
    "order_totalAmount": 42,
    "err": "order.number not found"
  },
  "order_2": {
    "cmd": "update",
    "order_number": 165240551,
    "ref_number": "MYNUMBER00001",
    "shipping_amount": 10.5,
    "order_amount_without_shipping": 31.5,
    "order_totalAmount": 42,
    "customer_id": 2433,
    "customer_updated": true,
    "customer_inserted": false,
    "order_updated": true,
    "order_inserted": false,
    "order_id": 6060,
    "err": "OK"
  },
  "received": 2,
  "valid": 1,
  "invalid": 1,
  "inserted": 0,
  "updated": 1,
  "err": "ErrProcessingOrders",
  "errDescr": "An error occurred in one or more records",
  "sess": "173403027",
  "end": "2025-01-16T20:12:36-03:00",
  "et": 104
}
              

Sempre serão retornados os registros e indicado em cada registro se ocorreu ou não erro ao processar aquele registro.

Outras informações do retorno:

9 - Realizando Testes

Disponibilizamos uma página para facilitar a realização de testes de integração via navegador e assim conhecer melhor o funcionamento da API. Segue o endereço:

API Test

9.1 Comando LIN

Neste teste, será possível ver o processo para fazer login e obter token para as requisições da API.

No campo Cmd selecione a opção Login (LIN). Preencha os campos e clique em Entrar.

Campos retornados pela API:

Como resultado, teremos a seguinte estrutura:

{
  "begin": "2025-01-17T18:09:43-03:00",
  "srv": "dom0web7",
  "cmd": "LIN",
  "id": 184,
  "st": "SP Departamentos",
  "usr": "Alexandre",
  "err": "ErrOK",
  "errDescr": "OK",
  "sess": "179662158",
  "tk": "2032158669138",
  "end": "2025-01-17T18:09:43-03:00",
  "et": 16
}
              

9.2 Comando OMN

Neste teste, serão alterados dois pedidos

No campo Cmd selecione a opção OMN. Preencha os campos IDLoja, Token e no campo OrdersData informe o JSON com os registros que deseja alterar e clique em Entrar.

Exemplo

{
  "send-webhook-notifications": true,
  "sync-marketplaces": true,
  "sync-stores": true,
  "manage-stock": true,
  "accept-only-store-products": true,
  "orders": [
    {
      "cmd": "update",
      "order": {
        "number": "165240550",
        "status": "New"
      }
    },
    {
      "cmd": "update",
      "order": {
        "number": "165240551",
        "status": "Approved"
      }
    }
  ]
}
              

Como resultado, teremos a seguinte estrutura:

{
  "begin": "2025-01-17T18:25:22-03:00",
  "srv": "dom0web7",
  "cmd": "OMN",
  "send-webhook-notifications": true,
  "sync-marketplaces": true,
  "sync-stores": true,
  "manage-stock": true,
  "accept-only-store-products": true,
  "order_1": {
    "cmd": "update",
    "order_number": 165240550,
    "customer_inserted": false,
    "customer_updated": false,
    "customer_id": 2433,
    "order_updated": true,
    "order_inserted": false,
    "order_id": 6059,
    "err": "OK"
  },
  "order_2": {
    "cmd": "update",
    "order_number": 165240551,
    "customer_inserted": false,
    "customer_updated": false,
    "customer_id": 2433,
    "order_updated": true,
    "order_inserted": false,
    "order_id": 6060,
    "err": "OK"
  },
  "received": 2,
  "valid": 2,
  "invalid": 0,
  "inserted": 0,
  "updated": 2,
  "err": "ErrOK",
  "errDescr": "OK",
  "sess": "179662158",
  "end": "2025-01-17T18:25:22-03:00",
  "et": 124
}
              

10 - Dicionário de Dados

Order Management [Comando OMN]

JSON de API de pedidos [Inclusão/Alteração]

11 - Tratamento de Erros

Os erros são retornados em "err" e "errDescr" respectivamente.

No exemplo o retorno aponta que não tiverem erros:

  "err": "ErrOK",
  "errDescr": "OK",
              

Exemplo de retorno da API quando ocorre erro:

  "err": "ErrOrderManagementInvData",
  "errDescr": "Invalid OrderData",