QuoboDocs
Criar conta

Documentação

Integre o seu estoque com a Quobo

A Quobo se conecta ao seu sistema de duas formas: webhooks assinados, que já avisam o seu servidor a cada mudança, e uma API REST para ler e escrever o estoque, que chega em breve. Comece pelos guias abaixo.

O que já está disponível

Webhooks estão no ar, a partir do plano Starter: registre seus endpoints no painel, em Configurações → Webhooks, e a Quobo entrega os eventos assinados ao seu servidor.

A API REST por token (as convenções e endpoints desta documentação) está em breve, a partir do plano Pro. Você já pode gerar um token no painel, mas ele ainda não autentica chamadas.

Base da API

Todos os endpoints ficam sob a versão v1, na base de produção. As respostas são JSON e os identificadores são UUID.

Base URL
https://api.quobo.com.br/api/v1

Autenticação

Quando a API REST estiver disponível, cada requisição levará um token de API no cabeçalho Authorization, no formato Bearer. Você já pode gerar o token em Configurações → Integração na plataforma (ele é exibido uma única vez, no momento da criação), mas o acesso programático que o consome entra a partir do plano Pro. O token pertence à organização e carrega as permissões dela.

bash
curl https://api.quobo.com.br/api/v1/catalog/items \
  -H "Authorization: Bearer qbo_seu_token_aqui"

Nunca exponha o token no cliente

O token dá acesso total à organização. Use-o apenas do seu servidor, guarde-o em variável de ambiente e revogue-o pela plataforma se suspeitar de vazamento. O front-end e o app nunca precisam dele.

Idempotência

Toda requisição que altera dados (POST, PATCH, PUT, DELETE) exige o cabeçalho Idempotency-Key: um valor único que você gera por operação. Se a mesma chave chegar de novo, a Quobo devolve a resposta já registrada em vez de executar a operação outra vez. Assim uma retentativa de rede não duplica uma movimentação.

bash
curl -X POST https://api.quobo.com.br/api/v1/inventory/movementations \
  -H "Authorization: Bearer qbo_seu_token_aqui" \
  -H "Idempotency-Key: 8f2b1c9a-3d5e-4a71-9b0c-1e2f3a4b5c6d" \
  -H "Content-Type: application/json" \
  -d '{ "item_id": "…", "move_type": "entry", "quantity": 10 }'

Paginação

As listagens são paginadas por cursor. Envie limit e, para a próxima página, after com o next_cursor da resposta anterior. Quando has_more for false, não há mais páginas.

Resposta 200
{
  "data": [ /* … itens … */ ],
  "next_cursor": "eyJpZCI6IjRm…",
  "has_more": true
}

Erros

Erros retornam o status HTTP adequado e um corpo com três campos: code (um identificador estável, feito para o seu código decidir o que fazer), message (texto para desenvolvedores, em logs) e details (contexto opcional, como os campos que falharam na validação).

Resposta 422
{
  "code": "validation_failed",
  "message": "Validation failed: Quantity must be greater than 0",
  "details": { "quantity": ["must be greater than 0"] }
}

Trate o code, não a message

O code é estável entre versões; a message é um texto técnico em inglês, sujeito a mudança, e nunca deve ir para a tela do usuário final. Mapeie cada code para a mensagem que você mostra.

Valores monetários

Dinheiro trafega sempre como número inteiro em centavos, em campos com o sufixo _cents (por exemplo sale_price_cents). Divida por 100 para exibir. Isso evita os erros de arredondamento de ponto flutuante. As quantidades de estoque, por outro lado, aceitam frações (veja unidades de medida).