> For the complete documentation index, see [llms.txt](https://ajuda.uplaces.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ajuda.uplaces.com.br/integracoes/api.md).

# API de integração

API de integração da Uplaces para ERPs e integradores: peça a chave, escolha as permissões e leia e grave produtos, clientes e pedidos da loja B2B.

A API de integração da Uplaces permite que o seu ERP, o seu e-commerce ou o integrador que você contratou leia e grave produtos, clientes e pedidos da sua loja B2B por conta própria. É a saída para quem usa um ERP sem [conexão pronta](https://ajuda.uplaces.com.br/integracoes/integracao-com-erp.md) (Bling, Tiny e Omie têm). Esta página mostra como obter a chave, definir o que ela pode fazer e por onde começar. Os detalhes técnicos de cada chamada estão na documentação interativa da API.

## Antes de começar

* A API é para quem vai programar a integração, ou para o integrador que você contratou. Se você usa Bling, Tiny ou Omie, a [conexão pronta](https://ajuda.uplaces.com.br/integracoes/integracao-com-erp.md) dispensa a API.
* Usuário administrador ou diretor da loja, para abrir **Integração ERP › API**.
* Um usuário da Uplaces com o perfil **Integração**, cadastrado em **Usuários**, para ser o responsável pelas operações que entram pela API.
* A chave de API é **por loja**: ela enxerga apenas o catálogo, os clientes e os pedidos da loja a que pertence.

{% stepper %}
{% step %}

## Pedir a chave

1. No menu, abra **Integração ERP › API**.
2. Na linha **API KEY**, clique em **Clique aqui para solicitar sua chave de API**. Isso leva ao contato com o time da Uplaces, que entrega a chave a você. Se preferir, peça pelo suporte.
3. Guarde a chave como uma senha. Quem tem a chave lê e grava dados da sua loja. Passe-a só ao integrador, por um canal seguro, e nunca a publique em código aberto, em print ou em mensagem para quem não precisa dela.

Se suspeitar de que a chave vazou, ou ao trocar de fornecedor de integração, fale com o suporte da Uplaces para gerar uma nova. A chave antiga para de funcionar na hora, e todo sistema que a usa precisa ser reconfigurado.
{% endstep %}

{% step %}

## Definir o status e as permissões

Na mesma tela, preencha o formulário e clique em **Salvar**:

| Campo                   | Para que serve                                                                                                                                                                                                                                                    |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Usuário**             | o usuário de perfil **Integração** responsável pelas operações da API                                                                                                                                                                                             |
| **Status**              | **Inativo** desliga a API: as chamadas são recusadas. **Homologação** serve enquanto o integrador testa. **Produção** vale para o uso real. O status fica registrado nos pedidos que a integração atualiza e aparece na coluna **Integração** da lista de pedidos |
| **Permissões da chave** | a chave sempre pode gerenciar produtos, clientes e pedidos. Marque **Permitir alterar a aparência da loja** só se o integrador também for configurar logos, cores e banners                                                                                       |

O padrão é não permitir alterar a aparência. Sem essa permissão, a chave ainda pode **ler** a configuração da loja, mas não alterá-la.
{% endstep %}

{% step %}

## Abrir a documentação

Na mesma tela, o botão **Acessar API** abre a documentação interativa, onde o integrador vê cada endereço, os campos e exemplos, e pode testar as chamadas. Os botões **Pedidos**, **Clientes** e **Produtos** abrem direto na parte de cada recurso, e **Como funciona a API** traz uma introdução. A documentação também fica em [b2b.admin.uplaces.com.br/doc/api.html](https://b2b.admin.uplaces.com.br/doc/api.html).
{% endstep %}
{% endstepper %}

## O que o integrador precisa saber para começar

* Autenticação: a chave vai no cabeçalho `X-Authorization` de toda requisição.
* Formato: HTTPS, dados em JSON. Toda resposta traz `content` (o dado) e `erros` (lista, vazia quando deu certo).
* O que a API cobre:

| Recurso                 | Para que serve                                                                                                                                                             |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Produtos (`/products`)  | cadastrar, atualizar e consultar produtos, com foto, categoria, variações e tabelas de preço. Para o dia a dia, há chamadas só de preço e só de estoque, mais leves        |
| Clientes (`/customers`) | sincronizar a carteira de compradores. Cliente criado pela API já pode acessar o catálogo e enviar pedidos. O campo `idExternal` amarra o cliente ao código do seu sistema |
| Pedidos (`/orders`)     | trazer para o ERP os pedidos feitos na loja, devolver o status de cada um (faturado, enviado, entregue) e o número dele no ERP, e cancelar                                 |
| Loja virtual (`/store`) | ler a configuração da loja (logos, cores, banners, rodapé, WhatsApp, códigos de medição) e, com a permissão do passo 2, alterá-la                                          |

* Trazer só o que mudou: as listas usam o parâmetro `lastUpdate`, no formato `dd-mm-aaaa HH:mm` (por exemplo, `01-01-2020 00:00`). O formato ISO não é aceito. Para trazer o catálogo inteiro, use uma data anterior ao início da operação.
* Atualização parcial: no `PUT`, o campo que você não envia permanece como está.
* Limites: há um limite de requisições por segundo e por dia, por chave. Ao passar dele, a API responde `429`: espere e repita, e espace as chamadas em cargas grandes.
* Conta suspensa: se o plano da loja estiver bloqueado ou suspenso, a API responde `401` mesmo com chave válida.

## Receber avisos em vez de consultar toda hora

Para o seu sistema ser avisado quando algo muda, cadastre endereços em **Integração ERP › Gatilhos (webhooks)**. Os campos **Pedidos**, **Produtos** e **Clientes** recebem o endereço que a Uplaces chama quando um pedido é recebido ou muda de status, quando um produto é incluído ou atualizado e quando um cliente é incluído ou atualizado. Se o seu sistema exigir autenticação, preencha **Chave de autorização (opcional)**, que a Uplaces envia no cabeçalho de todas as chamadas. O interruptor de **Gatilhos** liga e desliga todos os endereços de uma vez.

## Resultado

O integrador consegue autenticar, ler os pedidos novos da loja, enviá-los ao seu ERP e devolver o status e o número do pedido no ERP. Acompanhe o que trafegou em [Log de integração](https://ajuda.uplaces.com.br/integracoes/log-de-integracao.md) e, na lista de pedidos, na coluna **Integração**.

## Problemas comuns

<details>

<summary>A API responde que a chave é inválida ou não foi informada</summary>

Confira se a chave vai no cabeçalho `X-Authorization`, sem espaço sobrando, e se é a da loja certa.

</details>

<details>

<summary>A API responde que a integração está desabilitada</summary>

O **Status** da integração está em **Inativo**. Mude para **Homologação** ou **Produção** em **Integração ERP › API** e salve.

</details>

<details>

<summary>A API responde 403 ao alterar a loja</summary>

A chave não tem a permissão. Marque **Permitir alterar a aparência da loja**, salve e tente de novo.

</details>

<details>

<summary>A lista volta vazia</summary>

Confira o formato de `lastUpdate`: `dd-mm-aaaa HH:mm`. Para trazer tudo, use uma data anterior ao início da operação.

</details>

<details>

<summary>A API responde 429</summary>

O limite de requisições foi atingido. Espere e repita, espaçando as chamadas.

</details>

## Perguntas frequentes

<details>

<summary>A Uplaces tem API aberta para integrar com o meu ERP?</summary>

Sim. A API de integração cobre produtos, clientes, pedidos e a aparência da loja, e tem documentação interativa. A chave é entregue pela Uplaces a cada loja.

</details>

<details>

<summary>Preciso da API se uso Bling, Tiny ou Omie?</summary>

Não. Essas três têm [conexão pronta](https://ajuda.uplaces.com.br/integracoes/integracao-com-erp.md), configurada pela tela.

</details>

<details>

<summary>Posso dar a chave ao meu integrador?</summary>

Pode, e é para isso que ela existe. O integrador enxerga só o catálogo, os clientes e os pedidos da sua loja, e só altera a aparência se você marcar a permissão.

</details>

<details>

<summary>A API cria pedido na Uplaces?</summary>

Sim, o `POST` em `/orders` inclui um pedido. O caminho mais comum, porém, é o inverso: a loja recebe o pedido e o ERP o busca pela API.

</details>

## Veja também

* [Integrações](https://ajuda.uplaces.com.br/integracoes/integracao-com-erp.md)
* [Log de integração](https://ajuda.uplaces.com.br/integracoes/log-de-integracao.md)
* [Importar do ERP](https://ajuda.uplaces.com.br/integracoes/importar-do-erp.md)
* No site: [integrar pedidos ao ERP](https://uplaces.com.br/integrar-pedidos-ao-erp/)
