Para quem integra
Documentação da API
Tudo o que a sua equipe faz no painel também pode ser feito pelo sistema da sua empresa. As mesmas regras de plano, permissão e isolamento valem fora da tela.
Endereço
Toda chamada parte deste endereço. A versão faz parte da URL: uma mudança que quebre integração existente entra numa versão nova, nunca nesta.
https://cloud.lecodaro.com.br/api/v1
Como criar a credencial
- Entre na sua conta e confirme, no seletor do topo, que você está no Espaço certo.
- Abra Meu perfil e vá até a área da API pública.
- Dê um nome que lembre onde a credencial vai ser usada e escolha o acesso: somente leitura, ou leitura e escrita.
- Copie o segredo na hora. Ele aparece uma única vez, e nem nós conseguimos mostrá-lo de novo depois.
A credencial fica presa ao Espaço em que foi criada e não acompanha a troca de Espaço na tela. Para integrar dois Espaços, crie uma credencial em cada um. Revogar pela tela corta a próxima chamada na hora.
Autenticação
Envie a credencial no cabeçalho de cada chamada.
curl https://cloud.lecodaro.com.br/api/v1/context \
-H "Authorization: Bearer SUA_CREDENCIAL" \
-H "Accept: application/json"
O acesso da credencial é um teto, não uma autorização por si só: a participação e o perfil da pessoa que a criou continuam sendo verificados a cada chamada. Se a pessoa sair do Espaço ou perder a permissão, a credencial para de funcionar mesmo existindo.
Limite de requisições
O limite é por credencial, por minuto, e acompanha o plano do Espaço. Ao estourar, a resposta vem com o código 429 e o cabeçalho Retry-After, dizendo em quantos segundos tentar de novo.
| Plano | Requisições por minuto |
|---|---|
| Básico | 60 |
| Plus | 120 |
| Premium | 300 |
| Corporativo | 600 |
Formato das respostas
- JSON em UTF-8. Para escrever, envie
Content-Type: application/json. - Sucesso devolve o conteúdo dentro de
data. Erro devolvemessagee, quando faz sentido,error.codeou a lista de campos inválidos. - Datas em ISO 8601, no fuso UTC. Valores em dinheiro vêm em centavos inteiros.
- Listas vêm paginadas, com 25 itens por página e no máximo 100.
- Toda resposta traz
X-Request-Id. Guarde esse valor: com ele o suporte localiza a chamada sem que você precise enviar a credencial.
Códigos de resposta
| Código | Quando acontece |
|---|---|
| 200 e 201 | Sucesso. Criação devolve 201. |
| 204 | Remoção concluída, sem corpo. |
| 401 | Credencial ausente, inválida ou revogada. |
| 403 | O escopo da credencial ou o perfil da pessoa não permite a operação. |
| 404 | O recurso não existe dentro do Espaço da credencial. |
| 422 | Validação falhou. O corpo traz o campo e o motivo. |
| 429 | Limite de requisições excedido. A resposta traz Retry-After. |
Um recurso que pertence a outro Espaço responde 404, e não 403. A API não confirma a existência de dado que não é seu.
Todos os endereços
A lista completa, com o método, o caminho e o escopo exigido. Um teste compara esta página com as rotas realmente registradas nos dois sentidos, então ela não pode ficar para trás nem descrever algo que não existe.
Contexto
Confirma que a credencial funciona e mostra o Espaço a que ela pertence. É a primeira chamada de qualquer integração.
| Método | Caminho | Escopo | O que faz |
|---|---|---|---|
GET |
/context |
read | Espaço, participação e escopo da credencial. |
Tags
Rótulos usados para organizar os demais módulos. Não existe exclusão de tag: o produto não apaga rótulo já aplicado.
| Método | Caminho | Escopo | O que faz |
|---|---|---|---|
GET |
/tags |
read | Lista as tags do Espaço. |
POST |
/tags |
write | Cria uma tag. |
PATCH |
/tags/{tag} |
write | Renomeia uma tag. |
Links curtos
Endereços curtos com destino editável, contagem de acessos e lixeira.
| Método | Caminho | Escopo | O que faz |
|---|---|---|---|
GET |
/short-links |
read | Lista os links curtos. |
GET |
/short-links/{shortLink} |
read | Detalhe de um link curto. |
POST |
/short-links |
write | Cria um link curto. |
PATCH |
/short-links/{shortLink} |
write | Edita título, destino, contexto ou tag. |
POST |
/short-links/{shortLink}/pause |
write | Pausa o link, que passa a não redirecionar. |
POST |
/short-links/{shortLink}/activate |
write | Reativa um link pausado. |
DELETE |
/short-links/{shortLink} |
write | Move para a lixeira. |
POST |
/short-links/{shortLink}/restore |
write | Restaura da lixeira. |
DELETE |
/short-links/{shortLink}/permanent |
write | Exclui definitivamente. Não há volta. |
QR Codes
QR Codes dinâmicos: o destino muda depois de impresso, sem gerar código novo.
| Método | Caminho | Escopo | O que faz |
|---|---|---|---|
GET |
/qr-codes |
read | Lista os QR Codes. |
GET |
/qr-codes/{qrCode} |
read | Detalhe de um QR Code. |
GET |
/qr-codes/{qrCode}/svg |
read | Imagem do QR Code em SVG. |
GET |
/qr-codes/{qrCode}/download/{format} |
read | Baixa a imagem no formato pedido. |
POST |
/qr-codes |
write | Cria um QR Code. |
PATCH |
/qr-codes/{qrCode} |
write | Edita destino, cor, marca ou tag. |
POST |
/qr-codes/{qrCode}/pause |
write | Pausa o QR Code. |
POST |
/qr-codes/{qrCode}/activate |
write | Reativa um QR Code pausado. |
DELETE |
/qr-codes/{qrCode} |
write | Move para a lixeira. |
POST |
/qr-codes/{qrCode}/restore |
write | Restaura da lixeira. |
DELETE |
/qr-codes/{qrCode}/permanent |
write | Exclui definitivamente. |
Códigos de barras
Códigos de barras dos produtos, com imagem pronta para arte e embalagem.
| Método | Caminho | Escopo | O que faz |
|---|---|---|---|
GET |
/barcodes |
read | Lista os códigos de barras. |
GET |
/barcodes/{barcode} |
read | Detalhe de um código. |
GET |
/barcodes/{barcode}/svg |
read | Imagem do código em SVG. |
GET |
/barcodes/{barcode}/download/{format} |
read | Baixa a imagem no formato pedido. |
POST |
/barcodes |
write | Cria um código de barras. |
PATCH |
/barcodes/{barcode} |
write | Edita os dados do código. |
DELETE |
/barcodes/{barcode} |
write | Move para a lixeira. |
POST |
/barcodes/{barcode}/restore |
write | Restaura da lixeira. |
DELETE |
/barcodes/{barcode}/permanent |
write | Exclui definitivamente. |
Páginas de links
Páginas públicas com categorias e itens ordenados, e geração de QR Code ou link curto da própria página.
| Método | Caminho | Escopo | O que faz |
|---|---|---|---|
GET |
/link-pages |
read | Lista as páginas. |
GET |
/link-pages/{linkPage} |
read | Detalhe da página com categorias e itens. |
POST |
/link-pages |
write | Cria uma página com suas categorias e itens. |
PATCH |
/link-pages/{linkPage} |
write | Edita a página e reordena categorias e itens. |
POST |
/link-pages/{linkPage}/pause |
write | Tira a página do ar. |
POST |
/link-pages/{linkPage}/activate |
write | Coloca a página no ar. |
POST |
/link-pages/{linkPage}/qr-code |
write | Gera um QR Code da página. Exige também poder criar QR Code. |
POST |
/link-pages/{linkPage}/short-link |
write | Gera um link curto da página. Exige também poder criar link curto. |
DELETE |
/link-pages/{linkPage} |
write | Move para a lixeira. |
POST |
/link-pages/{linkPage}/restore |
write | Restaura da lixeira. |
DELETE |
/link-pages/{linkPage}/permanent |
write | Exclui definitivamente. |
Arquivos
Materiais do produto. Arquivo grande sobe em partes, para que a conexão cair no meio não perca o envio inteiro.
| Método | Caminho | Escopo | O que faz |
|---|---|---|---|
GET |
/files |
read | Lista os arquivos. |
GET |
/files/{file} |
read | Detalhe de um arquivo. |
GET |
/files/{file}/download |
read | Baixa o arquivo e conta o download. |
POST |
/files |
write | Envia um arquivo direto, em uma requisição. |
POST |
/files/uploads |
write | Inicia um envio em partes e devolve o tamanho de cada parte. |
POST |
/files/uploads/{upload}/part |
write | Envia uma parte, em ordem. |
POST |
/files/uploads/{upload}/complete |
write | Fecha o envio. O conteúdo é verificado antes de virar arquivo. |
DELETE |
/files/uploads/{upload} |
write | Aborta um envio em andamento. |
DELETE |
/files/{file} |
write | Move para a lixeira. |
POST |
/files/{file}/restore |
write | Restaura da lixeira. |
DELETE |
/files/{file}/permanent |
write | Exclui definitivamente e libera a cota. |
Analytics
Números agregados de uso. Nunca devolve evento individual, IP, navegador nem origem bruta.
| Método | Caminho | Escopo | O que faz |
|---|---|---|---|
GET |
/analytics/summary |
read | Totais, série diária, módulos, segmentos e rankings do período. |
Cuidados com a credencial
- Guarde o segredo no gerenciador de senhas do seu sistema, nunca no código enviado ao repositório nem no navegador do cliente.
- Crie uma credencial por integração. Assim você revoga uma sem derrubar as outras.
- Revogue ao encerrar a integração, ao trocar de fornecedor ou diante de qualquer suspeita de exposição.
- Nesta versão a credencial não expira sozinha. A revogação é sua responsabilidade.
Precisa de ajuda para integrar?
Conte o que a sua operação precisa e a gente responde com o caminho mais curto.
Falar com a gente