r repor documentação de integração
Guia rápido

Integração externa oficial

Conecte ERP, PDV ou sistema de mercado ao repor

Este guia foi feito para o desenvolvedor integrar com o repor de forma segura, objetiva e sem adivinhação. Aqui você encontra os ambientes corretos, o fluxo recomendado, os endpoints disponíveis, exemplos por linguagem e os cuidados operacionais para homologação e produção.

Autenticação externa x-api-key
Chave de idempotência eventId obrigatório
Fluxo atual Sistema externo envia dados para o repor
Escopo atual Produtos, packs e baixas automáticas

Antes de começar

O que o integrador precisa ter para a integração funcionar

Se você é o programador responsável pela integração, confirme estes pontos primeiro. Isso evita perda de tempo com testes em ambiente certo, payload errado ou expectativa incorreta sobre o que o repor recebe.

Checklist mínimo

  • Conta do mercado com Integração Externa ativada no app.
  • x-api-key gerada pelo administrador do mercado.
  • JWT de administrador para consultar setores e configuração.
  • Setores já criados no repor para obter sectorId válido.
  • Sistema do mercado com capacidade de fazer requisições HTTP.
  • Venda ou estoque identificado por EAN e quantidade.

Como isso roda na prática

  • Terminal, curl e Postman são apenas para homologação técnica.
  • A operação real deve rodar no backend, ERP, PDV ou retaguarda do cliente.
  • O leitor de código de barras não integra sozinho: quem integra é o sistema que registra a venda.
  • O sistema do cliente deve chamar os endpoints de products/upsert, batches/sync e sales.

Leitura rápida para não perder tempo

Se o sistema do mercado não consegue enviar requisições HTTP, não consegue expor o EAN vendido ou não permite customização/integradores, a integração não será automática. O repor está pronto para receber os dados; o sistema externo também precisa estar apto a enviá-los.

Ambientes

Use homologação para testes e produção apenas para operação real

A integração externa do repor possui ambientes separados. Sempre valide a implementação em homologação antes de apontar o sistema para produção.

Homologação Recomendado para testes

https://api-hml.repor.app

  • Ambiente público para testes técnicos com ERP, PDV e sistemas parceiros.
  • Ideal para validar autenticação, payloads, idempotência e cenários de erro.
  • Não afeta a operação real do mercado.
  • Dados podem ser ajustados ou reiniciados pela equipe do repor.
Produção Uso operacional

https://api.repor.app

  • Use apenas após homologação concluída e validada.
  • Afeta dados reais do mercado e a rotina operacional do app.
  • Exige chave e massa de dados próprias de produção.
  • Não use payloads de teste ou eventos experimentais neste ambiente.

Regra prática

Se você está ajustando payloads, validando retorno da API ou testando a integração pela primeira vez, use homologação. Produção deve receber apenas tráfego validado.

Arquitetura

Como a integração funciona hoje

O que já funciona

  • Receber catálogo de produtos por EAN.
  • Receber packs ou lotes com quantidade, validade e setor.
  • Receber vendas para baixa automática de quantidade.
  • Permitir operação manual no app mesmo com integração ativa.
  • Tratar reenvio de eventos com idempotência por eventId.

O que não faz hoje

  • Enviar cadastro manual do repor de volta para o ERP.
  • Sincronizar automaticamente setores criados fora do repor.
  • Operar como integração bidirecional completa.

Passo a passo

Fluxo recomendado para iniciar uma integração

1

Ative a integração no repor

No app, acesse Ajustes > Integração Externa e ative a integração do mercado.

2

Gere a chave

Um administrador do repor deve gerar a chave de integração do mercado.

3

Consulte os setores do mercado

Use GET /markets/current/integration/sectors com JWT de administrador para descobrir os sectorId válidos.

4

Valide a conectividade

Faça um GET /integrations/status com x-api-key no ambiente correto.

5

Sincronize produtos

Envie o catálogo por EAN usando POST /integrations/products/upsert.

6

Sincronize packs

Envie lotes com externalId, validade, quantidade e sectorId.

7

Envie vendas

Ao vender no caixa, envie o evento para POST /integrations/sales para baixa automática.

8

Promova para produção

Após validar tudo em homologação, troque a base URL e a chave para produção.

