Documentação
Documentação
Start typing to search…

Integração com CRM


Fluxo de Requisição e Resposta

Abaixo está um exemplo simplificado do fluxo de comunicação:

  1. Flowbiz envia requisição para seu endpoint com autenticação
  2. Sua API valida a autenticação
  3. Sua API retorna dados estruturados no formato JSON
  4. Flowbiz processa os dados recebidos
Exemplo detalhado: Listar pedidos (GET /api/v2/orders)

1) Endpoint e método
   GET /api/v2/orders

2) Parâmetros de query
   - `offset` (opcional, padrão 0): início da paginação.
   - `limit`  (opcional, padrão 50, máximo 100): quantidade por página.
   - `start_date` (obrigatório): início do intervalo no formato ISO 8601 `YYYY-MM-DD`.
   - `end_date`   (obrigatório): fim do intervalo no formato ISO 8601 `YYYY-MM-DD`.

3) Headers obrigatórios
   - `X-Impulse-Key`: sua API Key de integração.

4) Requisição de exemplo
   HTTP
   GET /api/v2/orders?offset=0&limit=10&start_date=2023-01-01&end_date=2023-01-31
   X-Impulse-Key: valor_da_api_key

   cURL
   # All comments in English
   # Query params: pagination (offset/limit) and date filter (start_date/end_date)
   curl -X GET \
     "https://sua-plataforma.com/api/v2/orders?offset=0&limit=10&start_date=2023-01-01&end_date=2023-01-31" \
     -H "X-Impulse-Key: valor_da_api_key" \
     -H "Accept: application/json"

5) Resposta de sucesso (200)
{
  "data": [
    {
      "orderId": "12345",
      "date": "2023-01-15T12:30:00Z",
      "total": 105.00,
      "currency": "BRL",
      "rawPaymentStatus": "Pago",
      "customerId": "1",
      "customerEmail": "[email protected]",
      "items": [
        {
          "productId": "1",
          "sku": "SKU123",
          "name": "Nome do Produto",
          "price": 50.00,
          "quantity": 2
        }
      ]
    }
  ],
  "total": 42,
  "offset": 0,
  "limit": 10,
  "count": 1,
  "hasNext": true,
  "nextOffset": 10
}

6) Paginação (como funciona)
   - A resposta sempre inclui `total`, `offset` e `limit`.
   - Para obter a próxima página, some `limit` ao `offset` atual.
   - A resposta inclui também `count`, `hasNext` e `nextOffset` para facilitar a navegação sem cálculos no cliente.
   Exemplo página 2 → `offset=10&limit=10`.

   cURL (página 2)
   curl -X GET \
     "https://sua-plataforma.com/api/v2/orders?offset=10&limit=10&start_date=2023-01-01&end_date=2023-01-31" \
     -H "X-Impulse-Key: valor_da_api_key" \
     -H "Accept: application/json"

7) Filtro de datas (regras)
   - Use formato `YYYY-MM-DD` (sem hora) para `start_date` e `end_date`.
   - O intervalo é inclusivo (inclui as datas informadas).
   - Se sua base usa fuso horário, normalize para UTC antes de aplicar o filtro.

8) Códigos de status e respostas de erro
   - 401 Unauthorized / 403 Forbidden: API Key ausente ou inválida.
{
  "error": "unauthorized",
  "message": "X-Impulse-Key is missing or invalid"
}
   - 400 Bad Request: parâmetros inválidos.
{
  "error": "bad_request",
  "message": "start_date must be in YYYY-MM-DD format"
}
   - 429 Too Many Requests: limite de requisições excedido (se aplicável).
{
  "error": "rate_limited",
  "message": "Try again later"
}
   - 5xx: falha interna do servidor.
{
  "error": "server_error",
  "message": "Unexpected error"
}

9) Erros comuns (e como corrigir)
   - Falta do header `X-Impulse-Key` → adicione-o em todas as requisições.
   - Datas em formato diferente de `YYYY-MM-DD` → converta antes de enviar.
   - `limit` acima de 100 → ajuste para no máximo 100.
   - `offset` negativo → use valores >= 0.

Endpoints Obrigatórios

Sua API deve implementar os seguintes endpoints:

EndpointMétodoDescriçãoParâmetros
/healthzGETCheck de alive da API
/categoriesGETLista todas as categoriasoffset, limit
/brandsGETLista todas as marcasoffset, limit
/productsGETLista todos os produtosoffset, limit
/ordersGETLista todos os pedidosoffset, limit, start_date, end_date

Requisitos Técnicos

Autenticação

