# API LojaHub > API REST do LojaHub (hub/ERP para vendedores multi-conta em marketplaces: Mercado Livre, Shopee, Amazon e outros). Permite a sistemas próprios, parceiros e agentes de IA consultar vendas, notas fiscais (NF-e) e grupos de produtos, e receber notificações (webhooks) de vendas novas, cancelamentos e mudanças na situação das notas. Regras importantes para quem integra (inclusive agentes de IA): - Base URL: https://integra.lojahub.api.br — versão v1 (piloto). - Autenticação: OAuth 2.0 client credentials em `POST /oauth/token` (HTTP Basic com client_id/client_secret, `grant_type=client_credentials`). Envie `Authorization: Bearer `. O token vale 30 minutos; peça outro ao expirar. - Cada credencial pertence a UMA loja. Recursos de outras lojas respondem 404. - Escopos: `vendas:read`, `notas:read`, `notas:xml` (XML contém dados pessoais; desligado por padrão), `grupos:read`, `webhooks:manage`. - Envelope único: o conteúdo vem em `data` com as chaves em PORTUGUÊS; os metadados ficam fora de `data` com as chaves em inglês (`pagination.limit`, `pagination.next_cursor`, `request_id`, `status`, `code`). Exceções: `POST /oauth/token` (corpo da RFC 6749) e `/saude`, `/pronto`. - Sincronize de forma incremental: use `atualizado_desde` (máximo 31 dias atrás) e siga `pagination.next_cursor` até vir `null`, repetindo os mesmos filtros em cada página. Use margem de sobreposição: `atualizado_desde` = 1 hora antes do maior `atualizada_em` já recebido, descartando os repetidos pelo `id` (cobre gravações fora de ordem e a hora repetida de um eventual horário de verão). Prefira webhooks ou `GET /v1/eventos` a consultar repetidamente. - Limites: cabeçalhos `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`; em `429`, respeite `Retry-After`. Em `502`/`503`, tente novamente com backoff exponencial. - Erros vêm em `application/json` no mesmo envelope, trocando `data` por `error`: `{"request_id","status","code","error":{"tipo","titulo","detalhes"}}`; programe pelo `code`, que é estável (ex.: `RECURSO_NAO_ENCONTRADO`, `LIMITE_EXCEDIDO`, `PARAMETRO_INVALIDO`). - Datas em ISO-8601, sempre no horário de Brasília: toda data devolvida vem com `-03:00`; nas datas enviadas, o fuso explícito é respeitado e, sem fuso, vale Brasília (`2026-10-20` = meia-noite de Brasília). As cotas diárias viram à meia-noite de Brasília. Valores monetários como string decimal (ex.: "129.90"). - Nenhuma resposta JSON contém dados pessoais do comprador final (LGPD). - O campo `codigo_marketplace` é o código da venda que o lojista vê no marketplace; use-o para buscas (`GET /v1/vendas/codigo/{codigo}`). - Situação de nota fiscal: `rejeitada`/`erro` trazem a mensagem da SEFAZ ou do marketplace em `mensagem`. ## Documentação - [Documentação completa (navegável)](/docs): guias de primeiros passos, autenticação, sincronização, webhooks, erros e referência de cada endpoint. - [Contrato OpenAPI 3.1 (YAML)](/openapi.yaml): fonte única e versionada de todos os endpoints, parâmetros, respostas e códigos de erro. ## Endpoints principais - [GET /v1/vendas](/docs#tag/Vendas): listar vendas por período, conta, marketplace, situação ou situação da nota. - [GET /v1/vendas/codigo/{codigo}](/docs#tag/Vendas): buscar venda pelo código do marketplace. - [GET /v1/notas](/docs#tag/Notas-fiscais): listar notas fiscais (ex.: `?situacao=rejeitada`). - [GET /v1/notas/{id}/xml](/docs#tag/Notas-fiscais): XML da NF-e (escopo `notas:xml`, auditado). - [GET /v1/grupos](/docs#tag/Grupos): produtos com dados fiscais (NCM, CEST, origem), estoque e automações. - [POST /v1/webhooks](/docs#tag/Notificacoes): assinar eventos; valide `X-LH-Assinatura` com HMAC-SHA256. - [GET /v1/eventos](/docs#tag/Notificacoes): feed de eventos (alternativa aos webhooks, 30 dias). ## Opcional - Servidor MCP do LojaHub: em desenvolvimento (somente leitura no lançamento; ações exigirão confirmação humana).