Autenticação

Há dois tipos de acesso envolvidos

Tipo Uso Como autentica
Administrador do repor Ativar integração, consultar configuração e gerar chave. Authorization: Bearer <jwt-admin>
Sistema externo Enviar produtos, packs e vendas para o repor. x-api-key: <chave>

Checklist

Pré-requisitos antes da primeira chamada

1. Mercado com integração ativa

Sem isso, a API externa não deve ser usada como pronta para operação.

2. Chave gerada

A x-api-key deve ficar apenas no backend do integrador.

3. Setores existentes no repor

Os packs exigem sectorId válido. Consulte GET /markets/current/integration/sectors antes do primeiro batches/sync.

4. Estratégia de eventId

Use um identificador único por evento para evitar duplicidade no reenvio.

Endpoints

Use os filtros para focar apenas no que interessa

GET/markets/current/integration

Retorna a configuração atual da integração do mercado autenticado.

Auth: Authorization: Bearer <jwt-admin>

PATCH/markets/current/integration

Ativa ou desativa a integração e ajusta preferências do mercado.

Body: { enabled, realtimeUpdates?, syncIntervalSeconds?, soldOutLabel?, providerName? }

POST/markets/current/integration/rotate-key

Gera uma nova chave de integração para o sistema externo.

Resposta: { apiKey, integration }

GET/markets/current/integration/sectors

Lista os setores válidos do mercado para o integrador obter o sectorId correto.

Auth: Authorization: Bearer <jwt-admin>

Resposta: { sectors: [{ id, name, defaultAlertDays, description }] }

GET/me/snapshot

Útil para consultar dados internos do mercado, inclusive setores e respectivos IDs, mas o endpoint preferencial para integração é /markets/current/integration/sectors.

GET/integrations/status

Healthcheck da integração. Use para validar se a chave está correta.

Header: x-api-key

POST/integrations/products/upsert

Cria ou atualiza produtos do catálogo do repor por EAN.

Header: x-api-key

Limite: até 500 produtos por chamada.

POST/integrations/batches/sync

Cria ou atualiza packs ou lotes do repor.

Header: x-api-key

Chave externa: externalId

POST/integrations/sales

Envia vendas para o repor dar baixa automática nas quantidades por EAN.

Header: x-api-key

Limite: até 500 itens por chamada.

Payloads

Contratos oficiais

Ativar integração

{
  "enabled": true,
  "realtimeUpdates": true,
  "syncIntervalSeconds": 15,
  "soldOutLabel": "Esgotado",
  "providerName": "ERP Mercado X"
}

Setores da integração

{
  "sectors": [
    {
      "id": "6264f55f-961f-4c55-8bd0-6678380c7933",
      "name": "Mercearia",
      "defaultAlertDays": 30,
      "description": "Setor principal"
    }
  ]
}

Produtos

{
  "eventId": "products-2026-06-20-001",
  "products": [
    {
      "externalId": "PROD-001",
      "ean": "7890000000123",
      "name": "Iogurte natural 170g",
      "brand": "Marca X",
      "unit": "un"
    }
  ]
}

Packs ou lotes

{
  "eventId": "batches-2026-06-20-001",
  "batches": [
    {
      "externalId": "LOT-0001",
      "ean": "7890000000123",
      "productName": "Iogurte natural 170g",
      "quantity": 12,
      "expirationDate": "2026-07-15",
      "sectorId": "UUID_DO_SETOR_NO_REPOR",
      "alertLeadDays": 30
    }
  ]
}

Vendas

{
  "eventId": "sale-2026-06-20-001",
  "soldAt": "2026-06-20T14:03:00.000Z",
  "items": [
    {
      "ean": "7890000000123",
      "quantity": 2
    }
  ]
}

Exemplos por linguagem

Filtre para ver apenas o exemplo que você precisa

Node.js com fetch

const response = await fetch(
  "https://api-hml.repor.app/integrations/products/upsert",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": process.env.REPOR_API_KEY
    },
    body: JSON.stringify({
      eventId: "products-2026-06-20-001",
      products: [
        {
          externalId: "PROD-001",
          ean: "7890000000123",
          name: "Iogurte natural 170g",
          brand: "Marca X",
          unit: "un"
        }
      ]
    })
  }
);