A autenticação é realizada através de uma API Key enviada no header X-Impulse-Key em todas as requisições. Sua API deve validar este header e recusar requisições que não incluam a chave correta.

Exemplo de Header de Autenticação:

X-Impulse-Key: valor_da_api_key

Resposta em caso de falha na autenticação:

  • Status: 401 (Unauthorized) ou 403 (Forbidden)
  • Corpo: Mensagem de erro indicando que a autenticação falhou

Notas sobre segurança:

  • Armazene a API Key de forma segura, preferencialmente em variáveis de ambiente.
  • Considere implementar um mecanismo para rotação de chaves quando necessário.
  • Todas as requisições devem ser feitas via HTTPS para garantir a segurança da API Key durante a transmissão.

Paginação

Todos os endpoints de listagem devem suportar paginação via parâmetros offset e limit:

  • offset: Posição inicial dos registros (padrão: 0)
  • limit: Número máximo de registros a retornar (padrão: 50, máximo: 100)

A resposta deve incluir o total de registros disponíveis, além dos parâmetros de paginação utilizados.

Convenção de Paginação (obrigatória)

Para eliminar ambiguidade e permitir que o consumidor saiba quando não há mais páginas, a resposta deve incluir os campos a seguir:

  • total (number): total de registros encontrados após aplicar todos os filtros.
  • offset (number): deslocamento do primeiro registro retornado nesta resposta.
  • limit (number): máximo solicitado por página.
  • count (number): quantidade real de itens em data nesta página.
  • hasNext (boolean): indica se existe próxima página. Regra: hasNext = (offset + count) < total.
  • nextOffset (number, opcional): próximo offset quando hasNext = true. Regra: nextOffset = offset + count.

Exemplo prático

  • Você possui total = 23000 pedidos no intervalo de 30 dias.
  • O cliente chama com limit = 100 e offset = 0.
  • Se a página retornou count = 100, então hasNext = (0 + 100) < 23000 → true e nextOffset = 100.
  • O cliente segue chamando offset = 100, 200, 300, ... até que em uma página final offset = 22900 e count = 100, teremos hasNext = (22900 + 100) < 23000 → false. Não há mais páginas.

Opcional (boas práticas): Disponibilize cabeçalhos Link com rel="next" e rel="prev" seguindo RFC 5988, e/ou forneça prevOffset/hasPrev na resposta.

Filtro de Data para Pedidos

O endpoint de pedidos deve suportar filtragem por um intervalo de datas:

  • start_date: Data inicial no formato ISO 8601 (YYYY-MM-DD)
  • end_date: Data final no formato ISO 8601 (YYYY-MM-DD)

Modelos de Objeto JSON

Abaixo estão os exemplos de estruturas JSON que sua API deve retornar.

Campos Obrigatórios

Objeto Order

  • orderId (obrigatório)
  • date (obrigatório, formato ISO 8601)
  • total (obrigatório, numérico positivo)
  • currency (obrigatório, formato ISO 4217)
  • rawPaymentStatus (obrigatório)
  • customerId (obrigatório)
  • customerEmail (obrigatório, formato válido)
  • items (obrigatório, pelo menos um item)

Objeto Product

  • productId (obrigatório)
  • variants (obrigatório, pelo menos uma variante)
    • Cada variante deve ter:
      • sku (obrigatório)
      • name (obrigatório)
      • price (obrigatório, numérico positivo)
  • category (obrigatório, pelo menos uma categoria)

Objeto Category

  • id (obrigatório)
  • name (obrigatório)

Objeto Brand

  • id (obrigatório)
  • name (obrigatório)

Nota importante: Não existe um objeto Customer separado nesta implementação. As informações do cliente (CustomerId, CustomerEmail, etc.) são incluídas diretamente no objeto Order.

Descrição dos Campos

