Registrar novas categorias e seus relacionamentos

Este endpoint é utilizado para registrar um lote de categorias de uma vez. É ideal para sistemas que precisam sincronizar uma grande quantidade de dados de categoria, incluindo suas relações hierárquicas.

POST /v1/batch/categories

Header

• Authorization: Basic Auth contendo a chave publica e secreta disponibilizadas para o cliente.
  • Exemplo: Basic <base64-encoded-credentials>

Exemplo de Autorização

Para gerar o valor de Authorization, você precisa codificar suas credenciais (public_key:secret_key) em base64. Por exemplo, se sua chave pública for public_key e sua chave secreta for secret_key, você deve codificar public_key:secret_key em base64.

echo -n 'public_key:secret_key' | base64

Corpo da Requisição

O corpo da requisição deve ser uma lista de objetos de categoria, cada um contendo os seguintes campos:

Campo	Tipo	Nullable	Descrição
externalReference	string	Sim	Referência externa da categoria para rastreabilidade. Se não fornecida, será gerada automaticamente.
name	string	Não	Nome da categoria.
title	string	Não	Título da categoria.
description	string	Não	Descrição detalhada da categoria.
punctuation	int	Não	Pontuação para ordenação.
similarTerms	string	Sim	Termos similares para busca.
children	array de categorias	Sim	Lista de categorias filhas, permitindo criar hierarquias.

Exemplo de Corpo da Requisição

[
  {
    "externalReference": "cat-1",
    "name": "Alimentos",
    "title": "Alimentos",
    "description": "Categoria de alimentos",
    "punctuation": 1,
    "similarTerms": "comida, alimentação",
    "children": [
      {
        "externalReference": "cat-1-1",
        "name": "Cereais",
        "title": "Cereais",
        "description": "Categoria de cereais",
        "punctuation": 1,
        "similarTerms": "grãos, granola"
      }
    ]
  },
  {
    "externalReference": "cat-2",
    "name": "Bebidas",
    "title": "Bebidas",
    "description": "Categoria de bebidas",
    "punctuation": 2,
    "similarTerms": "líquidos, drinks"
  }
]

Processamento Assíncrono

O processamento das categorias é realizado de forma assíncrona através do Azure Service Bus. Isso significa que:

1. A requisição retorna imediatamente com um operationId
2. As categorias são processadas em background
3. Notificações sobre o progresso são enviadas via webhook
4. As categorias são processadas respeitando sua hierarquia (pai antes dos filhos)

Respostas

• 200: Retorna sucesso da operação. A resposta incluirá detalhes sobre o processamento da lista de categorias.
• 400: Retorna erro de requisição inválida. Isso geralmente ocorre devido a dados de entrada mal formatados ou faltando.
• 500: Retorna erro interno do servidor. Indica problemas no processamento da requisição no servidor.

Exemplo de Resposta para Sucesso (200)

{ "operationId": "402fe685-2060-432b-ac57-223eb2e680f3" }

Exemplo de Resposta para Erro (400)

{
  "error": "Invalid request",
  "details": "The name field is missing in one of the category items."
}

Mensagem de notificação webhook

Quando a operação é processada, mensagens são enviadas para os endpoints de notificação registrados pelo webhook. As mensagens são enviadas para cada categoria processada.

{
  "operationId": "54d6a979-5f62-4e17-9d4c-dbd9f5ede403",
  "relatedEntity": "Category",
  "eventType": 7,
  "data": {
    "externalReference": "cat-1",
    "name": "Alimentos",
    "title": "Alimentos",
    "description": "Categoria de alimentos",
    "punctuation": 1,
    "similarTerms": "comida, alimentação"
  },
  "contractAccountId": "9f36a666-acd5-4987-a47f-3de247f65d82"
}

• OperationId: Identificador único da operação.
• RelatedEntity: Entidade relacionada ao evento (Category).
• EventType: Tipo de evento.
  • Os tipos possíveis para categoria são:
    • Category_Created = 7
    • Category_Updated = 8
    • Category_Deleted = 9
• Data: Dados específicos do evento.
• ContractAccountId: Identificador da conta do contrato.
• Error: Detalhes do erro caso exista algum.