const data = await response.json();
console.log(data);

Node.js com Axios

const axios = require("axios");

async function syncProducts() {
  const { data } = await axios.post(
    "https://api-hml.repor.app/integrations/products/upsert",
    {
      eventId: "products-2026-06-20-001",
      products: [
        {
          externalId: "PROD-001",
          ean: "7890000000123",
          name: "Iogurte natural 170g",
          brand: "Marca X",
          unit: "un"
        }
      ]
    },
    {
      headers: {
        "x-api-key": process.env.REPOR_API_KEY
      }
    }
  );

  console.log(data);
}

syncProducts();

PHP com cURL

$payload = [
  "eventId" => "products-2026-06-20-001",
  "products" => [
    [
      "externalId" => "PROD-001",
      "ean" => "7890000000123",
      "name" => "Iogurte natural 170g",
      "brand" => "Marca X",
      "unit" => "un"
    ]
  ]
];

$ch = curl_init("https://api-hml.repor.app/integrations/products/upsert");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Content-Type: application/json",
  "x-api-key: " . getenv("REPOR_API_KEY")
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Python com requests

import os
import requests

payload = {
  "eventId": "products-2026-06-20-001",
  "products": [
    {
      "externalId": "PROD-001",
      "ean": "7890000000123",
      "name": "Iogurte natural 170g",
      "brand": "Marca X",
      "unit": "un"
    }
  ]
}

response = requests.post(
  "https://api-hml.repor.app/integrations/products/upsert",
  json=payload,
  headers={"x-api-key": os.getenv("REPOR_API_KEY")}
)

print(response.status_code)
print(response.json())

Respostas esperadas

Leitura rápida dos retornos da API

Status Significado Como tratar
200 Consulta processada com sucesso. Seguir normalmente.
202 processed Evento recebido e processado. Marcar como concluído no sistema de origem.
202 duplicate O mesmo eventId já foi processado antes. Não reenviar o mesmo evento como se fosse falha crítica.
202 ignored Não havia pack elegível para aplicar a baixa. Registrar para auditoria e revisar saldo ou EAN de origem.
401 Chave ausente, inválida ou desatualizada. Revisar x-api-key e o ambiente usado.
422 Payload inválido. Corrigir os dados antes de reenviar.

Erros comuns

Os retornos mais frequentes durante a implantação

401 Unauthorized

Acontece quando a x-api-key está ausente, inválida ou pertence a outro ambiente.

422 Unprocessable Entity

Ocorre quando o payload não segue o contrato esperado, como EAN inválido, data fora do formato ou campo obrigatório faltando.

202 duplicate

Não é erro operacional. Significa que o mesmo eventId já foi processado anteriormente.

202 ignored

O evento foi recebido, mas não havia pack compatível para aplicar a baixa automática.

Segurança

Boas práticas para integrar com segurança

Faça

  • Armazene a x-api-key apenas no backend do integrador.
  • Use homologação antes de apontar para produção.
  • Crie um eventId único por evento enviado.
  • Registre logs internos do seu lado para auditoria e retentativa.
  • Rotacione a chave se houver qualquer suspeita de exposição.

Não faça

  • Não exponha a chave em frontend, app público ou código cliente.
  • Não compartilhe a chave em print de tela, issue pública ou repositório.
  • Não teste produção com massa artificial ou dados de homologação.
  • Não use o mesmo segredo operacional em homologação e produção.
  • Não trate 202 duplicate como falha crítica.

Transparência importante

Esta documentação foi escrita para ser útil ao integrador sem expor segredos reais, credenciais operacionais ou detalhes internos desnecessários de infraestrutura. Use sempre credenciais próprias, segregação por ambiente e armazenamento seguro do lado servidor.

FAQ técnico

Dúvidas frequentes

Qual ambiente devo usar primeiro?

Homologação: https://api-hml.repor.app.

Quando uso produção?

Somente após validar autenticação, produtos, packs e vendas em homologação.

O repor envia cadastro manual de volta para o ERP?

Não hoje. O fluxo atual é de entrada de dados do sistema externo para o repor.

Qual identificador usar para produtos?

O principal identificador de produto é o EAN.

Qual identificador usar para packs?

O principal identificador externo é o externalId do lote ou pack.