Objeto Order

  • platform: Nome da sua plataforma de e-commerce (ex: "SuaPlataforma")
  • orderId: Identificador único do pedido na plataforma
  • cartId: Identificador do carrinho de compras associado ao pedido
  • date: Data e hora da criação do pedido (formato ISO 8601)
  • subtotal: Valor subtotal do pedido (antes de descontos e frete)
  • freight: Valor do frete (equivalente ao campo DeliveryAmount em algumas implementações)
  • currency: Código da moeda no formato ISO 4217 (ex: "BRL", "USD")
  • tax: Valor de impostos aplicados ao pedido
  • discounts: Valor total de descontos aplicados (equivalente ao campo DiscountAmount em algumas implementações)
  • total: Valor total do pedido (após descontos e frete)
  • coupons: Códigos de cupons de desconto aplicados ao pedido
  • rawPaymentStatus: Status atual do pedido (ex: "Pago", "Enviado", "Cancelado")
  • isPaid: Booleano indicando se o pedido foi pago (derivado do RawPaymentStatus)
  • customerId: Identificador único do cliente na plataforma
  • customerEmail: Email do cliente para contato
  • customerCpf: CPF do cliente (opcional)
  • customerCnpj: CNPJ do cliente (opcional)
  • customerPhone: Telefone do cliente (opcional). Formatar com país + prefixo do estado + número = +5511999999999
  • optIn: Booleano indicando se o cliente aceitou receber comunicações de marketing
  • items: Lista de itens incluídos no pedido
    • productId: Identificador único do produto
    • categories: Lista de categorias às quais o produto pertence
      • id: Identificador único da categoria
      • name: Nome da categoria
    • sku: Código SKU (Stock Keeping Unit) do produto
    • name: Nome do produto
    • brand: Nome da marca do produto
    • price: Preço unitário do produto
    • priceFrom: Preço original antes de desconto (se aplicável)
    • Quantity: Quantidade do produto no pedido
    • url: URL completa para a página do produto
    • imageUrl: URL da imagem do produto
    • properties: Propriedades adicionais do produto (opcional)
      • customNumber: Lista de valores personalizados (ex: códigos de variantes)
  • paymentMethods: Lista de métodos de pagamento utilizados
    • type: Tipo do método de pagamento
    • amount: Valor pago com este método
  • deliveryMethods: Lista de métodos de entrega
    • type: Tipo do método de entrega
    • amount: Valor do frete
  • deliveryAddress: Endereço de entrega
    • city: Cidade
    • addressLine2: Detalhes adicionais/complemento (equivalente ao campo Detail em algumas implementações)
    • neighborhood: Bairro (equivalente ao campo District em algumas implementações)
    • addressNumber: Número (equivalente ao campo Number em algumas implementações)
    • state: Estado (UF)
    • addressLine1: Rua/Avenida (equivalente ao campo Street em algumas implementações)
    • postalCode: CEP (equivalente ao campo Zipcode em algumas implementações)
    • country: País

Objeto Product

  • productId: Identificador único do produto na plataforma
  • url: URL completa para a página do produto
  • brand: Informações da marca do produto
    • id: Identificador único da marca
    • name: Nome da marca
  • category: Lista de categorias às quais o produto pertence
    • id: Identificador único da categoria
    • name: Nome da categoria
  • variants: Lista de variantes do produto
    • sku: Código SKU (Stock Keeping Unit) da variante
    • name: Nome da variante
    • price: Preço da variante
    • priceFrom: Preço original antes de desconto (se aplicável)
    • stock: Quantidade em estoque
    • imageUrl: URL da imagem da variante
    • url: URL específica para a variante
    • available: Indica se a variante está disponível para compra
    • properties: Propriedades adicionais da variante
      • customNumber: Lista de valores personalizados (ex: códigos de variantes)

Nota importante: A estrutura do objeto Product utiliza o conceito de variantes. Cada produto pode ter múltiplas variantes (ex: tamanhos, cores), cada uma com seu próprio SKU, preço, estoque, etc. O campo quantity mencionado anteriormente como obrigatório para Product na verdade pertence ao OrderItem quando o produto faz parte de um pedido.

Objeto Category

  • id: Identificador único da categoria na plataforma
  • name: Nome da categoria

Objeto Brand

  • id: Identificador único da marca na plataforma
  • name: Nome da marca

Objeto Order (Exemplo Completo)

{
  "Platform": "SuaPlataforma",
  "OrderId": "12345",
  "CartId": "cart123",
  "Date": "2023-06-01T10:00:00Z",
  "Subtotal": 100.0,
  "Freight": 10.0,
  "currency": "BRL",
  "tax": 0.0,
  "ciscounts": 5.0,
  "total": 105.0,
  "coupons": "WELCOME10",
  "rawPaymentStatus": "Pago",
  "isPaid": true,
  "customerId": "1",
  "customerEmail": "[email protected]",
  "customerCpf": "123.456.789-00",
  "customerCnpj": "",
  "customerPhone": "+5511999999999",
  "optIn": true,
  "items": [
    {
      "productId": "1",
      "categories": [
        {
          "id": "10",
          "name": "Eletrônicos"
        }
      ],
      "sku": "SKU123",
      "name": "Nome do Produto",
      "brand": "Marca XYZ",
      "price": 50.0,
      "priceFrom": 60.0,
      "quantity": 2,
      "url": "https://seusistema.com/produto/1",
      "imageUrl": "https://seusistema.com/imagens/produto1.jpg",
      "properties": {
        "customNumber": ["001", "002"]
      }
    }
  ],
  "paymentMethods": [
    {
      "type": "Cartão de Crédito",
      "amount": 105.0
    }
  ],
  "deliveryMethods": [
    {
      "type": "Correios - SEDEX",
      "amount": 10.0
    }
  ],
  "deliveryAddress": {
    "postalCode": "01000-000",
    "addressLine1": "Rua Principal",
    "addressNumber": "123",
    "addressLine2": "Apto 101",
    "city": "São Paulo",
    "state": "SP",
    "country": "Brasil",
    "neighborhood": "Centro"
  }
}

Objeto Product

{
  "productId": "1",
  "url": "https://seusistema.com/produto/1",
  "brand": {
    "id": "1",
    "name": "Nome da Marca"
  },
  "category": [
    {
      "id": "1",
      "name": "Nome da Categoria"
    }
  ],
  "variants": [
    {
      "sku": "SKU123-P",
      "name": "Camiseta Azul - P",
      "price": 49.90,
      "priceFrom": 59.90,
      "stock": 10,
      "imageUrl": "https://seusistema.com/imagens/camiseta-azul-p.jpg",
      "url": "https://seusistema.com/produto/1?variant=p",
      "available": true,
      "properties": {
        "customNumber": ["001", "P"]
      }
    },
    {
      "sku": "SKU123-M",
      "name": "Camiseta Azul - M",
      "price": 49.90,
      "priceFrom": 59.90,
      "stock": 5,
      "imageUrl": "https://seusistema.com/imagens/camiseta-azul-m.jpg",
      "url": "https://seusistema.com/produto/1?variant=m",
      "available": true,
      "properties": {
        "customNumber": ["001", "M"]
      }
    }
  ]
}

Objeto Category

{
  "id": "1",
  "name": "Nome da Categoria"
}

Objeto Brand

{
  "id": "1",
  "name": "Nome da Marca"
}

Checklist de Implementação

Use o checklist abaixo para garantir que sua implementação está completa:

  • Validação do header de autenticação (X-Impulse-Key) em todos os endpoints
  • Endpoint de Listagem de Categorias (/categories)
  • Endpoint de Listagem de Marcas (/brands)
  • Endpoint de Listagem de Produtos (/products)
  • Endpoint de Listagem de Pedidos (/orders)
  • Suporte à paginação em todos os endpoints de listagem
  • Suporte ao filtro de data no endpoint de pedidos
  • Os schemas JSON de resposta correspondem exatamente à especificação
  • Todos os campos marcados como obrigatórios na especificação estão sendo preenchidos
  • Resposta apropriada (401/403) para requisições sem o header X-Impulse-Key ou com valor inválido
  • Testes realizados com os exemplos CURL fornecidos

Perguntas Frequentes

Qual é a diferença entre este padrão e outras integrações?

Este padrão inverte a responsabilidade da integração. Em vez de cada sistema desenvolver um conector específico para sua plataforma, você implementa um contrato de API padronizado. Isso permite uma integração mais rápida e escalável com múltiplos sistemas.

Preciso implementar todos os campos do objeto Order?

Os campos marcados como obrigatórios na especificação técnica devem ser implementados. Os demais campos são opcionais, mas recomendamos implementar o máximo possível para enriquecer os dados disponíveis para integração.

Por que não existe um objeto Customer separado?

Na implementação atual, as informações do cliente são armazenadas diretamente no objeto Order. Não é necessário implementar um endpoint separado para clientes, pois os dados do cliente são coletados junto com os pedidos.

Como devo implementar o objeto Product com variantes?

O objeto Product utiliza o conceito de variantes. Cada produto pode ter múltiplas variantes (ex: tamanhos, cores), cada uma com seu próprio SKU, preço, estoque, etc. É importante implementar a estrutura de variantes conforme especificado para garantir a compatibilidade com os sistemas integrados.

Posso usar HTTPS para a API?

Sim, e recomendamos fortemente o uso de HTTPS para garantir a segurança da comunicação, especialmente considerando que dados sensíveis de pedidos são transmitidos.

Suporte

Em caso de dúvidas durante o processo de desenvolvimento, entre em contato com a equipe de suporte técnico através do e-mail [email protected] ou pelo telefone (51) 9790-9718.

Próximos Passos

Após implementar a API conforme esta especificação:

  1. Execute testes locais usando os exemplos CURL fornecidos
  2. Solicite uma validação da sua implementação pela equipe técnica do sistema integrador Flowbiz
  3. Após a validação, receberá as credenciais de produção
  4. Sua plataforma estará integrada e pronta para troca de dados!

Updated 3 months ago